blender-image-to-3d

Blender 图像转 3D

通过逐步通过各阶段的门槛，将一张或多张参考图转化为最终交付的游戏资产。 每道门槛都必须通过渲染证据来验证：从与参考图相同的相机视角，以游戏内像素尺寸进行对比，绝不能只看视口并觉得“好像没问题”就算通过。这条工作流中最常见的无用功，是在比例错误的基础上增加细节，因此轮廓通过检查之前，不添加任何细节。

这里的“完美”有明确标准：通过 references/delivery-and-acceptance.md 中的验收清单；对比图表中没有超出该阶段容差的测量偏差；且参考图没有展示的每个尺寸或侧面都标注为推断所得。如果单张图迫使你进行推断，就要明确说明；不要把猜测的背面当作事实呈现。

运行环境

• Blender 4.2 或更高版本（已通过 5.2 测试），以无头模式运行：blender --background --python <script> -- <args>。 Blender 5.x 更改了这些构建脚本涉及的若干 API；references/blender-5-notes.md 列出了相关变更，以及运行时、烘焙和审查方面的经验。 按以下顺序确定一次 Blender 可执行文件：$BLENDER_BIN、PATH 中的 blender，然后是 /Applications/Blender.app/Contents/MacOS/Blender。Workbench 渲染在 macOS 或 Windows 上无需 GPU；在没有 GPU 的无头 Linux 机器上，运行 review_render.py 时传入 --engine cycles 进行审查。
• 可选：通过 MCP 服务（execute-Python 工具）连接正在运行的 Blender 会话，便于检查。即便如此，也应通过编号脚本构建并保存到同一个主文件，以保持构建过程可复现。在实时会话中，可通过 exec(open(path).read()) 执行脚本并调用其函数，而不是使用命令行。
• 所有建模均以 bpy 代码写入 <asset>/build/NN_<phase>.py，这些文件复制自 assets/build_template.py。每个脚本都会打开主文件、删除其负责的内容、重新构建并保存。可安全地重新运行任意阶段。常量以米为单位，并附有注释，注明其来源参考视图；或标注为 # inferred。
• 技能脚本（均支持 -- --help）：

脚本	用途
scripts/init_master.py	主 .blend 文件：单位、集合、校准代理、按真实比例设置的参考平面、游戏相机
scripts/review_render.py	从固定视角、与参考图匹配的相机和游戏内像素尺寸进行黏土、轮廓、线框、棋盘格和材质渲染；转台渲染、姿势帧
scripts/compose_review.py	生成对比图表（参考图、渲染图、叠加图、游戏内尺寸条带），并计算轮廓 IoU 和宽度轮廓数值；使用 Pillow 的纯 Python 脚本
scripts/world_gate.py	针对正交参考视图计算世界坐标对齐的轮廓 IoU：相机覆盖参考遮罩精确的世界窗口，因此比例和位置误差都会计入
scripts/validate.py	拓扑、变换、UV、权重、骨架、插槽、碰撞体、命名、三角形预算；失败时退出码为 1
scripts/bake_maps.py	从 HIGH 烘焙法线和 AO 到 LOW，并烘焙底色、粗糙度、金属度；重建交付材质
scripts/export_delivery.py	导出 GLB/FBX，并生成 asset-manifest.json 和 animation-contract.json
scripts/roundtrip.py	将导出文件导入空白 Blender，报告导入内容并渲染检查图

进入 Phase 0 前，请阅读 references/categories.md，了解资产所属类别。进入 Phase 6 前，请阅读 references/rigging-animation.md；进入 Phases 1、5 和 9 前，请阅读 references/delivery-and-acceptance.md。如果脚本在 5.x API 上运行失败，或准备进行长时间渲染和烘焙，请阅读 references/blender-5-notes.md。

阶段结束时使用的门控协议

