blender-compositing-nodes

Blender 合成节点专家

概述

此技能为 Blender 5.x 合成器节点提供专家指导，涵盖合成管线设计、编写 Python 脚本来构建合成器节点树、组合和处理渲染通道、调色、抠像以及配置多层输出。参考文件包含完整的节点列表和 Python API 模式。

MCP 优先方案

优先使用官方 Blender MCP Server（Blender Lab，Blender 5.1+）来构建合成树、调整通道，以及在运行中的 Blender 会话中直接预览渲染结果。仅当 MCP 服务未连接时，才改用输出 Python 脚本。

**检测：**会话开始时，查找名称与 execute_blender_code、get_objects_summary 或 search_api_docs 匹配的工具——这些工具属于官方 blender-mcp 服务。只要其中任意一个存在，即表示 MCP 可用。

此技能使用的工具：

• execute_blender_code — 在实时会话中运行 bpy Python（主要操作）
• get_objects_summary、get_object_detail_summary — 修改前检查场景状态
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — 清点文件内容
• search_api_docs、get_python_api_docs、search_manual_docs — 调用 API／运算符前确认名称是否正确
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — 验证视觉效果
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — 操作 UI，使更改可见
• render_thumbnail_to_path、render_viewport_to_path — 获取快速视觉反馈

**工作流：**使用 get_* / search_* 工具检查 → 通过 execute_blender_code 修改 → 使用截图或摘要工具验证。代码块应保持简短且幂等，以便快速定位故障。

设置说明：参见 docs/blender-mcp-setup.md。

任务决策树

• “为 X 设置合成” -> 设计节点树，然后生成 Python 代码（参见“合成方案”）
• “对我的渲染进行降噪” -> 参见“降噪”方案
• “为我的渲染调色” -> 参见“调色”方案
• “抠出绿幕” -> 参见“抠像”方案
• “添加眩光／泛光” -> 参见“眩光”方案
• “分离渲染通道” -> 参见“渲染通道分离”方案
• “保存为多层 EXR” -> 参见“文件输出”方案
• “哪个合成器节点可以实现 X？” -> 查阅 references/node_reference.md
• “编写合成器节点树脚本” -> 查阅 references/python_api.md，了解 API 模式

生成合成器节点树

通过 Python 创建合成器设置时：

1. 阅读 references/python_api.md，了解正确的 API 模式和节点类型名称
2. 按照以下模式组织脚本：
   • 在场景中启用合成器：scene.use_nodes = True
   • 访问合成器节点树：tree = scene.node_tree
   • 清除默认节点
   • 使用正确的类型字符串添加所有节点
   • 从左到右放置节点（x 间距约 300，y 间距约 200）
   • 设置节点输入的默认值
   • 创建所有节点连接
   • 在视图层中启用所需的渲染通道
3. 使用 Frame 节点将复杂设置整理为逻辑分区

节点类型字符串约定

• 大多数合成器节点：CompositorNode<PascalCaseName>（例如：CompositorNodeRLayers、CompositorNodeComposite）
• 不确定准确的类型字符串时，请查阅 references/python_api.md

合成方案

降噪

1. 渲染层 → 降噪节点 → 合成
2. 连接：Image → Image、Denoising Normal → Normal、Denoising Albedo → Albedo
3. 启用降噪数据通道：view_layer.use_pass_denoising_normal = True、view_layer.use_pass_denoising_albedo = True
4. 使用内置的降噪节点（OpenImageDenoise），以获得最佳质量
5. 对于 Cycles，优先使用内置渲染降噪器（scene.cycles.use_denoising = True），以简化设置

色彩分级

1. Render Layers → Color Balance（Lift/Gamma/Gain 或 Offset/Power/Slope）→ Composite
2. 添加 Hue/Saturation/Value 来调整饱和度
3. 添加 Color Curves（RGB Curves），精细控制色调曲线
4. 节点链：Render Layers → Bright/Contrast → Color Balance → Hue Sat → Curves → Composite
5. 使用 Split Viewer 对比处理前后的效果

键控（绿幕／蓝幕）

1. Image/Movie Clip → Keying 节点 → Composite
2. 将 Key Color 设置为屏幕颜色（使用吸管）
3. 调整：Pre Blur、Screen Balance、Clip Black/White、Despill Factor/Balance
4. 对于较难处理的键控：Image → Keying Screen → Keying 节点
5. 添加 Dilate/Erode 清理遮罩边缘
6. 在遮罩上添加 Blur（Gaussian），使边缘柔和
7. 合成：Set Alpha → Alpha Over（将前景叠加到背景底图上）

光晕（Bloom／条纹／雾光）

1. Render Layers → Glare → Composite
2. 光晕类型：'BLOOM'、'STREAKS'、'FOG_GLOW'、'GHOSTS'
3. 关键设置：Threshold（值越低，光晕越多）、Quality（最终渲染时设为 High）、Mix（混合量）
4. 若要选择性添加 Bloom：先使用 Color Ramp 或 Math（> threshold）分离高光

景深（后期处理）

