Natron Add 节点（net.sf.openfx.AddPlugin）完全指南：常量加法原理、参数详解与文档生成机制

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

本文以 Natron 官方静态文档 Documentation/source/plugins/net.sf.openfx.AddPlugin.rst 为核心骨架，系统讲解 Color 组中 Add 节点（插件标识net.sf.openfx.AddPlugin，版本 2.0）的用途、输入接口、全部控制参数及其底层实现。读者将掌握如何在节点图中用 Add 为所选通道叠加一个常量颜色、如何通过 Mask、Mix、Invert Mask、(Un)premult 控制叠加范围与强度，并能从 Engine/ImageMaskMix.cpp 等源码理解这些参数的精确数学行为，同时了解这类插件参考文档是如何由 Natron 自动生成的。

节点概览：一句话理解 Add

根据官方文档，Add 节点的作用非常直接：

Add a constant to the selected channels.（向所选通道加上一个常量。）

它属于Color 组（节点组的完整清单见 Documentation/source/_groupColor.rst，其中列出了 Clamp、ColorCorrect、Gamma、Grade、Invert、Multiply 等同组节点），是 Natron 中做基础通道偏移/加法运算的数学节点。它与同组的 Multiply 节点（net.sf.openfx.MultiplyPlugin.rst）互为姊妹：Multiply 是"乘以一个常量"，Add 是"加上一个常量"，二者共享几乎完全相同的输入接口与宿主级参数结构。

Add 的典型应用场景包括：

• 整体提亮/压暗：对 RGB 三个通道同时加上一个正值或负值，整体移动亮度（注意使用负值需配合 Clamp 等节点防止下溢）。
• 单通道偏移：只对红色通道加值，制造色偏或做通道级调整。
• 与 Mask 配合的局部调整：通过 Mask 输入限定叠加发生的区域，再结合 Mix 控制叠加强度。
• Alpha 相关处理：配合 (Un)premult 在预乘图像上进行正确的常量加法。

输入接口（Inputs）

文档中 Add 节点共有两个输入，如下表所示：

• Source（必选）：被处理的源图像，运算的对象。未连接时节点无法产出有效结果。
• Mask（可选）：遮罩输入，用于限定"加法运算"施加的空间范围。从 Engine/EffectInstance.cpp 的取图逻辑可以看到，Natron 在处理 Mask 输入时会按掩码层（mask layer）读取其对应通道（默认取 Alpha 通道），当 Mask 未启用或通道不可用时，channelForMask会回退到 Alpha；而isHostMaskingEnabled()与isInputMask()共同决定了 Mask 输入是否参与最终合成（见下文 Mix / Mask 数学原理）。

控制参数详解（Controls）

文档给出的参数表是本文的核心，完整继承如下：

下面逐个深入讲解。

1. Value（value）：要加的常量

• 类型：Color（颜色），4 个维度分别对应 R、G、B、A 四个通道。
• 默认值：r: 0, g: 0, b: 0, a: 0——即默认不做任何加法，节点是透明的。
• 含义：给每个所选通道加上该常量对应维度的值。例如把 RGB 设为r: 0.1, g: 0, b: 0，则每个像素的红色通道加 0.1（浮点图像域内），产生红色偏置；把 Alpha 也设值则可以整体平移透明度。

与 Multiply 形成对比：Multiply 的value默认是r: 1, g: 1, b: 1, a: 1（恒等变换，见 net.sf.openfx.MultiplyPlugin.rst），而 Add 的加性恒等元是 0，这也是 Add 默认全 0 的原因。在浮点渲染管线中，加法不受 0~1 归一化范围的物理限制（取决于目标图像的位深与钳制设置），可加出超出 1 的值，因此常配合 Clamp（net.sf.openfx.Clamp，同样位于 Color 组）使用。

2. (Un)premult（premult）：预乘图像的正确处理

文档说明：

Divide the image by the alpha channel before processing, and re-multiply it afterwards. Use if the input images are premultiplied. （处理前将图像除以 Alpha 通道，处理结束后再重新乘回。若输入图像是预乘格式，请开启此项。）

