sladro
91a6821c0c
- 修复play_recording方法中错误调用clear_all_paths()的问题 - path_visualization是列表类型，应使用遍历方式清除PyBullet debug线条 - 更新CLAUDE.md文档记录此次修复 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
194 lines
7.5 KiB
Markdown
194 lines
7.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
这是一个**现实环境机械臂运作可行性测试项目**，用于验证真实工业机械臂在复杂环境中的作业能力。
|
||
|
||
### 核心测试需求
|
||
|
||
**主要目标**：验证机械臂能否在有障碍物的现实环境中完成精确作业任务
|
||
|
||
**测试场景**：机械臂从指定基座位置出发，到达取物点A，抓取物体，通过智能路径规划避开障碍物（包括但不限于穿越洞口），到达目标点B并释放物体
|
||
|
||
**现实对应**：
|
||
- 工厂环境中的跨区域物料传送
|
||
- 建筑工地的穿墙作业
|
||
- 危险环境中的精确物品递送
|
||
- 医疗手术中的精密器械传递
|
||
|
||
**可行性验证内容**：
|
||
1. **到达性分析**：机械臂工作空间是否覆盖所有任务点
|
||
2. **避障能力**：是否能规划出安全路径（根据环境自动选择直达、绕行或穿越策略）
|
||
3. **精度要求**：是否能在约束空间内完成精确操作
|
||
4. **安全性**：整个作业过程是否避免碰撞
|
||
|
||
## 技术栈
|
||
|
||
- **PyBullet**: 物理仿真引擎（统一使用PyBullet进行运动学计算和仿真）
|
||
- **AI RRT***: 路径规划算法
|
||
|
||
## 路径规划设计理念
|
||
|
||
系统采用通用RRT*算法，根据实际环境配置自动选择最优路径：
|
||
- 如果存在直达路径，选择直线（最高效）
|
||
- 如果有障碍阻挡，自动避障（可能穿洞或绕行）
|
||
- 不强制特定路径形态，由算法根据环境智能决策
|
||
|
||
## 配置管理原则
|
||
|
||
**配置管理遵循单一职责原则：**
|
||
|
||
### 跨文件共享配置（存储在 `config.json`）
|
||
- 机械臂模型路径从 `config.robot.model_path` 读取
|
||
- 墙体参数从 `config.wall` 读取
|
||
- 洞口参数从 `config.hole` 读取
|
||
- 任务点A、B从 `config.task_points` 读取
|
||
- 运送物体参数从 `config.transport_object` 读取
|
||
- 仿真参数从 `config.simulation` 读取
|
||
- 路径规划的碰撞检测和执行参数从 `config.path_planning` 读取
|
||
|
||
### 单文件专用配置（定义为文件内常量）
|
||
- **运动学求解参数**：在 `src/robot/kinematics.py` 中定义 `MAX_ITERATIONS`、`EPSILON`
|
||
- **RRT*算法参数**：在 `src/planning/ai_rrt_star.py` 中定义所有算法常量
|
||
- **路径优化参数**：在 `src/planning/path_optimizer.py` 中定义优化常量
|
||
- **GUI界面参数**：在 `src/gui/main_window.py` 中定义界面常量
|
||
- **洞口穿越参数**：在 `src/planning/hole_crossing.py` 中定义策略常量
|
||
|
||
**原则**：配置文件用于多文件共享，单文件使用的参数定义为文件内常量
|
||
|
||
## 项目架构
|
||
|
||
### 目录结构
|
||
- `config.json`: **核心配置文件**，包含所有运行参数
|
||
- `models/`: 机械臂模型文件目录
|
||
- `manual_robot.urdf`: 9自由度机械臂URDF配置文件
|
||
- `CLAUDE.md`: 项目开发指南
|
||
|
||
### 机械臂模型规范
|
||
- 使用URDF格式定义机械臂模型
|
||
- 遵循右手坐标系统：X轴(红色)、Y轴(绿色)、Z轴(蓝色)
|
||
- 关节轴向定义：
|
||
- `xyz="1 0 0"`: 绕X轴旋转
|
||
- `xyz="0 1 0"`: 绕Y轴旋转
|
||
- `xyz="0 0 1"`: 绕Z轴旋转
|
||
|
||
### 坐标系统
|
||
- 位置定义：`<origin xyz="x y z" rpy="roll pitch yaw"/>`
|
||
- xyz: 位置偏移（米）
|
||
- rpy: 旋转角度（弧度） - roll绕X轴，pitch绕Y轴，yaw绕Z轴
|
||
|
||
## 开发指导
|
||
|
||
### 核心功能模块
|
||
1. **机械臂控制模块**: 基于pybullet的仿真控制
|
||
2. **路径规划模块**: 使用RRT*算法进行避障路径规划
|
||
3. **运动学计算模块**: 使用kdl进行正逆运动学计算
|
||
4. **障碍物检测模块**: 碰撞检测和环境感知
|
||
|
||
## 业务流程（严格按此顺序执行）
|
||
|
||
### 1. 系统初始化
|
||
1. **读取配置文件**: 从 `config.json` 加载所有配置参数
|
||
2. **验证配置**: 检查所有必要参数是否存在且有效
|
||
3. **初始化pybullet仿真环境**: 使用 `config.simulation` 参数
|
||
|
||
### 2. 环境构建
|
||
1. **加载机械臂**: 使用 `config.robot.model_path` 指定的URDF文件
|
||
2. **设置机械臂基座**: 使用 `config.robot.base_position` 和 `base_orientation`
|
||
3. **创建墙体障碍**: 根据 `config.wall` 参数创建墙体
|
||
4. **创建洞口**: 在墙体中根据 `config.hole` 参数创建洞口
|
||
5. **放置运送物体**: 在 `config.transport_object.initial_position` 放置物体
|
||
|
||
### 3. 任务执行
|
||
1. **路径规划阶段1**: 机械臂基座 → A点（取物点）
|
||
2. **抓取物体**: 在A点抓取运送物体
|
||
3. **路径规划阶段2**: A点 → 穿越洞口 → B点（避障路径规划）
|
||
4. **运送物体**: 携带物体穿越障碍到达B点
|
||
5. **释放物体**: 在B点释放物体
|
||
|
||
### 4. 关键约束
|
||
- **配置驱动**: 所有参数必须从config.json读取
|
||
- **避障要求**: 机械臂和物体不能与墙体碰撞，只能通过洞口
|
||
- **路径平滑**: 使用RRT*算法确保路径可行且平滑
|
||
- **运动学约束**: 遵循机械臂的运动学限制
|
||
|
||
## 开发规范
|
||
|
||
### 配置文件使用规范
|
||
```python
|
||
# 正确的配置读取方式
|
||
import json
|
||
|
||
# 1. 必须首先读取配置文件
|
||
with open('config.json', 'r') as f:
|
||
config = json.load(f)
|
||
|
||
# 2. 从配置读取机械臂模型路径
|
||
robot_model_path = config['robot']['model_path']
|
||
|
||
# 3. 从配置读取所有其他参数
|
||
wall_params = config['wall']
|
||
hole_params = config['hole']
|
||
task_points = config['task_points']
|
||
transport_object = config['transport_object']
|
||
```
|
||
|
||
### 严禁的做法
|
||
```python
|
||
# ❌ 严禁硬编码路径和参数
|
||
robot_model = "models/manual_robot.urdf" # 错误！
|
||
wall_position = [2.0, 0.0, 1.0] # 错误！
|
||
```
|
||
|
||
### 测试验证
|
||
- 配置文件修改后，程序行为应相应改变
|
||
- 不同的机械臂模型应能正确加载
|
||
- 墙体和洞口参数变化应反映在仿真中
|
||
- A、B点位置调整应影响路径规划结果
|
||
|
||
## 系统架构更新（2025-01-14）
|
||
|
||
### PyBullet统一架构 ✅ 已完成
|
||
系统已完全迁移到PyBullet架构，彻底移除了KDL依赖：
|
||
- **运动学计算**：全部使用PyBullet的IK/FK
|
||
- **碰撞检测**：使用PyBullet原生功能
|
||
- **关节顺序**：统一使用PyBullet顺序，无需转换
|
||
- **已删除文件**：`src/robot/kinematics.py`（KDL相关代码）
|
||
|
||
### 主要改进
|
||
1. **精度提升**：IK residualThreshold从0.001降至0.0001
|
||
2. **容差调整**：position_tolerance从0.02增至0.05
|
||
3. **代码简化**：移除了所有关节顺序转换代码
|
||
4. **架构统一**：消除了KDL和PyBullet混用导致的不一致性
|
||
5. **维护性提升**：减少了外部依赖，降低了系统复杂度
|
||
|
||
## 录制回放功能 ✅
|
||
|
||
**核心功能**：
|
||
- 执行时录制关节位置、路径数据
|
||
- 回放时显示路径和精确重现动作
|
||
- 自动保存为时间戳命名的JSON文件
|
||
|
||
**最新修复**（2025-09-14）：
|
||
- 修复录制回放时路径可视化错误：AttributeError: 'list' object has no attribute 'clear_all_paths'
|
||
- 修复位置：src/gui/main_window.py:1058行，将错误的clear_all_paths()调用替换为正确的清除逻辑
|
||
|
||
## 碰撞可视化功能 ✅（2025-01-14）
|
||
|
||
**功能描述**：当路径规划检测到碰撞时，将碰撞的双方（机器人link和障碍物）显示为红色
|
||
|
||
**实现方案**：
|
||
1. **碰撞检测增强**：添加`check_collision_detailed()`方法返回碰撞对信息
|
||
2. **可视化实现**：碰撞双方自动变红色标记，保存原始颜色以便恢复
|
||
3. **路径执行改进**：即使有碰撞也尝试执行路径，让物理引擎自然处理碰撞
|
||
|
||
## 重要提醒
|
||
|
||
**开发原则**：
|
||
- 听话照做，不添加用户未要求的功能
|
||
- 简单直接，能1行解决绝不写2行
|
||
- 配置驱动，所有参数从config.json读取
|
||
- 错误立即暴露，不使用后备方案掩盖故障
|
||
- MVP至上，严禁过度开发 |