Natron 中 G'MIC Square to Circle 节点完全指南：圆形与方形图像域的可逆映射与参数详解

G'MIC Square to Circle（eu.gmic.SquaretoCircle）是 Natron 节点图工具链中一个专用于圆形 ↔ 正方形图像域相互映射的变形滤镜。本文以仓库内自动生成的插件文档 eu.gmic.SquaretoCircle.rst 为骨架，结合 Natron 的 GMIC 节点组、插件文档生成机制与同族节点参数体系，完整讲解该节点的输入、全部 13 项控件参数及其典型用法，帮助你直接在节点图中完成圆形/方形域变形、边缘处理与输出控制。

节点是什么：一个基于 G'MIC 框架的圆形-方形映射滤镜

Square to Circle 节点属于 Natron 中 GMIC 节点组（GMIC group）。从 Engine/AppInstance.cpp 的节点组注册代码可以看到，groups << QString::fromUtf8("GMIC"); // openfx-gmic，即该组由独立的 OpenFX 插件集 openfx-gmic 提供；而在 Natron 文档的节点索引 Documentation/source/_groupGMIC.rst 中，eu.gmic.SquaretoCircle 与数百个 G'MIC 滤镜节点并列，用户可以通过左侧工具栏的节点组按钮或节点图区域的右键菜单进入 GMIC 组后创建它。

根据原文档的 Description 段，该滤镜实现的是 C. Fong 提出的圆形-正方形映射函数（circle-to-square / square-to-circle mapping），滤镜作者为 David Tschumperle（G'MIC 与 CImg 库的主要作者），最近更新于 2017/10/30。整条插件链的结构是：Natron 作为 OpenFX 宿主 → openfx-gmic 作为 G'MIC 框架的包装器（wrapper，由 Tobias Fleischer 与 Frederic Devernay 编写）→ 底层调用 G'MIC/CImg 的图像处理内核。因此该节点的行为本质上是把 G'MIC 语言编写的一个滤镜命令，以 OpenFX 参数化的形式暴露给 Natron 的节点图。

核心能力：在保持图像内容连续性的前提下，把一个正方形画面变形为内切圆（Square to Circle），或把圆形画面展开回正方形（Circle to Square）。这类映射常见于 360° 全景/鱼眼素材的中间处理、抽象艺术变形、以及对圆形构图与方形构图之间做过渡动画的场景。由于映射是可逆双向的，同一个节点可以完成正反两个方向的变换。

输入端口：唯一的 Source 输入

输入	描述	是否可选
Source	待变形的源图像	否（必连）

该节点只有一个 Source 输入，且为必连（Optional = No）。在 Natron 节点图中，将上游任何图像类节点的输出（例如 Read 节点、合成 Merge 结果、其他滤镜输出）连接到 Source 即可；断开或未连接时节点无法执行渲染。与多数 G'MIC 滤镜相同，本节点没有额外的遮罩（mask）输入，所有控制都通过右侧参数面板完成。

控件参数详解

以下是原文档 Controls 段的完整参数表（参数显示名 / 脚本名、类型、默认值均已保留），随后逐项说明含义与使用建议。需要指出的是，这组参数中前四项（Mode、Interpolation、Boundary、X/Y-Factor、X/Y-Offset）是本滤镜的专属参数，而后六项（Output Layer、Resize Mode、Ignore Alpha、Global Random Seed、Animate Random Seed、Log Verbosity）是与所有 G'MIC 节点共享的通用参数——对照同组的 eu.gmic.CircleTransform.rst 与 eu.gmic.AboutGMIC.rst 可以确认它们出现在每一个 G'MIC 包装节点上。

参数（显示名 / 脚本名）	类型	默认值	可选值/功能
Mode / Mode	Choice	Square to Circle	Square to Circle；Circle to Square
Interpolation / Interpolation	Choice	Linear	Nearest Neighbor；Linear
Boundary / Boundary	Choice	Transparent	Transparent；Nearest；Periodic；Mirror
X-Factor (%) / XFactor_	Double	0	百分比数值
Y-Factor (%) / YFactor_	Double	0	百分比数值
X-Offset (%) / XOffset_	Double	0	百分比数值
Y-Offset (%) / YOffset_	Double	0	百分比数值
Output Layer / Output_Layer	Choice	Layer 0	Merged；Layer 0；Layer -1 … Layer -9
Resize Mode / Resize_Mode	Choice	Dynamic	Fixed (Inplace)；Dynamic；Downsample 1/2；Downsample 1/4；Downsample 1/8；Downsample 1/16
Ignore Alpha / Ignore_Alpha	Boolean	Off	On / Off
Global Random Seed / Global_Random_Seed	Integer	0	整数种子
Animate Random Seed / Animate_Random_Seed	Boolean	Off	On / Off
Log Verbosity / Log_Verbosity	Choice	Off	Off；Level 1；Level 2；Level 3

