🤖 机器人手臂（6自由度参数化机械臂工程）

基于 CadQuery 的参数化 6 自由度人形机械臂建模工程。对标智元灵犀 X1 构型，采用 6 颗 60mm 标准减速电机模组，支持全参数化建模、动态全域碰撞检测、制造文件（STEP/STL）导出及单文件离线三维交互查看器。

---

🌟 核心设计特性

1. 一体化直锁电机：全面取消外挂独立端面齿联轴器，所有关节由 3×M2 沉头螺钉直锁电机输出轴，轴向尺寸大幅压缩，刚度显著提升。
2. 电机前端双向夹紧 + 2mm 厚度公差：每个关节的电机由「后端板 4×M3x10 + 前端 R35 压盖 4×M3x8」前后两面夹死；后端板承压面按 MOTOR_TOL=2.0 让空成尾端垫片位（armcore.MOTOR_TOL / arm_build.REAR_SEAT），装配时在电机尾端面与承压面之间叠 0~2.6mm 的 M3 平垫，逐台电机按实测长度配垫（T = 58.6 − 电机实际长度 L），让前端盖正好落到压盖面上。
3. 五级流线圆角系统：建立统一的有机曲面过渡规范（R=1.5mm 微圆角 ~ R=15mm 视觉主导大圆角），彻底消除锐边与机械生硬台阶。
4. 全行程动态零干涉：经 sweep_v2.py 多进程全域扫描与二分逼近验证，各自由度极限角度下实现 0 碰撞。
5. 100% 流形单实体：9/9 构件均为无缝单一实体拓扑，完全杜绝浮动壳体与布尔破碎，满足 FDM/SLA 打印及 CNC 加工要求。

---

🚀 快速上手

1. 编译并导出最新模型

一键重新生成全部 9 个打印构件、装配体、STEP/STL 制造文件及 3D 查看器数据：

python src/arm_model.py

导出的 STEP 文件保存在 out/parts_step/，打印用 STL 保存在 out/print_stl/（重跑构建自动更新）。

2. 全行程动态防碰撞扫描

多进程并行扫描全关节运动极限硬边界，并更新滑动安全范围：

python src/sweep_v2.py

3. 三维交互查看器

• 使用方式：直接双击打开项目根目录下的 机器人手臂3D查看器.html 即可在任意浏览器全屏交互查看（纯本地离线单文件，无需任何外网或 CDN）。
• 支持：全自由度姿态滑块调节、部件爆炸图、单零件孤立透视、应力与干涉显示。

---

📁 项目目录结构

机器人手臂/
├── 机器人手臂3D查看器.html        # 单文件内置 3D 查看器（双击即用）
├── README.md                     # 本说明文档
├── src/                          # 核心源码目录
│   ├── arm_model.py              # ⭐ 装配流水线：载电机模组→按件收集 specs()→导出 STEP/STL/BOM/网格→打包查看器
│   ├── part_tools.py             # 跨件共用刀法：X 向基础体、减重腔 helper、电机前端压盖、pitch->roll 转接座骨架
│   ├── parts/                    # ⭐ 每个零部件一个文件：几何 + 件号/配色/说明 + 装配帧归属 JOINT
│   │   ├── p01_column.py         # P01_A/B/C 立柱三段（含立柱定位 X_COL）
│   │   ├── p02_base.py           # P02 底座三段（中核心/前向力臂/后向力臂）
│   │   ├── p03_girdle.py         # P03 肩吊臂
│   │   ├── p04_fork.py           # P04 肩叉（减重槽开度 P04_CH 在此）
│   │   ├── p05_roll_base.py      # P05 大臂旋转座
│   │   ├── p06_humerus.py        # P06 大臂骨架（窗开度 P06_WIN_XZ / P06_HOLLOW_WIN 在此）
│   │   ├── p07_forearm.py        # P07 小臂骨架（减重槽开度 P07_CH 在此）
│   │   ├── p08_wrist.py          # P08 腕偏转座
│   │   └── p09_flange.py         # P09 工具法兰
│   ├── sweep_v2.py               # ⭐ 权威动态碰撞检测与行程扫描工具
│   ├── arm_build.py              # 底层几何基础库与通用装配/导出函数
│   ├── build_viewer.py           # 3D 查看器打包生成脚本
│   ├── human_layout.py           # 机械臂各关节运动学拓扑与唯一事实参数源
│   ├── shot.py                   # 渲染截图工具
│   ├── draw_sheet.py             # 2D 工程图纸生成（查看器图纸页数据 sheets.jsdata）
│   ├── finalize_travel.py        # 行程数据维护（从 sweep 明细重建 travel.json）
│   ├── strength_check.py         # 刚度与应力分析
│   └── torque_balance.py         # 关节力矩平衡校核

