README.md

---
license: mit
library_name: pytorch
tags:
  - robotics
  - reinforcement-learning
  - visuo-tactile
  - grasping
  - pybullet
  - tacto
---

# Single-Step Grasp Refinement

This repository stages the public checkpoint for the single-step visual-tactile grasp refinement policy. The default release contains one evaluation-ready Full SGA-GSN model trained with the PPCT/SGA-GSN perception backbone.

License: MIT. The single-step RL code and staged model checkpoint are released
under the same permissive license family as the AdaPoinTr-derived SGA-GSN code.
Dataset, perception weights, and simulation assets remain separate dependencies
with their own license terms.

## Contents

```text
checkpoints/full_sga_gsn_seed8_best.pt
configs/full_sga_gsn_seed8/configs/
metadata/
normalization/
ablations/
backbones/
```

The public checkpoint keeps `actor_critic`, `calibrator`, `experiment_cfg`, `object_split`, and best-metric metadata. It omits `optimizer` and full training `history`, so it is intended for rollout/evaluation rather than exact training resume.

## Default Model

- Release name: `full_sga_gsn_seed8`
- Best validation metric: `validation/outcome/success_lift_vs_dataset = 0.109375`
- Best iteration: `465`
- Completed iterations: `466`
- Split seed: `7`
- Train objects: `000` to `074`
- Validation objects: `078`, `082`, `085`, `087`
- Test objects: `075`, `076`, `077`, `079`, `080`, `081`, `083`, `084`, `086`

The formal unseen-test summary used for this staging pass reports `macro_success_lift_mean = 0.0969230769` for `full-sga-gsn-seed8`. See `metadata/evaluation_metrics.json` for the full table.

## Required External Assets

This model repo does not include the perception weights, dataset, or simulator assets. A working rollout environment must provide:

- SGA-GSN perception code and weights:
  - `ap_ps55.pth`
  - PPCT/SGA-GSN `ckpt-best.pth`
  - matching PPCT/SGA-GSN config
- 3DA-VTG dataset restored to the path expected by the RL config.
- VT-Grasp simulation assets:
  - GraspNet VHACD object models
  - GSmini TACTO config/background
  - GSmini Panda hand assets
- The RL code and Docker environment that define `scripts/evaluate_best_checkpoints.py`, PyBullet, TACTO, and the environment wrappers.

The `v1.1.0` config snapshot uses the public runtime variables
`VT_GRASP_SGAGSN_ROOT`, `VT_GRASP_DATASET_ROOT`, and
`VT_GRASP_OUTPUT_ROOT`. The public bootstrap command creates the required
weight and asset links without legacy compatibility paths.

## Config Snapshot

The config snapshot is nested as:

```text
configs/full_sga_gsn_seed8/configs/{experiment,env,perception,calibration,rl,model}/
```

This preserves compatibility with the RL loader, which resolves paths such as `configs/env/grasp_refine_env_stb5x.yaml` relative to a directory named `configs`.

The recommended setup is:

```bash
bootstrap_release.sh all-small
```

For evaluation, copy or symlink this inner `configs/` directory next to `checkpoints/best.pt` in an experiment directory:

```text
my_eval_exp/
├── checkpoints/
│   └── best.pt
└── configs/
    ├── experiment/
    ├── env/
    ├── perception/
    ├── calibration/
    ├── rl/
    └── model/
```

## Normalization

No separate observation normalization file was found in the current RL code or selected experiment. Action scaling is encoded in `configs/full_sga_gsn_seed8/configs/env/grasp_refine_env_stb5x.yaml`:

- `translation_bound: [0.01, 0.01, 0.01]`
- `rotation_bound: [0.1, 0.1, 0.1]`

## Ablations

The minimal public release does not include ablation checkpoints. Learned ablation candidates are documented in `ablations/README.md`. `no-action` and `rand-action` baselines do not require model weights.

## Checksums

Run checksum verification from the repository root:

```bash
sha256sum -c checksums.sha256
```