🧩JSON-SQLite DBJsonReader

所在模块：yingzao.ancientArchi.utils.DBJsonReader

YingZaoComponent
YingZaoComponent

功能概述

DBJsonReader 是一个面向 Rhino 8 / GhPython 的数据库读取与 JSON 解析工具类，用于从 SQLite 表中读取指定字段，并支持两种输出模式：

  1. 按 JsonPath 提取 JSON 内部的目标值（输出到 Value）。
  2. 在 ExportAll=True 时，展开整棵 JSON 的叶子节点并输出键值对列表（输出到 All）。

若目标字段不是 JSON 字符串，则直接返回原始字段值。

适用场景

  • 从构件数据库中读取参数字段（如 params_json）
  • 在 Grasshopper 中按路径读取某一层级参数
  • 快速将 JSON 参数平铺为可视化键值列表，便于调试与连线输出

输入参数

参数 类型 说明
db_path str SQLite 数据库路径；支持通过文档默认路径回退解析
table str 表名
key_field str 过滤字段名（可选）
key_value any 过滤字段值（与 key_field 配对使用）
field str 要读取的目标字段
json_path list[str] JSON 路径（多层键名列表，逐层向下取值）
export_all bool 是否导出全部 JSON 叶子节点
ghenv GhPython 环境对象 用于设置组件 Message（可选）

输出结果

run() 返回三元组：

  • value：按 json_path 提取到的值；若字段非 JSON，则为字段原始值
  • all_pairs：当 export_all=True 且字段可解析为 JSON 时，返回 (name, value) 列表；否则为 None
  • log：处理过程日志，用于排错和追踪数据来源

核心行为说明

  • 输入校验阶段会检查：
    • 数据库路径是否可解析且文件存在
    • table、field 是否为空
  • 读取逻辑使用 SELECT field FROM table ... LIMIT 1，仅取首条匹配记录
  • JSON 解析仅对字符串/字节类型字段尝试 json.loads
  • json_path 逐层访问字典键，若中途键缺失会中断并记录日志
  • export_all_flat 递归展开 JSON：
    • dict 继续下钻
    • 非 dict（含 list）视为叶子值
  • 展平后的键名规则为：
    • 路径用 __ 连接（如 a__b__c）
    • 非字母数字下划线字符会被替换为 _
    • 若首字符为数字，会自动补前缀 _

组件状态提示（Message）

  • JSON OK：字段成功解析为 JSON
  • Field (non-JSON)：字段为普通值，未作为 JSON 处理
  • No DBPath / DB not found / No Table / No Field / No row / DB error：常见输入或访问异常状态

设计要点

  • 兼容“JSON 字段”和“普通字段”两类数据源，降低组件耦合
  • 支持全量平铺导出，便于在 GH 中快速观测参数结构
  • 通过日志与 Message 双通道反馈运行状态，利于可视化调试

🧩 DB Fields To Outputs（.gha）

所在位置：grasshopper/YingZao.GH/Components/DbFieldsToOutputsComponent.cs

YingZaoComponent
YingZaoComponent

功能概述

DB Fields To Outputs 是一个 Grasshopper 动态输出组件，用于把上游传入的数据库字段结果（通常是按顺序组织的 name-value 对）自动展开为多个稳定输出端口。
它的核心作用是：把“可变字段集合”转成“可连接、可复用、可持久化”的 GH 输出结构，减少手工改线。

输入参数

参数 类型 说明
All list 来自 Python 核心或其他上游组件的字段键值对集合（有序）
RefreshOutputs bool 是否在下一次求解时按当前字段结构刷新动态输出端口

输出参数

参数 类型 说明
Log string 组件运行日志（字段数量、schema 状态、刷新提示等）
动态字段输出 item/list/tree（自动推断） 每个字段对应一个输出端口，端口名为字段名

支持的数据解析形式

组件会尽量兼容多种键值对表示，常见包括：

  • Python tuple 字符串（如 (‘field’, value)）
  • IList / object[]（前两项视作 name 与 value）
  • DictionaryEntry、KeyValuePair
  • 带 Key/Value 属性对象
  • 可索引对象（Count + int 索引器）
  • 嵌套可枚举集合中的键值对

