Implement arrangement framework for node groups

- Introduced `frames.py` to manage field complex calculations and their arrangement within node groups.
- Added functionality to create and remove field frames based on node arrangements.
- Developed `passages.py` to find unobstructed paths for connections around calculation frames.
- Implemented `references.py` to route shared results on peripheral tracks, ensuring efficient distribution of outputs.
- Created `sections.py` to reserve space for field calculations adjacent to geometry consumers.
- Added `sources.py` to position shared calculation sources effectively beside their distribution channels.
- Enhanced outline smoothing with `outline_smoothing.py` to adapt camera depth along original outlines.

openspec/changes/compact-repeat-node-arrangement/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-11

openspec/changes/compact-repeat-node-arrangement/design.md

@@ -0,0 +1,21 @@
+## Context
+
+排列器以几何主链、取值支线及共享引用组织节点。循环目前额外计算支线宽度并预留两端间距。
+
+## Goals / Non-Goals
+
+目标是让循环执行步骤紧凑可读，并保持前置几何处理的横向先后关系。
+
+## Decisions
+
+- 预览层从完整区域成员中筛选几何执行主链，取值计算复用支线排列流程。
+- 横向列依赖保留实际几何来源，局部引用端口保持连接顺序。
+- 使用真实 Depth Cutout 和小型循环验证布局、连接及几何求值。
+- 简单计算链在有限高度内纵向分段，复杂支线按消费者形成独立 Frame。
+- 支线按实际消费输入与连通依赖分组，计算流程保持连续展开。
+- 几何引用线同时处理向前与回向连接，水平通道统一避让节点、支线及已有通道。
+- 引用线的高差通过有横向展开的斜向曲线过渡。
+
+## Risks / Trade-offs
+
+支线引用循环数据时可能需要回向连线；通过分离主链通道和支线区域保证可读性，并验证几何连接语义保持一致。

openspec/changes/compact-repeat-node-arrangement/proposal.md

@@ -0,0 +1,22 @@
+## Why
+
+Repeat 为取值支线预留宽度，导致单个 Set Position 的循环被拉长，前置循环的处理顺序也难以辨认。
+
+## What Changes
+
+- 按循环执行主链排列 Repeat 两端，取值支线独立排列。
+- 几何处理节点按真实上游依赖确定先后位置。
+- 更新排列测试、节点资产和交互预览。
+- 将长计算链紧凑排列，为复杂支线添加 Frame，并分离几何引用线通道。
+
+## Capabilities
+
+### New Capabilities
+
+- `compact-repeat-arrangement`: 紧凑呈现循环执行主链并保持几何处理顺序。
+
+### Modified Capabilities
+
+## Impact
+
+涉及 `tools/nodes/arrangement`、`tools/nodes/preview`、相关测试和 `O_AnyImage.blend`。

openspec/changes/compact-repeat-node-arrangement/specs/compact-repeat-arrangement/spec.md

