Material Maker 的 Symmetric Nearest Neighbor 节点:边缘保持平滑滤镜的原理与实战

原创2026-10-11 11:51:571,419 阅读
文章标签:图形学3D渲染桌面应用

Material Maker 的 Symmetric Nearest Neighbor 节点:边缘保持平滑滤镜的原理与实战

导读

Symmetric Nearest Neighbor(对称最近邻,SNN)是 Material Maker(基于 Godot 引擎的过程化材质生成与 3D 模型绘制工具)内置的一款边缘保持平滑滤镜节点。它能在消除纹理噪点的同时显著保留边缘与细节,是制作表面微光洁度、金属拉丝、砖墙缝等需要"去噪不糊边"场景的常用工具。本文将以 节点官方文档 为核心骨架,结合仓库中的 节点定义文件 与引擎源码,讲解该节点的输入输出、全部参数、底层 Shader 算法原理以及实战用法,帮助你读完后能直接在材质图中正确配置并使用它。

节点概览:它是什么,在哪里找到

根据官方文档,Symmetric Nearest Neighbor 节点对其输入应用一种边缘保持(edge-preserving)的平滑滤镜。与传统均值模糊(Box Blur)或高斯模糊不同,SNN 在平滑时会对每个对称采样点做出"就近选择",因此不会模糊掉高频边缘。

  • 在节点库中,它位于 Filter 分类下,条目为 Filter/Symmetric Nearest Neighbor(见 基础节点库 base.json),显示名为 "Symmetric Nearest Neighbor",图标为 filter_symmetric_nearest_neighbor;
  • 其 .mmg 定义的 longdesc 为 "Edge-preserving smoothing filter"(边缘保持平滑滤镜),shortdesc 为 "Symmetric Nearest Neighbor Filter";
  • 官方文档将其收录在 过滤器节点总览 nodes_filter.rst 中,与 Denoiser、Blur、Classic Kuwahara、Anisotropic Kuwahara 等滤镜并列。

节点在编辑器中的形态(输入/输出端口与四个参数控件)如下:

Symmetric Nearest Neighbor 节点界面截图

输入与输出

SNN 节点结构非常简洁(文档明确说明只有一个输入与一个输出):

端口 类型 说明
Input (in) rgb 待平滑的输入图像,通常连接任意纹理生成节点(噪声、图案、贴图等)
Output (out) rgb 平滑滤镜处理后的结果图像

这一端口定义可以从 .mmg 定义中的 ios 子节点确认:输入端口定义 声明输入名为 in、类型 rgb、说明 "Input image";输出端口定义 声明输出名为 out、类型 rgb、说明 "Filtered Image"(滤镜处理后的图像)。

参数详解

节点共暴露 4 个参数(全部由 remote 类型的 gen_parameters 子节点提供,详见 参数定义区):

Resolution(分辨率)

  • 作用:用于采样输入的分辨率("Resolution used to sample the input")。
  • 实现细节:该控件是 linked_control 类型,同时联动到 shader_1 的 size、iterate_buffer 的 size 以及 buffer_2 的 size 三个内部节点。分辨率取值通过 pow(2, v) 换算成实际像素尺寸(见 gen_buffer.gd 与 gen_iterate_buffer.gd 中 var size = pow(2, get_parameter("size"))),即值为 9 表示 512×512、10 表示 1024×1024、13 表示 8192×8192。.mmg 中 size 类型参数的范围是 first=4、last=13(见 shader 参数定义),默认值为 10(1024 像素)。
  • 实战建议:分辨率越高,SNN 采样越精细,边缘保持越准确,但计算开销随像素数线性增长。对于 2D 预览,可先使用较小值(如 8/512px)调试,最终导出时再提高。

Buffer(缓冲)

  • 作用:布尔开关,决定是否在滤镜执行前先将输入采样到一个 Buffer(纹理缓冲)中("When set, a buffer is used to sample the input before the filter")。
  • 实现细节:该控件是 config_control 类型,通过内部 switch 节点切换数据通路(见 配置文件映射):开启时 buffer_2 的输出被选中,关闭时输入直接进入滤镜。Buffer 子节点(buffer_2 定义)由 gen_buffer.gd 实现,其描述为"Samples input into a texture of a given resolution"——即将输入按指定分辨率预渲染成一张纹理,后续多次采样时不再反复执行上游生成逻辑。
  • 实战建议:当上游是计算密集的噪声/图案节点、或 SNN 需要多次迭代时,建议开启 Buffer 以避免上游被重复求值,显著加快预览速度。

