On this page
article
刀具體
🧩木料 build_timber_block_uniform
所在模块：yingzao.ancientArchi.CuttingToolBody.FT_timber_block_uniform
功能概述
根据给定的尺寸参数和定位信息，构造一个轴对齐的方材长方体（Brep），并同步提取一组标准化的几何特征，用于后续的榫卯切割工具对齐与加工操作。
其几何特征提取逻辑与 FT_TimberBoxFeatures 组件完全一致，保证两者输出可互换对接。
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
length_fen |
float |
木料长度（沿局部 X 轴），单位：分 |
width_fen |
float |
木料宽度（沿局部 Z 轴），单位：分 |
height_fen |
float |
木料高度（沿局部 Y 轴），单位：分 |
base_point |
rg.Point3d |
木料起始角点（Corner 0）的世界坐标 |
reference_plane |
rg.Plane，可选 |
定义局部坐标系的参考平面；若省略，则以世界 XZ 平面为基准（Z 轴竖直向上） |
返回值
函数返回一个元组，包含以下内容：
| 返回项 | 类型 | 说明 |
|---|---|---|
TimberBrep |
rg.Brep |
构造完成的方材实体 |
FaceList |
list[rg.BrepFace] |
6 个面，按 +X/-X/+Y/-Y/+Z/-Z 顺序排列 |
PointList |
list[rg.Point3d] |
8 个顶点坐标 |
EdgeList |
list[rg.Curve] |
12 条棱线 |
CenterPoint |
rg.Point3d |
几何中心点 |
CenterAxisLines |
list[rg.Line] |
从中心出发沿 ±X/±Y/±Z 的 6 条半轴线段 |
EdgeMidPoints |
list[rg.Point3d] |
各棱线中点 |
FacePlaneList |
list[rg.Plane] |
各面的定向平面（法线朝外） |
Corner0Planes |
list[rg.Plane] |
起始角点处的 3 个构造平面（XY / XZ / YZ） |
LocalAxesPlane |
rg.Plane |
以 base_point 为原点的局部坐标平面 |
AxisX/Y/Z |
rg.Vector3d |
局部三轴单位向量（Forward / Left / Up） |
FaceDirTags |
list[str] |
各面的方向标签，如 "+X"、"-Z" |
EdgeDirTags |
list[str] |
各棱线的方向标签 |
Corner0EdgeDirs |
list[rg.Vector3d] |
起始角点处三条邻边方向，按参考平面 X/Y/Z 轴顺序排列 |
Log |
list[str] |
计算过程日志，用于调试 |
设计要点
- 尺寸约定：
length_fen→ 局部 X，height_fen→ 局部 Y，width_fen→ 局部 Z。 - 特征排序稳定：面与棱的输出顺序依据局部坐标轴方向标签确定性排列，不受 Rhino 内部 Brep 拓扑枚举顺序影响。
- 与
FT_TimberBoxFeatures对齐：所有特征由_build_canonical_box_outputs通过参考平面解析式计算，而非从 Brep 拓扑反向推导，保证两者输出在任意旋转姿态下一致。 - 单位：所有长度单位为分（宋式营造尺制），调用方须在传参前完成单位换算。
🧩块切割器 build_timber_block_uniform
所在模块：yingzao.ancientArchi.CuttingToolBody.FT_timber_block_uniform
功能概述
同 木料，只是将其作为切割刀具。
🧩偏轴木料 BuildTimberBlockUniform_SkewAxis
所在模块：yingzao.ancientArchi.CuttingToolBody.BuildTimberBlockUniform_SkewAxis
功能概述
在基础方材构造（build_timber_block_uniform）基础上，引入斜移（Skew）控制平面与辅助构造点的高级构建器类。用于需要沿长度方向产生倾斜或渐变加工方向的复杂木料几何建模，如古建筑中带斜度的梁架构件。
该类同时提供标准的方材特征提取（与 FT_TimberBoxFeatures 对齐），以及新增的 Skew 相关控制几何。
类初始化
BuildTimberBlockUniform_SkewAxis(
length_fen,
width_fen,
height_fen,
base_point,
reference_plane=None,
Skew_len=20.0
)
| 参数 | 类型 | 说明 |
|---|---|---|
length_fen |
float |
木料长度（沿局部 X 轴），单位：分 |
width_fen |
float |
木料宽度（沿局部 Z 轴），单位：分 |
height_fen |
float |
木料高度（沿局部 Y 轴），单位：分 |
base_point |
rg.Point3d |
木料起始角点的世界坐标 |
reference_plane |
rg.Plane，可选 |
定义局部坐标系的参考平面；若省略，默认为 XZ 平面 |
Skew_len |
float，默认 20.0 |
沿 X 轴的斜移距离，单位：分 |
属性说明
标准方材特征（同 build_timber_block_uniform）
| 属性 | 类型 | 说明 |
|---|---|---|
TimberBrep |
rg.Brep |
构造完成的方材实体 |
FaceList |
list[rg.BrepFace] |
6 个面，按方向标签排列 |
PointList |
list[rg.Point3d] |
8 个顶点坐标 |
EdgeList |
list[rg.Curve] |
12 条棱线 |
CenterPoint |
rg.Point3d |
几何中心点 |
CenterAxisLines |
list[rg.Line] |
6 条中心半轴线段 |
EdgeMidPoints |
list[rg.Point3d] |
各棱线中点 |
FacePlaneList |
list[rg.Plane] |
各面的定向平面 |
Corner0Planes |
list[rg.Plane] |
起始角点的 3 个构造平面 |
LocalAxesPlane |
rg.Plane |
局部坐标平面 |
AxisX/Y/Z |
rg.Vector3d |
局部三轴单位向量 |
FaceDirTags/EdgeDirTags |
list[str] |
方向标签 |
新增 Skew 特征
| 属性 | 类型 | 说明 |
|---|---|---|
Skew_A |
rg.Point3d |
木料中心轴处的参考点（木料宽度中线，距离 base_point 为 width_fen/2 在 Z 方向） |
Skew_Point_B |
rg.Point3d |
从 Skew_A 沿参考平面 X 轴偏移 Skew_len 后的控制点 |
Skew_Point_C |
rg.Point3d |
从 Skew_Point_B 沿参考平面 Y 轴（高度方向）上升 height_fen 后的控制点 |
Skew_Planes |
list[rg.Plane] |
3 个斜移平面，分别过 Skew_Point_B：- 平面 0：沿 XY 方向 - 平面 1：沿 XZ 方向 - 平面 2：沿 YZ 方向 |
Skew_ExtraPoints_GF_EH |
list[rg.Point3d] |
4 个补充控制点 [G, F, E, H]，分别对应木料底部、顶部在 Skew_len 处的投影：- G：底面左前角- F：底面右前角- E：顶面右前角- H：顶面左前角 |
使用场景
- 梁架倾斜加工：需要从一个基准平面按斜移距离演变到加工平面的木构件。
- 渐变刀具对齐：Skew 平面与点可作为刀具运动轨迹的控制条件。
- 测量基准建立：
Skew_Point_B、Skew_Point_C等可作为现场定位和工艺验证的关键点。
设计要点
- 参数一致性：内部方材仍按
length_fen→X、height_fen→Y、width_fen→Z 的约定构造。 - Skew 方向：始终沿参考平面 X 轴（长度方向）进行斜移；若需其他方向斜移，建立时应相应调整参考平面。
- 单位：所有长度参数均为分（宋式营造尺制）。
- 容错处理：若构造过程出现异常，
TimberBrep为None，错误信息存储在Log属性中。
🧩 欹䫜刀build_qiao_tool
所在模块：yingzao.ancientArchi.CuttingToolBody.FT_QiAo
功能概述
构造欹䫜（斜切）刀具实体，该刀具用于对古建筑梁架木料进行欹䫜形断面的切割。欹䫜截面由 水平边、竖直边和过渡弧线 组成，形成平滑的切削边缘；刀具本体通过沿法线方向的拉伸生成。
函数签名
build_qiao_tool(
qi_height,
sha_width,
offset_fen,
extrude_length,
base_point,
reference_plane=None,
extrude_positive=True
)
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
qi_height |
float |
欹高——截面中竖直边的长度，单位：分 |
sha_width |
float |
殺宽——截面中水平边的长度，单位：分 |
offset_fen |
float |
欹䫜量——对角线中点沿"平面内垂直对角线"的内偏移距离，形成圆滑过渡，单位：分 |
extrude_length |
float |
刀具拉伸厚度，沿截面平面法线方向的距离，单位：分 |
base_point |
rg.Point3d |
直角点位置——水平边与竖直边的交点（切割角），世界坐标 |
reference_plane |
rg.Plane，可选 |
定义截面朝向的参考平面；若省略，默认为 XZ 平面（X=水平，Z=竖直，法线沿 ±Y） |
extrude_positive |
bool，默认 True |
拉伸方向：True 为沿平面法线正向；False 为反向 |
返回值
函数返回一个 4 元组 (ToolBrep, CornerPoint, BaseLine, SectionPlane, FacePlane)，或在失败时返回 (None, None, None, None, None)：
| 返回项 | 类型 | 说明 |
|---|---|---|
ToolBrep |
rg.Brep | None |
欹䫜刀具的 3D 实体（闭合 Brep） |
CornerPoint |
rg.Point3d | None |
直角点在世界坐标系中的位置（= base_point） |
BaseLine |
rg.Line | None |
从直角点沿拉伸方向的参考线段，长度为 extrude_length |
SectionPlane |
rg.Plane | None |
截面所在平面（用于后续刀具对齐） |
FacePlane |
rg.Plane | None |
参考平面，原点为 BaseLine 中点，XY 轴分别为竖直方向和法线方向 |
截面几何
欹䫜截面 由以下部分组成：
- 水平边：从直角点沿参考平面 X 轴延伸
sha_width - 竖直边：从直角点沿参考平面 Y 轴延伸
qi_height - 过渡弧线：
- 连接水平端点与竖直端点
- 通过对角线中点沿"垂直对角线方向"偏移
offset_fen - 形成光滑的三点圆弧，避免尖锐切边
- 闭合轮廓：方向为
直角点 → 水平端点 → 弧线 → 竖直端点 → 直角点
刀具拉伸
- 截面沿参考平面的法线方向（
reference_plane.ZAxis）拉伸，形成 3D 刀具实体 - 拉伸距离为
extrude_length - 若
extrude_positive=False，则沿法线反向拉伸
使用场景
- 梁架欹䫜削：古建梁架中常见的斜切加工，用于接榫或过渡
- 刀具路径规划：
BaseLine与FacePlane可作为数控加工的刀具中心轨迹与定向参考 - 加工工艺模拟：直观呈现欹䫜削的三维形态，用于工艺验证
单位与坐标系
- 长度单位：所有尺寸参数（
qi_height、sha_width等）均为分（宋式营造尺制） - 默认坐标系：
- 水平方向（殺）：世界 X 轴
- 竖直方向（欹）：世界 Z 轴
- 法线方向：世界 Y 轴（±取决于
extrude_positive）
- 参考平面自定义：通过
reference_plane参数可改变刀具朝向
设计要点
- 圆滑过渡：
offset_fen参数控制圆弧偏移量，实现从尖锐切边向圆滑削面的平缓过渡，提高加工质量 - 容错设计：若截面构造失败（如弧线无效）或拉伸失败，返回全
None，调用方应检查返回值 - 坐标系稳定：直角点始终位于
base_point，参考平面方向独立可控，便于多个刀具的一致对齐