1. Render Layers → Defocus 节点 → Composite
2. 将 Z 通道连接到 Z 输入（启用 Z 通道：view_layer.use_pass_z = True）
3. 设置 f-Stop、Max Blur、Threshold
4. 对 Cycles，优先使用相机景深，而非后期处理 Defocus（质量更好）
5. 对 EEVEE，建议使用相机景深，而非合成器景深

镜头畸变

1. Render Layers → Lens Distortion → Composite
2. Distortion：桶形畸变（-1 到 0）或枕形畸变（0 到 1）
3. 启用“Fit”，避免出现黑边
4. Dispersion：色差（使用较小的值，如 0.01-0.05）

暗角

1. Ellipse Mask → Blur（Gaussian）→ Mix（Multiply）→ Composite
2. 或者：使用 Lens Distortion，仅启用 Dispersion，创建轻微暗角
3. 调整遮罩的大小／位置来控制暗角形状

胶片颗粒

1. Render Layers → Mix → Composite
2. 生成噪点：Value 节点 + Noise Texture（或使用基于图像的颗粒）
3. 混合模式：使用较低的系数（0.05-0.15）进行 Overlay 或 Add 混合

渲染通道分离

1. Render Layers 节点会提供所有已启用的通道
2. 启用通道：Diffuse Color/Direct/Indirect、Glossy Color/Direct/Indirect、Transmission、Emission、Environment、AO、Shadow、Mist、Normal、Z
3. 分别处理每个通道（例如，增强 Glossy、降低 Diffuse 的饱和度）
4. 重新合成：将 Shader 通道相加，然后与 Color 通道相乘

多层 EXR 输出

1. Render Layers → File Output 节点（将格式设为 OpenEXR Multilayer）
2. 为要保存的每个通道添加输入插口
3. 设置基础路径和文件名
4. 每个输入都会成为 EXR 中的一个图层
5. 如需输出单独文件：使用 File Output，并为每个插口设置文件路径

序列编辑器条带信息（Blender 5.1）

1. CompositorNodeStripInfo 输出 VSE 条带的时间元数据（5.1 中新增）
2. 输出：Frame、Strip Start、Strip End、Strip Duration、Speed Factor
3. 可用于根据片段时间驱动合成器效果
4. 场景中必须有活动的序列编辑器条带

遮罩转 SDF（Blender 5.1）

1. CompositorNodeMaskToSDF 将二值遮罩转换为有符号距离场（5.1 中新增）
2. 输出：SDF（有符号距离值，内部为负，外部为正）
3. 可用于创建平滑的遮罩边缘、可变宽度轮廓和辉光效果
4. 与 Math 节点组合，可对 SDF 宽度进行阈值处理或调整

雾／薄雾

1. 启用 Mist 通道：view_layer.use_pass_mist = True
2. 在 Scene Properties → World → Mist Pass 中配置薄雾（Start、Depth、Falloff）
3. Render Layers（Mist）→ Color Ramp → Mix（与雾的颜色混合）→ Composite

Cryptomatte

1. 在视图层中启用 Cryptomatte 通道
2. 在合成器中添加 Cryptomatte 节点
3. 在 Viewer 中选取对象／材质
4. 输出：Image（提取的图像）、Matte（遮罩）、Pick（ID 可视化）
5. 使用遮罩进行选择性后期处理

调试与优化

常见问题

• 合成器未运行：确保已在合成器标题栏中勾选 Use Nodes，并在 Post Processing（Render Properties）中启用 Compositing
• 输出为黑色：检查 Render Layers 节点是否已连接到 Composite 节点。确保场景已渲染（合成器处理的是渲染结果）
• 通道数据错误：确认已在 View Layer Properties 中启用该通道。启用通道后重新渲染
• 未显示背景：在合成器标题栏中启用 Backdrop。连接一个 Viewer 节点
• 合成速度慢：降低预览分辨率。使用 “Fast Gaussian” 模糊类型。禁用未使用的节点

性能提示

1. 使用 Viewer 节点预览中间结果，无需完整重新合成
2. 静音未使用的分支（Ctrl+M）
3. 迭代期间使用较低的质量设置，最终渲染时切换为 High
4. 对于动画，优先使用渲染级别的降噪，而非合成器降噪（速度更快）
5. File Output 节点带来的额外开销极小——可放心用于通道调试
6. Mix 节点：在 5.1 中，执行 Alpha 感知混合操作时速度最高可提升 2 倍

节点参考

如需查看按类别（Input、Output、Color、Filter、Converter、Matte、Vector、Distort）整理的完整合成器节点目录，请参阅 references/node_reference.md。

可搜索的主要类别：

• 颜色调整：搜索 “Color”“Balance” 或 “Curves”
• 模糊/滤镜效果：搜索 “Blur” 或 “Filter”
• 键控/遮罩：搜索 “Key” 或 “Matte”
• 渲染通道：搜索 “Render Layers” 或 “pass”
• 输出：搜索 “File Output” 或 “Composite”
• Blender 5.1 的变更：搜索 “5.1”“Strip Info” 或 “SDF”

Python API 参考

如需查看完整的 Python API 用法模式，包括合成器节点类型字符串、节点树设置、渲染通道启用和 File Output 配置，请参阅 references/python_api.md。