Filter Size(滤镜尺寸)

  • 作用:滤镜的尺寸(文档中写为 Size,shortdesc 为 Filter Size,longdesc 为 "Size of the filer")。它联动 shader_1 的 kernel_size 参数。
  • 取值范围:kernel_size 的 min=4、max=32、step=1、default=4(见 shader 参数定义),节点默认值为 6。
  • 实现细节:注意实际传入 Shader 的核尺寸是 kernel_size 的 2 倍——输出表达式为 symmetric_nearest_neighbor($uv, int($kernel_size*2.0))(见 shader 输出定义)。也就是说 Size=6 实际对应 12 像素的采样窗口(随后在 Shader 内被修正为奇数 11)。Size 越大,平滑范围越广,边缘保护半径也越大。

Iterations(迭代次数)

  • 作用:滤镜对输入应用的总次数("Number of times the filter is applied to the input image")。
  • 取值范围:联动 iterate_buffer 的 iterations 参数。在引擎定义中该参数类型为 float、min=1、max=50、step=1、default=5(见 gen_iterate_buffer.gd 的参数定义),本节点默认值为 1。
  • 实战建议:单次 SNN 可能不足以消除顽固噪点;需要更强平滑时可逐步提高 Iterations(如 2~4)。每次迭代都会把上一次的输出作为输入继续滤波,平滑效果会累积,但同时也会逐步压缩高频细节,需在平滑度与细节保留之间权衡。

底层原理:SNN 算法的 Shader 实现

SNN 节点的核心是内部 shader_1 子节点中一段实例 Shader 函数。该函数基于 fiveko 的 symmetricnn.js 实现改写(代码中保留了原始来源注释 "Based on https://github.com/fiveko/fivekogfx...",MIT 许可),完整代码见 shader_1 的 instance 代码:

vec3 $(name)_symmetric_nearest_neighbor(vec2 uv, int kernel_size) {
    kernel_size += ~(kernel_size & 1);              // 修正为奇数
    vec2 one_pixel = vec2(1.0 / $size);            // 单像素 UV 步长
    int half_size = kernel_size / 2;
    vec3 v = $in(uv).rgb;                          // 中心像素颜色
    vec4 mean_color = vec4(0.0);
    for (int y = 0; y <= half_size; y++){
        for (int x = -half_size; x <= half_size; x++){
            vec3 v1 = $in(uv + vec2(float(x), float(y)) * one_pixel);
            vec3 v2 = $in(uv + vec2(float(-x), float(-y)) * one_pixel);
            vec3 d1 = abs(v - v1);
            vec3 d2 = abs(v - v2);
            vec4 rv = vec4(((d1[0] < d2[0]) ? v1[0] : v2[0]),
                ((d1[1] < d2[1]) ? v1[1] : v2[1]),
                ((d1[2] < d2[2]) ? v1[2] : v2[2]),1);
            mean_color += rv;
        }
    }
    return mean_color.rgb / float(kernel_size*(half_size + 1));
}

逐段拆解其工作流程:

  1. 核尺寸归一:kernel_size += ~(kernel_size & 1) 将传入的偶数核修正为奇数(例如 12 → 11),保证窗口围绕中心像素对称。
  2. 对称采样:双层循环遍历窗口。对每个偏移 (x, y),同时采样两个关于中心中心对称的像素 v1(偏移为 (x,y))与 v2(偏移为 (-x,-y))。
  3. 逐通道就近选择:分别计算 v1、v2 与中心像素 v 的绝对差 d1、d2;对 R、G、B 三个通道独立地选择与中心更接近的那一侧像素值。这正是 "Symmetric Nearest Neighbor" 名称的由来——每个对称对只保留"最近邻"的一方。
  4. 加权平均:所有被选中的值累加后除以采样总数 kernel_size * (half_size + 1)(即窗口内采样对数),得到平滑后的颜色。

为什么它能保边? 因为当中心像素恰好位于一条边缘上时,对称采样对中总有一侧的颜色与中心差异很大、另一侧接近中心;SNN 会优先采纳"更像中心"的那一侧,从而把边缘两侧的颜色各自平滑、而非互相涂抹。相比之下,普通均值滤波会直接混合两侧颜色导致边缘模糊。

