scenario-patina-retexture

Scenario PATINA 重新贴图

概览

如果网格的材质是纯色或占位材质（例如图像转 3D 的结果或完整的立体场景），只需三步即可将其转换为采用 PBR 着色的资产：将材质归类为不同的物理表面类别，在 Scenario 上为每个类别生成一个无缝 PATINA 材质，然后将五张贴图接入 Blender 材质，同时保持顶点、面和变换不变。可选的影片会沿同一条相机路径渲染原始场景和重新贴图后的场景，并使用相同的灯光、曝光和剪辑，因此两个画面之间只有材质响应不同。影片在本地渲染，用于展示 3D 成果，绝不在 Scenario 上生成，因此此技能的输出类型仍为 3D。

PATINA 是 Scenario 上 Patina AI 的材质系列（标签 sc:texture）。此技能使用 PATINA Material，即提示词转材质的成员；扁平贴图成员（Image to Maps、Material Extract）属于 scenario-textures。使用 3D 转 3D 贴图模型为整个网格重新着色属于 scenario-3d 路线；此技能则保留对各材质的独立控制和可编辑的 Blender 着色器。Agent 自身的步骤在 MCP 上执行；随附脚本（Blender 4.2 或更新版本、带 Pillow 和 numpy 的 Python 3、ffmpeg）负责本地重复性工作，绝不会调用 Scenario。连接方式和核心流程请参阅 scenario 技能。如果此处提到的某个同系列技能不在可用技能中，请要求用户安装（npx skills add scenario-labs/skills --skill <name>）；在无人值守的情况下，根据工具架构继续操作并标记此缺失项。

快速参考

步骤	工具	备注
范围	teams_list、projects_list	源资产和生成目标可能位于不同项目中：每次调用都传入正确的一对项目
获取网格	asset_get，然后调用 asset_download	properties.materialCount、faceCount、hasUVs、dimensions；使用 curl -fL 保存
清点	在 Blender 中运行 inventory.py	写入 Before.blend 和 inventory.json：按材质统计对象数量、边界和基色
查找 PATINA	使用 search，并设置 target="models"、query="patina"、public=true	选择 PATINA Material（txt2img）；运行前先调用 model_schema_get
估价	使用 model_run 并设置 dry_run=true	编写本文档时，一套 1024x1024 的五张贴图需要 17 CU；width、height、maps、upscaleFactor 和 numOutputs 会影响价格
生成	对每个材质系列分别调用一次 model_run，并设置 wait=false	每个系列使用固定的 seed；对所有 job_id 调用一次 jobs_wait
识别贴图	对每个输出调用 asset_get	metadata.type 用于标识贴图用途；切勿依赖顺序
下载	调用 asset_download，然后运行 curl -fL	textures/<family>/<role>.png
应用	在 Blender 中运行 apply_materials.py	清单见 materials-manifest.md；会校验几何体哈希
渲染影片	调用 film.py 的 pilot、run、status	配置见 film-config.md；支持续传

材质系列

读取 inventory.json，不要读取场景。根据表面的物理材质对材质分组（灰泥、雪松、陶土、釉面陶瓷、黄铜、涂漆钢材、玻璃、帆布、沥青、植物），不同颜色变体可复用同一系列：默认情况下，着色器会将每种原始颜色作为色调叠加在 PATINA 基色上，因此一套灰泥贴图即可用于奶油色、赭色和灰色墙面。若相同颜色出现在不同表面上（例如帆布遮阳篷和涂漆标牌上的同一种绿色），则使用以对象名称前缀为键的 object_overrides 条目将其拆分。一个包含 41 种材质的立体模型需要 14 个系列；预计每个系列对应一个任务。如果网格已经建模出砖块、屋顶瓦片或木板，则提示词应描述单个元素的材质（烧制黏土、风化雪松），而不要描述其图案：结构由几何体提供，带图案的贴图会使图案重复。

每个材质系列生成一组