1. Mode（映射方向）

• Square to Circle（默认）：把正方形的 Source 图像映射到内切圆形区域，画面四角的内容向四周"收拢"，角落像素被映射到圆周之外（具体如何处理由 Boundary 决定）。
• Circle to Square：逆映射，把圆形内容展开铺满整个方形画布，是前者的反函数。

两个方向共用同一套映射函数族，因此你可以把两次该节点串联（Square to Circle 后再接 Circle to Square）近似还原原图，用于验证映射的一致性，或制作方向反转的变形动画。

2. Interpolation（重采样插值）

决定映射取样的像素插值算法：

• Nearest Neighbor（最近邻）：取最接近的像素，速度最快，但会产生硬边与锯齿，适合像素风、逐像素风格化或大比例降采样场景。
• Linear（线性，默认）：双线性插值，平滑过渡，绝大多数合成场景的推荐选项。

3. Boundary（边界处理）

当映射使采样点越过图像边缘（例如 Square to Circle 时四角区域需要读取画布外的数据）时，决定如何处理越界像素：

• Transparent（默认）：越界区域输出透明像素，四角自然变成透明，便于后续与其他图层合成。
• Nearest：复制最接近的边缘像素向外延伸，避免出现透明洞。
• Periodic：按周期平铺采样（类似重复贴图），适合做无缝循环图案。
• Mirror：镜像反射采样（类似镜像翻转），可形成对称延续的边缘纹理。

4. X-Factor (%) / Y-Factor (%) 与 X-Offset (%) / Y-Offset (%)

这四个参数均为 Double 类型、默认值 0、以百分比表达：

• X-Factor / Y-Factor：从参数命名与数值语义可以推断，它们分别控制映射在水平轴与垂直轴方向上的变形强度（因子），0 为中性默认值，向正/负方向调整会改变映射在对应轴上的拉伸程度，用于产生非均匀（椭圆形化）的变形效果。
• X-Offset / Y-Offset：控制映射中心在水平/垂直方向上的偏移量（百分比），用于把圆形映射区域相对画布中心进行平移，例如把圆心对准画面中的主体再执行变形。

由于单位是百分比，对非方形（例如 1920×1080）的画布，X 与 Y 方向的实际像素位移由对应边长比例折算，调整时建议以 5–10 为单位步进观察预览效果。这四个参数都支持 Natron 的动画曲线与表达式，可用于制作中心漂移或强度渐变的动态变形。

5. Output Layer（输出图层）

G'MIC 支持多图层（layers）图像模型，本参数选择输出哪个图层：

• Merged：输出所有图层合并后的结果。
• Layer 0（默认）：输出基础图层。
• Layer -1 至 Layer -9：从底部向上数（负索引）的图层。当源素材是 PSD 等多图层文件、且经过支持图层读取的节点链传入时，此参数才有实际意义；单图层普通素材下选择 Layer 0 即可。

6. Resize Mode（画布尺寸策略）

控制滤镜处理时对输出画布尺寸的处理方式：

• Fixed (Inplace)：保持输入尺寸不变，在原画布内原地变换。
• Dynamic（默认）：根据映射结果动态调整画布尺寸，避免变形后内容被裁剪。
• Downsample 1/2、1/4、1/8、1/16：先将图像按 1/2、1/4、1/8、1/16 比例降采样后再处理，输出对应的小尺寸结果。这四档用于快速预览或主动输出低分辨率版本，能显著降低大图（如 4K/8K）上的处理开销。

7. Ignore Alpha（忽略 Alpha）

Boolean 类型，默认 Off。开启后滤镜只对 RGB 颜色通道执行映射、不处理 Alpha 通道；默认关闭时 Alpha 通道参与采样与插值。对于需要保留原始遮罩形状、或希望避免透明区域插值引入半透明毛边的合成管线，建议开启。

8. Global Random Seed 与 Animate Random Seed（随机种子）

• Global Random Seed（整数，默认 0）：为滤镜内部任何随机过程提供确定性种子；固定种子可以保证同一输入下多次渲染结果一致（跨帧、跨渲染可复现），在 Natron 的缓存与渲染农场场景下尤为重要。
• Animate Random Seed（Boolean，默认 Off）：开启后种子会随时间（帧号）自动变化，使随机效果逐帧不同。

