Natron 中 G‘MIC「Illuminate 2D Shape」节点完全指南：为透明背景上的二维图形自动生成光照

• 音视频
• 视频处理
• 图形学
• 桌面应用

导读

本文围绕 Natron 开源合成软件中随 G'MIC（openfx-gmic）插件族一起提供的「Illuminate 2D Shape」（eu.gmic.Illuminate2DShape）节点展开。该节点面向透明背景上的不透明二维图形（Logo、字幕、遮罩形状等），能自动为其检测形状、生成凹凸/法线信息，并以可调的 Blinn-Phong 风格光照模型合成出具有立体感的照明效果。读完本文，你将掌握该节点的全部 35 个控制参数的取值含义与默认行为，理解形状检测、光照渲染、混合叠加的完整工作链路，并了解这份文档本身的生成机制与相关源码位置。

一、节点定位：G'MIC 插件族中的光照工具

「Illuminate 2D Shape」是 G'MIC（GREYC's Magic for Image Computing，由法国 CNRS GREYC 实验室 David Tschumperle 开发的开放图像处理框架）滤镜库中的一个滤镜，经由 OpenFX 插件包装后集成进 Natron。包装工作由 Tobias Fleischer 与 Frederic Devernay 完成，文档标注的版本为 1.0，作者为 David Tschumperle，最近更新日期为 2018/05/18。

在 Natron 中，所有 G'MIC 滤镜都以eu.gmic.*前缀的插件 ID 出现在GMIC节点分组下。该分组的完整节点清单可见 Documentation/source/_groupGMIC.rst，其中包含 360 个左右的滤镜文档，覆盖 3D 效果、模糊、艺术滤镜、修复、锐化、噪声、形状变换等大类。在 Engine/AppInstance.cpp 的exportDocs()与 Gui/DocumentationManager.cpp 中，"GMIC"分组被显式注册，与 Image、Color、Filter、Merge 等内建分组并列，而 CHANGELOG 记录显示 G'MIC 插件（beta）随 Natron 二进制发行版捆绑分发。

注意：与 About G'MIC 等"关于"类滤镜不同，Illuminate 2D Shape 是一个真正执行图像计算的滤镜。G'MIC 滤镜整体仍处于 beta 阶段（见 CHANGELOG.md 中"Update CImg and G'MIC to 2.8.4 and fix several issues in GMIC plugins (which are still beta)"的说明），参数布局在版本迭代中可能调整。

二、关于本文档：由 Natron 自动生成的参数参考

在你继续阅读前，需要先了解这份文档的特殊性质：eu.gmic.Illuminate2DShape.rst是由 Natron 程序自动生成的，不能手工编辑。

生成链路如下：

1. 每个插件的描述与参数帮助文本存放在插件自身的 C++ 源码（kPluginDescription 定义）中；
2. Natron 通过--export-docs命令行（见 Engine/AppInstance.cpp 的exportDocs()）为每个已注册插件实例化一个节点，并调用 Engine/NodeDocumentation.cpp 中的Node::makeDocumentation()，遍历节点的所有 Knob，把参数标签、脚本名、类型、默认值、枚举项与帮助文本拼装成 Markdown 表格；
3. 生成的.md文件再由 tools/genStaticDocs.sh 通过 pandoc 转换为.rst，并插入.. _eu.gmic.Illuminate2DShape:标签、Controls 表格的tabularcolumns/cssclass:: longtable属性，最终写入Documentation/source/plugins/目录。

因此，文档开头会有<!-- Do not edit this file! It is generated automatically by Natron itself. -->的声明；Documentation/source/guide/tutorials-writedoc.rst 也明确把Documentation/source/plugins下的插件文档列入"自动生成、不可编辑"的名单。理解这一点，就能明白为什么各参数的行为描述往往非常简短——它直接继承自滤镜源码内的帮助文本，本文在此基础上结合参数名与取值集合做进一步解读。

三、输入与整体处理流程

该节点只有一个输入：

从文档 Description 中的核心提示"该滤镜会自动为定义在透明背景之上的不透明形状添加光照"以及参数构成来看，典型工作流是：把带 Alpha 的 Logo/图形接入 Source，节点内部经历"形状检测 → 生成凹凸（bump）信息 → 光照计算 → 与输入合成"几个阶段，最终输出带立体感光照的结果。参数表也恰好按这些阶段分成几组：输入模式与形状检测（Input Type 等）、凹凸/表面预处理（Erosion/Dilation、Smoothness、Bump Factor、Avg/Max Weight、Resolution）、光照渲染（Ambient/Diffuse/Specular/Shininess、Light-X/Y/Z、Levels 等）、合成（Blending Mode、Opacity），以及所有 G'MIC 滤镜共享的通用输出与预览参数（Output Layer、Resize Mode、Preview Type 等）。