1. 使用 review_render.py 和 --ref-cam AZ EL LENS（在阶段 0 中估算），再加上 front,side,threequarter，并采用阶段要求的模式；--gameplay-px 设置为主体在游戏中的屏幕高度 （默认值为 128）。
2. 使用 compose_review.py --measure 对照与相机匹配的参考视图。查看对照表和数值。观察 图像；数值能捕捉到肉眼容易忽略的偏差。compose_review 会按包围盒对齐两个剪影，因此无法发现模型 过矮或偏离轴线。对于正交视图表，还要对清理后的参考遮罩运行 world_gate.py（擦除标签、标尺、地面线以及模型不包含的所有内容），并确保数值符合该阶段的容差。当参考图自身的视图不一致时（例如，披风在正面视图中比背面视图更宽），应记录冲突以及各视图的上限，作为偏差，而不是试图同时满足两者。
3. 将不匹配之处写成测量结果，而非形容词：“头部过高 12%”“轴距短 0.3 m”“band 4 宽度 +0.06”。修正构建脚本中的常量，重新运行该阶段并重新渲染。重复此过程，直到每项不匹配都在该阶段的容差范围内。
4. 向用户展示对照表、剩余偏差以及推断内容。获得批准后继续。如果用户表示无需询问，则在达到容差后继续，并将对照表保存在 review/ 中供其查看。如果用户在实时视口中审阅，则每次重新构建后都要在其中重新加载主文件：只为渲染而隐藏的内容（例如服装下面的人体模型）仍会显示在用户的视图中。

容差：灰盒阶段的 IoU 为 0.85，且每条带的宽度与参考值相差不超过 0.05（造型阶段分别为 0.90 和 0.03）；比例方面，简报中列出的测量项在灰盒阶段应控制在 5% 以内，在造型阶段应控制在 2% 以内；材质验收标准为：在材质转台的移动光照下，以及以游戏尺寸显示的灰度图中，各材质角色均能正确呈现。

阶段 0：阅读参考资料，撰写简报

在操作 Blender 前，先查看所有提供的图像。按以下确切结构编写 <asset>/asset-brief.md：

ASSET      prefix and name (CH_, CR_, AR_, VH_, PR_, WP_, EN_)
CATEGORY   character | creature | architecture | vehicle | prop | weapon | environment, plus subtype (biped, quadruped, winged, wheeled, tracked, modular kit, hinged prop)
VIEWS      per image: view type (front, side, back, top, three-quarter, concept), estimated camera azimuth, elevation, lens (0 = orthographic), how much of the image height the subject fills, where the ground line sits
SCALE      real size along each axis with the evidence (human height, door, wheel, brick course, weapon grip); state the number used
PROPORTIONS 8 to 15 ratios measured in the image that the blockout gate will check (head heights, shoulder width to height, wheelbase to length, storey height to width)
PARTS      every part in construction and overlap order; for each: separate object yes/no, rigid/deforming/simulated, attaches to, moves about (pivot)
SILHOUETTE the 3 to 5 features that make it read at gameplay size
MATERIALS  per part: role (skin, scales, worn leather, painted metal, carved stone, glass), colour, roughness range, wear pattern
ARTICULATION rig family, joints or pivots, sockets needed, animation needs (none / idle only / full library)
INFERRED   every side, dimension or part the images do not show and the prior used to fill it
TARGET     engine, export format, budget tier from the table, game camera (elevation, distance, lens), subject height in pixels at typical gameplay distance

只询问用户图像无法提供的信息：目标引擎和格式、没有比例线索时的实际尺寸、预算档位、是否需要绑定和动画，以及游戏摄像机。提供以下默认值；如果用户表示直接开始，就采用这些默认值：1 个单位 = 1 米，Blender 中 Z 轴朝上、主体朝 -Y，导出 GLB，采用预算表中的标准档位，使用 50 mm 的俯视四分之三角度摄像机，主体高度为 128 px，仅在类别需要变形时绑定，除非用户提出要求，否则不制作动画。

第一阶段开始前，将每张参考图都以描述性名称保存为 <asset>/ref/ 中的文件：脚本会从磁盘加载参考图，而粘贴到对话中的图像会作为临时文件传入，因此要先将它们复制到该目录。

多图参考：一次请求中可以包含任意数量的图像。标注哪些视图是正交图纸（据此测量），哪些是透视概念图（仅供参考轮廓和细节，绝不能用于确定比例）。图像之间有冲突时：尺寸以正交图纸为准，表面细节以概念图为准；说明各处分别采用了哪张图。单张图像也可能包含多个视图（例如带有正面、侧面和背面面板及细节标注的转面图或模型表）：为每个面板单独添加一个 VIEWS 条目，并注明其像素框；将正交面板裁剪成单独的文件，使其共用一个比例和地面线（ref/front.png、ref/side.png、ref/back.png），供 init_master.py 和关卡检查使用；表面细节则参考标注。对于照片：根据透视汇聚估算镜头焦距（长焦产品照使用长焦镜头，手机照片使用 24 到 35 mm），并在 --ref-cam 中匹配。

对于涵盖多个资产的请求，先按类别各选一个资产完成所有阶段（一名角色、一只生物、一件套件、一辆载具），并取得用户批准，然后再将经验证的比例、绑定、材质和导出规则应用到其余资产。每种角色仍需有自己的表单和动作；共用绑定骨架系列不代表共用比例。