> **改哪件就开哪个文件**；`arm_model.py` 里不再有件号字符串和几何代码。
> 件级开关（`FENCE_OPEN_CUT`、`P04_CH`、`P07_CH`、`P06_WIN_XZ`）随各自的模块搬走：
> 做 A/B 必须写它所在的件文件（如 `parts.p04_fork.P04_CH = cfg`），
> 写 `arm_model.P04_CH = cfg` **不生效**（`arm_model` 对件级符号只作只读转发，供旧脚本取值）。
> 判据：翻转开关后体积必须变化（`scratch/verify_switches.py` 实测 2.70 / 22.23 cm³ 灵敏度）。
├── docs/                         # 权威数据与渲染截图（历史报告已清理）
│   ├── travel.json               # 各关节实测行程与硬限位（sweep_v2.py 扫描生成）
│   ├── travel_detail.json        # 逐对扫描明细与组合折叠约束
│   ├── bom.json                  # 零件明细与质量属性表（构建自动生成）
│   ├── collision.json            # 静态干涉检测结果（构建自动生成）
│   └── shots/                    # 渲染截图
├── web/                          # 查看器底层模板与几何网格数据 (mesh_arm.json)
└── out/                          # 编译制造产物（重跑 arm_model.py 自动重建）
    ├── parts_step/               # 各零件标准 STEP 实体
    └── print_stl/                # 各零件 3D 打印 STL 文件

---

🦾 机械臂构件清单 (P01 ~ P09)

