CAD 工作室渲染

将 CAD 装配体转化为产品页面所需的内容：照片级工作室拍摄、透明抠图、旋转展示视频以及支持手机 AR 的自托管 3D 查看器。一次运行只需一条命令，所有操作均在本地完成。GPU 负责渲染；不涉及 AI 图像生成，因此像素完全基于真实几何数据。

python3 "${CLAUDE_SKILL_DIR}/scripts/studio.py" model.step --name "产品名称"

${CLAUDE_SKILL_DIR} 是此技能的文件夹（Claude Code 会自动填充）。在其他代理中，请使用此 SKILL.md 所在的文件夹。以下所有脚本路径均相对于该文件夹。

何时使用

“渲染这个 STEP 文件”、“制作产品照片/包装图来自 CAD”、“此零件的照片级渲染”
“将 3D 模型放到我们的网站上”、“使其可旋转”、“产品的 AR 视图”
“产品的透明 PNG”、“目录用的抠图”、“旋转展示视频”
3D 艺术家希望获得一个可手动完成的 Blender 场景

此技能不适用：从头开始建模（应使用 CAD 工具）、根据文本提示生成图像、或渲染非产品的场景（室内、角色等）。

安装此技能

Claude Code，终端： claude plugin install cad-studio-renders --marketplace abchiaravalle/cad-studio-renders
Claude Code，桌面应用： 让 Claude 将 https://github.com/abchiaravalle/cad-studio-renders 克隆到 ~/.claude/skills/cad-studio-renders（桌面应用和终端都读取该文件夹）。
任何其他代理： 将此文件夹放置到该代理加载 SKILL.md 文件夹的位置。

要求（先检查）

blender --version       # 4.2 或更新。如果缺失：https://www.blender.org/download/
uv --version            # 读取 CAD 文件。如果缺失：https://docs.astral.sh/uv/
ffmpeg -version         # 仅 --turntable 视频需要

如果 Blender 已安装但不在 PATH 中，请设置 BLENDER=/path/to/blender。GPU（Apple Silicon、NVIDIA、AMD）使渲染速度提高 5-20 倍；CPU 也可用，但较慢。首次运行会将 CAD 库（~60 MB）和工作室 HDRI（24 MB，CC0）下载到 ~/.cache/cad-studio-renders/。

工作流程

在渲染任何内容之前先映射材质。 CAD 文件很少携带真实的表面处理。
```
python3 "${CLAUDE_SKILL_DIR}/scripts/studio.py" model.step --map-only
```
阅读表格。每个零件都会显示其预设和原因。以 (review me) 结尾的行是猜测。使用规则文件（下一节）修正错误项，并重新运行 --map-only，直到正确。
预览（约 10 秒）：--preview 渲染一张 1000 px 的草稿。在花费数分钟处理最终图之前先检查一下。检查：方向正确、零件组装完整（无漂浮物）、构图、材质。
最终渲染：去掉 --preview。默认会生成一张 2400 px 的带有背景的封面图、相同构图的无背景透明 PNG、一个可编辑的 .blend 文件以及网页嵌入包。
以完整尺寸检查输出（放大到最密集的区域）后再交付。

修复材质：规则文件

{"rules": [
  {"match": "frame|base", "preset": "powder_coat", "color": "#2b2f33"},
  {"match": "^Cover", "preset": "plastic_textured"},
  {"match": "motor", "preset": "motor_housing"},
  {"match": "logo plate", "preset": "anodised_color", "color": "#c8102e"},
  {"match": "spindle", "preset": "steel_polished", "params": {"roughness": 0.05}},
  {"match": "safety guard", "hide": true},
  {"match": "gantry", "offset_mm": [0, 0, 80]}
]}

match 是一个不区分大小写的正则表达式，针对零件名称、实例名称和装配路径进行测试。第一个匹配的规则生效。params 会覆盖任何预设值（粗糙度、金属度、涂层、各向异性、倒角、凹凸等）。offset_mm 设置零件在爆炸视图中的位置。预设位于 assets/presets/materials.json；可在此处添加新预设。

没有规则时，自动映射器按以下顺序使用：零件名称关键字（紧固件、轴承、直线导轨、滚珠丝杠、电机、橡胶、玻璃等），然后是 CAD 颜色（高饱和颜色变为漆面，共享相同颜色的零件共享表面处理），最后是尺寸。

重要选项

标志	功能说明
`--shots hero,front,side,top,iso,back,square,hero_low,detail`	相机角度（`assets/presets/shots.json`）
`--lighting studio_soft / high_key / dramatic / hdri_only`	灯光布局（`assets/presets/lighting.json`）
`--backdrop 0.42` 或 `--backdrop "#1d1f22"`	背景灰色或颜色
`--size 4000 --aspect 16:9`	输出尺寸和宽高比
`--samples 768`	更多采样 = 更清晰的高光细节，渲染时间更长
`--exposure 0.3`, `--light-scale 1.2`, `--env-scale 0.8`	亮度
`--hdri photo_studio_01` 或 `--hdri my.exr`, `--hdri-rotation 40`	反射环境
`--dof 0` / `--dof 2`	背景模糊关闭/减弱
`--bevel-scale 0`	关闭边缘圆角（圆角是让 CAD 看起来真实的关键）
`--detail-target "spindle	chuck"`配合`--shots detail`
`--no-transparent`, `--no-backdrop`, `--no-embed`, `--no-blend`	跳过某些交付物
`--clay`	灰色粘土通道（灯光/形状检查，设计评审）
`--passes`	多层 EXR：深度、法线、环境光遮蔽、雾效、Cryptomatte（对象+材质ID）
`--exploded 0.4`	爆炸视图（零件从中心推出；`offset_mm` 规则会覆盖）
`--turntable [--turntable-transparent]`	360° MP4 + WebM（可选透明）+ PNG 帧
`--up y`	如果自动检测猜错，强制指定 up 轴

