📄 产品需求文档 (PRD) - [路径偏置算法V2.0]

文档状态: [Draft]

更新日期: 2026-3-7

作者: [Tree]

版本: v1.0

1. 🎯 项目概述 (Overview)

• 项目目标：根据已经生成的规划刀路，根据刀具参数进行反向偏置，生成对应的膨胀刀路并可视化，用于用户在界面与原始轮廓对比查看，判断是否产生了过切

• 核心价值：完全贴合工程的数据结构和机制去设计，参与到路径规划之中

2. 👥 目标用户 (Target Audience)

• Persona 1: CAM 编程工艺师 / 数控机器操作员

• 痛点：通常看到的刀路只是一根线（刀心轨迹），在遇到复杂的内腔或尖角时，仅凭肉眼无法判断带有实际半径的刀具是否会“切到不该切的地方”（过切），从而导致昂贵的材料报废或撞刀事故

• 诉求：不需要懂底层的 CCSPath 数据结构。他只需要在图形界面（GUI）上，直观地看到“刀具的实际加工扫掠范围（膨胀刀路）”与“原始设计轮廓”的重叠比对。如果发生过切，希望能高亮显示，让他敢放心地把程序下发给机床

• Persona 2:CAM 算法工程师

-痛点：在开发或重构底层路径规划算法（如处理复杂的左/右路规划、多岛屿避让）时，仅靠打印坐标点或看单线刀轨，很难 Debug（排错）

-诉求：因为这个偏置算法“完全贴合工程数据结构（CCSPath）”，他需要借助这个膨胀偏置后的可视化结果，来反向验证（Reverse Verify）前置的路径规划算法是否正确。这是他用来排查几何计算 Bug、校验切削深度（Z值）和刀宽补偿逻辑的重要可视化 Debug 工具

3. 🚧 边界与范围 (Scope & Non-Goals)

3.1 明确在范围内 (In-Scope)

• 代码编写到zkLyrToolPathBias.cpp中

• 按照工程的数据结构和机制进行开发，针对已经规划出的左右路CCSPAth，结合数据结构的语义信息或者索引去获取相关属性

• 生成的内容符合机制逻辑

• 使用封装好的接口方法，必要时添加合理的私有方法函数

• 功能函数预期插入到 toolPathBias文件，去实现偏置计算和可视化

• 尽量设计为一个外部接口函数去处理插入工程

3.2 明确在范围外/非目标 (Out-of-Scope / Non-Goals)

• 非目标：不需要使用目前机制存在的拼接功能

• 非目标：不要过多的去侵入已有的工程文件，除非是必要的

• 非目标：

4. ⚙️ 核心功能与验收标准 (Features & Acceptance Criteria)

功能 1：平底路径和抬刀路径分类

• 描述：

由于几何算法的考量，抬刀路径的处理更为复杂，因此需要和平底路径进行区分处理逻辑 去分别处理

底部路径：以切削深度为基准平面，位于该平面上的运动路径，z值固定为-切削深度的路径

抬刀路径：为实现小R角和过近点清角，需通过抬升刀具高度，利用更小半径的刀具进行切削。z值大于切削深度，且连续的路径

在设计过程中，要尽量避免冗余的数据结构设计，尽量通用

• 验收标准 (Acceptance Criteria)：

• 输入一组CCSPath，对CCSPath 准确的根据平底和抬刀进行分类。

• 分类后能够执行不同的处理逻辑

• 并最终 能够打包好路径 进行输出

功能 2：平底路径偏置处理&可视化

• 描述：

对分类后的平底刀路进行左右偏置，最终可视化的 左刀路生成的偏置放置到”左偏置”中，右刀路生成的偏置放置到”右偏置”中

1. 颜色使用Color(255, 0, 255, 255)

2. 通过工程的语义索引，通过CCSPath反向获取对应的原始边 以及对应的工具参数信息和工序参数，以及对应原始边的图层信息——刀锋高度进行参与

3. 参考旧代码的处理，计算偏置距离，并使用新的非对称offset接口，进行左右偏置

4. 偏置后的路径 需要根据刀锋高度，设置到对应的高度，其操作逻辑可参考旧版本代码

5. 设计合理的数据结构进行输出，并进行可视化

子功能 ：“燕尾”裁剪功能

• 描述：

设计功能函数：

交点机制+截断机制+缓冲区裁剪机制

通过计算交点，并进行路径的裁剪，对规划路径建立缓冲区，将侵入缓冲区内部的偏置路径 进行去除

• 使用：

在offset计算后，进行调用，重新调整出新的offset路径组

• 验收标准 (Acceptance Criteria)：

• 对CCSPath参数进行正确的获取

• 对偏置距离进行正确的计算

• 完成偏置操作后并成功输出

• 输出后并成功完成可视化