构件编号	构件名称	关联驱动关节	设计说明
P01	立柱（三段 A/B/C）	根基固定	66×66mm 三角截面立柱，分段榫接 + M4 自攻对锁孔防反装；顶端为 P03 安装台
P02	底盘（核心座 + 前/后防翻力臂）	根基固定	195×190mm 核心承力座 + 48mm 套筒 + 前后三角加强筋；前后防翻力臂带 M5 预埋螺母
P03	肩吊臂 / 肩关节安装悬臂	J1 驱动抱紧	轻量化板式桁架：双侧 6mm 竖板 + 帐篷减重窗（≥52°自支撑）+ 9mm 承力鞍座 + Ø15 螺母柱，抱紧 M1 电机（实心 728→286cm³，-61%，外轮廓不变）
P04	肩叉	J1 ➔ J2	90° 一体化高刚度正交转向肘，直锁 M1，抱紧 M2；M2 前端压盖（R35 / Y155.5161）：电机前端盖再加 4×M3x8（BCD55）夹一次，与后端板 4×M3x10 前后双向面压，消掉大扭矩下电机在座孔里的倾斜；前端围挡只切敞口那半圈（见下）；立柱减重槽（X2335 / Y102~154 / Z525↑ 敞开）：立柱由实心变 U 形槽钢，361→289cm³，抗弯靠两侧 X 向腹板（z=560 截面 I 207370→199777，降 3.6%，而面积降 28%）
P05	大臂旋转座	J2 ➔ J3	16 层 Loft 曲面平滑过渡，直锁 M2（J2 法兰盘背面后移到 Y=162，给 P04 前端压盖让位，J2 凸台同步加长以保住 S01 咬合），后侧刚性抱紧 M3；M3 前端压盖（R35 / Z 384.0~389.5，4×M3x8 BCD55）：M3 是 roll 电机（轴向 -Z），压盖与后端板 4×M3x10 前后双向面压；代价是对侧 P06 的 J3 毂面后移 5.5mm 让位
P06	大臂骨架	J3 ➔ J4	流线型工字背脊骨架，直锁 M3，下端抱紧 M4 肘电机；M4 前端压盖 4×M3x8（BCD55），同 P04 配方；前端围挡只切敞口那半圈（见下）；J3 毂面后移 5.5mm（顶端 388.5→383.0，直锁凸台 59.5→65.0）：给 P05 的 M3 前端压盖让位，留 1.0mm 动间隙——与 Y 轴三处（J2/J4/J5 令从动法兰盘 Y157→162）完全同源，换算式同为「压盖 5.0 + 动间隙 1.0 − 原基准 0.5」；凸台同步加长，3×S01 输出螺钉咬合量与 J3 直锁关系一律不变
P07	小臂骨架	J4 ➔ J5	L 型圆弧强化立柱，大范围自由运动避让，抱紧 M5；M5 前端压盖 4×M3x8（BCD55）；前端围挡只切敞口那半圈（本件环壁 r32.2535，因 2.0mm 关节间隙而更薄，见下）；J4 从动侧（法兰盘/立柱/圆弧加强筋）整体后移到 Y=162 给 P06 压盖让位，J4 凸台同步加长；顶板减重槽（X−343 / Y103~153 / Z255↑ 敞开）：288→230cm³，Y 上限取 153 以避开 y_hub_in=158.5 起的竖直立柱本体（那是 J4 从动法兰的承力柱）
P08	腕偏转座	J5 ➔ J6	16 层 Loft 双曲面过渡，直锁 M5（J5 法兰盘背面后移到 Y=162，给 P07 前端压盖让位，J5 凸台同步加长），立式抱紧 M6 腕旋转电机；M6 前端定位环只切敞口那半圈（尚无 M6 前端压盖，环是光板，见下）。壁厚峰值 8.3mm，本就是薄壳
P09	工具法兰	J6 输出	直锁 M6 输出轴，标准工业 ISO 法兰（4x M4 螺孔 BCD 44mm）；填充 100%→30%：该截面安全系数 288，是全机裕度最大的件，满填充纯属浪费
M1~M6	关节电机模组 ×6	各关节驱动	Ø60 方形标准减速电机模组（63.6mm 方形尾盖），210 g/台，整机 1260 g

⚠️ 电机装配必须配垫片（厚度公差 2mm）：各台 Ø60 电机的轴向长度实测差可达 2mm。 这条轴向链是「后端板 4×M3x10 + 前端 R35 压盖 4×M3x8」两个刚性夹持面，螺钉头一旦坐死 在沉孔台阶上就不能再进给，所以公差不能靠拧紧消化，只能由后端板的承压面让空出来的 垫片位吸收（armcore.MOTOR_TOL = 2.0，arm_build.REAR_SEAT = 0.6 + 2.0 = 2.6）。 装配顺序：① 后端板承压面上叠 T = 58.6 − 电机实测长度 L 的 M3 平垫（0.5/1.0/1.5 组合， 标称电机约 0.6mm，量程 0~2.6mm）；② 电机推入到尾端面贴住垫片；③ 前端压盖 4×M3x8 拧紧， 此时前端盖正好落在压盖面上（0.0 面压）；④ 后端板 4×M3x10 拧紧夹死垫片。 不做第①步的后果：电机长 1mm 以上就装不进去（前端盖越位 1mm 撞压盖本体）， 电机短 1mm 以上压盖就压不上、只剩后端板单面锁死，大扭矩下电机照样点头。 校核脚本：scratch/motor_tol_window.py（窗口换算）+ scratch/motor_tol_check.py （真实电机包络布尔验证 5 个夹紧关节 × ±2mm，全部零干涉）。 另：J1/M1（P03 侧开式电机舱）本身就是 Ø60.7 直通长孔、比电机长 3mm，天然覆盖该公差，无需配垫。

