soft-robot/README.md

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

这是一个基于 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 管理，无需修改代码即可调整机械臂尺寸。

📂 项目结构

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 树描述