企业官网建设流程全解析

• 桌面应用
• 图形学
• 3D渲染
• 图像处理

导读

本文围绕 Material Maker 2D 有向距离函数（SDF）节点体系中的sdCircleRepeat（圆周重复）算子展开，讲解它如何将任意输入 SDF 形状沿圆周等角复制，从而快速生成花瓣、齿轮、轮辐、雪花与环形装饰等重复图案。读完本文，你将掌握该节点的输入输出约定、Count 与 Variations 两个核心参数的行为与取值范围、它在编辑器中的位置与调用链，以及底层 shader 的实现原理，可直接在 Material Maker 中动手搭建可复用的循环图案节点图。

节点定位：Simple / SDF / Operators 家族中的"循环算子"

sdCircleRepeat 是 Material Maker 的 2D SDF 算子之一，官方文档描述为："该节点通过沿圆周重复输入，生成一张有向距离图像"（原始文档）。它属于 Simple / SDF 节点体系 的 Operators（算子）分组，与 sdBoolean、sdSmoothBoolean、sdRoundedShape、sdAnnularShape、sdMorph、sdRepeat、sdMaskToSDF 并列。

SDF 节点的整体工作方式遵循"基础形状 + 算子组合 + sdShow 输出"的流程：

1. 用 sdCircle、sdBox、sdLine、sdPolygon 等基础形状节点定义几何；
2. 用布尔、变形、重复类算子组合出复杂图案；
3. 最后通过sdShow节点将 SDF 数值渲染为灰度图像（节点体系说明）。

sdCircleRepeat 是其中的"重复类算子"，其定位可从库文件 library/base.json 中确认：它在节点树的Simple/SDF/Operators/sdCircle Repeat位置注册，显示名为 "sdCircle Repeat"（注册条目）。同时，仓库还提供了同名的 3D 版本 CircleRepeat 节点（文档），本文只讨论 2D 版本。

节点核心元数据记录在 addons/material_maker/nodes/sdcirclerepeat.mmg 中，这是一个 JSON 格式的节点定义文件，包含 shader_model（shader 代码模板）、输入、输出与参数描述，是理解该节点的第一手依据。

输入与输出约定

输入：单个 SDF 输入

sdCircleRepeat 只接受一个输入，类型为sdf2d（2D 有向距离函数）。节点定义中该输入的声明如下（节点定义）：

• 参数名：in
• 类型：sdf2d
• 说明：输入形状，定义为有向距离函数（longdesc: "The input shape, defined as a signed distance function"）
• 默认值：0.0

任何能输出 sdf2d 的节点都可以直接连入，例如 sdCircle、sdBox、sdLine、sdPolygon、sdStar5 等基础形状，也可以连入其他算子节点的输出，实现"先组合、再圆周重复"的嵌套图案。

输出：重复后的 SDF

输出类型同样为sdf2d，语义是"重复操作生成的形状"。在 shader 模型中，输出值由输入值$(name_uv)_in直接承接（节点定义），也就是说：输出的是一整圈重复后的新 SDF 值，可直接继续接入下游的布尔、变形、平滑算子，最终交给 sdShow 渲染。

注意：输出仍是 SDF，不是图像。要看到实际图案，必须再接一个 sdShow 节点（或者经由后续 SDF 算子后再输出），这与所有 2D SDF 节点一致（体系说明）。

参数详解：Count 与 Variations

节点定义了两个参数（参数声明）：

Count：圆周上的副本数量

Count控制输入形状在圆周上的重复份数。从节点定义看，它声明为type: "float"、step: 1、min: 1、max: 32、default: 4，即整数值 1～32，默认 4。

在 base.json 的默认实例 中，该节点创建时的初始参数被设为c: 6.0（6 份副本），而 sdcirclerepeat.mmg 内的默认 shader 参数同样是c: 6。也就是说：实际在编辑器里拖入该节点时，默认会出现 6 个副本（与文档配图、库默认实例一致），手动调整参数范围是 1～32。

Count 在 shader 中直接参与角度切分计算：6.28318530718/count把整圆（2π）均分为 count 份，每一份的扇形角度为 2π/count。副本数越大，每个副本的扇形越窄、图案越密集；副本数越小（如 1、2），重复越少，接近原始形状。