阶段 1：校准和主文件

在开始建模前确定标准单位，并始终保持一致：1 个单位 = 1 米，Z 轴朝上，-Y 朝前，原点位于接地点（载具取地面中心，套件取网格角点）。如果目标游戏使用其他逻辑单位，请记录换算系数，并在以下两种做法中选择其一：换算所有相关数值（移动速度、触及距离、单元格尺寸、碰撞体、摄像机偏移）；或仅在渲染边界进行映射。绝不能只缩小资产，却让游戏度量继续沿用旧单位。

此文件中的命令以一名身高 1.85 m 的骑士（CH_Knight，Unity）为示例；所有特定于资产的数值（名称、高度、摄像机、预算、引擎、推断出的列表）均从简报中获取。

$BLENDER_BIN --background --python scripts/init_master.py -- \
  --out CH_Knight/CH_Knight_master.blend --name CH_Knight --height 1.85 \
  --ref-front ref/front.png --ref-right ref/side.png --ref-extra ref/concept.png \
  --subject-frac 0.88 --ground-frac 0.04 --cell 2.0 --cam-elev 50 --cam-az 30 --cam-dist 12 --cam-lens 50

此操作会创建集合（REF、HIGH、LOW、RIG_CTRL、RIG_DEF、COLLISION、SOCKETS、EXPORT）、带米制刻度的目标高度标尺、网格单元、门洞净空、碰撞胶囊体、游戏摄像机，以及按实际比例放置且地面线位于 z = 0 的参考图立面。每个资产都必须经过此校准；如果英雄角色、敌人和门洞从未在同一文件中以相同比例出现，它们在引擎中就无法彼此匹配。

命名规范见 references/delivery-and-acceptance.md：CH_Knight_Body_LOD0、DEF-upper_arm.L、SOCKET_hand.R、COL_torso、CUT_window。最终交付的任何内容中都不得出现 .001 名称。

阶段 2：白模与剪影验收关卡

根据模板构建 build/02_blockout.py。只制作主体体块：躯干、头部、骨盆和四肢使用简单体块；载具使用车身外壳、车轮和驾驶舱；套件组件使用地板、墙壁、屋顶和开口。手、脚、下颌、角、翅膀、车门、炮塔和其他附加部件从一开始就作为独立的粗模对象。此时放置关节中心和枢轴，位置应符合简报中的测量值，因为后续所有内容都依赖它们。

检查承重和平衡：确保脚和臀部能支撑体重，为奔跑者设置向前的驱动线，为四足动物设置胸廓和骨盆，设置能够支撑预期动作的颈部和翼根，并让车轮位于载具重心下方。将服装、护甲、外覆板和面板作为独立体块添加。检查武器的攻击范围、手部空间、车门开启范围，以及资产在极限姿势或状态下（攻击、蹲伏、转身、方向盘打满、车门打开）的剪影。

在黏土和剪影模式下验收，使用 LOW 集合，并运行一次 --show-ref，根据标尺确认比例。类别必须能在没有纹理、粒子或标签的情况下从游戏摄像机视角辨认。对于多资产制作，以相对比例渲染灰盒阵列，检查它们的角色差异是否体现在肩宽、头部形状、姿势和站姿上，而不只是颜色。

$BLENDER_BIN --background --python scripts/review_render.py -- --blend CH_Knight/CH_Knight_master.blend \
  --out CH_Knight/review/02_blockout --collections LOW --views front,side,threequarter \
  --ref-cam 35 12 50 --mode clay --gameplay-px 128
python scripts/compose_review.py --ref ref/front.png --render CH_Knight/review/02_blockout/clay_front.png \
  --out CH_Knight/review/02_blockout/compare_front.png --measure --gameplay-px 128

阶段 3：形体

build/03_forms.py。制作顺序：先做主要解剖结构或主体体块，再做次级形体（布料体块、护甲结构、面板分割、装饰线条），最后才做三级细节（褶皱、损伤、铆钉、毛孔、织纹），并且只做到能在纹理分辨率和游戏摄像机视角下保留下来的尺度。大面积随机噪声会掩盖形体，并在远处闪烁。

有机体：在 HIGH 中将白模合并为一个融合底模（体素重构，体素尺寸约为高度的 1/200），并用 push 塑形；或者保留皮肤链底模，细化其半径和关节位置。 硬表面：通过放样、挤出、旋转和切割来制作，并加入真实的面板间隙、板材厚度和能捕捉光线的倒角。按照真实的叠放顺序建模分层部件。眼睛、牙齿、爪子、角、玻璃、灯、薄膜等需要独立着色、变形或活动的部件应保持分离；仅在导出副本中合并。