若某条数据可转字符串后仍能解析为 tuple，也会被接收。

自动类型推断规则

动态输出端口的访问类型会依据字段值自动判断：

  • 普通值或字符串：item
  • 一层可枚举集合：list
  • 含嵌套可枚举集合：tree

这使同一组件可同时承载标量参数、列表参数和树形参数。

刷新与稳定性机制

  • 当首次运行且检测到字段 schema 时，会自动安排一次初始输出构建。
  • 当 RefreshOutputs 为 true 且当前 schema 与已存 schema 不一致时，会安排刷新重建输出。
  • 若用户请求刷新但 schema 未变化，会在 Log 中提示无需刷新。
  • 若输出端口数量与 schema 不一致，Log 会提示手动触发一次 RefreshOutputs。

Schema 持久化

组件会把字段 schema（字段名 + 访问类型）写入 GH 文档，并在重新打开文件时恢复动态输出布局。
因此下游连线在常规场景下可保持稳定，不会因会话重启而丢失输出结构。

适用场景

  • 把 DBJsonReader 或其他数据库查询组件输出的字段对，快速映射为可直接建模使用的 GH 端口
  • 处理字段集合会变化的参数化流程（分类型、分构件族、分工况）
  • 需要在不中断下游网络的前提下，维护可演进的数据结构输出

🧩 DB Path Provider DBPathProvider

所在模块：yingzao.ancientArchi.utils.DBPathProvider

YingZaoComponent
YingZaoComponent

功能概述

DBPathProvider 用于为当前 Grasshopper 文档注册、维护或清除默认数据库路径（DBPath），作为后续数据库组件（如 DBJsonReader）的统一路径来源。
它把数据库路径配置从“每个组件单独输入”提升为“文档级共享配置”，减少重复连线与路径不一致问题。

输入参数

参数 类型 说明
DBPath str 需要注册为当前 GH 文档默认值的数据库路径
Clear bool 是否清除当前文档已注册的默认 DBPath（默认 False）

输出参数

参数 类型 说明
DBPathOut str | None 当前生效的默认 DBPath；清除或未设置时为 None
DocKey str 当前 GH 文档标识键（用于文档级隔离）
Log list[str] 运行日志（注册、保留、清除、空输入等状态）

核心行为说明

  • 注册默认路径：当 DBPath 有效时，写入当前文档的默认 DBPath。
  • 空输入处理：
    • 若已有默认路径，则保持不变并返回当前值；
    • 若尚未注册默认路径，则返回 None 并记录提示。
  • 清除路径：当 Clear=True 时，移除当前文档的默认 DBPath。
  • 文档级隔离：通过 DocKey 区分不同 GH 文档，避免跨文档污染路径状态。

自动刷新机制

当默认 DBPath 发生变化时，组件会调度一次文档内对象的轻量刷新（ExpireSolution(False)），促使依赖该路径的组件在下一轮求解中读取到最新路径。
为避免重复触发，内部使用 scriptcontext.sticky 做单次调度标记。

典型使用流程

  1. 在画布放置 DBPathProvider，输入数据库文件路径。
  2. 执行一次后，文档级默认 DBPath 被注册。
  3. 下游数据库读取组件可不再重复输入路径，自动回退到该默认值。
  4. 需要切换数据库时更新 DBPath；需要取消默认配置时将 Clear 置为 True。

设计要点

  • 以“文档级默认路径”统一数据库访问入口，提高组件协同稳定性。
  • 保持对空输入和未注册状态的显式日志反馈，便于排查。
  • 与 DBPathContext 协同工作，路径解析逻辑集中、可复用。

🧩 Point Index Viewer FT_PointIndexViewer

所在模块：yingzao.ancientArchi.utils.FT_PointIndexViewer

YingZaoComponent
YingZaoComponent

功能概述

FT_PointIndexViewer 是一个用于 Grasshopper / Rhino 视窗调试的点序号标注工具。
它会从输入几何中自动提取代表点，并为每个点生成对应的索引编号与 TextDot 标注，用于快速检查点集顺序、几何中心位置以及数据结构展开结果。

输入参数