为什么要这样做？预乘（premultiplied）图像的像素值已经乘过 Alpha，透明区域（alpha=0）的 RGB 为 0。若直接对预乘图像加常量，透明区域也会被加上该常量，随后在合成时再乘回 Alpha 时，颜色虽被消除但会引入不必要的数值变化，且在低透明度区域会放大加法的相对影响，造成边缘泛光或颜色偏移。先"去预乘"（除以 Alpha，恢复未乘前的颜色强度）→ 做加法 → 再"重新预乘"（乘以 Alpha），就能保证加法只作用于"有效可见"的颜色，符合合成数学的预期。

这一参数对应 OpenFX 标准的kOfxImageEffectPropPreMultiplication处理约定：勾选后，节点在内部以"未预乘"语义处理数据。这是所有带颜色的 OFX 数学节点（Add、Multiply、Gamma 等）共用的标准开关，属于插件自身声明的参数。

3. Invert Mask（maskInvert）：反转遮罩

文档说明：

When checked, the effect is fully applied where the mask is 0. （勾选后，效果在遮罩值为 0 的区域被完全应用。）

默认关闭时，遮罩值越大、加法应用得越充分（mask=1 处完全应用，mask=0 处完全不应用）；开启后语义反转：mask=0 处完全应用，mask=1 处不应用。

这个参数名maskInvert是 Natron 作为宿主为插件注入的标准参数。在 Engine/Node.h 中可以看到宿主的参数名定义：

#define kOfxMaskInvertParamName "maskInvert" #define kOfxMixParamName "mix"

其数学实现在 Engine/ImageMaskMix.cpp 的Image::applyMaskMixForMaskInvert中清晰可见：

