3D Face HRN代码实例：自定义输入路径+批量处理+UV贴图导出Python脚本-开发者社区

3D Face HRN代码实例：自定义输入路径+批量处理+UV贴图导出Python脚本

1. 这不是普通的人脸重建，而是能直接进3D软件的“数字面模”

你有没有试过——拍一张自拍照，几秒钟后，电脑里就生成了一个带纹理、可旋转、能导入Blender的3D人脸模型？不是渲染图，不是示意图，是真正基于几何结构重建出来的、带UV坐标的三维网格。

这不是科幻电影里的特效，而是3D Face HRN正在做的事。它不只输出一张好看的纹理图，而是把人脸“拆解”成标准3D建模流程能直接用的数据：顶点坐标、法线、三角面片，以及最关键的——可编辑、可映射、可重着色的UV贴图。

很多AI人脸项目止步于“看起来像”，但HRN的目标是“用得上”。它生成的UV图不是扁平的装饰画，而是严格遵循0-1归一化空间、无拉伸、无重叠、边缘对齐的工业级贴图。这意味着你导出后，不用修图、不用重展UV，拖进Unity材质球就能实时预览皮肤细节；扔进Blender的Shader Editor，立刻能叠加Subsurface Scattering模拟真实透光感。

更关键的是：它默认的Gradio界面只是个“演示入口”，真正的生产力藏在底层代码里——只要你愿意改几行Python，就能绕过网页上传，实现本地文件夹批量处理、自定义保存路径、自动命名、跳过UI等待、直接拿到.png+.obj双输出。这篇文章，就带你亲手打开这个“隐藏开关”。

2. 从Gradio界面到底层脚本：我们到底在操作什么

2.1 模型本质：ResNet50不是拿来分类的，是来“解构”人脸的

别被名字骗了——iic/cv_resnet50_face-reconstruction里的ResNet50，早就不干图像分类的老本行了。它被彻底重构为一个端到端的3D参数回归器：

输入：一张RGB人脸图（224×224，中心裁切）
输出：两组核心数据
- 3D几何参数：64维FLAME基础形变系数 + 12维姿态参数（旋转+平移）
- 纹理参数：80维Albedo（反照率）系数，用于驱动UV贴图生成

模型本身不直接输出顶点或UV，而是通过一个预置的3D人脸模板（FLAME mesh），把参数“注入”进去，动态变形出你的专属网格。而UV贴图，则是用训练好的纹理解码器，把Albedo系数+光照估计结果，映射回模板UV空间，生成最终的2048×2048纹理图。

所以，当你看到Gradio界面上那张色彩饱满的UV图时，背后发生的是：参数解码 → 纹理合成 → UV空间采样 → Gamma校正 → uint8量化。每一步都可干预、可替换、可批量复用。

2.2 Gradio只是“外壳”，真正干活的是`model.inference()`

打开原始app.py，你会看到类似这样的核心调用：

def process_image(image): # image: PIL.Image or numpy.ndarray (H, W, 3) result = model.inference(image) # ← 这才是真正的引擎 return result["uv_texture"], result["mesh"]

model.inference()返回的result字典里，藏着所有你想要的原始数据：

"uv_texture"：numpy.ndarray，形状(2048, 2048, 3)，值域[0, 255]，RGB顺序
"mesh"：trimesh.Trimesh对象，含.vertices（顶点）、.faces（面片）、.vertex_normals（法线）
"landmarks_2d"：68点2D关键点，可用于对齐或质检
"camera"：相机内参，方便后续渲染

Gradio做的，不过是把result["uv_texture"]转成PIL Image再显示，把result["mesh"]转成.obj字符串再下载。所有这些转换，你都可以在脚本里自己写，而且更快、更稳、更可控。

3. 手把手写一个真正能干活的批量处理脚本

3.1 环境准备：不装Gradio，只留最精简依赖

我们不需要网页界面，所以可以大幅精简依赖。新建一个batch_processor.py，开头只需这四行：

import os import cv2 import numpy as np from modelscope.pipelines import pipeline from modelscope.utils.constant import Tasks

安装命令也极简（GPU用户加--extra-index-url https://download.pytorch.org/whl/cu118）：

pip install modelscope opencv-python numpy trimesh pillow

注意：trimesh用于保存.obj，pillow用于高质量PNG保存，这两个是导出环节刚需，不能省。

3.2 加载模型：跳过Gradio初始化，直连推理管道