参数 类型 说明
GeoIn list[object] 输入几何对象，可为点、曲线、面、Brep、Mesh、Plane 或其嵌套列表
Size float 标注文字尺寸，默认 1.0
Enable bool 是否生成可预览的编号标注，默认 True
Key str 调试标识字符串，用于日志区分不同组件实例

输出参数

参数 类型 说明
Points list[rg.Point3d] 从输入几何中提取出的代表点列表
Indices list[int] 与点列表一一对应的序号索引
Dots list[rg.TextDot] 用于 Rhino 视窗显示的文本标注对象
Log str 运行日志，记录输入数量、提取点数量、尺寸和启用状态

点提取规则

组件会先对输入进行安全拍平，仅展开真正的容器对象，不拆解 Rhino 几何本体。
随后按几何类型提取代表点：

  • Plane：取原点
  • Point3d / Point：直接取点坐标
  • Curve：优先取面积质心，其次取长度中点，再退回包围盒中心
  • Surface / BrepFace：优先取面积质心，否则取包围盒中心
  • Brep：优先取体积质心，其次面积质心，再退回包围盒中心
  • Mesh：取包围盒中心
  • 其他 GeometryBase：取包围盒中心

若某对象无法成功提取点，则跳过。

核心行为说明

  • 输入支持嵌套列表、.NET List、Array 等容器结构
  • 输出索引从 0 开始，顺序与拍平后的有效点顺序一致
  • 当 Enable=True 时，为每个点创建一个 TextDot
  • 只要 Dots 输出端开启预览，Rhino 视窗中即可显示编号
  • Size 会尽量写入 TextDot 的字体高度属性，但不同 Rhino 版本中显示效果可能存在差异

适用场景

  • 检查点列、顶点列、角点列的顺序是否符合预期
  • 验证几何拍平后的数据对应关系
  • 在建模和装配调试中快速识别构件控制点编号
  • 辅助分析曲线、面、Brep 等复杂对象的代表点位置

设计要点

  • 采用“只展开容器、不展开几何”的策略，避免将 Rhino 对象误拆成底层元素
  • 对不同几何类型采用分层回退的取点策略，提高鲁棒性
  • 输出 Points、Indices 与 Dots 三组结果，兼顾数据计算与视图调试两种用途

如果你要继续整理这一批文档，我也可以按同样格式继续写 GeoAligner_xfm、PlaneRotatorGH、CleanTreeTool。

🧩 清理 TREECleanTreeTool

所在模块：yingzao.ancientArchi.utils.CleanTreeTool

YingZaoComponent
YingZaoComponent

功能概述

CleanTreeTool 是一个用于清理 Grasshopper DataTree 数据结构的纯工具类，主要作用是移除树中无效、空值或不可用的数据项，并保留仍然有效的分支与数据内容。 因为会自动更新改组件的 NickName，因此常用于复制数据的中间组件。 该工具不包含任何 Grasshopper 组件界面操作，适合作为底层数据清洗逻辑在 .ghpy 或其他模块中复用。

核心功能

CleanTreeTool 提供两个静态方法：

方法 说明
is_null_or_invalid(x) 判断单个对象是否应从输出树中移除
clean(tree_in) 清理输入 DataTree，返回移除无效项后的新树

清理规则

以下对象会被视为“应移除”的无效项：

  • None
  • 空字符串 ""
  • 空列表 []
  • 空元组 ()
  • IGH_Goo 对象且：
    • IsNull == True
    • IsValid == False
    • 或其内部 Value 存在 IsValid=False
  • 任意带有 IsValid 属性且其值为 False 的对象

其余对象默认保留。

输入输出

项目 类型 说明
tree_in DataTree[object] 待清理的 Grasshopper 数据树
返回值 DataTree[object] | 原值 | None 若输入为有效 DataTree，返回清理后的新树；若输入为 None，返回 None；若输入不是 DataTree[object]，则直接原样返回

行为说明

  • 清理过程会逐个 branch 遍历
  • 每个 branch 中仅保留通过有效性检查的项目
  • 若某个 branch 在清理后为空，则该 branch 不再写入输出树
  • 返回的是一个新的 DataTree[object]，不会原地修改输入对象

