soft-robot/README.md

# Soft Arm Sim - ROS 2 柔性机械臂深度学习与仿真平台

![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)

这是一个基于 ROS 2 Humble 开发的通用柔性机械臂（Soft Manipulator）仿真与控制平台。
本项目不仅实现了基于 **常曲率（PCC）** 的运动学模型和高帧率无延迟仿真，还集成了一套完整的 **数据驱动逆运动学（Data-Driven IK）** 深度学习工作流，支持 3D 轨迹规划与避障。

## 🤖 机器人参数

- **物理构型**：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/soft_arm_sim/
├── config/                     # [配置] 机器人物理参数与仿真频率配置
│   └── config.yaml
├── launch/                     # [启动] 一键启动脚本
├── soft_arm_sim/               # === Python 核心源码 ===
│   ├── base/                   # [可视化层]
│   │   └── simulation_node.py  # 核心仿真器：计算 PCC 正解，发布无延迟 Marker 和 TF
│   ├── control/                # [传统控制]
│   │   └── test_controller.py  # 简单的正弦波开环控制示例
│   ├── model/                  # [数学层]
│   │   └── pcc_kinematics.py   # 纯数学 PCC 运动学库 (无 ROS 依赖，可被 PyTorch 调用)
│   └── deeplearning/           # [智能层 - 核心亮点]
│       ├── dataset_generator.py # 数据生成器：生成平滑约束下的 (Pos -> Angles) 数据集
│       ├── train.py             # 训练脚本：带有归一化和学习率衰减的训练流程
│       ├── pinn_model.py        # 网络定义：支持三角编码的高维 MLP
│       ├── inference_node.py    # 推理节点：加载模型，实现 3D 规划、避障与闭环控制
│       └── *.pth / *.csv        # 训练好的模型权重与数据集
└── urdf/                       # [描述] 机器人的基础 TF 树描述
```