即使服装或面板会覆盖，也要在主文件中保留完整的底层身体或车体；在导出副本上制作覆盖裁切，并针对每种装备组合检查是否有穿孔。

角色：references/categories.md 第 2 节介绍了贴合校准蓝图的面部、手部、颈部连接、贴合底层服装的护甲，以及发束碰撞体和着色。查看颈部、手部和每处护甲重叠部位的多个角度特写，并显示视口中的所有内容；使用网格重叠测试检查间隙。

验收：从参考摄像机和所有固定视角检查黏土效果与形体容差，并进行一次 --turntable 8 黏土检查。游戏尺寸下的剪影必须仍与阶段 2 一致；如果形体改变了剪影，就修正形体，而不是参考图。

阶段 4：拓扑

build/04_topology.py 会为已批准的造型生成低模交付网格。在需要处理轮廓、关节弯曲、面部动作、布料褶皱、面板边缘或材质边界的位置布置拓扑。对雕刻模型进行均匀重构并不等于变形拓扑（Blender 重拓扑说明：https://docs.blender.org/manual/en/latest/modeling/meshes/retopology.html）。实用流程：先创建干净的基础笼，在每个关节处布置环线（Subdivision 1 下的链式蒙皮网格已包含这些环线），然后使用 Shrinkwrap 贴合高模造型，进行 Subdivision 1，再编辑关节和褶皱处的环线。刚性部件和碎石可以使用可控的 Decimate；主角的肩部、手部、面部、铰链和需要模拟的布料则应精心布置环线。

源模型使用四边面，交付时进行三角化；烘焙前锁定三角化，避免之后阴影发生变化。运行清理流程：合并重合点、移除游离网格岛和零面积面、修正翻转法线、清除重叠的内部壳体。布料片、发片卡片和贴花可以有开放边界；碰撞代理模型必须封闭。现在使用 lod_copy 创建 LOD1 和 LOD2，并手动修正轮廓，保留头部、肩部、武器、车轮和门口的轮廓。

验收门槛：使用预算档位对应的三角面数运行 validate.py（退出码为 0，且需说明警告原因）；以线框模式渲染低模，并与阶段 3 的渲染进行纯色对比，确认轮廓没有损失。

$BLENDER_BIN --background --python scripts/validate.py -- --blend CH_Knight/CH_Knight_master.blend \
  --collections LOW,COLLISION,SOCKETS --out CH_Knight/review/04_validate.json --budget-tris 60000 --require-uv

阶段 5：UV、烘焙、材质

build/05_materials.py。根据结构和可见性，在合适的位置设置缝线；为面部、视觉焦点服装和主角表面留出专属空间；为重复边缘和大面积表面使用装饰条和平铺纹理；为小型道具使用图集；同一资产系列保持统一的纹素密度。在关节、下摆、面部和握持处使用检查纹理渲染检查失真。检查最低实用 MIP 层级下的填充边距。

在 Blender 中创作原创材质（程序化或手绘），从任务说明中指定的材质类别开始：皮肤、干燥骨骼、机织布料、磨损皮革、腐蚀金属、涂漆钢材、雕刻石材、玻璃。粗糙度范围应符合材质类别；边缘磨损应体现结构和接触痕迹，而不是给每条边缘都描一圈白边；基础颜色中不得烘焙带方向性的光照。然后烘焙可移植材质集，并重建交付材质：

$BLENDER_BIN --background --python scripts/bake_maps.py -- --blend CH_Knight/CH_Knight_master.blend \
  --low LOW --high HIGH --res 2048 --maps normal,ao,basecolor,roughness,metallic \
  --out CH_Knight/textures --extrusion 0.02 --ray-dist 0.05 --margin 16 --samples 64 \
  --match-by-name --rebuild-material --save CH_Knight/CH_Knight_baked.blend

当投射会延伸至相邻部件时，按命名组烘焙（例如牙齿、分层服装）；使用 --exclude-sources 将透明壳体（角膜、面罩、玻璃）排除在源对象之外。烘焙 LOD0；LOD1 和 LOD2 重用其材质和贴图（它们由 lod_copy 生成，使用相同的 UV 布局）。只有在某个 LOD 使用独立 UV 时才传入 --all-lods。在清单中记录每张贴图的色彩空间、法线贴图绿色通道约定，以及任何通道打包信息。