四、输入模式（Shape 阶段）详解

4.1 Input Type：告诉滤镜你的输入是什么

Input Type（脚本名Input_Type）决定滤镜如何理解输入图像，共四个选项，默认Single Opaque Shapes Over Transp. BG：

文档特别指出：「Minimal Shape Area」参数仅在 Multiple Colored Shapes 输入模式下生效——因为只有多形状模式才需要做"哪些区域算一个形状"的判定。

4.2 形状检测与轮廓控制

• Input Guide Color（Input_Guide_Color，Color，默认r:1 g:0 b:0 a:0）：引导色，默认是带透明度的纯红色。从参数定位看，它用于在多形状模式下标记/指导对目标形状的识别，可以理解为"告诉滤镜我关心的形状是什么颜色"。
• Minimal Shape Area（Minimal_Shape_Area，Integer，默认4）：最小形状面积阈值（像素单位），小于该面积的色块会被当作噪点忽略。只在 Multiple Colored Shapes 模式下生效。
• Preview Detected Shapes（Preview_Detected_Shapes，Boolean，默认Off）：打开后可在画布上预览滤镜检测到的形状轮廓，便于先确认识别结果、再关闭它进行正式渲染。
• Keep Base Layer as Input Background（Keep_Base_Layer_as_Input_Background，Boolean，默认On）：是否把输入的原图保留为背景层参与合成；关闭后可能只保留计算出的光照结果。
• Keep Transparency in Output（Keep_Transparency_in_Output，Boolean，默认On）：输出是否保留输入原有的 Alpha 透明通道，保证光照结果仍作为带 Alpha 的素材继续参与下游合成。

五、凹凸生成与表面预处理

形状被识别后，需要把二维形状转换成可供光照计算的表面几何信息。这一组参数控制"从平面形状到凹凸高度场"的转换质量：

• Erosion / Dilation（Erosion__Dilation，Double，默认0）：对检测到的形状蒙版做腐蚀（负值）或膨胀（正值）处理，调节形状边界的收缩/扩张，从而微调光照边缘。

• Smoothness（Smoothness，Double，默认3）：凹凸场的平滑程度，值越大表面越光滑、光照过渡越柔和。

• Bump Factor（Bump_Factor，Double，默认1）：凹凸强度倍率，控制表面起伏的幅度；增大可让光照对比更强烈。

• Avg / Max Weight（Avg__Max_Weight，Double，默认1）：从参数名看，它决定生成凹凸场时"平均化"与"取最大值"两种策略之间的权重，影响边缘与细节的保留方式。

• Resolution（Resolution，Choice，默认256）：光照计算的内部分辨率，从高到低依次为：

  选项	含义
  Full (Slower)	全分辨率计算，质量最高、最慢
  2048 / 1024 / 512	高分辨率档
  256（默认）	中分辨率档
  128 / 64 (Faster)	低分辨率档，速度最快、细节最少

  与预览参数配合，可以在调参阶段用低分辨率快速迭代，定稿后再切回 Full 输出。

六、光照渲染参数（Illumination 阶段）

这一组是节点的核心。Ambient / Diffuse / Specular / Shininess 的组合是典型的 Blinn-Phong 反射模型参数；Light-X / Light-Y / Light-Z 定义光源方向向量（默认(2, -2, 2)，可理解为从右上前方照射）；Levels、Linearity、Flatness、Smoothness_2 则进一步塑造光照的明暗分布与表面质感。

调整建议（结合参数集合给出的实践路径）：先用 Light-X/Y/Z 摆好光源角度，再用 Ambient/Diffuse/Specular/Shininess 塑造整体质感，最后用 Flatness、Linearity、Levels、Smoothness_2 做细节整形；如果输出过亮或过暗，打开 Normalize Illumination 重新校准动态范围。

七、合成与混合

光照计算完成后，滤镜需要把它与输入合成：

• Blending Mode（Blending_Mode，Choice，默认Hard Light）：光照层与背景的混合模式，提供 12 个选项：

  选项	选项	选项
  Normal	Lighten	Screen
  Dodge	Add	Darken
  Multiply	Burn	Overlay
  Soft Light	Hard Light（默认）	Grain Merge

  其中 Hard Light、Soft Light、Overlay、Screen 等属于经典"光照类"混合模式，用于让光照效果自然地"打在"背景上，这也是默认值选择 Hard Light 的原因——它既能增强高光又能加深阴影，适合模拟真实打光。

• Opacity (%)（Opacity_，Double，默认75）：光照层的整体不透明度，100 为完全不透明。默认 75% 意味着保留 25% 的原图底色参与混合。

八、通用 G'MIC 参数（所有滤镜共享）