适用场景

  • 清理由多组件串联后产生的空路径、空值和失效几何
  • 在输出到下游建模组件前，压缩并净化数据树
  • 统一处理 IGH_Goo 包装对象与 Rhino 几何对象中的无效值
  • 作为更高层显示组件或树结构整理组件的底层清洗逻辑

设计要点

  • 纯数据工具：不依赖 UI 侧修改逻辑，适合在导入时稳定复用
  • 兼容 GH 类型系统：专门处理 IGH_Goo 包装对象及其内部值
  • 最小副作用：输入不是目标 DataTree[object] 时不强行转换，直接返回原对象
  • 分支保守保留：仅删除空分支，不改变仍有有效数据的路径结构

🧩索引列表FTPlaneFromLists

所在模块：yingzao.ancientArchi.utils.PlaneFromLists

YingZaoComponent
YingZaoComponent

功能概述

FTPlaneFromLists 用于根据点列表与参考平面列表中指定索引的元素，构造一个新的平面对象。
它等价于 Grasshopper 中将 List Item 与 Plane Origin 组合使用：先分别取出一个原点和一个基准平面，再用该原点替换基准平面的原点位置，保留其原有 X/Y 轴方向，生成新的 Plane。

该工具同时提供详细日志输出，适合在 GhPython 中复用和调试。

输入参数

参数 类型 说明
origin_points list[rg.Point3d] 或 rg.Point3d 原点点列表，或单个点
base_planes list[rg.Plane] 或 rg.Plane 基准平面列表，或单个平面
index_origin int 用于选取原点的索引
index_plane int 用于选取基准平面的索引
wrap bool 是否采用环绕索引，默认 True

输出结果

build_plane() 返回四元组：

返回项 类型 说明
base_plane rg.Plane 或 None 从 base_planes 中取出的基准平面
origin_point rg.Point3d 或 None 从 origin_points 中取出的原点
result_plane rg.Plane 或 None 以 origin_point 为原点、以 base_plane 的 X/Y 轴为方向构造的新平面
log list[str] 详细运行日志

核心行为说明

  • 若输入不是 list / tuple，会自动按单元素列表处理
  • 若输入为 None，则返回 None 并记录日志
  • 若列表为空，则返回 None
  • 当索引为 None 时，默认使用 0
  • 当 wrap=True 时，索引越界会按取模方式回绕，行为与 GH List Item 的 Wrap 一致
  • 当 wrap=False 时，越界索引会直接返回 None
  • 仅当选中的对象类型分别为 rg.Point3d 与 rg.Plane 时，才会成功创建 result_plane

构造规则

生成的新平面满足以下条件：

  • 原点：来自 origin_point
  • X 轴方向：继承 base_plane.XAxis
  • Y 轴方向：继承 base_plane.YAxis

也就是说，FTPlaneFromLists 的本质是：

  • 选一个点
  • 选一个参考平面
  • 用这个点替换平面的原点
  • 保持平面方向不变

适用场景

  • 在多个点位上复制同一类方向平面
  • 依据点列与平面列生成成组局部坐标系
  • 在装配、刀具定位、节点构造中快速建立参考平面
  • 替代 GH 中重复的 List Item + Plane Origin 组合，提高脚本可复用性

设计要点

  • 对输入类型较宽容，兼容“单值输入”和“列表输入”
  • 提供与 GH List Item 接近的索引行为，减少脚本和画布逻辑差异
  • 详细日志可帮助定位索引越界、类型不匹配或空输入问题

🧩 点控参考平面·旋转与翻转PlaneRotatorGH

所在模块：yingzao.ancientArchi.utils.PlaneRotatorGH

YingZaoComponent
YingZaoComponent

功能概述

PlaneRotatorGH 用于在 Grasshopper 中基于输入原点与参考平面，按局部轴进行连续旋转，并可对最终轴向执行翻转，输出最终平面及其变换矩阵。
它适合将“参数化角度 + 轴向翻转”统一为稳定的坐标系构造流程，便于后续构件定位、刀具对齐和几何变换。

输入参数