if (maskPixels == 0) { maskScale = maskInvert ? 1.f : 0.f; // 无遮罩像素时：反转则全应用，否则不应用 } else { maskScale = *maskPixels * (1.f / maxValue); // 遮罩值归一化到 0~1 if (maskInvert) { maskScale = 1.f - maskScale; // 反转：取 1 - maskScale } }

即maskInvert = true时，每个像素的遮罩系数变为1 - mask，正好与文档描述"mask 为 0 处完全应用"吻合。该模板函数随后根据图像位深（8 位 255、16 位 65535、浮点 1.0）在 Engine/ImageMaskMix.cpp 中实例化分派。

4. Mix（mix）：原始图像与变换图像的混合

文档说明：

Mix factor between the original and the transformed image. （原始图像与变换后图像之间的混合因子。）

• 类型：Double（浮点）。
• 默认值：1，即默认完全使用"变换后"的结果。
• 取值含义：mix=0时输出完全等于原始图像（加法不生效）；mix=1时输出完全等于加常量后的结果；0~1之间按比例渐变，可用于对叠加强度做逐帧动画或局部过渡。mix同样由宿主注入（kOfxMixParamName），见上文 Engine/Node.h。

在 Engine/EffectInstance.cpp 中，宿主在渲染阶段统一读取这些值：

bool useMaskMix = _publicInterface->isHostMaskingEnabled() || _publicInterface->isHostMixingEnabled(); double mix = useMaskMix ? _publicInterface->getNode()->getHostMixingValue(time, view) : 1.; bool doMask = useMaskMix ? _publicInterface->getNode()->isMaskEnabled(_publicInterface->getNInputs() - 1) : false;

可以看到当宿主 mask/mix 功能启用时，mix取自节点（可通过动画/表达式驱动），且最后一个输入（getNInputs() - 1，即 Mask）的启用状态决定是否做遮罩合成。

运算数学：Mask、Mix、Invert 如何共同决定输出像素

结合 Engine/ImageMaskMix.cpp 的实现，可以给出 Add 节点最终像素级的精确行为。设：

• dst为"变换后"像素（即源图像加上value后的结果，Add 节点的处理输出）；
• src为原始输入像素；
• maskScale为按遮罩与maskInvert计算出的 0~1 系数；
• mix为混合因子。

合成的核心公式为：

alpha = mix * maskScale out = dst * alpha + (1 - alpha) * src

展开即：

out = (1 - mix * maskScale) * src + mix * maskScale * (src + value)

几个特例与文档一一对应：

• 无 Mask、mix=1时：alpha=1，out = src + value，纯加法。
• 无 Mask、mix=0时：alpha=0，out = src，节点透明。
• 有 Mask 且maskInvert=Off：遮罩亮处maskScale≈1（加法完全生效），暗处maskScale≈0（保持原图）。
• 有 Mask 且maskInvert=On：遮罩暗处加法完全生效，亮处保持原图，即文档所述的"Invert Mask"行为。

从源码结构看，applyMaskMix系列模板函数（Engine/Image.h 中的applyMaskMixForMasked声明）对通道数（1~4）、位深（8/16/32 位浮点）、是否带遮罩、是否反转做了全组合的模板特化，保证运行时零分支开销，这也是 Natron 对这类合成运算的统一性能优化路径。

关于文档本身：Add 节点文档是如何生成的

值得说明的是，本文依据的 net.sf.openfx.AddPlugin.rst 并非手写文档。文件头部明确写着：

Do not edit this file! It is generated automatically by Natron itself.（不要编辑此文件！它由 Natron 自动生成。）

整个生成链路在仓库中清晰可查：

1. 命令行导出：Renderer 二进制支持--export-docs参数（解析逻辑在 Engine/CLArgs.cpp），触发 Engine/AppInstance.cpp 的AppInstance::exportDocs()：遍历所有已安装插件（getPluginIDs()），对每个插件创建一个离屏节点实例，调用node->makeDocumentation(false)生成 Markdown 文档，并把插件图标拷贝为插件ID.png。
2. Markdown 组装：Engine/NodeDocumentation.cpp 的Node::makeDocumentation()遍历节点所有参数（getKnobs_mt_safe()），跳过隐藏参数与未由插件声明的参数，依据KnobColor、KnobBool、KnobDouble等类型映射出上表中的"类型"列，从getDefaultValue()读取默认值、从getHintToolTip()读取功能描述。
3. RST 转换：脚本 tools/genStaticDocs.sh 用 pandoc（要求 2.3.1 及以下，以强制输出 grid tables）把导出的 Markdown 转成 RST，并批量注入tabularcolumns/cssclass:: longtable等排版属性，最后按节点组生成_group*.rst目录树（Color 组的入口正是 Documentation/source/_groupColor.rst）。

这意味着：本文所有参数表、默认值、类型与功能描述，本质上都直接来自插件运行时自身的声明（OFX 参数描述），只要安装了对应版本的 Add 插件（net.sf.openfx.AddPlugin2.0），即可用NatronRenderer --export-docs <目录> <工程文件>重新生成一份完全同步的文档。

另外，原文档还附带了一个"See also"参考链接，指向 Nuke 中同名 Add 节点的说明存档页（原链接为外部网页归档地址，此处不展开），说明这一"常量加法"运算在合成软件生态中是跨软件通用的经典操作。

实战建议

• 提亮画面：连接 Source，设value的 RGB 为0.05~0.15之间的正值，mix配合0~1动画实现渐亮效果；若想避免超白，后面串接 Color 组的 Clamp。
• 做局部色偏：只调整value的单个通道，并接上 Mask 输入（如来自 Roto 节点的遮罩），配合mix做边缘柔化的过渡。
• 处理带 Alpha 的合成素材：输入图像若来自预乘流程（如某些渲染器输出），开启premult，避免透明区域被错误提亮产生边缘光晕。
• 反向擦除：需要"除某区域之外都加常量"时，勾选maskInvert，让遮罩暗部成为生效区域，省去额外反转遮罩的节点。
• 调试节点流：将mix设为 0 可以快速对比"加常量前后"，验证加法对画面其余部分无副作用。

延伸阅读（仓库内）

• Documentation/source/_groupColor.rst：Color 组全部节点索引，Add 的同组邻居。
• Documentation/source/plugins/net.sf.openfx.MultiplyPlugin.rst：与 Add 完全对称的"乘常量"节点，参数结构可对照学习。
• Engine/ImageMaskMix.cpp：Mask/Mix/Invert 的像素级实现（本文公式的出处）。
• Engine/Node.h：宿主注入参数maskInvert、mix的定义。
• Engine/EffectInstance.cpp：渲染阶段读取 mask/mix 值的宿主逻辑。
• Engine/NodeDocumentation.cpp：本文所依据的参数表如何从插件声明生成。
• tools/genStaticDocs.sh 与 Engine/AppInstance.cpp：--export-docs文档再生成流程的完整实现。

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