从 Documentation/source/plugins/eu.gmic.AboutGMIC.rst 的 Controls 表可以看到，以下几组参数在所有 G'MIC 滤镜中都会出现，属于包装层的通用控制：

• Open Interactive Preview（Open_Interactive_Preview，Boolean，默认Off）：打开后弹出 G'MIC 的交互预览窗口，可实时拖拽调参。

• Preview Type（Preview_Type，Choice，默认Full）：预览窗口的视图布局，共 12 种：

  组别	选项
  单视图	Full
  前向分割	Forward Horizontal、Forward Vertical
  后向分割	Backward Horizontal、Backward Vertical
  复制平铺	Duplicate Top / Left / Bottom / Right / Horizontal / Vertical
  棋盘格	Checkered、Checkered Inverse

• Output Layer（Output_Layer，Choice，默认Layer 0）：当滤镜输出多图层结果时选择输出哪一层，选项为Merged、Layer 0、Layer -1至Layer -9。多数滤镜默认合并（Merged）或输出 Layer 0。

• Resize Mode（Resize_Mode，Choice，默认Dynamic）：滤镜内部处理尺寸策略：

  选项	含义
  Fixed (Inplace)	固定分辨率原地处理
  Dynamic（默认）	动态适配输入尺寸
  Downsample 1/2、1/4、1/8、1/16	先降采样处理再回采样，换取速度

• Ignore Alpha（Ignore_Alpha，Boolean，默认Off）：忽略输入 Alpha 通道只处理 RGB。

• Preview/Draft Mode（PreviewDraft_Mode，Boolean，默认Off）：草稿模式，降低计算精度以加速预览。

• Global Random Seed（Global_Random_Seed，Integer，默认0）与Animate Random Seed（Animate_Random_Seed，Boolean，默认Off）：控制滤镜内部随机过程的种子；开启 Animate 后种子随时间轴逐帧变化，可在动画场景下让随机效果连续变化。

• Log Verbosity（Log_Verbosity，Choice，默认Off）：G'MIC 运行日志的详细程度，Off / Level 1 / Level 2 / Level 3，Level 越高输出越详细，用于排查滤镜参数问题。

提示：表中反引号内的脚本名（如LightX、Blending_Mode、Preview_Type）是参数在项目文件（.ntp）与 Python 表达式中的真实标识符。在 Natron 的表达式编辑器或 Py 脚本中引用这些参数时，必须使用脚本名而非界面显示名。

九、完整参数速查表

以下汇总本文全部 35 个参数，按节点面板顺序排列，供日常查阅（信息完整继承自 eu.gmic.Illuminate2DShape.rst）：

十、推荐实战流程

结合节点内部阶段划分与参数默认值，一个典型的"给 Logo 加光照"流程如下：

1. 将带透明通道的 Logo/图形接入Source输入；
2. 保持Input Type默认（Single Opaque Shapes Over Transp. BG）；若画面含多个形状，切换为Multiple Colored Shapes Over Transp. BG，并配合Minimal Shape Area过滤小色块；
3. 打开Preview Detected Shapes检查形状识别是否正确，确认后关闭；
4. 调整Erosion / Dilation、Smoothness、Bump Factor塑造凹凸质感；
5. 用Light-X / Light-Y / Light-Z摆放光源，用Ambient / Diffuse / Specular / Shininess调整光照强度与质感；
6. 若输出明暗失衡，开启Normalize Illumination；
7. 用Blending Mode（默认 Hard Light）与Opacity把光照合成回原图；
8. 调参期间可降低Resolution、开启Preview/Draft Mode或Open Interactive Preview加速迭代，定稿后再切回 Full 分辨率并关闭草稿模式渲染。

十一、相关资源

• 本节点所属分组完整清单：Documentation/source/_groupGMIC.rst
• G'MIC 插件总体说明（含自定义 .gmic 滤镜的编写方法）：Documentation/source/plugins/eu.gmic.AboutGMIC.rst
• 插件文档自动生成机制的源码实现：Engine/NodeDocumentation.cpp、Engine/AppInstance.cpp、tools/genStaticDocs.sh
• Natron 文档编写与生成流程说明（含 Sphinx/pandoc 用法）：Documentation/source/guide/tutorials-writedoc.rst
• G'MIC 插件在 Natron 中的迭代记录（beta 状态、CImg/G'MIC 2.8.4 更新）：CHANGELOG.md

使用提醒：G'MIC 滤镜在 Natron 中仍标记为 beta，且历史版本曾出现参数不向后兼容的调整（CHANGELOG 2.3.14 中注明"Fix many G'MIC plugins. Changes are not backward compatible and existing graphs may need to be reworked"）。若你保存的项目中使用了本节点，升级 Natron 版本后建议检查参数是否被重置或映射变化。

• 音视频
• 视频处理
• 图形学
• 桌面应用