发现 ID 后，model_schema_get 给出的内容就是契约；以下名称是在编写时确认的。 prompt（必填，2048 个字符）用于描述平坦、光照均匀、无缝的物理表面，且不包含物体或标识。 即使只有一个条目，maps 也必须是数组（单独的字符串会被忽略）；保留默认的全部五种贴图。 width 和 height 的范围为 512 至 2048，步长为 16，默认值为 1024；tileSize（128，约 1024 px）随之调整：2048 的贴图组设为 256，否则重复窗口将无法匹配纹理。upscaleFactor 设为 2 或 4 时，只会放大预测贴图，不会放大基础纹理。tilingMode 可将重复限制在一个轴向，适用于木板或波纹板。numOutputs 最多为同一提示词返回 4 个变体，每个都单独计价。enablePromptExpansion 默认开启；提示词经过仔细设计时，将其关闭。为每个系列设置 seed，并将其保存在清单中，以便完全相同地重新生成该系列。

将 dry_run 和 wait 放在 model_run 顶层，与 model_id、team_id 和 project_id 并列；只有模型输入属于 parameters。使用 dry_run=true 为准确的载荷估价（这是费用估算，不是参数验证），确认预算（系列数量乘以费用），然后对每个系列都以 wait=false 启动任务，并使用一次 jobs_wait 等待所有任务 ID（每次最多 32 个）；若超时，则使用 pending_job_ids 再次调用，而不是通过第二次 model_run 来响应。发生传输错误时，先调用 jobs_list 再重新运行：任务通常已经成功提交。

使用默认的五种 maps 且 numOutputs 为 1 时，完成的任务在编写时会返回六个资源 ID：基础纹理（metadata.type 为 inference-txt2img-texture）以及每种贴图对应的一个资源，标签分别为 texture-albedo、texture-normal、texture-smoothness、texture-metallic 和 texture-height；numOutputs 会使整组数量相应倍增。应以通过 asset_get 读取的 metadata.type 值为准，将其映射到五种角色，切勿依赖顺序。粗糙度请求返回的标签是 smoothness；但在编写时，这些值实际表示 roughness（拉丝黄铜贴图的颜色比哑光灰色贴图更暗），因此陷阱在标签，而非数据：在修改清单中的 roughness_is_smoothness 之前，先对一个表面效果已知的系列调用 asset_display 查看该贴图；当该字段为 true 时，会反转贴图。使用 asset_download 将每种贴图（默认格式为 PNG）下载到 textures/<family>/<role>.png，并在清单的 provenance 下记录提示词、seed、任务 ID、资源 ID、范围对以及计费的 cuCost。

在 Blender 中应用

blender --background --factory-startup --python scripts/inventory.py -- model.glb work/ 会导入网格（GLB、glTF、OBJ 或 FBX）或打开 .blend，保存打包后的 work/Before.blend，并写入 work/inventory.json。编写 work/materials.json，将每个材质名称映射到一个系列，并将每个系列映射到其五种贴图（清单参考文件包含所有键和默认值），然后运行 blender --background --factory-startup work/Before.blend --python scripts/apply_materials.py -- work/materials.json。该脚本会验证清单，沿每个面的主导轴按物体尺度投影专用的 PatinaUV 图层，使 tile_span 表示每次重复对应的米数（共享网格的关联副本会先转为单用户），为每种原始材质和系列构建一个 Principled BSDF，打包图像，并断言几何哈希未发生变化。最终交付物是 .blend 文件：导出 glTF 会扁平化经过校准的着色器节点图（导出器只保留直接纹理连接），因此在导出到引擎之前先烘焙。在投入电影的渲染时间之前，先打开结果或渲染一张静帧。

对比影片

python3 scripts/film.py config.json pilot 会以半分辨率渲染每个镜头两端的画面，并为两次渲染写入 Pilot Contact.jpg 和粗略的时间估算。根据这张图修正构图和材质缺陷，然后运行 run，即可按原生分辨率渲染、续渲有效帧、将两个摄像机场景保存为可编辑的 .blend 文件，并组装和验证影片；status 会打印进度。运行文件夹根据输入、脚本和配置生成指纹，因此其中任何一项发生变化都会创建新文件夹。入口点共用 common.py 和 scene.py，而 film.py 会在 Blender 中启动 worker.py；这三个文件都不会直接运行。