Variations：副本的随机变体

Variations是一个布尔开关，勾选后会对输入启用"变体采样"，使圆周上每个副本的输入形状出现随机的形态差异（例如随机缩放、旋转或形状变化），从而让重复图案看起来更自然、更有手工感，避免完全机械复制。

在 shader 模型中，变体开关对应的代码是（shader 代码）：

float $(name_uv)_ids = $variations ? rand(vec2((floor(fract((0.15915494309*atan($uv.x - 0.5, $uv.y - 0.5) - 0.5 / $c)) * $c) / $c))) + $seed : 0.0; float $(name_uv)_in = $in.variation(circle_repeat_transform_2d($uv-vec2(0.5), $c)+vec2(0.5), $(name_uv)_ids);

当variations为 true 时，会为每个扇区计算一个随机 id（_ids），并将该 id 作为"变体种子"传入输入函数$in.variation(...)。这依赖 Material Maker 引擎的变体机制：所有节点的实例函数都会被注入float _seed_variation_, vec4 _controlled_variation_两个变体参数（gen_shader.gd），而对带.variation后缀的输入调用，生成器会按参数个数决定是追加"种子变体 + 受控变体"还是只追加"受控变体"（gen_shader.gd）。

此外，节点还带有一个seed_int种子字段（节点定义），用于固定变体随机序列，便于复现相同的变体效果。种子在引擎侧通过seed_int / MAX_SEED归一化参与随机采样（gen_base.gd）。

提示：只有当输入形状本身"支持变体"（即其 shader 实现响应 variation 采样）时，Variations 开关才有实际效果。对于简单的基础形状，变体主要体现为随机的缩放/形变组合；而像 sdNgon 这类由多个子算子组合出的形状，变体效果会通过其输入链逐级传递（见下文原理小节）。

工作原理：圆上均匀分布的坐标变换

sdCircleRepeat 的实质是一个周期性的旋转-折叠坐标变换：把 UV 坐标围绕圆心逐扇区"折叠"到基准扇区，使得同一份输入形状在每个扇区中被重复渲染。其核心全局函数定义在节点 shader 的global段中（全局函数）：

