readme

README.md

@@ -1,24 +1,43 @@
 # Soft Arm Sim - ROS 2 柔性机械臂仿真平台
 
-这是一个基于 ROS 2 (Humble) 开发的柔性机械臂（Soft Manipulator）仿真程序。
-项目实现了基于常曲率（PCC）假设的运动学模型，包含可视化仿真、运动控制接口，并预留了深度学习与硬件控制的扩展接口。
+这是一个基于 ROS 2 (Humble) 开发的柔性机械臂（Soft Manipulator）仿真系统。
+项目实现了基于 **常曲率（PCC）** 假设的运动学模型，并解决了软体机器人在 Rviz 中常见的 **视觉同步延迟问题**，实现了高帧率、无滞后的动态仿真。
 
-## 🤖 机器人参数
-- **结构**：3 段 PCC (Piecewise Constant Curvature) 串联
-- **每段配置**：
-  - 长度：240mm (3 disks × 80mm间隔)
-  - 磁盘直径：80mm
-  - 绳索孔距：33mm
-- **自由度**：配置空间 (Configuration Space) 控制，每段由 `theta` (弯曲角) 和 `phi` (偏转角) 定义。
+## 🤖 项目概况
+- **机器人构型**：3 段 PCC 串联结构。
+- **物理参数**：总长 720mm (3段 x 240mm)，每段包含 3 个圆盘（Disk），直径 80mm。
+- **核心特性**：
+  - **解耦架构**：数学模型 (Model)、可视化 (Base)、控制 (Control) 完全分离。
+  - **零延迟可视化**：采用 `MarkerArray` 技术同时渲染骨架与圆盘，彻底消除 TF 插值导致的时序不同步。
+  - **扩展性**：预留了深度学习（RL）与硬件电机控制接口。
+
+## 📂 文件结构说明
 
-## 📂 文件结构
 ```text
-src/soft_arm_sim/
-├── soft_arm_sim/          # Python 核心源码
-│   ├── base/              # ROS 2 仿真节点 (TF发布, Marker绘制)
-│   ├── control/           # 控制算法 (测试控制器, PID, 甚至 RL)
-│   ├── model/             # 纯数学模型 (PCC运动学, 无ROS依赖)
-│   └── deeplearning/      # 强化学习环境 (Gym)
-├── launch/                # 启动脚本
-├── urdf/                  # 机器人视觉模型描述 (Xacro)
-└── resource/              # ROS 资源文件
+src/
+├── soft_arm_sim/
+│   ├── config/                     # [预留] 存放 .yaml 配置文件 (如机械臂尺寸参数)
+│   ├── launch/
+│   │   └── simulate.launch.py      # [启动] 一键启动脚本，同时加载 Rviz、仿真节点和状态发布器
+│   ├── resource/                   # ROS 资源索引文件
+│   ├── urdf/
+│   │   └── soft_arm.urdf.xacro     # [模型] 机器人的物理描述文件 (主要用于定义 base_link 关系)
+│   ├── soft_arm_sim/               # === Python 核心源码包 ===
+│   │   ├── __init__.py
+│   │   ├── base/                   # [可视化层]
+│   │   │   ├── __init__.py
+│   │   │   └── simulation_node.py  # [核心节点] 负责：
+│   │   │                           # 1. 调用 Model 计算运动学
+│   │   │                           # 2. 发布 TF (用于后台坐标系维护)
+│   │   │                           # 3. 发布 MarkerArray (用于 Rviz 零延迟显示 Disk 和 轴线)
+│   │   ├── control/                # [控制层]
+│   │   │   ├── __init__.py
+│   │   │   └── test_controller.py  # [示例] 发送正弦波信号，测试机械臂蠕动效果
+│   │   ├── deeplearning/           # [学习层] 预留给 Gym 环境或强化学习训练脚本
+│   │   ├── model/                  # [数学层]
+│   │   │   ├── __init__.py
+│   │   │   └── pcc_kinematics.py   # [算法] 纯数学 PCC 正运动学解算，生成 Disk 变换矩阵和贝塞尔曲线点
+│   ├── package.xml                 # ROS 包依赖描述
+│   ├── setup.cfg                   # Python 脚本安装路径配置 (解决 libexec 报错)
+│   └── setup.py                    # Python 包构建配置
+└── startbash                       # [工具] 自定义启动脚本 (如果包含相关指令)