Add model card

README.md

@@ -0,0 +1,114 @@
+---
+license: apache-2.0
+library_name: robomimic
+pipeline_tag: robotics
+tags:
+- robotics
+- diffusion-policy
+- imitation-learning
+- lerobot
+- variable-admittance
+- force-control
+- doosan
+datasets:
+- aleleanza/vac-pipe-dual-cam
+---
+
+# Diffusion Policy — VAC Pipe Insertion (input/output ablation)
+
+Six **stock robomimic Diffusion Policy** checkpoints for the contact-rich
+**pipe-insertion** task on a Doosan M0609 + Inspire RH56 hand under a **Variable
+Admittance Controller (VAC)**. All trained on
+[`aleleanza/vac-pipe-dual-cam`](https://huggingface.co/datasets/aleleanza/vac-pipe-dual-cam)
+(202 episodes, 145,712 frames @ 50 Hz).
+
+This repo is a clean **2 × 3 ablation**: two *output* representations (where the policy
+sits relative to the admittance filter) × three *input* modalities.
+
+## Variants (subfolders)
+
+| Subfolder | Output (action) | Inputs (obs) | Action dim | Best val loss | @epoch |
+|---|---|---|---:|---:|---:|
+| `vac_pre_vis` | **pre**: `user_cmd[6]` + `K` + `ζ` + `hand_binary` | vision | 9 | 0.2445 | 67 |
+| `vac_pre_vis_wrench` | pre | vision + wrench | 9 | 0.2583 | 8 |
+| `vac_pre_vis_wrench_state` | pre | vision + wrench + state | 9 | 0.2739 | 11 |
+| `vac_post_vis` | **post**: `vel_cmd[6]` + `hand_binary` | vision | 7 | 0.0580 | 48 |
+| `vac_post_vis_wrench` | post | vision + wrench | 7 | 0.0572 | 48 |
+| `vac_post_vis_wrench_state` | post | vision + wrench + state | 7 | **0.0547** | 48 |
+
+- **pre** = predict the operator command *before* admittance, including the compliance
+  command itself (`stiffness_cmd` K + damping ζ) → the policy *learns to set compliance*.
+  Consumed downstream by the variable-admittance node.
+- **post** = predict the Cartesian velocity the controller executed *after* admittance →
+  the policy bypasses admittance and drives velocity directly.
+
+Each subfolder contains:
+
+```
+<variant>/
+├── best.pth              # lowest validation loss
+├── last.pth              # final epoch
+├── config.json           # full robomimic training config
+├── action_stats.json     # action normalization (min-max) + action_components + hand binarization
+└── dataset_summary.json  # train/valid episode split + frame counts
+```
+
+## Architecture & training
+
+- **Algorithm:** robomimic Diffusion Policy (DDPM noise-prediction loss; **no** anchor /
+  additional loss — stock).
+- **Backbone:** conditional UNet `[128, 256, 512]`; ~89.4–90.0M params.
+- **Horizons:** observation 2, action 4, prediction 8 (frame stack 2, seq length 8).
+- **Image:** D405 wrist stream (`observation.images.camera`) → `front_rgb`, **84×84**.
+- **Common:** 300 epochs, batch 16, lr 1e-4, DDPM 50/50 train/infer steps.
+- **Split:** train episodes 0–171, valid 172–201.
+- **Action normalization:** min-max to [−1, 1]; hand head is **binarized** from
+  `action.absolute[:, 8:12]` (mean ≥ 0.85 → open). See each `action_stats.json`.
+
+### Reading the results
+
+The **post** (vel_cmd) variants reach far lower validation loss (~0.055–0.058) than the
+**pre** (user_cmd + K + ζ) variants (~0.24–0.27): predicting executed velocity is an
+easier target than predicting raw operator intent plus compliance. For `pre + wrench`
+and `pre + wrench+state` the best validation arrives very early (epoch 8–11) while
+training loss keeps dropping — a sign of **overfitting on proprioceptive inputs** at this
+model/dataset size. Adding wrench/state did **not** help at this scale.
+
+## Inference (ROS 2)
+
+Run with the project's `robot_learning` real-time inference nodes (Doosan M0609 + Inspire
+hand). The action contract determines the runner:
+
+- **`pre` variants (9D)** → `diffusion_policy_vac_preimg_runner`. Publishes
+  `/delta_pose_cmd` + `/predicted_K` + `/predicted_zeta`, consumed by
+  `variable_admittance_node` (`variable_K:=true`). Add the Bota driver for `*_wrench*`.
+- **`post` variants (7D)** → velocity runner: streams `vel_cmd` directly via the DSR
+  `speedl` interface (no admittance node).
+
+```bash
+# pre family (variable-stiffness path)
+ros2 run robot_learning diffusion_policy_vac_preimg_runner \
+  --ros-args -p checkpoint:=/path/to/vac_pre_vis_wrench_state/best.pth
+
+# post family (direct velocity path)
+ros2 run robot_learning diffusion_policy_fixed_k_runner \
+  --ros-args -p checkpoint:=/path/to/vac_post_vis_wrench_state/best.pth -p mode:=vel_cmd
+```
+
+The binary hand head publishes to `/inspire_hand/left/cmd`; RGB observations come from
+the compressed camera topic; `*_wrench*` variants subscribe to `/bota_ft_sensor/wrench`
+(tared per trial). `action_stats.json` provides the exact normalization to undo at
+inference.
+
+## Intended use & limitations
+
+- **Use:** research on force-aware / compliance-predicting imitation learning for
+  contact-rich insertion; a baseline ablation for VAC.
+- **Limitations:** single task (`pipe_fixing`), single embodiment (M0609 + RH56), 84×84
+  vision, binary hand. The `pre` variants overfit at this scale. Not validated for
+  safety-critical or autonomous deployment.
+
+## Related
+
+- **Dataset:** [`aleleanza/vac-pipe-dual-cam`](https://huggingface.co/datasets/aleleanza/vac-pipe-dual-cam)
+- **Collection:** *VAC — Pipe Insertion*