画布背景 · Canvas Background

📖 功能概述

这是 LK 自动排版体系的核心执行组件，兼具两项独立功能：

📥 输入参数

名称	类型	必填	说明
曲线 (C)	Curve	必需	需要添加到画布背景的曲线列表。组件会进行镜像变换（关于 ZX 平面），让曲线在 Grasshopper 画布上正确显示。该输入端默认隐藏。
以下参数仅在模式二（按钮 2 开启后）显示：
矩形框 (R)	Curve	可选**	定义电池移动目标位置的矩形框列表。每个矩形框对应目标组件应该移动到的位置区域。必须是闭合曲线。
名称列表 (N)	Text	可选**	电池分组的名称列表。用于将矩形框索引与目标名称匹配。

** 仅在模式二开启后可见及有效。

📤 输出参数

名称	类型	说明
无输出（模式一）	—	模式一只绘制背景，不输出数据。
以下参数仅在模式二开启后显示：
程序名称列表 (N)	Text	通过 SelectedComponents 识别出的各矩形框中「Connected」或「LK_Rename Object」组件输入端数据源的昵称列表。
重复名称列表 (N)	Text	如果程序名称列表中存在重复项，这里会列出所有重复的名称。用户可通过此输出排查命名冲突。

🔘 双按钮操作

组件带有两个按钮，功能各不相同：

按钮	操作	效果
按钮 1（默认）	点击触发	执行背景曲线绘制。将输入的曲线镜像变换后更新到画布背景。
按钮 2（扩展）	点击切换开关	切换模式二的开/关状态。开启时，组件会显示额外的输入/输出参数，并在求解时执行电池移动逻辑。按钮状态通过 Write / Read 持久化保存。

🎨 功能一：背景绘制

当组件求解时，ProcessBackgroundDrawing 方法执行以下操作：

• 读取输入的曲线列表
• 对每条曲线执行 ZX 平面镜像变换（Transform.Mirror(Plane.WorldZX)）
• 镜像后的曲线赋值到 Curves 属性
• Curves 属性的 setter 被重写，自动将新曲线传给自定义属性中的 ListCurves
• 自定义属性 GUIButton 在画布渲染时将曲线绘制到背景层

📦 功能二：电池自动排版

当按钮 2 开启时，组件在求解后会额外执行 ProcessComponentMoving 方法。这是一个复杂的电池自动排版流程：

整体流程

步骤① — 矩形框预处理

• 验证所有矩形框均为闭合曲线，非闭合时报错
• 全部执行 ZX 平面镜像，适应 GH 坐标
• 计算需要额外添加的矩形框数量（自动补齐到 50 + 当前组件数 - 矩形框数）
• 以最后一个矩形框为基础，沿 Y 轴逐个复制填充

步骤② — 识别寻址名称

通过 SelectedComponents.RunScript 分析每个矩形框内的组件：

• 找出昵称为 "Connected"、"LK_Rename Object" 或 "RN" 的组件
• 读取其第一个输入端的连线数据源
• 提取数据源的昵称作为该组的「寻址名称」
• 检查名称唯一性——重复名称报错并终止

步骤③ — 匹配目标位置

• 用户通过「名称列表」（N）输入每个电池组应该去往的目标矩形框索引
• 将步骤②识别出的「当前名称列表」与用户输入的「目标名称列表」一一对应
• 未匹配到的名称默认偏移到左侧（原 X - 框宽）

步骤④ — 移动电池组

• 计算每个矩形框的中心点
• 为每个电池组计算从当前位置到目标位置的 PlaneToPlane 变换矩阵
• 应用变换，移动组内所有电池组件的 Attributes.Pivot 到新位置
• 调用 ExpireLayout() 刷新布局

🧪 典型使用场景

场景	说明
自动排版系统	配合 LKWireframe、AutoConnect、RenameObject 组成完整的 LK 自动排版流水线。
批量对齐电池	在大型 Grasshopper 程序中，用矩形框将混乱的电池分组调整到整齐的网格布局中。
背景辅助线	仅使用模式一，在画布上绘制分区背景，帮助视觉理解程序结构。

⚠️ 注意事项

• 不可逆操作：电池移动功能（模式二）会直接修改画布上组件的位置，无法撤销。使用前务必备份。
• 名称唯一性：如果「程序名称列表」（输出 0）出现重复，组件会报错并终止。请确保每个寻址组件有唯一名称。
• 模板要求：电池移动功能依赖于特定的模板结构——每个矩形框中需要包含命名为 Connected / LK_Rename Object / RN 的组件来作为寻址标记。
• 矩形框必须闭合：所有输入的矩形框曲线必须闭合，否则组件报错。
• C 输入端默认隐藏：曲线输入（C）是隐藏参数，不会在组件体上显示端口，连接后才会出现。
• 按钮 2 状态持久化：通过 Write/Read 序列化保存到 .gh 文件中。
• 源码文件为 CanvasBackground.cs，类位于 LK.Component.LK_GUI 命名空间。

📋 组件信息

名称	画布背景
英文名	Canvas Background
分类	LK → GUI
基类	GH_Component（自定义 UI 属性 + 双按钮）
GUID	{FF17E09A-FC16-4305-A762-8A55A342EF60}