验收门槛：使用 --turntable 12 进行材质模式渲染（让光线在表面移动），按游戏内显示尺寸进行灰度对比，并确保关节处的检查纹理渲染无异常。在法线贴图转台渲染中检查硬边和 UV 缝线。

阶段 6：关节绑定

仅适用于没有活动部件的静态道具和套件部件时才跳过。否则使用 build/06_rig.py：根据 references/rigging-animation.md 中的绑定系列，在 RIG_DEF 中创建变形骨架，在 RIG_CTRL 中创建控制器；为每个铰链、车轮、门和炮塔设置真实枢轴；在 SOCKETS 中创建插槽，轴向约定为附件前方 +Y、上方 +Z。将每个变形部件绑定到同一骨架，规范化权重，每个顶点最多 4 个影响骨骼作为交付目标，刚性装甲绑定到单根骨骼。绑定前应用缩放和旋转；切勿将 Armature 修改器应用为清理步骤。

验收门槛：制作极限姿势表（对参考文件列出的每个姿势运行 review_render.py --action <pose_action> --frame N），确保所有独立部件同时可见；validate.py 显示没有未加权或影响骨骼过多的顶点；使用真实附件在至少一个姿势中测试每个插槽。

Phase 7: 次级运动

仅适用于需求说明标记为需要模拟或具有次级运动的服装、链条、尾巴、翅膀、线缆、履带或天线。遵循 references/rigging-animation.md 第 6 节：将渲染、模拟和碰撞表示分开；附件固定区域需留出真实间隙；每个顶点的运动只能有一个控制者；提供骨骼链回退方案。验收标准：极限姿势的渲染中，身体或武器不会发生穿插；仅使用回退骨骼链时，服装仍能呈现出相同的效果。

Phase 8: 动画

仅在有需求时执行。使用 build/08_anim.py 或实时会话。创建命名 Action，并设置明确的范围、循环标记和用于事件的姿势标记；为原地移动标注速度；为上半身图层指定参考姿势和遮罩；交付时将 IK 烘焙到变形骨架，并保留未烘焙的主版本。验收标准：将每个片段渲染成不带转台、使用游戏摄像机视角的短序列；检查循环接缝处是否存在根节点漂移或跳变；根据 animation-contract.json 核对事件时间。

Phase 9: 导出与往返验证

导出明确选定的对象（LOW、RIG_DEF、SOCKETS、COLLISION）及清单，然后将其导入一个空白的 Blender，并与清单进行比对。REF、HIGH 或 RIG_CTRL 中的任何内容都不得交付。

$BLENDER_BIN --background --python scripts/export_delivery.py -- --blend CH_Knight/CH_Knight_baked.blend \
  --out CH_Knight/exports --name CH_Knight --format GLB --split-lods \
  --inferred "back of cloak from symmetry, sole tread generic" --engine unity
$BLENDER_BIN --background --python scripts/roundtrip.py -- --file CH_Knight/exports/CH_Knight.glb \
  --out CH_Knight/review/09_roundtrip --expect-height 1.85

验收标准：往返验证退出码为 0（各 LOD 的三角形数量、骨骼名称、片段长度和图像均与清单一致；高度误差在 1% 以内；没有任何内容低于地平面），且往返验证的灰模渲染与 Phase 3 的灰模渲染相符。然后，如果有目标引擎的干净项目可用，则将资源导入其中，并使用实际武器或服装组合播放每个片段。

Phase 10: 验收与交付

按照 references/delivery-and-acceptance.md 第 4 节的清单执行。生成 review/final/：包含参考摄像机和固定视角的对比图、游戏尺寸的灰度条、材质转台图、极限姿势图、validate.json 和 roundtrip.json。按以下顺序向用户报告：符合之处、尚存的实测偏差、参考资料未覆盖而自行推断的所有内容、相对于等级的预算使用情况，以及交付文件的准确清单。若测量结果不符，切勿声称资源与参考一致。

工作规则

• 先测量，再建模。每个常量都必须来自需求说明，或标记为推断值。
• 先剪影，再造型；先造型，再细节；先拓扑，再贴图；先绑定，再制作动画。
• 每个验收节点都要提供渲染证据；视口画面不算证据。
• 一个文件，一种比例：每个资源都必须通过带标尺的校准文件。
• 将独立运动、着色或模拟的部分分开；仅在导出副本中合并。
• 保持主版本无损；在交付副本上应用修改器。
• 切勿为了适配期望不同骨架的加载器而重命名导出内容；应提供映射。
• 明确说明参考资料中不可见的部分。清单中猜测的背面就是猜测。