Smart Align Node

中文

Smart Align Node 是一款 Blender 节点编辑器对齐插件，适用于几何节点、材质/着色器节点、合成节点以及其他节点树。

版本说明

从 v0.11.0 开始，本项目采用语义化版本。此前的 1.x 版本属于早期开发版本，版本号命名不规范；这些记录会保留在更新日志中作为历史参考，后续版本将从 v0.11.0 继续向 v1.0.0 推进。

功能

• 将所选节点向左、向右、向上或向下对齐。
• macOS 默认快捷键：Command + Shift + 左/右/上/下。
• Windows/Linux 默认快捷键：Ctrl + Shift + 左/右/上/下。
• 可在插件偏好设置中自定义方向键与修饰键。
• 可调整节点间距，减少节点连线被遮挡的情况。
• 保持非对齐轴不变：上下对齐不会横向移动节点，左右对齐不会纵向移动节点。
• 在尽量贴近目标对齐效果的同时避免节点视觉重叠。
• 当选中的 Frame 与外部节点一起对齐时，将 Frame 作为顶层节点参与排列。
• 当选中 Frame 及其内部节点时，可将内部节点对齐到 Frame 的内部边界。
• 多个选中的 Frame 会像普通节点一样参与对齐与间距计算。
• 重复执行 Frame 内部对齐时，会恢复 Frame 与子节点位置，避免累积漂移。
• 使用平台感知的视觉边界计算，使 macOS 与 Windows 上的节点间距尽量保持一致。

安装

1. 下载 Smart_Align_Node.zip 或 Align_Node.zip。
2. 在 Blender 中打开 Edit > Preferences > Add-ons。
3. 点击 Install... 并选择 zip 安装包。
4. 启用 Smart Align Node。

你也可以从源码安装：将 Align_Node 文件夹复制到 Blender 的插件目录。为了兼容已有安装结构，插件包目录仍保留为 Align_Node，但 Blender 中显示的插件名称是 Smart Align Node。

使用

在节点编辑器中选择两个或更多节点，然后按：

• macOS：Command + Shift + 方向键
• Windows/Linux：Ctrl + Shift + 方向键

插件会对齐所选节点的目标边缘，并且只在视觉边界可能碰撞时，沿当前操作方向拉开节点。

偏好设置

打开 Edit > Preferences > Add-ons > Smart Align Node。

可用设置：

• 左、右、上、下四个方向的快捷键。
• 修饰键：Ctrl、Shift、Alt、Command。
• Node Gap：碰撞避让后保留的额外节点间距，默认值为 24。

修改快捷键后，点击 Apply Node Align Shortcuts 使设置生效。

调试节点边界

你可以在插件偏好设置或节点编辑器菜单中使用 Debug Selected Node Bounds。插件会将所选节点的计算边界写入 Blender 文本块 Smart_Align_Node_Bounds_Debug；如果 Blender 允许，也会同时复制到剪贴板。

调试输出会包含 Blender 可提供的 location_absolute、插件使用的高度规则、其他高度候选值、父级/折叠状态以及 socket 元数据。执行 Frame 内部对齐后，还会包含最近一次 Frame 内部对齐诊断信息，方便比较操作前后的边界与漂移情况。

开发

在仓库根目录运行单元测试：

python3 -m unittest tests/test_alignment_logic.py

构建可安装的 zip：

zip -r Smart_Align_Node.zip Align_Node -x 'Align_Node/__pycache__/*'

维护者

Anthem

English

Smart Align Node is a Blender node editor alignment add-on for Geometry Nodes, shader/material nodes, compositor nodes, and other node trees.

Versioning

Starting with v0.11.0, this project uses semantic versioning. Earlier 1.x releases were early development builds with non-standard version numbering. They are kept in the changelog for historical reference, but future releases will continue from v0.11.0 toward v1.0.0.

Features

• Align selected nodes to the left, right, top, or bottom edge.
• macOS default shortcut: Command + Shift + Left/Right/Up/Down.
• Windows/Linux default shortcut: Ctrl + Shift + Left/Right/Up/Down.
• Customizable keys and modifiers in the add-on preferences.
• Configurable node gap for keeping links readable.
• Preserves the non-alignment axis. Up/Down never shifts nodes sideways, and Left/Right never shifts nodes vertically.
• Avoids visual overlap while keeping the layout as close as possible to the requested alignment.
• Treats selected Frames as top-level nodes when they are aligned with outside nodes.
• Aligns selected nodes inside a selected Frame to the Frame's inner boundary.
• Multiple selected Frames follow the same alignment and spacing rules as regular nodes.
• Repeated Frame-internal alignment restores Frame and child-node positions to avoid accumulated drift.
• Uses platform-aware visual bounds so spacing remains consistent on macOS and Windows.

Installation

1. Download Smart_Align_Node.zip or Align_Node.zip.
2. In Blender, open Edit > Preferences > Add-ons.
3. Click Install... and choose the zip file.
4. Enable Smart Align Node.

You can also install from source by copying the Align_Node folder into Blender's add-ons directory. The package folder is still named Align_Node for compatibility, while the add-on display name is Smart Align Node.

Usage

Select two or more nodes in a node editor, then press:

• macOS: Command + Shift + Arrow
• Windows/Linux: Ctrl + Shift + Arrow

The add-on aligns the selected edge and only spreads nodes along the movement axis when their visual bounds would collide.

Preferences

Open Edit > Preferences > Add-ons > Smart Align Node.

Available settings:

• Shortcut keys for Left, Right, Up, and Down.
• Modifier keys: Ctrl, Shift, Alt, Command.
• Node Gap: extra spacing between nodes after collision avoidance. The default value is 24.

After changing shortcuts, click Apply Node Align Shortcuts.

Debugging Bounds

Use Debug Selected Node Bounds in the add-on preferences or the node editor menu. The add-on writes the selected nodes' calculated bounds to a Blender text block named Smart_Align_Node_Bounds_Debug and also copies the output to the clipboard when Blender allows it.

The debug output includes location_absolute when Blender exposes it, the height rule used by the add-on, alternative height candidates, parent/collapse state, and socket metadata. After a Frame-internal alignment, it also includes the last internal Frame alignment diagnostics so boundary and drift behavior can be compared before and after the operation.

Development

Run the unit tests from the repository root:

python3 -m unittest tests/test_alignment_logic.py

Build the installable zip:

zip -r Smart_Align_Node.zip Align_Node -x 'Align_Node/__pycache__/*'

Maintainer

Anthem