根据 inventory.json 中的边界设计镜头，而不要照搬示例方案，因为其中的坐标只适用于一个资产。快速预设（EEVEE、24 个采样、半分辨率光线追踪反射并启用降噪、将 12 fps 的源素材插帧到 24 fps 以实现慢速移动）在笔记本电脑上的渲染速度约为每帧 1 秒（分辨率为 2368x1332），因此示例方案中每次渲染的 792 个源帧大约需要一刻钟；请根据 pilot_estimate.json 进行调整，并在快速运动时将 source_fps 设为 24。使用 review/Sweep Contact.jpg 进行验证；这张图以每秒 2 帧的采样率覆盖整个母版：每个镜头只看一张静帧，会漏掉在镜头中途逐渐显现的缺陷。编码器日志干净并不代表画面通过审核。

实例：为街景微缩模型重新贴图并拍摄对比视频

1. 使用用户已授权的团队／项目组合，或通过 teams_list 和 projects_list 列出选项并请用户选择。若无人值守且没有已授权的组合，请在进行限定范围的 调用前停止，并报告缺少范围信息。对微缩模型调用 asset_get（图像转 3D 的结果：41 种 材质、没有图像纹理、78K 个面），调用 asset_download，然后执行 curl -fL -o work/street.glb "<url>"。
2. 使用 inventory.py 盘点；将 41 种材质归入 plaster、cedar、terracotta、 ceramic、brass、steel、glass、canvas、asphalt 和 leaf 等类别，并设置 覆盖规则，将遮阳篷对象指定为 canvas。
3. 搜索 PATINA，然后对返回的 PATINA Material id 调用 model_schema_get；每个会话都要重新发现。
4. 对确切的类别载荷调用 model_run，并在顶层设置 dry_run=true。创作时，每个类别需要 17 CU， 十四个类别共需 238 CU；请使用当前估算值。在已授权预算内继续，或请用户批准总额。若无人值守且 授权预算不足，请返回估算值，并在开始生成前停止。
5. 调用十四次 model_run，并在顶层设置 wait=false；提示词示例："aged lime plaster wall, fine mineral grain, flat, evenly lit, seamless"，每个类别固定使用一个 seed；然后调用一次 jobs_wait，传入全部十四个 id，直到每一行都显示完成。
6. 对每个输出调用 asset_get 以读取 metadata.type；调用 asset_display 查看标注了平滑度的 石膏贴图，以确认极性；调用 asset_download，并使用 curl -fL 将每张贴图下载到 textures/<family>/。
7. 编写 materials.json（每个类别的粗糙度范围、已确认的 roughness_is_smoothness、 包含任务 id 和成本的 provenance），然后运行 apply_materials.py；打开一次 PATINA.blend。
8. 复制 example-config.json，根据盘点边界调整镜头构图，运行 film.py 的 pilot 模式，检查后再运行 run；交付母版、分享副本、两个渲染过程和两个可编辑 场景，并注明所用的插值方式。
9. 可选：按照 scenario 技能的分段上传流程操作：调用 upload_asset，传入 kind: "video"、file_name、content_type: "video/mp4" 和以字节为单位的 file_size（省略 data），将每个分段 PUT 到其返回的 URL，然后调用 upload_asset_complete，传入返回的 upload_id 和相同的范围信息。只有在完成操作返回视频资源 id 后，才将视频与源文件及贴图 一起归档到集合中（collection_create，然后调用 collection_add_assets：目录工具需通过 scenario_tool_execute_write 运行，并将参数放在 parameters 下）。

常见错误

• 按位置或仅凭 source 字段映射输出：请读取 metadata.type，并在反转前确认平滑度标签的极性。
• 在已建模出砖块、瓷砖或木板的网格上提示生成这些图案：图案会重复叠加。
• 用 PATINA 提示词生成标牌、物体或灯光：它生成的是材质，而不是场景。
• 因 jobs_wait 超时或 model_run 引发传输错误而重新生成某个类别：请用 pending_job_ids 再次调用，或先调用 jobs_list。
• 未先运行试拍就开始完整影片渲染，或仅凭每个镜头的一张静帧就批准成片，而未检查 2 fps 扫描表。
• 在运行过程中编辑配置或脚本并期望渲染续跑：指纹已改变，因此会从头开始。
• 将 PATINA id 或 17 CU 数值写死：请通过 search 重新发现，并通过 dry_run 重新估价。