Robot_Arm/README.md

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

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

---

## 🌟 核心设计特性

1. **一体化直锁电机**：全面取消外挂独立端面齿联轴器，所有关节由 3×M2 沉头螺钉直锁电机输出轴，轴向尺寸大幅压缩，刚度显著提升。
2. **五级流线圆角系统**：建立统一的有机曲面过渡规范（R=1.5mm 微圆角 ~ R=15mm 视觉主导大圆角），彻底消除锐边与机械生硬台阶。
3. **全行程动态零干涉**：经 `sweep_v2.py` 多进程全域扫描与二分逼近验证，各自由度极限角度下实现 0 碰撞。
4. **100% 流形单实体**：9/9 构件均为无缝单一实体拓扑，完全杜绝浮动壳体与布尔破碎，满足 FDM/SLA 打印及 CNC 加工要求。

---

## 🚀 快速上手

### 1. 编译并导出最新模型
一键重新生成全部 9 个打印构件、装配体、STEP/STL 制造文件及 3D 查看器数据：
```bash
python src/arm_model.py
```
> 导出的 STEP 文件保存在 `out/parts_step/`，打印用 STL 保存在 `out/print_stl/`（重跑构建自动更新）。

### 2. 全行程动态防碰撞扫描
多进程并行扫描全关节运动极限硬边界，并更新滑动安全范围：
```bash
python src/sweep_v2.py
```

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

---

## 📁 项目目录结构

```
机器人手臂/
├── 机器人手臂3D查看器.html        # 单文件内置 3D 查看器（双击即用）
├── README.md                     # 本说明文档
├── src/                          # 核心源码目录
│   ├── arm_model.py              # ⭐ 唯一权威主力建模脚本（含五级圆角与最新几何）
│   ├── 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         # 关节力矩平衡校核
├── 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 |
| **P05** | 大臂旋转座 | J2 ➔ J3 | 16 层 Loft 曲面平滑过渡，直锁 M2，后侧刚性抱紧 M3 |
| **P06** | 大臂骨架 | J3 ➔ J4 | 流线型工字背脊骨架，直锁 M3，下端抱紧 M4 肘电机 |
| **P07** | 小臂骨架 | J4 ➔ J5 | L 型圆弧强化立柱，大范围自由运动避让，抱紧 M5 |
| **P08** | 腕偏转座 | J5 ➔ J6 | 16 层 Loft 双曲面过渡，直锁 M5，立式抱紧 M6 腕旋转电机 |
| **P09** | 工具法兰 | J6 输出 | 直锁 M6 输出轴，标准工业 ISO 法兰（4x M4 螺孔 BCD 40mm） |
| **M1~M6** | 关节电机模组 ×6 | 各关节驱动 | Ø60 方形标准减速电机模组（63.6mm 方形尾盖），210 g/台，整机 1260 g |

> ⚠️ **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 吊臂根座安全系数 8.93，
> 最大挠度 1.6mm。减重救不了电机——J1 的 distal 载荷里 5 台电机占 65%（1.05kg），
> 打印件只占 0.58kg，把 P07/P08/P09 全部减掉 J1 也只降到 2.54 N·m。

---

## 📚 详细文档导航

- 📘 **权威数据（工具自动生成）**：
  - [各关节行程与硬限位 travel.json](file:///g:/Robot_v2/机器人手臂/docs/travel.json)（sweep_v2.py 扫描生成，修改几何后必须重扫）
    > 滑块范围 = **单关节**硬限位。组合折叠姿态下另有干涉约束，见 `travel_detail.json` 的
    > `combos` 字段（目前全部是工具法兰 P09 撞躯干占位 P01_A，属真约束）；查看器运行期
    > 另有胶囊碰撞模型按姿态夹取。
  - [零件明细与质量属性 bom.json](file:///g:/Robot_v2/机器人手臂/docs/bom.json)（构建自动生成）
  - [静态干涉检测结果 collision.json](file:///g:/Robot_v2/机器人手臂/docs/collision.json)（构建自动生成）
  - [截面刚度与应力 strength.json](file:///g:/Robot_v2/机器人手臂/docs/strength.json)（strength_check.py 生成）
  - [关节力矩与负载能力 torque_report.md](file:///g:/Robot_v2/机器人手臂/docs/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`(角加速度)。