参数 类型 说明
Origin rg.Point3d 平面原点；为空时默认 (0,0,0)
RefPlane rg.Plane 参考平面；为空或无效时默认 GH XY Plane
RotX float 绕平面局部 XAxis 旋转角（弧度）
RotY float 绕平面局部 YAxis 旋转角（弧度）
RotZ float 绕平面局部 ZAxis 旋转角（弧度）
FlipX bool 是否翻转最终平面 X 轴
FlipY bool 是否翻转最终平面 Y 轴
FlipZ bool 是否翻转最终平面 Z 轴

输出参数

参数 类型 说明
Plane rg.Plane 最终结果平面
XAxis rg.Vector3d 最终平面 X 轴单位向量
YAxis rg.Vector3d 最终平面 Y 轴单位向量
ZAxis rg.Vector3d 最终平面 Z 轴单位向量
Transform rg.Transform 从 RefPlane 到 Plane 的 PlaneToPlane 变换
Log str 运算日志（输入回退、旋转步骤、翻转记录）

核心行为说明

  • 参考平面无效时会自动回退为 GH XY Plane
  • 参考平面原点会被强制覆盖为 Origin
  • 旋转顺序固定为：Rx → Ry → Rz
  • 三次旋转均围绕“当前平面的自身轴”进行（局部轴、过平面原点）
  • 翻转在旋转完成后执行
  • 翻转后会重建并正交化轴向，维持稳定右手坐标系

变换定义

输出的 Transform 为：

  • Transform = PlaneToPlane(RefPlane, Plane)

即：可将位于参考平面坐标系下的几何，直接映射到最终平面坐标系。

适用场景

  • 构件局部坐标系参数化控制（角度联动）
  • 刀具朝向、加工基准平面生成
  • 由单一基准平面派生多组方向平面
  • 需要稳定输出轴向和变换矩阵的装配/定位流程

设计要点

  • 输入容错完善（None、无效平面、非数值角度、空布尔）
  • 旋转语义明确（局部轴、固定顺序）
  • 翻转后进行轴正交修复，减少数值漂移和轴错位
  • 日志信息完整，便于在 GH 中定位输入和姿态问题

🧩刀具对齐到木料FTAligner

所在模块：yingzao.ancientArchi.utils.FT_AlignToolToTimber

YingZaoComponent
YingZaoComponent

功能概述

FTAligner 是用于木构加工流程的通用“刀具对位与微调”工具类，可将刀具几何按目标木料面进行姿态匹配，并输出完整变换结果。
它支持单刀具与多刀具批处理、参数智能广播、平面对位与点向对位两种模式，以及旋转、翻转、深度/平面内偏移等后处理控制。

主要输入参数（核心）

参数 类型 说明
ToolGeo 几何 / Guid / 列表 待对位刀具几何（支持 Guid、Brep、Surface、Extrusion、Mesh、Curve 等）
ToolBasePlane rg.Plane 刀具基准平面
ToolContactPoint rg.Point3d 刀具接触点（point_dir 模式必需）
BlockFacePlane rg.Plane 木料目标面平面
BlockTargetPoint rg.Point3d 目标接触点（point_dir 模式必需）
Mode str 对位模式："plane" 或 "point_dir"
ToolDir rg.Vector3d / rg.Line 刀具方向向量（point_dir）
TargetDir rg.Vector3d / rg.Line 目标方向向量
ToolRotDeg float 刀具平面绕本地 Z 轴预旋转角（度）
BlockRotDeg float 目标平面绕本地 Z 轴预旋转角（度）
FlipX/FlipY/FlipZ bool 对目标平面进行局部轴翻转
DepthOffset float 沿主方向（法向或目标方向）附加偏移
MoveU float 沿目标平面 X 方向偏移
MoveV float 沿目标平面 Y 方向偏移

输出参数

参数 类型 说明
AlignedTool 几何或列表 对位后的刀具几何
XForm rg.Transform 或列表 总变换矩阵
SourcePlane rg.Plane 实际参与计算的刀具源平面
TargetPlane rg.Plane 处理旋转/翻转后的目标平面
SourcePoint rg.Point3d 源接触点
TargetPoint rg.Point3d 目标点（含偏移后的结果）
DebugInfo str 或列表 调试信息与失败原因