内部节点图:Buffer → Switch → 迭代循环

SNN 节点本身是一个 type: "graph" 的复合图(完整图定义),内部由 6 个子节点与 8 条连接组成:

gen_inputs ──► buffer_2 ──► switch ──► iterate_buffer ──► gen_outputs
                       │        ▲            │
                       │        └────────────┤ (loop 回环)
                       └──► switch ──► shader_1 ◄── iterate_buffer (loop_in)
  • switch:由 config_control(Buffer 开关)驱动 source 参数,在"直接输入"与"Buffer 预采样后输入"两条通路间切换(实现见 gen_switch.gd);
  • shader_1:上文分析的 SNN 滤镜函数本体;
  • iterate_buffer:负责把输入渲染成指定分辨率的纹理,并按 Iterations 参数在循环中反复应用滤镜。其 autostop 默认关闭、filter 默认开启、f32/mipmap/shrink 默认关闭(见 iterate_buffer 参数);
  • 连接关系显示,iterate_buffer 的输出(port 1,即 loop output)回环到 shader_1 的输入,shader_1 的输出再回到 iterate_buffer 的 loop input——构成"渲染 → 滤波 → 再渲染"的迭代闭环,这正是 Iterations 参数的物理载体。

迭代的执行逻辑由 gen_iterate_buffer.gd 负责:on_dep_update_buffer 中根据 current_iteration 判断是首次渲染(使用初始输入)还是循环渲染(使用 shader_1 的输出作为输入),每完成一次迭代更新一次 buffer 并递增迭代计数,直到达到 iterations 阈值后把最终结果输出到 port 0(见 迭代渲染主流程)。该引擎类的描述也印证了这一点:"Samples input into a texture and applies a 'loop subgraph' repeatedly"。

参数联动机制:远程控件(Remote)

四个公开参数全部由 remote 节点(gen_parameters)暴露,并通过两类控件与内部节点联动:

  • linked_control(联动控件):一个外部参数同时驱动多个内部参数。例如 Resolution 同时联动 3 个内部节点的 size;Filter Size 联动 shader_1.kernel_size;Iterations 联动 iterate_buffer.iterations。
  • config_control(配置控件):通过配置表改变内部结构。Buffer 开关在 "False"/"True" 两种配置下分别把 switch.source 设为 0/1,从而切换数据通路。

这种"外部简洁、内部复合"的设计正是 Material Maker 大量滤镜节点(如 Kuwahara 系列、Denoiser)的通用模式,让用户只面对少量高层参数即可控制复杂算法管线。

实战使用建议与技巧

  1. 去噪点而不糊细节:当输入纹理存在高频颗粒噪点、又需要保留锐利边缘(如划痕、砖缝、金属边缘)时,SNN 优于普通 Blur 节点;可以把它接在噪声或图案输出之后、进入法线/颜色贴图合成之前。
  2. 先开 Buffer 再调参:调试阶段开启 Buffer 开关,让输入预渲染成纹理,参数调整的预览响应会明显变快;正式导出时若上游本身很轻量,也可关闭以省去一次纹理往返。
  3. 小核多迭代:相比一次性把 Filter Size 拉到很大,保持中等 Size(4~8)+ 多次 Iterations(2~4) 通常能获得更自然、少"过平滑"的结果。每次迭代都基于上次输出,等效于不断收敛。
  4. 分辨率与性能的平衡:Resolution 采用 2 的幂(如 8=256、9=512、10=1024、13=8192)。3D 预览阶段用低分辨率,最终贴图导出前再提高到目标尺寸——因为 SNN 是窗口采样算法,分辨率直接影响边缘对齐精度。
  5. 与其他保边滤镜配合:仓库的 Filter 分类下还提供 Classic Kuwahara、Anisotropic Kuwahara、Generalized Kuwahara 等同类保边滤镜(见 nodes_filter.rst)。SNN 的优势是计算简单、无方向性假设;Kuwahara 系列则在局部方差判别上更精细,可按纹理特性替换试验。

效果参考

文档提供了官方示例图,展示输入图与经过 SNN 滤镜处理后的对比效果:

Symmetric Nearest Neighbor 滤镜效果示例对比图

参考资料

登录后查看全文
material-maker