@@ -0,0 +1,64 @@
+## ADDED Requirements
+
+### Requirement: Compact repeat execution path
+
+排列器 SHALL 按循环执行的几何步骤安排 Repeat 两端，取值支线独立排列。
+
+#### Scenario: Set Position loop with long value calculations
+- **WHEN** 循环只执行 Set Position，输入值来自长计算链
+- **THEN** Repeat 两端保持围绕 Set Position 的紧凑排列，预览执行区域按几何主链确定
+
+### Requirement: Geometry processing order
+
+排列器 SHALL 将前置循环安排在后续几何处理之前。
+
+#### Scenario: Depth Cutout boundary smoothing
+- **WHEN** 排列 O Image Depth Cutout 的前置边界平滑循环
+- **THEN** 循环位于其后续几何消费者左侧，保持原有连接与求值结果
+
+### Requirement: Readable field branches and geometry references
+
+排列器 SHALL 将取值支线紧凑安排在消费者附近，复杂支线使用互不重叠的 Frame，并分离几何引用的水平通道。
+
+#### Scenario: Long calculation chain
+- **WHEN** 消费者使用较长的简单计算链
+- **THEN** 计算链使用紧凑折叠及分段纵向布局
+- **AND** 连续依赖按计算方向展开，独立计算按实际消费输入分组
+
+#### Scenario: Complex depth cutout branches
+- **WHEN** 排列 O Image Depth Cutout
+- **THEN** 复杂计算支线分别成框，几何引用线保持独立的水平通道，并通过斜向曲线过渡，原有几何求值保持一致
+
+#### Scenario: Geometry trunk alongside its consumer frame
+- **WHEN** 几何主干向 Frame 内的计算节点供值
+- **THEN** 主干与完整 Frame 边界保持间距，通过斜向分支接入框内消费者
+
+#### Scenario: Long branch near its geometry consumer
+- **WHEN** 较大支线需要占用来源和消费者之间的横向空间
+- **THEN** 主线在消费者之前预留支线及斜向出口的空间，连续主线保持直接向前连接
+
+#### Scenario: Independent calculation before a geometry consumer
+- **WHEN** 支线独立于上游几何结果
+- **THEN** 支线可向主线起点之前展开，主线按实际出口位置保持紧凑
+
+#### Scenario: Return connection and neighboring reference tracks
+- **WHEN** 几何结果连接左侧消费者
+- **THEN** 连线直接向消费者方向过渡，各水平通道按最终范围保留间距
+
+#### Scenario: Geometry fanout without overlapping wires
+- **WHEN** 同一几何结果供多个节点消费
+- **THEN** 近处消费者直接接入，公共水平通道按从左到右分发，每段公共连线只绘制一次
+- **AND** 水平连线保持向前，短 reroute 间距合并，近乎平行的曲线与主线保持间距
+
+#### Scenario: Shared results outside calculation branches
+- **WHEN** 几何或其他类型的结果供多个支线消费
+- **THEN** 共享结果沿支线外围的公共管道分发，在消费者附近斜向接入
+- **AND** 原有主线连接保持执行顺序，公共管道与节点、Frame 及其他管道保留间距
+
+#### Scenario: Geometry transits an unrelated calculation
+- **WHEN** 几何连接沿途经过其他支线
+- **THEN** 整段曲线绕开不消费该结果的 Frame，仅允许进入自身来源或消费者所属的 Frame
+
+#### Scenario: Peripheral producers feed their shared pipes forward
+- **WHEN** 支线计算的结果通过公共管道供多个消费者使用
+- **THEN** 共享计算支线与管道一同位于消费者外围，管道入口在结果输出节点右侧

openspec/changes/compact-repeat-node-arrangement/tasks.md

@@ -0,0 +1,46 @@
+## 1. 排列
+
+- [x] 1.1 分离循环执行主链与取值支线，修正前置循环位置
+- [x] 1.2 更新预览区域和回归测试
+
+## 2. 验证
+
+- [x] 2.1 运行节点资产构建和全量测试
+- [x] 2.2 生成并检查交互预览
+
+## 3. 支线与引用
+
+- [x] 3.1 缩短支线，支持简单计算链纵向排列并靠近消费者
+- [x] 3.2 为复杂支线生成独立 Frame，并同步预览与坐标处理
+- [x] 3.3 统一几何引用线避让，分离水平通道和回向连线
+- [x] 3.4 更新回归测试、构建资产并完成全量及视觉验证
+
+## 4. 主干与 Frame 间距
+
+- [x] 4.1 为几何主干保留整个 Frame 的边界间距，覆盖相连消费者的 Frame
+- [x] 4.2 验证回归用例、重建资产并更新预览
+
+## 5. 支线消费位置
+
+- [x] 5.1 按较大支线及斜向出口所需空间延长主线，按出口距离选择支线位置
+- [x] 5.2 保留直接向前的主线连接，减少几何引用的外围折返
+- [x] 5.3 验证连接、求值与布局，重建资产并更新预览
+
+## 6. 收紧主线与分离回向连接
+
+- [x] 6.1 去掉回向连接在来源右侧的多余折返点
+- [x] 6.2 按实际出口估算主线间距，独立计算可在起点之前展开
+- [x] 6.3 按最终线段范围分配水平通道并扩大不同来源的间距
+- [x] 6.4 总线按从左到右分发，近处消费者直接接入，分离近乎平行的曲线并检查同源绿线重复覆盖
+- [x] 6.5 重建资产、检查截图区域并完成全量验证
+
+## 7. 共享结果外围管道
+
+- [x] 7.1 合并几何与其他类型的共享引用布线，共用结果沿支线外围就近分发
+- [x] 7.2 绿线绕开不消费该结果的 Frame，并验证实际曲线范围
+- [x] 7.3 验证主线保留、外围间距与连接语义，重建资产并检查预览
+
+## 8. 共享来源与管道入口
+
+- [x] 8.1 将共享结果的计算支线安排在消费者外围，管道从输出右侧开始
+- [x] 8.2 验证入口方向、支线位置及求值，重建资产并更新预览