对位模式说明

  • plane 模式：

    • 使用 PlaneToPlane(SourcePlane, TargetPlane) 完成主对位
    • 适合基于局部坐标系的整体刚体贴合

  • point_dir 模式：

    • 先把接触点平移到目标点
    • 再将 ToolDir 旋转对齐到 TargetDir
    • 适合“点位 + 方向”明确的装配/切削场景

批处理与广播规则

FTAligner 具备智能广播机制，便于一键批量对位：

  • 当 ToolGeo 只有 1 个时：

    • 运算次数取其它参数长度的最大值
    • 标量参数自动广播
    • 短列表用最后一个值补齐

  • 当 ToolGeo 有多个时：

    • 运算次数等于刀具数量
    • 其它参数按同样规则广播/补齐/截断

这使“单刀多姿态”与“多刀并行对位”都可用同一组件完成。

核心处理流程

  1. 输入类型归一化与容错转换（含 Guid 转几何）
  2. 源/目标平面预旋转（ToolRotDeg、BlockRotDeg）
  3. 目标平面轴翻转（FlipX/Y/Z）
  4. 执行主对位（plane 或 point_dir）
  5. 施加微调偏移（DepthOffset、MoveU、MoveV）
  6. 输出变换后几何与调试信息

适用场景

  • 木料加工刀具在构件面上的自动贴合
  • 同一刀具多工位/多姿态批量定位
  • 多刀具并行参数化装配
  • 需要严格追踪变换矩阵与调试日志的自动化流程

设计要点

  • 支持 Rhino 常见几何类型与 Guid 输入，适配 GH 实战数据流
  • 两种对位模式覆盖“坐标系对齐”和“点向约束对齐”两类主需求
  • 预旋转、翻转、偏移可叠加，形成完整工艺姿态控制链
  • 对失败场景返回明确错误信息，便于定位输入问题

🧩刀具切割木料FT_CutTimberByTools

所在模块：yingzao.ancientArchi.utils.FT_CutTimberByTools

YingZaoComponent
YingZaoComponent

功能概述

FT_CutTimberByTools 用于将已完成对位的刀具几何批量作用于木料几何，执行布尔裁切并输出结果与失败项。
组件支持两种裁切模式：默认保留“刀具外部”（差集），或保留“刀具内部”（交集），适合榫卯加工中“开槽去料”与“取交体段”两类工艺流程。

输入参数

参数 类型 说明
Timbers list 木料几何列表（推荐 Brep，也支持 Extrusion / Surface / Mesh）
Tools list 刀具几何列表（推荐封闭 Brep，也支持可转换对象）
KeepInside bool 裁切模式开关：False=差集保留外部；True=交集保留内部

输出参数

参数 类型 说明
CutTimbers list[rg.Brep] 裁切成功的结果 Brep 列表
FailTimbers list 裁切失败的原木料几何（原样保留）
Log list[str] 过程日志（公差、转换、布尔结果、失败原因）

核心流程

  1. 输入几何转 Brep
    自动将 Extrusion / Surface / Mesh 尽量转换为 Brep；不可转换对象会被记录并跳过。

  2. 刀具预处理与合并
    对有效刀具先尝试 BooleanUnion，若成功则优先使用联合刀具进行一次布尔运算；若失败再回退到“逐刀具”处理。

  3. 逐木料执行布尔裁切
    对每个木料按 KeepInside 分支执行：

    • False：BooleanDifference(timber - tools)
    • True：BooleanIntersection(timber ∩ tools)

  4. 失败回退
    若该木料布尔失败或结果为空（交集模式下常见），该木料会进入 FailTimbers，保留原件便于后续检查。

模式说明

  • KeepInside = False（默认）
    保留木料被刀具“切除后剩余”的部分，适用于常规去料加工。

  • KeepInside = True
    保留木料与刀具重叠的内部体，适用于提取交叠段、检查切入体积或反向工艺验证。

容错与稳定性策略

  • 自动读取文档公差（可通过构造参数覆盖）
  • 无刀具时不报错，直接保留原木料
  • 刀具 Union 失败自动回退逐刀具布尔
  • 任一木料失败不影响其他木料继续处理
  • 全流程异常会被捕获并写入 Log，保证输出始终可用

