text-to-cad SRDF 末端执行器指南从end_effector语义到 MoveIt2 位姿求解交接【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad本文基于 text-to-cad 仓库 SRDF 技能的 end-effectors 参考文档讲解 MoveIt2 SRDF 中末端执行器end effector的语义模型、必备台账字段、拓扑检查清单以及如何把目标/TCP 连杆显式地交接给 CAD Viewer 的 MoveIt2 位姿求解协议。读完你可以独立编写end_effector条目、理解校验器对末端拓扑的报错含义并构造可直接被srdf.solvePose协议消费的请求载荷。末端执行器是什么SRDF 中的语义标注而非物理结构在 text-to-cad 的 SKILL.md 中明确了格式边界URDF 拥有物理结构links、joints、几何、惯性、限位而 SRDF 拥有 MoveIt 规划语义——虚拟关节、被动关节、规划组、组状态、末端执行器与禁用碰撞对。末端执行器属于后者它是对末端工具组夹爪、传感器头、焊枪或其他终端部件的语义命名通常通过固定关节或附着连杆连接到父规划组上。这一点决定了编写末端执行器时最常见的失败模式不是 XML 语法错误而是看起来合理、规划语义却是错的组归属错了、TCP 连杆推断了、父连杆位置不对。因此该参考文档要求先记录台账字段、再写 XML而不是凭视觉印象直接命名。典型形态groupend_effector组合end-effectors.md 给出的典型形态如下group namegripper joint namefinger_joint/ /group end_effector namegripper_eef parent_linktool0 groupgripper parent_groupmanipulator/四个属性各自的角色属性含义校验要求name末端执行器唯一名称必填且不能与其他末端执行器重名group末端执行器自身的规划组如gripper必须在同一 SRDF 中已定义parent_group父规划组如manipulator可选若填写则必须已定义且必须满足拓扑约束parent_link末端执行器附着在哪个 URDF 连杆上如tool0必须存在于配对 URDF 的 link 表中源码层面source.py 中的解析器会读取这四个属性并归一化为SrdfEndEffector数据类source.py#L58-L63遍历robot根节点下所有end_effector元素name缺失直接报missing_end_effector_name错误source.py#L252-L273重名报duplicate_name。group与parent_group在此阶段允许为空字符串——它们的存在性与拓扑合法性推迟到与 URDF 交叉校验阶段处理。规划台账写 XML 之前先记录七个字段参考文档要求Required ledger fields——在动笔前必须记录末端执行器名称末端执行器组group父规划组parent group末端执行器附着的父连杆parent link用于 IK 与规划的目标/TCP 连杆末端执行器组与父组是否重叠父连杆在 URDF 图中是否与末端执行器组相邻。这套字段与 planning-ledger.md 中End effectors表格一一对应planning-ledger.md#L56-L62表头为| Name | End-effector group | Parent group | Parent link | Target/TCP link | Overlap checked? | Adjacent? | Notes |其中两条设计原则值得强调末端执行器组通常不应与其父组共享连杆当目标/TCP 连杆与推断出的组 tip不一致时必须显式记录 TCP 连杆不能依赖运行时推断。台账的意图是让规划假设在写 XML 之前就被显式化。SKILL.md 的工作流第 8 步也呼应了这一点Define end effectors after group membership is known——末端执行器要在组归属确定之后定义。编写前的检查清单参考文档列出了六项编写前检查末端执行器组存在若指定了父组父组存在父连杆存在于 URDF 中末端执行器组与父组不共享连杆父连杆属于父组或紧邻末端执行器组目标/TCP 连杆与推断的组 tip 不同时必须显式指定。文档特别指出当前运行时会强制执行其中若干检查但目标/TCP 的选择始终是语义决策。当规划目标是工具中心点TCP时不要依赖推断。这是本文档最核心的工程判断运行时能证明的是拓扑一致性证明不了你对 TCP 的意图。校验器如何强制执行这些检查源码级拆解SRDF 技能自带校验器命令形态见 SKILL.mdpython scripts/validate path/to/robot.srdf python scripts/validate path/to/robot.srdf --strict python scripts/validate path/to/robot.srdf --format json校验器一次性收集所有发现severity、code、XML path并与同目录、同名robot name的配对 URDF 做交叉验证。针对末端执行器cli.py 中的_validate_srdf_against_urdf依次执行三类存在性检查cli.py#L338-L367发现码含义触发条件missing_end_effector_parent_linkparent_link引用的连杆在 URDF 中不存在与配对 URDF 的 link 集合比对missing_end_effector_groupgroup引用的规划组未定义与本 SRDF 内已解析的组名比对missing_end_effector_parent_groupparent_group引用的规划组未定义同上仅当该属性非空时检查随后调用_validate_end_effector_topologycli.py#L632-L683执行三项拓扑检查这正是检查清单中可被运行时强制执行的部分组重叠检查end_effector_group_overlap用_link_names_for_groupcli.py#L574-L615分别展开末端组与父组的实际连杆集合——它不仅看组里直接写明的link还会沿组内joint、chain沿 URDF 树展开关节路径和子组递归推导连杆。两个集合有交集即报错并列出具体重叠连杆。父连杆必须在父组内end_effector_parent_link_outside_parent_groupparent_link若不属于父组的推导连杆集合说明附着点与父规划组脱节。父连杆必须与末端组相邻end_effector_parent_link_not_adjacent父连杆既不在末端组内又不与末端组中任何连杆由某个 URDF 关节直接相连即拓扑断裂。相邻判断由_joint_adjacent_to_any_link完成cli.py#L618-L629它遍历 URDF 关节表看是否存在一个关节把parent_link与末端组内某连杆直接连成 parent-child。注意这些检查都建立在配对 URDF 是一棵单根树的前提上若 URDF 本身不是单根树校验器会先发出paired_urdf_not_a_tree警告cli.py#L243-L252提示链式与相邻判断可能不可靠建议先用 URDF 技能校验。一个实用推论校验器对重叠的判定基于推导连杆集而非字面成员。若父组用chain base_linkbase_link tip_linkwrist_3_link/定义末端组又包含wrist_3_link即使两组文本上没有字面重复end_effector_group_overlap仍会触发——写 chain 组的作者尤其要留意 tip 连杆是否同时落进了末端组。目标/TCP 交接CAD Viewer 的srdf.solvePose载荷文档最后一节处理与$cad-viewer的交接当把 SRDF 交给 CAD Viewer 做可选的 MoveIt2 交互控制时应尽可能显式声明目标连杆。完整示例直接摘自参考文档{ protocolVersion: 1, type: srdf.solvePose, payload: { file: robot.srdf, target: { endEffector: gripper_eef, targetLink: tool0, frame: base_link, xyz: [0.4, 0.0, 0.2], quat_xyzw: [0, 0, 0, 1] }, moveit2: { planningGroup: manipulator, targetLink: tool0 } } }各字段与前面台账的对应关系target.endEffector引用 SRDF 中的end_effector name...即台账字段 1target.targetLink目标/TCP 连杆即台账字段 5——即使与组 tip 相同也建议显式写出target.framexyzquat_xyzw以base_link为基准系表达的位姿moveit2.planningGroup规划用哪个父规划组台账字段 3moveit2.targetLinkIK 求解指向的连杆应与target.targetLink一致。服务端行为可以从 cad-viewer 技能的 MoveIt2 服务源码确认protocol.py 声明支持的请求类型为srdf.solvePose与srdf.planToPosedispatcher.py 按request.type路由到对应处理器context.py 解析时把moveit2.planningGroup与target.get(targetLink)/target.get(link)作为目标连杆的取值链context.py#L780-L825并会验证planningGroup非空、targetLink必须引用真实存在的 URDF 连杆否则抛MotionProtocolError。两条使用规则来自参考文档原文仅在姿态确实不需要约束时才使用 position-only IK——载荷中给出完整四元数如示例中的单位四元数意味着姿态参与求解CAD Viewer 负责本地 MoveIt2 服务的启动与协议细节——SRDF 作者只负责把目标连杆语义写对不需要在 SRDF 中嵌入任何服务配置。MoveIt2 服务的本地启动方式见 moveit2-server.mdnpm --prefix scripts/viewer run moveit2:setup npm --prefix scripts/viewer run moveit2:check npm --prefix scripts/viewer run moveit2:serve服务默认监听ws://127.0.0.1:8765/ws在 CAD Viewer 中打开.srdf文件后展开右侧MoveIt2面板即可设置规划组、末端执行器、目标帧、XYZ 坐标以及求解器超时、尝试次数与容差。该面板与上文 JSON 载荷是同一套协议的手工/自动两种入口。收尾验证完成end_effector编写后回到 SKILL.md 的强制工作流运行scripts/validate对每个新建或修改的.srdf做交叉验证修复发现直至干净--strict会把警告也当作失败--format json输出机器可读的发现文档便于接入 CI 或 Agent 循环。若本地有 MoveIt 环境再跑 Setup Assistant 或项目 launch 做烟雾测试。最后提醒参考文档反复强调的两点边界其一end_effector条目的正确性是规划语义问题视觉渲染审阅不能证明规划正确其二凡是被推断出来的目标连杆、组归属或 TCP 选择都应在交付说明中如实报告为假设而不是当作已验证的事实。【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考