• 实际开发问题记录：

• 边缘情况：无

功能 3：抬刀路径处理————小R角，过近点，刮刀&可视化

• 描述：

颜色使用Color(255, 0, 255, 255)

• 要求：

1. 对于分离的抬刀路径，计算偏置时，将其投影到XY平面

2. 由于抬刀路径的特殊性，偏置路径需要对每个点进行单独的偏移，每个点的偏移距离根据刀高进行计算：

偏置距离计算中的bladeHalfWidth = std::fabs(std::tan(angleRad) * bladeHeight) 中的bladeHeight为当前点的刀高（即当前点的z值与切削深度的差值）

3. 对每个点进行偏移后，将这些点进行连接形成新的偏置路径，点的高度统一设置为对应抬刀路径 原始边设置的刀高

子功能 ：顶底修饰——小R角，过近点

• 描述：

此功能用于修饰 抬刀偏置路径的顶底位置偏置的表达,将对应抬刀的偏置显示更加整体化,并且更好的表示抬刀的刀具影响范围

• 要求：

1. 对抬刀路径的每个分段，找到该段中z值最高点和最低点

2. 在最低点位置，以该点为圆心，半径为一个合理的偏置距离（可以是与刀具半径相关的值），绘制一个圆形轮廓，表示刀具在该位置的影响范围

3. 在最高点位置，以该点为圆心，半径取刀具在该高度的最大宽度（根据刀具参数和当前点的刀高计算），绘制一个圆形轮廓，表示刀具在最高点位置的影响范围

4. 对于每个圆形轮廓，根据对应点的刀高设置其高度，使其在三维空间中正确显示

5. 将圆形轮廓与抬刀路径的偏置结果进行合并显示，使用户能够直观地看到抬刀路径在顶底位置的实际加工范围

6. 通过这种方式，用户可以更直观地看到抬刀路径在顶底位置的实际加工范围，帮助他们更好地评估抬刀路径的合理性和安全性

7. 注意抬刀中的过近点路径,可能要在一次分段中 就要处理多次的顶部和底部 的修饰显示

因此采用特征点识别

PS: 在设计这个功能时，要注意保持代码的简洁和可读性，尽量避免冗余的计算和复杂的数据结构。同时，要确保生成的圆形轮廓能够正确地反映刀具在不同高度的影响范围，以提供准确的视觉反馈给用户。

额外:在进行了圆形轮廓的显示后,我希望优化其显示,因为顶部和底部的圆形轮廓一定于偏置路径 相切或相交,为了优化显示效果,我希望在圆形轮廓与偏置路径相交的部分,进行裁剪处理,将相交部分裁剪掉,只保留圆形轮廓中没有被偏置路径覆盖的部分,以更清晰地展示抬刀路径在顶底位置的实际加工范围

问题记录：

1. 抬刀的高度筛选 需要包含刀锋高度，不然会误剔除一直沿着刀锋高度移动的路径段

2. 驼峰问题 & 脊峰问题

驼峰问题：

脊峰问题：

子功能 ：顶底修饰——刮刀

• 描述：

“刮刀”属于大分类中抬刀路径的一种路径，用于代替处理过去人为修刀锋的流程，其作用也是将锥度刀逼近刀锋，起到精修刀锋的作用

• 要求：

1. 刮刀路径的识别：根据数据结构的属性标志位识别出刮刀路径

2. 刮刀路径的去重&分离：由于刮刀路径可能存在重复的情况，需要进行路径段的去重；同时刮刀路径会有高于刀锋高度的情况，对于高出刀锋高度的部分，进行分离剔除

3. 刮刀路径的偏置处理：对于识别出的刮刀路径，对于每个点都根据其Z值进行动态的偏置距离计算，并进行生成圆，再将圆进行布尔合并操作，最终于其他抬刀路径进行布尔合并

4. 刮刀路径的可视化：将合并到“抬刀”大类，进行统一可视化操作

功能 4：多层显示优化

• 描述：

高刀切削 对于低刀在可视化上一定是过切的，因此在可视化上我希望能够区分不同刀具层的偏置显示

• 验收标准 (Acceptance Criteria)：

• 边缘情况：无

5. 🛡️ 非功能性需求 (Non-Functional Requirements)

• 注释：生成代码需要在合理的地方添加中文注释，其格式为”/— 注释内容 —/”

• 代码质量：生成代码 必须简洁，可读性强

6. 📈 成功标准 (Success Metrics)

• 发布后，能够将左右规划刀路都进行合理的路径偏置

• 由内部人员评估，偏置刀路是否可用

8. ✅ 完成的定义 (Definition of Done - DoD)

• 所有代码必须通过 Linter 静态检查，没有 Warn 和 Error。

• 没有任何 TODO 或 FIXME 残留在核心逻辑代码中。