适用场景

  • 对位后刀具对木料批量开槽/削切
  • 多刀具联合加工的结果验证
  • 交集体提取与加工区域分析
  • 自动化流水线中对“失败木料”做分流复检

设计要点

  • 将复杂布尔逻辑封装为类，便于脚本复用与流程集成
  • 优先“联合刀具一次切”，失败再“逐刀具迭代”，兼顾性能与成功率
  • 通过 CutTimbers + FailTimbers + Log 三路输出，兼顾生产结果与调试可追踪性

🧩分°⭢尺+米•宋SongStyleUnitConverter

所在模块：yingzao.ancientArchi.utils.SongStyleUnitConverter_Fen2ChiMi

YingZaoComponent
YingZaoComponent

功能概述

SongStyleUnitConverter 用于将宋式营造尺制中的“分”（以材高体系定义）转换为尺、厘米及指定输出单位，支持按“等材”等级自动换算。
该工具专门处理古建参数化建模中的单位统一问题，适合把构件参数从制度尺度转换到 Rhino/Grasshopper 实际建模尺度。

输入参数

参数 类型 说明
Grade str 等材等级，默认“第四等”；支持中文与英文等级名
Fen float 分值（按材高 15 分体系）
OutUnit str 自定义输出单位，默认 mm
ChiToCm float 1 尺对应厘米值，默认 31.2

输出参数

参数 类型 说明
ChiValue float 分值换算得到的尺值
CmValue float 尺值换算得到的厘米值
CustomValue float 按 OutUnit 指定单位输出的换算值
GradeInfo str 当前等级信息（中英文名、材广、材高）

核心换算逻辑

  1. 按 Grade 获取对应等材记录（材广、材高，单位为寸）。
  2. 以材高为基准，按固定规则计算单分对应寸值：
    单分寸值 = 材高(寸) / 15
  3. 将 Fen 换算为寸，再换算为尺：
    尺值 = Fen × 单分寸值 × 0.1
  4. 尺值可继续转换为 cm、mm、m、dm 等目标单位。

支持的等级输入

支持以下字符串形式：

  • 英文等级名（大小写不敏感），如 First_grade、Fourth_grade
  • 中文等级名，如 第一等、第四等
  • 阿拉伯数字中文格式，如 第4等

不支持数值型等级输入（int/float），这类输入会回落到默认第四等。

支持的输出单位

支持传统与公制单位映射，包括：

  • 传统：丈、尺、寸、分、厘
  • 公制：m、dm、cm、mm

未知单位默认按 mm 处理。

输入容错与稳健性

  • 提供 coerce_float 与 coerce_str，对 GH 中常见的字符串、单项列表输入做兜底转换
  • 空值、非法值自动回退默认参数，避免乘法类型错误
  • 适合在 GhPython 中直接接收面板文本或混合类型输入

适用场景

  • 古建构件参数从制度尺度到建模尺度的统一转换
  • 以等材等级驱动尺寸生成的梁架、斗栱、柱础等模块
  • Grasshopper 中跨组件传参与单位标准化处理

设计要点

  • 以“等材 + 分制”作为核心换算语义，贴合宋式营造参数体系
  • 默认值明确（第四等、31.2 cm/尺、mm 输出），便于开箱即用
  • 输入兼容性强，适配 GH 实际使用中的非严格类型数据流

🧩尺+米⭢分°•宋SongStyleUnitConverter_m2FenDegree

所在模块：yingzao.ancientArchi.utils.SongStyleUnitConverter_m2FenDegree

YingZaoComponent
YingZaoComponent

功能概述

SongStyleUnitConverter_m2FenDegree 用于把“任意常用长度单位”的输入值反向换算为：

  1. 宋尺制长度（ChiValue，单位：尺）
  2. 材分制分度（FenDegree，定义为 1 材高 = 15 分）

它是 Fen2Chi 方向转换器的逆向版本，适合把 Rhino/GH 中的公制尺寸或尺制值统一映射回营造法式参数体系。

输入参数

参数 类型 说明
Grade str 等材等级，默认“第四等”；支持中英文等级名与“第4等”写法
Value float 待换算长度值（支持字符串/列表输入兜底转 float）
ValueUnit str Value 的输入单位，默认 cm（未接线时强制按 cm）
ChiToCm float 1 宋尺对应厘米数，默认 31.2