承压面为什么是 R35 圆面而不是 64.4 方腔（2026-10-04 整改）：承压面下沉 2.6mm 后， 如果承压面段仍用 64.4 方腔，方腔壁以外 z=-2.6..0 那圈 R35 料就相对新承压面 凸起 2.6mm —— P04~P08 后端整圈「悬空凸台」，3D 打印时是悬空薄壁（要支撑、公差难保）。 现在承压面段用 R35 圆腔（arm_build.SEAT_R），整圈一次挖到承压面高度，凸台零残留。 SEAT_R 必须等于外壁 R35：只要小于 R35，刀半径与外壁之间那圈环墙就必然保留并相对 承压面凸起（P08 实测 1536.9mm³）—— 这就是用户 2026-10-05 在尾端指出的"围挡"， 是取值的必然产物而不是残留。连带好处：承压环从「1.95mm 窄环」变成「完整 R35 圆环 4.75mm」， 受压面积 383 → 974 mm²（2.5 倍），夹紧更实。SEAT_TOP=+1.0 越过电机尾端面 1mm， 吃掉半包开口处的 0.052cm³ 残片（取 0 时该残片会脱空成独立碎块）。

前端那一圈"围挡"（2026-10-05e，全机 5 处）：用户 2026-10-05 先在 J3/M3 指出电机 另一头（前端）也有一圈围挡，随后确认其余四处（M2/M4/M5/M6）完全同构。围挡本体不是残留料， 而是 front_collar_pocket 的必然产物：它把座孔从 R30.15 扩到 R30.25，于是留下那圈 r30.25..35、6mm 高的环墙，比电机前端盖 Ø60.3 凸出 4.75mm；J2/J3/J4/J5 上还骑着 R35 前端 压盖（Ø70 再凸 3.2mm）。我第一版把整个前端（定位环 + 压盖 + 腔口下沿）都切了 → 过度： 电机前端没了支撑面、M3 退回单面锁死，用户当场驳回。

【2026-10-07 修复：消除 P04/P06/P07/P08 误切缺角，完整补齐底壁】： 2026-10-05e 曾将 P05(M3) 的定位环敞口盒切推广到全机。但俯仰关节(J2/J4/J5)的局部 y=-3..40 坐标导致盒切向上侵入底壁实体 3mm（Z_axis+3），造成 P04、P06、P07、P08 的底壁和侧耳平白无故缺了一个 3mm x 6.1mm 的台阶缺角。现已彻底取消 P04/P06/P07/P08 处的切除，完整补齐底壁；该盒切仅保留于原本专用的 P05(M3) 敞口侧定位环（开关 arm_model.M3_FENCE_OPEN_CUT）。

原 P05(M3) 前端定位环敞口切（开关 arm_model.M3_FENCE_OPEN_CUT，切刀 cut_motor_fence()）： 按各关节自己的局部坐标切 —— 局部 y 从 -3 到 +40、z 49.456.1。5 处的定位环都恰好落在 局部 z 49.556（Y 轴电机 Y150156、roll 电机 Z395.5389），故一对参数通吃；敞口方向恒为 局部 +y（实测 5 处背脊方位角全部落在局部角 180360，无需逐件配置）。切口边界取 y=-3.0 而非 0： 环壁在该处仍与背脊侧实体连通，切出来是真正的缺口而不是零厚度缝，单实体拓扑天然保持（5/5 实测 solids=1）。背脊侧整圈定位环保留 —— 继续定位前端盖，并作为压盖唯一且足够强的支撑面 （4.75mm 宽 × 0.5mm 熔接带，本次完全不碰）；压盖本体 / Ø37 让位孔 / 4×M3x8 沉孔 / 腔口下沿 全部不动，电机仍是「后端板 4×M3x10 + 前端压盖 4×M3x8」前后双向面压。 各件减重：P04 −3.4 / P05 −3.2 / P06 −3.2 / P07 −2.1 / P08 −3.0 cm³（P07 环壁因 2.0mm 关节 间隙而较薄 r32.2535，故减得最少）。

为什么不整圈削到与电机齐平（R35→R31.8）：① 那圈壁与本体在两个方位与外壁相切，整圈 切完那两片切向楔形（P05 实测 1.32mm³）会脱空成孤立碎块，破坏单实体拓扑；② 压盖根部只有 0.5mm 熔接带，环削窄后连接面从 2.37mm² 掉到 0.78mm²，4×M3x8 的夹紧力会把压盖从本体上拉下来。