输出内容

<model>_studio/
  hero.png                    16位，工作室背景上
  hero_transparent.png        16 位 RGBA，保留软接触阴影（--shadow none 可去掉）
  hero_clay.png, hero_exploded.png, hero_passes.exr       （按需生成）
  <slug>_turntable.mp4 / .webm, turntable_frames/          （按需生成）
  <slug>_scene.blend          灯光、相机、材质、背景、纹理已打包
  materials_map.json          每个零件 -> 预设 + 原因（通过 --rules 编辑并重新运行）
  manifest.json               设置、计时、文件列表（含大小和哈希）
  embed/                      自托管 3D 查看器包（见下文）

.blend 文件专为手工完成而构建。 集合：Product（每个零件一个空对象，因此零件可单独移动或动画）和 Studio（背景、灯光、相机）。每个相机都绑定到一个时间线标记，因此滚动时间线即可切换镜头。材质是普通的 Principled BSDF 节点树。边缘圆角使用倒角着色器节点，因此几何体保持精确。

嵌入包

embed/ 是完全静态的，不发出任何外部请求。它内置了 Google <model-viewer>（Apache-2.0）和 Draco 解码器。将该文件夹上传到任何位置并粘贴 snippet.html，或使用 iframe 嵌入 embed.html。包含：

assets/<slug>.glb：Draco 压缩版，材质与渲染图匹配
assets/<slug>.usdz：通过 Quick Look 实现的 iPhone/iPad AR
一张海报图像
用于反射的工作室 HDRI
index.html：一个包含复制按钮和渲染下载的演示页面

针对 WordPress、Shopify、Webflow 等平台的托管说明见 embed/README.md。

常见问题（每个都在开发中出现过）

模型侧放或倒置。 SolidWorks、Inventor、Creo 和 Fusion 默认 Y 轴向上；大多数其他软件是 Z 轴向上。转换器读取 STEP 头部进行猜测，并打印猜测结果（up axis: Y (written by Solidworks)）。如果错误，请传递 --up z（或 y, -y, x...）。
零件散开 / “意外爆炸”。 原因是装配变换被应用了两次。场景构建器现在会检查分组零件是否移动了几何体，如果会则中止。如果你编辑场景代码，请保留该检查。
平坦、假的金属感。 通常是光照问题，而不是材质：没有环境意味着金属没有东西可反射。即使在有区域光的情况下也要保持 HDRI 开启（--env-scale，不要设为 0）。
首次渲染颜色暗淡。 灯光功率会根据模型尺寸进行缩放；如果你在 lighting.json 中添加了自定义灯光，功率会按（模型半径（米））² 计算。从低值开始，使用 --preview。
材质猜测错误。 含义不明的零件名称（P-0042, ASSY_7_REV2、音译的非英文名称）会使关键字匹配失效，转而依据颜色/尺寸。这由 (review me) 标记。为这些零件编写规则。
OCP 8 破坏了读取器（TDF_LabelSequence 已移动）。CAD 读取器固定使用 cadquery-ocp-novtk<8。未经重新测试请勿取消固定。
网页模型与渲染图看起来不同。 glTF 无法承载程序化凹凸、倒角或粗糙度噪点，因此网页模型只获得基础值。这是正常现象；海报图像才是真正的渲染图。
大型装配体（>500 万三角形）：预览时使用 --quality web；最终渲染仍然可行，但需要 RAM（Blender 中每 200 万三角形约需 1 GB）。

交付前验证

以 100% 比例打开 hero PNG，检查最密集的区域：无黑色面、曲线上无刻面、无飞溅亮点（白色斑点）。
将透明 PNG 放在深色和浅色背景上检查：边缘干净，阴影仅在产品下方。
在本地托管 embed/（python3 -m http.server -d embed 8000），打开并确认模型加载、旋转且控制台无错误。如果 AR 重要，请在手机上检查。
如果 materials_map.json 中仍有 review me 行，请在交付中说明。

文件

scripts/studio.py：入口点（上述 CLI）
scripts/cad_to_glb.py：STEP/IGES/BREP 转 glTF，包含装配名称和 CAD 颜色（uv 脚本）
scripts/automap.py：零件到材质的决策（纯 Python，可单独运行）
scripts/blender_studio.py：场景、材质、灯光、相机、渲染、.blend、网页导出
scripts/package_embed.py：自托管查看器包
assets/presets/*.json：材质、灯光布局、相机镜头
examples/make_demo_model.py：构建演示台钳（原始几何，CC0）

CAD 棚拍静帧