原Gradio代码中模型加载常嵌套在gr.Interface里，难以复用。我们把它抽出来，做成独立函数：

def load_hr_model(): """加载3D Face HRN模型，返回可调用的pipeline""" return pipeline( task=Tasks.face_reconstruction, model='iic/cv_resnet50_face-reconstruction', model_revision='v1.0.3' # 显式指定版本，避免更新导致行为变化 )

调用一次即可，后续所有图片都复用这个pipe对象，内存友好，启动快。

3.3 核心处理函数：支持单图/批量/自定义路径

下面这个函数，就是你未来会反复调用的“主力引擎”：

def process_single_image(pipe, img_path, output_dir, prefix=""): """ 处理单张人脸图，导出UV贴图和OBJ模型 Args: pipe: 加载好的modelscope pipeline img_path: 输入图片路径（str） output_dir: 输出目录（str），自动创建 prefix: 文件名前缀（str），如"person01_" """ # 1. 读取并预处理图像（模仿Gradio内部逻辑） img_bgr = cv2.imread(img_path) if img_bgr is None: print(f" 跳过无效图片：{img_path}") return False img_rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB) # BGR→RGB # 2. 模型推理（核心！） try: result = pipe(img_rgb) except Exception as e: print(f"❌ 模型推理失败 {img_path}：{str(e)}") return False # 3. 提取UV贴图并保存 uv_img = result["uv_texture"] # shape: (2048, 2048, 3), uint8, RGB base_name = os.path.splitext(os.path.basename(img_path))[0] uv_path = os.path.join(output_dir, f"{prefix}{base_name}_uv.png") # 使用PIL保存，确保色彩准确（OpenCV默认BGR，易出错） from PIL import Image pil_img = Image.fromarray(uv_img) pil_img.save(uv_path, optimize=True, quality=95) # 4. 提取并保存OBJ网格 mesh = result["mesh"] obj_path = os.path.join(output_dir, f"{prefix}{base_name}.obj") mesh.export(obj_path) print(f" 已保存：{uv_path} 和 {obj_path}") return True def batch_process_images(input_folder, output_folder, prefix="", max_count=None): """ 批量处理整个文件夹下的人脸图片 Args: input_folder: 输入图片文件夹路径 output_folder: 输出文件夹路径（自动创建） prefix: 所有输出文件统一前缀 max_count: 最大处理数量（调试用，None表示全部） """ os.makedirs(output_folder, exist_ok=True) # 支持常见图片格式 supported_exts = {'.jpg', '.jpeg', '.png', '.bmp'} img_files = [ os.path.join(input_folder, f) for f in os.listdir(input_folder) if os.path.splitext(f.lower())[1] in supported_exts ] if not img_files: print(f"❌ 输入文件夹 {input_folder} 中未找到支持的图片文件") return if max_count: img_files = img_files[:max_count] print(f" 仅处理前 {max_count} 张图片") print(f" 开始批量处理 {len(img_files)} 张图片...") pipe = load_hr_model() success_count = 0 for i, img_path in enumerate(img_files, 1): print(f"\n[{i}/{len(img_files)}] 正在处理：{os.path.basename(img_path)}") if process_single_image(pipe, img_path, output_folder, prefix): success_count += 1 print(f"\n 批量完成！成功 {success_count}/{len(img_files)} 张")

3.4 实际运行：三行代码搞定整批证件照

现在，你只需要在脚本末尾加这几行，就能一键跑通：

if __name__ == "__main__": # 配置你的路径（这才是真正自由的地方） INPUT_FOLDER = "/home/user/faces/id_photos" # 你的照片文件夹 OUTPUT_FOLDER = "/home/user/faces/3d_output" # 输出目录（自动创建） FILE_PREFIX = "id_" # 可选：给所有文件加前缀 # 开始处理 batch_process_images( input_folder=INPUT_FOLDER, output_folder=OUTPUT_FOLDER, prefix=FILE_PREFIX, max_count=None # 设为数字可限制张数，方便调试 )

执行它：

python batch_processor.py

几秒后，/3d_output/里就会出现：

id_personA_uv.png—— 2048×2048高清UV贴图，可直接拖进Substance Painter
id_personA.obj—— 带顶点、面片、法线的完整网格，Blender双击即开

没有弹窗，没有等待，没有手动点击——只有文件在安静生成。

4. 进阶技巧：让UV贴图真正“可用”的4个关键调整

4.1 为什么你的UV图导入Blender后颜色发灰？Gamma校正必须关

HRN模型输出的UV图，默认做了sRGB Gamma=2.2编码（这是Web显示标准），但Blender/Unity的PBR材质管线要求线性空间纹理。直接使用会导致肤色偏暗、高光不自然。

解决方法：在保存前，简单反Gamma（近似）：

# 在 process_single_image() 中，uv_img 生成后、保存前插入： uv_img_linear = np.power(uv_img / 255.0, 2.2) * 255.0 uv_img_linear = np.clip(uv_img_linear, 0, 255).astype(np.uint8) # 后续用 uv_img_linear 替代 uv_img 保存

这样导出的PNG，在Blender的Image Texture节点中勾选“sRGB”即可正确显示。

4.2 批量处理时如何过滤低质量结果？用2D关键点做可信度质检

不是每张图都适合重建。侧脸、闭眼、强阴影都会让关键点检测漂移，导致UV扭曲。我们可以用返回的landmarks_2d做快速过滤：

# 在 process_single_image() 的 try 块内，result 获取后加入： landmarks = result["landmarks_2d"] # shape: (68, 2) if landmarks.shape[0] < 68: print(f" 关键点检测不全，跳过 {img_path}") return False # 计算左右眼中心距离（粗略判断人脸大小和朝向） left_eye = landmarks[36:42].mean(axis=0) # 左眼6点 right_eye = landmarks[42:48].mean(axis=0) # 右眼6点 eye_dist = np.linalg.norm(left_eye - right_eye) if eye_dist < 20: # 小于20像素，说明人脸太小或严重侧转 print(f" 人脸过小或角度异常，跳过 {img_path}") return False

4.3 导出OBJ时如何保留UV坐标？默认trimesh不写UV，要手动加

result["mesh"]本身不含UV信息（UV是独立贴图），但你可以把UV坐标作为顶点属性写入OBJ：

# 替换原有的 mesh.export(obj_path) import trimesh # 创建新mesh，显式添加UV mesh = result["mesh"] # HRN的UV坐标已预计算在 mesh.visual.uv （如果存在），否则需手动映射 if hasattr(mesh.visual, 'uv') and mesh.visual.uv is not None: # 直接使用模型自带UV mesh_with_uv = trimesh.Trimesh( vertices=mesh.vertices, faces=mesh.faces, vertex_normals=mesh.vertex_normals, visual=trimesh.visual.TextureVisuals(uv=mesh.visual.uv) ) else: # 回退方案：用标准FLAME UV模板（需额外加载） mesh_with_uv = mesh mesh_with_uv.export(obj_path)

提示：实际项目中，建议提前下载FLAME官方UV模板（flame_template_uv.obj），用其UV覆盖，确保跨模型一致性。

4.4 如何让批量处理“断点续传”？加个简易日志记录

避免因某张图报错导致整批重跑，加一行日志：

# 在 process_single_image() 成功保存后加入： log_path = os.path.join(output_dir, "process_log.txt") with open(log_path, "a") as f: f.write(f"{base_name}\t{uv_path}\t{obj_path}\t{datetime.now().isoformat()}\n")

下次出错，直接看最后一行就知道卡在哪。

5. 总结：你刚解锁的不只是脚本，是一条3D内容生产流水线

回看这篇脚本，你真正掌握的远不止几行Python：

你绕过了UI层抽象，直达模型API：从此任何自动化流程（CI/CD、定时任务、API服务）都能调用HRN；
你定义了输入/输出契约：input_folder → [img] → output_folder → [uv.png + .obj]，这是可集成、可测试、可监控的工业接口；
你植入了质量守门员：关键点质检、尺寸过滤、Gamma校正，让输出稳定可靠；
你预留了扩展钩子：日志、前缀、最大数量、自定义后处理——所有变量都暴露为参数，而非硬编码。

这不再是“试试看”的玩具，而是一个随时能嵌入你3D工作流的模块。下周团队要做一批虚拟偶像面部资产？把证件照扔进文件夹，喝杯咖啡回来，OBJ和UV已就位。客户临时要100张不同角度的3D头像？加个for angle in range(0,360,30): rotate_and_save(...)，全自动产出。

技术的价值，从来不在它多炫酷，而在它多“顺手”。当你不再需要打开浏览器、点击上传、盯着进度条等待，而是让一切静默发生——那一刻，AI才真正成了你的同事。

获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

3D Face HRN代码实例：自定义输入路径+批量处理+UV贴图导出Python脚本