Cloth-splatters/dexgarmentlab-lift-correspondence-20260822

DexGarmentLab Lift Correspondence 2026-08-22

This is the point-cloud correspondence dataset used by the UniGarmentManip flat/deformation representation experiment pinned at commit 0701bc475877da68bc07f727a1995fd78a3de511, together with the full-state trajectory HDF5 used to train UniClothDiff models.

It contains 1,800 bimanual lift episodes (1,687 successful, 113 recorded failures) spanning tops, dresses, and trousers with garment-disjoint train/validation/test splits (see Splits below). The flat view contains one pre-contact observation per episode. The deformation view contains 16 deterministic progress-bin observations per episode (28,800 observations), including the recorded pre-grasp, single-grasp, and bimanual phases.

Each observation has 2,048 XYZ points and persistent surface-template IDs. Reviewed semantic-keypoint correspondences and visibility distances are also included. The manifests record episode IDs, garment IDs, task, split, source hashes, frame/control/time alignment, trajectory progress, and grasp phase.

Files

flat/
  clouds.npy
  surface_ids.npy
  semantic_indices.npy
  semantic_distance_m.npy
  manifest.json
  audit.json
deformation/
  clouds.npy
  surface_ids.npy
  semantic_indices.npy
  semantic_distance_m.npy
  manifest.json
  cache_audit.json
splits/
  shape-ood-v1.json          # current split (garment -> split, episode -> split)
  random-garment-v0.json     # original 2026-08-22 split, kept for provenance
dexgarmentlab_lift_full_state_20260822.h5          # full-state trajectories (31.6 GB)
dexgarmentlab_lift_full_state_20260822.audit.json
dexgarmentlab_lift_full_state_20260822.sha256
SHA256SUMS

The NumPy arrays are uncompressed and memory-mappable. Array row metadata is in the corresponding manifest.json. All coordinates and semantic distances are in metres.

Integrity and scope

Both cache audits pass. The deformation cache contains exactly 1,800 unique episodes and 28,800 aligned observations, with all 16 progress bins present for every episode and surface IDs in range.

The flat/ and deformation/ caches are the visible point-cloud correspondence cache and do not contain hidden mesh vertices, topology, or gripper trajectories; do not treat the visible cloud as complete-state ground truth. Those fields live in dexgarmentlab_lift_full_state_20260822.h5 (schema uniclothdiff-dexgarmentlab-full-state/v1): per trajectory the full mesh vertex positions, gripper poses and grasp states, actuated-vertex masks, the camera cloud with per-point surface IDs, and per-cloth rest positions, faces and edges. Groups are keyed <split>/<garment>/<trajectory>.

Splits

The current split is `shape-ood-v1` (recorded as split_scheme in both manifests, both audits, and the HDF5 root attributes). Splits are garment-disjoint. For each category, the test set is a held-out shape cluster: garments were clustered by symmetric Chamfer distance between their rest meshes (average linkage) and the cluster furthest from all remaining garments was held out, so that no test garment has a near neighbour in training. Validation garments are in-distribution (for model selection).

Under this split the median Chamfer distance from a test garment to its nearest training garment is 2.5× the training-set nearest-neighbour distance for tops, 1.5× for trousers and 1.2× for dresses (measured on the flat clouds). The original random-garment-v0 split, under which every test garment had a training neighbour as close as two episodes of the same garment (ratio ≈ 1.0), is preserved in splits/random-garment-v0.json; the pre-rewrite files are available at repository revision 771714a24ae37b9095ebc39ef9740b61b7c564eb.

Both split files map garments and episodes to training, validation or test and can be applied to either manifest or the HDF5 independently of the baked-in split field.

Loading

from pathlib import Path
import json
import numpy as np

root = Path("deformation")
manifest = json.loads((root / "manifest.json").read_text())
clouds = np.load(root / "clouds.npy", mmap_mode="r")
surface_ids = np.load(root / "surface_ids.npy", mmap_mode="r")

row = 0
print(manifest["entries"][row])
print(clouds[row].shape, surface_ids[row].shape)  # (2048, 3), (2048,)