openspec/changes/unify-boundary-depth-smoothing/design.md

@@ -46,7 +46,7 @@ flowchart TD
 
 | 节点组 | 深度 Blur 影响边界 | 标量与重建方式 |
 | --- | --- | --- |
-| O Image Depth Cutout | 原 Alpha 轮廓及 Split 后的新边界 | 平滑相机 Z；按新旧 Z 比例缩放原相机点，再进入现有投影 |
+| O Image Depth Cutout | 原 Alpha 轮廓及内侧两圈，保护 Split 边 | 按当前残差分批自适应平滑相机 Z；按新旧 Z 比例缩放原相机点，再进入现有投影 |
 | O Image Depth Plane | 有效性剔除及 Split 后的新边界；保护 UV 原矩形外框 | 平滑相机 Z；按原相机射线重建点，再进入现有投影 |
 | O Image Depth Panorama | 球面有效性剔除及 Split 后产生的实际开口 | 平滑有效径向距离；保持球面方向，再进入 Depth Scale 的半径表达式 |
 
@@ -58,6 +58,8 @@ Panorama 的经度接缝和极点依照真实球面拓扑求值；UV 接缝本
 
 ### 节点与资产组织
 
+Depth Cutout 的自适应实现位于 `common/outline_smoothing.py`。公开 `Outline Depth Fix`（默认 16，0–200），每轮重新计算当前相机深度残差，`Boundary Smooth` 提供该轮固定权重 Blur 的步数。残差换算至模型单位后除以置换前、Split 清理后全部边长的中位数，固定通过 0.25–0.5 Smoothstep 得到权重，再乘原轮廓两圈影响范围；不对 Weight 做 Blur。批内 Weight 在 Repeat 输入几何上显式采样，原轮廓对应关系在平面源几何上求值。复用现有切分属性保护 Split 边及交点，不新增命名属性。Cutout 资产及运行时请求版本更新为 21。
+
 公共函数以标量字段为复用边界，三个消费组分别完成相机与球面重建。使用显式域转换及明确源几何采样，所有几何组与嵌套组保持 Capture Attribute 为零。直接连接可复用字段；必要的现有临时命名协议在最后消费者后清理，保留用户属性。
 
 实施时读取当前工作区基线，保留其他修改。完成源码与测试后运行 `uv run node-group build`，更新 `O_AnyImage.blend` 并独立加载验证接口、求值和节点布局。

openspec/changes/unify-boundary-depth-smoothing/proposal.md

@@ -7,7 +7,7 @@ Alpha 轮廓和有效性剔除留下的网格边界仍可能采到突变深度
 - 为 `O Image Depth Cutout`、`O Image Depth Plane`、`O Image Depth Panorama` 统一加入置换前的边界深度平滑。
 - 复用 `Boundary Smooth` 控制深度 Blur 与现有边界网格平滑的迭代数，保留默认值 `5`、范围 `0–20`；`0` 完全关闭两者。
 - 在有效性剔除及 Split 后的连通网格上平滑深度标量，仅应用于可处理边界及邻近两圈，并保持各顶点原投影方向。
-- Cutout 的原 Alpha 轮廓参与深度平滑；Depth Plane 保留原矩形外框保护；Panorama 按球面径向距离处理实际网格边界。
+- Cutout 的原 Alpha 轮廓参与分批自适应深度平滑，Outline Depth Fix 控制批次数、Boundary Smooth 控制每批步数，Ratio 固定 0.25–0.5，保护 Split 切边；Depth Plane 保留原矩形外框保护；Panorama 按球面径向距离处理实际网格边界。
 - 复用公共构建函数，补齐行为测试、全景专项验证与节点资产重建。
 
 ## Capabilities