输出参数

参数 类型 说明
FenDegree float 材分制分度值（1 材高 = 15 分）
ChiValue float 输入值换算后的尺值
GradeInfo str 当前等材信息（中英文名、材广、材高）

核心换算流程

  1. 先将输入 Value 按 ValueUnit 统一换算为尺值 ChiValue
  2. 再依据 Grade 对应的材高（寸）将尺值换算为材分分度 FenDegree

材分换算核心关系：

  • 尺转寸：cun = chi × 10
  • 分度计算：FenDegree = cun × 15 / h_cun
    其中 h_cun 为该等材的材高（寸）

支持的输入单位

支持传统单位与公制单位（不区分大小写）：

  • 传统：丈、尺、寸、分、厘
  • 公制：m、dm、cm、mm

说明：这里的 ValueUnit = fen 是尺制链条中的“尺制分”（1寸=10分），仅用于输入单位解析；输出 FenDegree 是材分制分度，二者语义不同。

等材输入规则

支持：

  • 中文：第一等、第四等、未入等A 等
  • 英文：First_grade、Fourth_grade（大小写不敏感）
  • 数字中文格式：第4等

不建议使用纯数字字符串（如 "4"）作为等级输入；无法识别时回落默认第四等。

稳健性与默认行为

  • 对 Value、Grade、ChiToCm 提供类型兜底转换，减少 GH 输入类型波动导致的错误
  • ValueUnit 在“输入端未接线”时会被强制设为 cm，避免 Persistent Data 干扰默认值语义
  • 非法或未知单位自动按 cm 处理

适用场景

  • 将建模实测尺寸反推为营造法式材分参数
  • 依据等材等级统一归一化构件尺寸输入
  • 在 GH 流程中实现“公制建模值 ↔ 材分制参数”双向闭环

设计要点

  • 与 SongStyleUnitConverter（Fen2Chi 方向）形成互补，构成双向转换体系
  • 明确区分“尺制分”与“材分分度”，避免单位混淆
  • 默认行为稳定，便于在复杂 GH 画布中作为基础转换节点长期复用

🧩尺⭢米•宋ChiToMetric_Chi2Metric

所在模块：yingzao.ancientArchi.utils.ChiToMetric_Chi2Metric

YingZaoComponent
YingZaoComponent

功能概述

ChiToMetric_Chi2Metric 用于将宋尺制长度（尺，Chi）按给定换算基准 ChiToCm（默认 31.2 cm/尺）转换为公制单位输出：米（m）、厘米（cm）和毫米（mm）。
该组件面向 GhPython 数据流做了容错处理，适合在参数化流程中稳定完成尺制到公制的末端输出转换。

输入参数

参数 类型 说明
Chi float 尺值输入；支持 int/float/str，也可输入 list/树（自动取首个可用值）
ChiToCm float 每尺对应厘米值，默认 31.2；支持 int/float/str，也可输入 list/树

输出参数

参数 类型 说明
M float 米值
CM float 厘米值
MM float 毫米值

核心换算逻辑

设输入尺值为 Chi，换算系数为 ChiToCm，则：

  • CM = Chi × ChiToCm
  • MM = CM × 10
  • M = CM / 100

默认配置下即：1 尺 = 31.2 cm = 312 mm = 0.312 m。

输入容错与稳健性

  • 若输入为空或无法解析，自动回退为默认值（通常为 0.0）
  • 支持从字符串中提取数值（如 "31.2cm"）
  • 支持 list/tuple/可迭代对象，自动递归提取第一个元素
  • ChiToCm 若为 0 或负值，会自动回退默认 31.2

适用场景

  • 宋尺制参数在建模前/输出前转换为 Rhino 常用公制长度
  • 与材分制、等材转换组件串联后的公制落地
  • 需要对 GH 非严格输入（面板字符串、树结构）保持鲁棒输出的流程

设计要点

  • 专注“尺 -> 公制”单一职责，便于在流程末端复用
  • 对 GH 实际输入类型做宽容解析，降低组件报错概率
  • 默认值与异常回退明确，输出稳定可预期