polywright-references 是做什么的？
参考素材决定了3D结果的绝大部分：图像转3D模型会复制输入的灯光、透视和错误；建模师或bpy脚本需要尺寸和视图。首先收集或生成它们，放入资产的 refs/ 目录，并用 pw.py manifest --add-source 记录每个文件（生成的素材需注明模型名称和种子）。
回到中心：../polywright/SKILL.md。提示模板与检查清单：references/reference-kit.md。
步骤1：确定模型所需参考
| 模型类型 | 收集（真实） | 生成（想象或缺失） |
|---|---|---|
| 真实物体 | 从六个侧面拍摄的照片，画面中需包含尺子；特写照片；真实尺寸（制造商的参数表、维基百科、卷尺测量） | 仅在照片质量差时进行正交清理 |
| 车辆、产品、家具 | 蓝图或CAD图纸（检查一个已知尺寸）、制造商尺寸 | 以技术绘图风格生成正面、侧面、顶面视图 |
| 建筑 | 占地面积（OSM）、高度或楼层数、每个面的照片、屋顶形状 | 每个面的立面图、屋顶平面图 |
| 真实地点 | 地图截图、高程数据、航拍照片、地标地面照片 | 无：地点来自数据（polywright-capture） |
| 想象的道具 | 风格参考 | 一张三分之二侧面主图，然后正面/左面/背面/右面等比例视图 |
| 角色或生物 | 风格和服装参考 | 转圈漫走：正面、侧面、背面、三分之二侧面、A-pose、身高比例尺、纯色背景 |
| 表面（墙壁、地面、地形） | 材质的照片，需平整且光照均匀 | 无缝可平铺的反照率贴图，然后生成其他贴图（步骤4） |
始终添加比例参考：一个已知尺寸、一个1.8米高的人影轮廓、或参考图上标注的身高比例尺。
历史研究包（由historywright插件创建的文件夹，包含 answer.md、refs/index.json 和 anachronism.md）本身就是一个有效的资产文件夹：从中开始，不要重复搜索。读取 refs/index.json：每个参考都带有对象本身的日期、地点、机构、登录号和许可证。只使用 object_date 符合项目时间背景的参考。若参考标记有 nc: true，则不能用于商业模型。在生成网格之前，必须对照 anachronism.md 检查每个生成的视图。
步骤2：生成视图（关键规则）
要求图像工具满足以下条件：单个物体、居中、约占画面三分之二；纯白色或浅灰色背景；平坦、均匀、无阴影的灯光；无强烈透视（长焦镜头或正交视角效果）；分辨率1024像素或更高；无文字。角色以放松的A-pose站立（手臂向下30至45度，双腿略微分开）：T-pose会扭曲比例，而动态姿势在生成器和骨架系统中容易失败。各类参考的提示模板在kit中。
为从单张图像生成一致的额外视图，使用带有广角适配器的图像编辑模型（如Qwen Image Edit配合Multiple Angles LoRA，2025-2026年）比单独提示每个视图更能保持一致性；但需注意颜色漂移，并将每个视图的颜色与正面进行匹配。检查每个生成的视图是否与正面一致：相同的比例、相同数量的手臂、相同的物品，没有任何部分被重新指向。放弃不一致的视图；一个错误的背面视图比没有更糟。根据照片像素（中位数色调、饱和度、明度）命名真实物体的颜色，而不是用单词描述：编辑模型会遵循单词而非图片（L-003）。背面视图容易将正面的标记复制到背面。
针对Z-Image Turbo主机的现成工作流：references/zimage-reference.api.json（使用 {SUBJECT} 占位符；已于2026-10-11测试）。
步骤2b：设计道具的参考图来自模型
当道具是设计出来的（用文字或粉丝图纸描述的武器、工具、车辆零件），而文本提示总是只能给出一半形状时，停止提示：用bpy脚本构建它（polywright-blender配方“从文字描述生成设计道具”），并从模型渲染参考图——侧面和顶面正交视图，在平坦的中灰色背景上，当GPU忙时使用CPU上的Cycles渲染器。模型是精确的，每次修改后只需几秒即可重新渲染，并且同一个文件以后可以将道具合成到图片中（中心：“将模型合成到图片中”）。当零件以镜像对出现，或一个零件隐藏在另一个后面时，将侧面相机抬高10到15度。
步骤3：从粗模生成视图（当视图不断出现不一致时）
构建一个粗略的粗模（基本几何体，或仅生成正面网格），用 pw.py render <file> --out refs/blockout --views front,right,back,left --color clay 渲染，然后让图像编辑模型用主题的颜色和细节重绘每个灰色渲染（以渲染图作为第一参照、正面视图作为第二参照进行图像到图像的转换）。只有相机移动，因此没有任何部分会被重新指向或长出多余肢体；背面只能显示粗模暗示的内容。将重绘后的整套图像输入多视角生成。
步骤4：纹理与材质
- 优先使用CC0材质（Poly Haven、ambientCG）而非生成材质。
- 生成可平铺纹理：要求“无缝、可平铺、俯视、平坦均匀光照”，尺寸为2的幂，然后执行
pw.py texture <img> --out refs/tex --seamless（偏移混合接缝），并查看2x2平铺效果。 - 从照片或反照率生成快速贴图：
pw.py texture <img> --out refs/tex [--convention opengl|directx]会写入从亮度导出的高度、法线和粗糙度贴图。适用于道具和地形，不适用于精确测量的材质。法线贴图：Blender、Unity、Godot、glTF、three.js、Roblox使用OpenGL（Y+）；Unreal使用DirectX（Y-）。 - 照片中烘培的光照会变成反照率中的烘培光照：在上游用平坦光照修复，或添加
--delight（消除宽梯度；尖锐的投射阴影会保留，需手动绘制去除）。法线贴图仅改变着色：轮廓保持平坦，大形状在掠射角时会破裂，因此需塑造大形，只在细节区域应用贴图。
步骤5：投入应用
- 在Blender中：将参考图像作为空白对象放置在正面、右侧和顶面视图，并按已知尺寸缩放（
pw.py render的正交渲染会报告metres_per_px）；配方在polywright-blender中。 - 用于图像转3D：正方形、填充边缘、1024像素；
pw.py gen会自动填充边缘并去除背景。在GPU运行之前判断图片质量，并确定需要在图片中修复什么而不是在网格中修复：references/images-for-3d.md。 - 在展板（PureRef 2.1）上供人类使用：按视图分组，在展板上标注尺寸。
维护
常青单元，层级 fast。配套文件：RESEARCH.md、CHANGELOG.md、LEARNINGS.md、TESTS.md（包含 evals/evals.json）、MAINTENANCE.md，状态保存在 evergreen.json 中。每次使用时读取 evergreen.json；到期时刷新。