openspec/changes/unify-boundary-depth-smoothing/specs/boundary-depth-smoothing/spec.md

@@ -2,12 +2,12 @@
 
 ### Requirement: Shared Boundary Smooth control
 
-`O Image Depth Cutout`、`O Image Depth Plane`、`O Image Depth Panorama` SHALL 使用同一 `Boundary Smooth` 输入控制边界深度 Blur 和现有边界网格平滑的迭代数，默认值为 5，范围为 0–20，并保留该输入的既有标识。
+`O Image Depth Cutout`、`O Image Depth Plane`、`O Image Depth Panorama` SHALL 保留 `Boundary Smooth` 输入，Depth Cutout 默认值为 2，另外两组为 5；Cutout 范围为 1–20，另外两组为 0–20。Depth Cutout 使用它控制每轮深度 Blur 的步数和现有边界网格平滑次数；另外两组使用它控制深度 Blur 与网格平滑次数。
 
 #### Scenario: Positive iteration count
 - **WHEN** 用户将任一组的 Boundary Smooth 设为 12
-- **THEN** 深度 Blur 和现有边界网格平滑均使用 12 次迭代
-- **AND** 修改器只提供现有 Boundary Smooth 控制项
+- **THEN** 每批深度 Blur 和现有边界网格平滑均使用 12 次迭代
+- **AND** Depth Cutout 的批次数由 Outline Depth Fix 控制
 
 #### Scenario: Disabled smoothing
 - **WHEN** Boundary Smooth 为 0
@@ -16,7 +16,7 @@
 
 ### Requirement: Topology-local scalar smoothing
 
-系统 SHALL 在有效性剔除及 Split 后、投影前的网格 Point 域对深度标量执行 Weight 为 0.5 的 Blur，并在可处理边界及邻近两圈内应用结果。边界影响权重 SHALL 由边界字段的 2 次 Weight 为 1 的 Blur 与原边界字段取最大值后，排除保护点得到。
+系统 SHALL 在有效性剔除及 Split 后、投影前的网格 Point 域对深度标量执行 Blur，并在可处理边界及邻近两圈内应用结果。Depth Plane 和 Panorama 的 Blur Weight 为 0.5；Depth Cutout 使用当前残差计算的自适应权重。边界影响范围 SHALL 由边界字段的 2 次 Weight 为 1 的 Blur 与原边界字段取最大值后，排除保护点得到。
 
 #### Scenario: Isolated boundary spike
 - **WHEN** 原本平缓的表面在一个可处理边界点具有深度尖刺并启用 Boundary Smooth
@@ -33,7 +33,18 @@
 
 ### Requirement: Cutout silhouette depth smoothing
 
-Depth Cutout SHALL 将原 Alpha 轮廓和 Split 后的新边界纳入深度平滑，并保留现有后置网格平滑的原轮廓保护规则。
+Depth Cutout SHALL 仅将原 Alpha 轮廓及内侧两圈纳入自适应深度平滑，保护 Split 切边及其与原轮廓的交点。后置网格平滑保持既有职责。对外轮廓术语 SHALL 统一使用 Outline，与 Fine Outline 一致。
+
+#### Scenario: Adaptive batches
+- **WHEN** Outline Depth Fix 大于 0 且 Boundary Smooth 大于 0
+- **THEN** 每轮根据当前相机深度与 Weight 0.5 的一步 Blur 之差，乘 Uniform Scale 后除以置换前、Split 清理后所有网格边长的中位数
+- **AND** Ratio 固定以 0.25–0.5 的 Smoothstep 映射到 0–1，并乘轮廓影响范围
+- **AND** Weight 不再 Blur，批内固定使用 Boundary Smooth 次，每轮重新计算
+- **AND** Outline Depth Fix 默认 16，范围 0–200；0 关闭轮廓深度处理
+
+#### Scenario: Split boundary preservation
+- **WHEN** Split 在原轮廓内形成新的切边
+- **THEN** 深度平滑保持这些切边的相机采样不变，包括与原轮廓相交的切分点
 
 #### Scenario: Fine Outline with zero thickness
 - **WHEN** Fine Outline 的原轮廓存在异常深度，Thickness 为 0 且 Boundary Smooth 大于 0