⚠️ P01 / P02 是固定测试台架，不是机器人本体。它在扫描中代表机械臂与躯干的连接 界面——臂撞立柱 = 臂撞躯干，是真约束，碰撞计算必须包含它。但台架的位置与截面 是一个假设，所以躯干侧的工作空间只和这个假设一样准。要改的是"真机躯干占位"这个 输入，而不是改台架（改台架是改测试工装）。sweep_v2.py --no-stand 是诊断开关： 排除台架重扫，给出不含躯干约束的自由空间行程，用来分辨某个限位是臂自身折叠产生的 还是躯干挡的。默认包含台架。

⚠️ 关节电机力矩现状：按 torque_balance.py 的实测（零件真实质心 + 可达姿态搜索）， J1 肩抬举仅悬停自身臂身即需 3.84 N·m、J2 需 2.48 N·m，已超出假定许用连续力矩 2.0 N·m；带 0.5 kg 末端负载时 J1 达 6.14 N·m（307%）。详见 docs/torque_report.md。 结论对电机额定参数敏感，该参数目前为工程假定（无数据手册），可用 ARMT_CONT 覆盖重算。

相反地，结构本身不是瓶颈：12 个剖面全部合格，最差的 P03 吊臂根座安全系数 9.25， 最大挠度 1.6mm。减重救不了电机——J1 的 distal 载荷里 5 台电机占 65%（1.05kg）， 打印件只占 0.58kg，把 P07/P08/P09 全部减掉 J1 也只降到 2.54 N·m。

2026-10-02 手臂件减重：按厚度场扫描（scratch/thickness.py）定位厚料后， P04 立柱 / P06 过渡块 / P07 顶板改为薄壁槽与减重窗，P09 填充 100%→30%， 手臂 6 件实心 1214→1061cm³、BOM 1506→1316g。按 gyroid 实际打印口径（墙 5×0.42mm 以内 100%、深处 2530%）估，手臂打印件 906→817g，净省约 90g。 减重开度由 scratch/tune_hollow.py 按「减重区最差安全系数 ≥ 无槽基线 95%」选定 （第一版开太大，P06 曾掉到基线的 66%，收窄后全部回到 95100%）。 代价只有惯性矩小幅下降（P04 截面 I 降 3.6%、P06/P07 减重区强度回到满值）， 行程范围与碰撞检测完全不变，13/13 零件仍是单实体。

---

📚 详细文档导航

• 📘 权威数据（工具自动生成）：
  • 各关节行程与硬限位 travel.json（sweep_v2.py 扫描生成，修改几何后必须重扫）

    滑块范围 = 单关节硬限位。组合折叠姿态下另有干涉约束，见 travel_detail.json 的 combos 字段（目前全部是工具法兰 P09 撞躯干占位 P01_A，属真约束）；查看器运行期 另有胶囊碰撞模型按姿态夹取。

  • 零件明细与质量属性 bom.json（构建自动生成）
  • 静态干涉检测结果 collision.json（构建自动生成）
  • 截面刚度与应力 strength.json（strength_check.py 生成）
  • 关节力矩与负载能力 torque_report.md（torque_balance.py 生成）
• 🔬 测试与校验工具（src/ 目录）：
  • sweep_v2.py — 权威动态碰撞检测与行程扫描
  • strength_check.py — 剖面刚度/应力校核（零件真实质心 + 可达姿态搜索，输出含挠度估算）
  • torque_balance.py — 关节电机力矩、惯量与负载能力校核（拓扑取自 human_layout，不手抄）
  • finalize_travel.py — 从 travel_detail 重建 travel.json（含组合卡死阈值提示）

三个校验脚本共用同一套零件表与运动学链（strength_check.part_table / chain， 关节轴来自 human_layout.py），改几何后不存在"报告与模型不同步"的问题。 环境变量：ARMPAY(末端负载 kg)、ARMDYN(动载系数)、ARMINFILL(实体率)、 ARMMAT(材料)、ARMT_CONT/ARMT_PEAK/ARMT_ALLOW(电机力矩)、ARMT_ALPHA(角加速度)。