vec2 circle_repeat_transform_2d(vec2 p, float count) { float r = 6.28318530718/count; // 每份的角跨度：2π / count float pa = atan(p.x, p.y); // 当前像素的极角 float a = mod(pa+0.5*r, r)-0.5*r; // 折叠到以 0 为中心的基准角区间 [-r/2, r/2] vec2 rv; float c = cos(a-pa); // 旋转补偿角 float s = sin(a-pa); rv.x = p.x*c+p.y*s; // 旋转坐标 rv.y = -p.x*s+p.y*c; return rv; }

该函数的计算过程可拆解为四步：

1. 计算扇区角宽：r = 2π / count，即每个副本占据的角度；
2. 求像素极角：pa = atan(p.x, p.y)，得到当前采样点相对圆心的角度；
3. 折叠到基准扇区：a = mod(pa + r/2, r) - r/2，把任意角度映射到[-r/2, r/2]的基准区间内；
4. 旋转补偿：构造旋转矩阵[[cos(a-pa), sin(a-pa)], [-sin(a-pa), cos(a-pa)]]，把采样点绕圆心旋转回基准扇区对应的位置。

随后节点主代码执行坐标平移并对输入采样：

float $(name_uv)_in = $in.variation(circle_repeat_transform_2d($uv-vec2(0.5), $c)+vec2(0.5), $(name_uv)_ids);

即先把 UV 平移到以圆心为原点（减去(0.5, 0.5)），经过折叠变换后再平移回纹理坐标空间（加回(0.5, 0.5)），最后对输入 SDF 采样。由于每个扇区的采样点都被折叠到同一基准扇区，输入形状就在圆周上被等角复制 count 份。

值得说明的是，这一"围绕圆心重复"的思想并不仅用于此一个节点：SDF 构建器中的sdNgon 正多边形形状正是"旋转 + sdcirclerepeat + sdngon"三个算子组合的产物（ngon.gd），可见"圆重复"是构建对称几何的基础能力。圆形重复相当于"按角折叠"，与 sdRepeat 的"按距离重复"（矩形网格重复）形成互补，两者分别适用于极坐标对称与直角网格两类图案。

在编辑器中的使用方式

在 Material Maker 中新建/打开一个 2D SDF 材质图后，按以下步骤使用 sdCircleRepeat：

1. 添加节点：在节点树（Library 面板）中依次展开Simple / SDF / Operators，双击sdCircle Repeat（或使用 Add Node 弹窗搜索 "sdCircle Repeat"），节点即以默认参数（Count=6、Variations 关闭）加入画布（库注册条目）。
2. 连接输入：把一个基础 SDF 形状节点（如 sdCircle、sdBox、sdPolygon、sdStar5）的输出连接到 sdCircleRepeat 的输入端口（sdf2d）。注意输入形状应位于靠近圆心的位置，这样圆周重复后副本才会分布在圆周上形成环形图案；若输入形状远离圆心，副本会围成半径更大的环形。
3. 连接输出：把 sdCircleRepeat 的输出接到sdShow节点的输入，最终渲染为灰度图预览（SDF 体系说明）。也可继续接入 sdBoolean、sdSmoothBoolean 等其他算子后再输出。
4. 调整参数：选中 sdCircleRepeat 节点，在参数面板中修改：
   • Count：改为 8、12、16 等，观察副本密度变化；最小 1（不重复），最大 32；
   • Variations：勾选后每个副本将产生随机形态差异；配合节点的种子（seed）可固定随机效果。
5. 预览与导出：在 2D 预览面板查看结果，满意后经输出节点导出为纹理。

如果你希望拷贝一个与文档一致的参考实现，可以在仓库 examples 目录 中搜索使用到该节点的示例材质（如 doc_tools、skulls 等 ptex 工程文件），用 Material Maker 打开即可查看完整节点图。

与 3D CircleRepeat 的对照

仓库还包含功能对等的 3D 版本CircleRepeat节点（3D 文档），其输入/输出均为sdf3d类型，参数同样是 Count 与 Variations。两者唯一显著的差异是：

• 2D 版本直接对平面坐标做圆周折叠，输入形状可位于任意半径处；
• 3D 版本要求源对象必须沿正 Y 方向偏离中心偏移（"The source object must be offset in the positive Y direction from the center"），因为 3D 场景中圆形重复是绕 Y 轴旋转复制，输入对象需要先偏移到旋转半径上。

因此在 3D 节点图中使用 CircleRepeat 时，记得先用 Translate 类变换把形状沿 +Y 偏移，否则重复结果会挤在圆心处。

小结与实战建议

• sdCircleRepeat 接受单个sdf2d输入，输出圆周重复后的sdf2d，必须经 sdShow 等节点渲染为可见图像；
• Count（内部名c）：float 型，1～32，默认 6（节点定义默认 4，库实例与 shader 默认 6），控制圆周副本数量；
• Variations：布尔开关，默认关闭；开启后利用引擎的_seed_variation_变体机制为每个副本注入随机种子，产生差异化副本；节点自带seed_int可固定随机序列；
• 底层通过circle_repeat_transform_2d()把 UV 逐扇区折叠到基准角区间再采样输入，实现"一入多出"的圆周复制；
• 与 sdRepeat（直角网格重复）配合，几乎可以覆盖对称类程序化纹理的绝大多数重复需求；
• 想生成齿轮、轮辐、花瓣、雪花或环形装饰，只需换用不同输入形状并调节 Count 与 Variations 即可。

参考路径

• 节点文档原文：material_maker/doc/node_simple_sdf_operators_sdcirclerepeat.rst
• SDF 节点体系总览：material_maker/doc/node_simple_sdf.rst
• 节点实现定义：addons/material_maker/nodes/sdcirclerepeat.mmg
• 库注册与默认实例：material_maker/library/base.json
• 变体机制实现：addons/material_maker/engine/nodes/gen_shader.gd
• 种子处理：addons/material_maker/engine/nodes/gen_base.gd
• 3D 对应版本文档：material_maker/doc/node_3d_sdf_operators_circlerepeat.rst

• 桌面应用
• 图形学
• 3D渲染
• 图像处理