@@ -88,3 +99,21 @@ Cutout 和 Depth Plane SHALL 在深度平滑阶段保持原相机射线，通过
 - **WHEN** 执行节点资产构建并在独立 Blender 进程中重新加载保存资产
 - **THEN** 资产与源码构建结果通过相同的行为验证
 - **AND** 公共参数、节点连接和 Capture 禁用检查通过
+
+### Requirement: Simplified Cutout shaping controls
+
+Depth Cutout SHALL 固定前后法线平滑为 100 次，原联动宽范围滤波固定为 512 次；移除 Normal Smooth 输入。系统 SHALL 删除 Edge Round 输入及对应前表面位移、厚度补偿和圆化字段，保留 Split 基础收口。
+
+#### Scenario: Reduced interface
+- **WHEN** 新建 Depth Cutout
+- **THEN** Outline Depth Fix 默认 16、Boundary Smooth 默认 2
+- **AND** 输入中没有 Edge Round、Normal Smooth 或 Outline Smooth Iterations
+
+### Requirement: Cutout Options order and inflation factor
+
+Depth Cutout 的 Options SHALL 按 Cleanup Threshold、Smooth Weight、Reference Depth、Boundary Smooth、Outline Depth Fix、Front Inflation 排列。Front Inflation SHALL 为 0–1 Factor、默认 0；Boundary Smooth SHALL 为 1–20、默认 2。
+
+#### Scenario: New Cutout defaults
+- **WHEN** 新建 Depth Cutout
+- **THEN** Front Inflation 为 0，Boundary Smooth 不能从界面设为小于 1
+- **AND** Outline Depth Fix 保持默认 16

openspec/changes/unify-boundary-depth-smoothing/tasks.md

@@ -26,3 +26,29 @@
 
 - [x] 5.1 运行 uv run node-group build，更新 O_AnyImage.blend 和必要资产版本标识，在独立 Blender 进程中加载并验证。
 - [x] 5.2 运行相关节点及 Operator 测试，确认正常退出；核对源码与资产的一致性、最终差异和旧引用，保留已有其他修改。
+
+## 6. Cutout 轮廓自适应深度平滑
+
+- [x] 6.1 固定 Ratio 0.25–0.5，按当前深度分批更新权重，删除 Weight Blur，保护 Split 切边并沿原相机射线重建。
+- [x] 6.2 公开 Outline Smooth Iterations，Boundary Smooth 兼作每批深度步数，更新资产版本及行为测试。
+- [x] 6.3 构建验证节点资产，运行相关回归并保存可调实图文件。
+
+## 7. Cutout 输入与轮廓形状精简
+
+- [x] 7.1 固定法线平滑 100、Boundary Smooth 默认 2，Outline Depth Fix 默认 16，彻底删除 Edge Round 形状调整与输入。
+- [x] 7.2 更新相关行为测试和版本标识，构建验证资产并刷新可调样例。
+
+## 8. Cutout Options 接口
+
+- [x] 8.1 Front Inflation 改为 0–1 Factor、默认 0；Boundary Smooth 最小值 1；Options 按 Cleanup Threshold、Smooth Weight、Reference Depth、Boundary Smooth、Outline Depth Fix、Front Inflation 排列。
+- [x] 8.2 更新接口与默认行为测试、重建验证资产并刷新可调样例。
+
+## 9. Plane 与 Balloon Options 统一
+
+- [x] 9.1 Depth Balloon 前三项为 Cleanup Threshold、Smooth Weight、Reference Depth；Depth Plane 前三项为 Smooth Weight、Reference Depth、Boundary Smooth，Boundary Smooth 默认 2，法线平滑固定 100 并移除输入。
+- [x] 9.2 Depth Plane Split Threshold 默认 0.1；验证接口及厚度行为，更新版本并重建验证资产。
+
+## 10. Cutout 求值精简
+
+- [x] 10.1 Front Inflation 为零时旁路膨胀计算，移除共用平滑中的固定选择节点和未使用 Repeat 通道，统一 outline 平滑内部命名。
+- [x] 10.2 验证零值及连续膨胀行为、共用平滑结果与性能，重建验证资产。