dl2

README.md

@@ -1,46 +1,55 @@
-# Soft Arm Sim - ROS 2 柔性机械臂仿真平台
+# Soft Arm Sim - ROS 2 柔性机械臂深度学习与仿真平台
 
-这是一个基于 ROS 2 (Humble) 开发的柔性机械臂（Soft Manipulator）仿真系统。
+![ROS2 Humble](https://img.shields.io/badge/ROS2-Humble-blue) ![PyTorch](https://img.shields.io/badge/PyTorch-Deep%20Learning-red) ![License](https://img.shields.io/badge/License-MIT-green)
-项目实现了基于 **常曲率（PCC）** 假设的运动学模型，并解决了软体机器人在 Rviz 中常见的 **视觉同步延迟问题**，实现了高帧率、无滞后的动态仿真。
 
-## 🤖 项目概况
+这是一个基于 ROS 2 Humble 开发的通用柔性机械臂（Soft Manipulator）仿真与控制平台。
+本项目不仅实现了基于 **常曲率（PCC）** 的运动学模型和高帧率无延迟仿真，还集成了一套完整的 **数据驱动逆运动学（Data-Driven IK）** 深度学习工作流，支持 3D 轨迹规划与避障。
 
-- **机器人构型**：3 段 PCC 串联结构。
+## 🤖 机器人参数
-- **物理参数**：总长 720mm (3段 x 240mm)，每段包含 3 个圆盘（Disk），直径 80mm。
-- **核心特性**：
-  - **解耦架构**：数学模型 (Model)、可视化 (Base)、控制 (Control) 完全分离。
-  - **零延迟可视化**：采用 `MarkerArray` 技术同时渲染骨架与圆盘，彻底消除 TF 插值导致的时序不同步。
-  - **扩展性**：预留了深度学习（RL）与硬件电机控制接口。
 
-## 📂 文件结构说明
+- **物理构型**：3 段串联 PCC (Piecewise Constant Curvature) 结构。
+- **尺寸参数**：
+  - 总长：0.72m (3段 x 0.24m)
+  - 磁盘直径：80mm
+  - 绳索孔距：33mm
+- **自由度**：6 DoF (Configuration Space: $\theta_1, \phi_1, \dots, \theta_3, \phi_3$)。
+
+## ✨ 核心特性
+
+1. **零延迟可视化 (Zero-Latency Viz)**：
+    - 摒弃传统的 `RobotModel` + TF 插值方案，采用自定义 `MarkerArray` 技术，实现了骨架与圆盘的绝对时序同步，彻底消除 Rviz 中的“视觉拖影”问题。
+
+2. **深度学习逆运动学 (Deep Learning IK)**：
+    - 基于 PyTorch 的全连接网络 (MLP)。
+    - 采用 **三角函数编码 (Trigonometric Encoding)** 解决关节角周期性断崖问题。
+    - 实现了 **Sim2AI2Sim** 闭环：数据生成 -> 模型训练 -> 实时推理控制。
+
+3. **智能规划与避障**：
+    - 内置基于人工势场法 (APF) 的简易避障算法，能够自动规划路径绕过障碍物。
+    - 支持 3D 空间内的点对点轨迹插值规划。
+
+4. **高度可配置**：
+    - 所有物理参数均通过 `config/config.yaml` 管理，无需修改代码即可调整机械臂尺寸。
+
+## 📂 项目结构
 
 ```text
-src/
+src/soft_arm_sim/
-├── soft_arm_sim/
+├── config/                     # [配置] 机器人物理参数与仿真频率配置
-│   ├── config/                     # [预留] 存放 .yaml 配置文件 (如机械臂尺寸参数)
+│   └── config.yaml
-│   ├── launch/
+├── launch/                     # [启动] 一键启动脚本
-│   │   └── simulate.launch.py      # [启动] 一键启动脚本，同时加载 Rviz、仿真节点和状态发布器
+├── soft_arm_sim/               # === Python 核心源码 ===
-│   ├── resource/                   # ROS 资源索引文件
+│   ├── base/                   # [可视化层]
-│   ├── urdf/
+│   │   └── simulation_node.py  # 核心仿真器：计算 PCC 正解，发布无延迟 Marker 和 TF
-│   │   └── soft_arm.urdf.xacro     # [模型] 机器人的物理描述文件 (主要用于定义 base_link 关系)
+│   ├── control/                # [传统控制]
-│   ├── soft_arm_sim/               # === Python 核心源码包 ===
+│   │   └── test_controller.py  # 简单的正弦波开环控制示例
-│   │   ├── __init__.py
+│   ├── model/                  # [数学层]
-│   │   ├── base/                   # [可视化层]
+│   │   └── pcc_kinematics.py   # 纯数学 PCC 运动学库 (无 ROS 依赖，可被 PyTorch 调用)
-│   │   │   ├── __init__.py
+│   └── deeplearning/           # [智能层 - 核心亮点]
-│   │   │   └── simulation_node.py  # [核心节点] 负责：
+│       ├── dataset_generator.py # 数据生成器：生成平滑约束下的 (Pos -> Angles) 数据集
-│   │   │                           # 1. 调用 Model 计算运动学
+│       ├── train.py             # 训练脚本：带有归一化和学习率衰减的训练流程
-│   │   │                           # 2. 发布 TF (用于后台坐标系维护)
+│       ├── pinn_model.py        # 网络定义：支持三角编码的高维 MLP
-│   │   │                           # 3. 发布 MarkerArray (用于 Rviz 零延迟显示 Disk 和 轴线)
+│       ├── inference_node.py    # 推理节点：加载模型，实现 3D 规划、避障与闭环控制
-│   │   ├── control/                # [控制层]
+│       └── *.pth / *.csv        # 训练好的模型权重与数据集
-│   │   │   ├── __init__.py
+└── urdf/                       # [描述] 机器人的基础 TF 树描述
-│   │   │   └── test_controller.py  # [示例] 发送正弦波信号，测试机械臂蠕动效果
+```
-│   │   ├── deeplearning/           # [学习层] 预留给 Gym 环境或强化学习训练脚本
-│   │   ├── model/                  # [数学层]
-│   │   │   ├── __init__.py
-│   │   │   └── pcc_kinematics.py   # [算法] 纯数学 PCC 正运动学解算，生成 Disk 变换矩阵和贝塞尔曲线点
-│   ├── package.xml                 # ROS 包依赖描述
-│   ├── setup.cfg                   # Python 脚本安装路径配置 (解决 libexec 报错)
-│   └── setup.py                    # Python 包构建配置
-└── startbash                       # [工具] 自定义启动脚本 (如果包含相关指令)
-
-