# Hunyuan3D Paint 白模贴图教程

用现成原创网格和一致参考图运行Paint纹理管线，保留形状并检查侧面与背面贴图。AI给白模上材质与重新生成几何是两个任务，不把手工烘焙参考当作AI纹理。

## 执行范围

已执行：Blender 5.2.1原创几何、真实相机渲染、UV展开、CPU手工材质烘焙、GLB/OBJ导出重载；本题附带离线检查。未执行：目标项目模型下载/推理、Gradio运行、生成纹理/深度/视频mask。reference、geometry-reference、original命名文件都是原创输入或手工参考，绝非模型结果。官方图片只在网页按来源引用。

## 步骤

### 1. 先重载现成网格确认形状

打开reference-colored.glb，检查顶点、面数和三个不对称结构；本包同时有实际烘焙参考。运行前复制一份source-mesh.glb，不允许纹理任务覆盖唯一原件。

### 2. 检查参考图是否属于同一物件

front/left/back是同一原创场景的真实三视图。比对天线、电池和足部颜色，避免把三种不同商品当成“多视图风格参考”后要求模型保证一致。

### 3. 按官方Paint示例准备独立纹理管线

示例从hy3dgen.texgen导入Hunyuan3DPaintPipeline，加载2.0的paint-v2-0-turbo子目录。纹理依赖和custom rasterizer需按官方环境编译，形状模型能跑不等于纹理环境已可用。

### 4. 把现成mesh与参考图传给Paint

参照run-hunyuan-task.py的paint分支，trimesh加载source-mesh.glb，再把参考图列表传给pipeline(mesh,image=images)。此步不调用shape管线；若输入mesh是Scene先按真实版本处理，不能默默丢掉其他对象。

### 5. 实际导出后核对几何是否改变

将真实结果另存actual-painted.glb，比较输入与输出的结构、面数和尺度；记录管线对网格的实际处理。不要仅根据“Paint”这个名字就声称顶点逐字节不变。

### 6. 旋转检查接缝与纹理遗漏

按正侧背三个角度看边界，尤其电池、天线背侧和脚底。UV缝和灯光高光不同，固定查看器照明后再判断，记录未覆盖区域与错误细字。

### 7. 区分AI贴图与手工交换文件参考

包内reference-textured.obj/MTL/PNG是Blender实际烘焙的手工材料，验证重载与纹理文件关系；模型纹理尚未生成。两套材料不能互相更名来填满结果图。

## 命令

```bash
# 复制并保留原网格，在官方Hunyuan3D-2匹配环境运行
python run-hunyuan-task.py --repo /path/to/Hunyuan3D-2 --task paint --mesh source-mesh.glb --out actual-painted.glb
# 离线手工参考查看
python3 -m http.server 8391 --bind 127.0.0.1
```

## 参考文件

- 以“本题实际文件”列表为准：original-toy.png或front.png/views为Blender原创输入。
- 若本包含reference-colored.glb：它是手工材质参考。
- 若本包含reference-textured.obj/MTL/PNG：它们是Blender真实UV/烘焙交换文件。
- 若本包含geometry-reference-depth.npy/PLY：它们是原创场景已知几何，非深度模型预测。
- runtime.json：目标模型初始not-executed。
- verification.json / blender-reload.json：文件及重载证据，不是模型生成证据。

## 官方依据

https://github.com/Tencent-Hunyuan/Hunyuan3D-2
https://github.com/Tencent-Hunyuan/Hunyuan3D-2/blob/main/examples/fast_texture_gen_multiview.py

## 本题实际文件

- `back.png`
- `blender-reload.json`
- `cameras.json`
- `clay-back.png`
- `clay-front.png`
- `commands.md`
- `exchange-reload.json`
- `front.png`
- `helper-checks.json`
- `left.png`
- `original-toy.png`
- `reference-camera-scene.glb`
- `reference-clay.glb`
- `reference-colored.glb`
- `reference-texture.png`
- `reference-textured.glb`
- `reference-textured.mtl`
- `reference-textured.obj`
- `reference-vertexcolor.glb`
- `review.csv`
- `run-hunyuan-task.py`
- `runtime.json`
- `source-mesh.glb`
- `verify.py`
- `viewer.html`
- `viewer.js`
- `views/view-00.png`
- `views/view-01.png`
- `views/view-02.png`
- `views/view-03.png`
- `views/view-04.png`
- `views/view-05.png`

模型命令仅供在你准备好的官方环境执行；from_pretrained类入口首次运行可能拉取大权重，本轮没有执行。