需要说明的是，本节点实现的是确定性几何映射，随机种子主要作为 openfx-gmic 包装器的通用参数组保留（与所有 G'MIC 节点一致），当后续在滤镜组合中引入随机化子命令时才会实际生效。

9. Log Verbosity（日志级别）

控制 G'MIC 内核向 Natron 日志输出的详细程度：

• Off（默认）：不输出 G'MIC 处理日志。
• Level 1 / Level 2 / Level 3：逐级提高输出量，分别对应简要、详细、非常详细（含调试信息）的日志。

日常使用保持 Off；当节点行为异常、需要排查 G'MIC 命令执行细节时，可临时调高到 Level 2/3，再通过 Natron 的日志窗口查看输出。

在 Natron 节点图中的典型用法

1. 创建节点：在节点图区域右键 → GMIC 组，或在左侧工具栏的 GMIC 节点组按钮中选择 Square to Circle（eu.gmic.SquaretoCircle）。
2. 连接输入：将上游图像（Read 节点输出、Merge 合成结果等）连到 Source 端口。
3. 设置方向：默认即 Square to Circle；如需反向展开，把 Mode 切到 Circle to Square。
4. 处理边缘：当四角出现不需要的透明区时，将 Boundary 从默认的 Transparent 改为 Nearest/Mirror，观察边缘延续效果。
5. 微调变形：用 X-Factor/Y-Factor 改变轴向拉伸，用 X-Offset/Y-Offset 平移映射中心，直到变形中心对准画面主体。
6. 预览与输出：开发阶段可将 Resize Mode 设为 Downsample 1/2 加速预览；最终渲染切回 Dynamic 或 Fixed (Inplace) 保证质量。开启 Ignore Alpha 可保持原有遮罩。
7. 下游连接：将节点输出接到 Viewer 查看，或继续接入后续滤镜与 Merge 合成。

由于 Mode、Factor、Offset 等参数均可在时间轴上打关键帧，本节点很适合制作方形画面逐渐"吸入"为圆形的转场，或相反从圆形扩展到全屏的揭示效果——这也是它名称"Square to Circle"在动态设计中的主要应用场景。

文档来源与生成机制（进阶阅读）

本节点文档属于 Natron 的自动生成插件文档体系，这一点在 Documentation/README-Natron-documentation.md 中有明确说明："Don't edit index.rst or files prefixed with _ , or anything in the plugins folder"——Documentation/source/plugins/ 下的全部文件由工具链自动产出，不应手工编辑（原文档正文首部也带有"Do not edit this file! It is generated automatically by Natron itself."注释）。

完整生成流程记录在 tools/genStaticDocs.sh：

1. 调用 NatronRenderer --export-docs <输出目录> <工程文件>，由渲染器遍历所有已加载插件，导出每个插件的 Markdown 文档（脚本第 67 行）；
2. 用 pandoc 将 Markdown 转为带 grid table 的 reStructuredText（第 72–95 行），并插入 .. _插件ID: 锚点、.. tabularcolumns:: 表格属性等 Sphinx 排版指令；
3. 处理 :ref: 链接与表格元素，最后统一拷贝到 Documentation/source/plugins/。

文档内容的生成代码位于 Engine/NodeDocumentation.cpp 的 Node::makeDocumentation()：其中描述段来自插件的 description 元数据，参数表则遍历插件的全部 knobs，逐一输出参数标签（getLabel()）、脚本名（getName()）、默认值与提示文本（getHintToolTip()）。这意味着本文上面这张参数表与你鼠标悬停在该节点参数上看到的提示、以及 Natron 内置的 HTML 插件文档，数据源完全一致；如果你参与插件开发，可以在插件 C++ 源码中通过 kPluginDescription 与各参数 hint 宏维护这些文本（参见 Documentation/source/guide/tutorials-writedoc.rst 的写作指南）。

小结

G'MIC Square to Circle 是 Natron GMIC 节点组中结构简单但用途明确的几何变形滤镜：一个必连的 Source 输入，配合 Mode / Interpolation / Boundary / Factor / Offset 五个专属参数与 Output Layer、Resize Mode、Ignore Alpha、随机种子、日志级别等 G'MIC 通用参数，即可在节点图内完成正方形与圆形图像域的往返映射。理解每个参数的默认值（如 Boundary 默认 Transparent、Resize Mode 默认 Dynamic）与脚本名（如 XFactor_、Output_Layer、Log_Verbosity），不仅方便你在 Natron 参数面板中快速操作，也有助于在 Python 脚本与项目文件（.ntp）中直接读写这些参数。如需在渲染农场或无人值守渲染中复现一致结果，请保持 Global Random Seed 固定，并在最终渲染前将预览用的 Downsample 档位切回 Dynamic。