Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,49 @@
+---
+license: mit
+tags:
+  - robotics
+  - 3d-reconstruction
+  - shape-completion
+  - point-cloud
+  - perception-for-manipulation
+library_name: gapseg
+---
+
+# GapSeg — Diagnosis-Gated Learned Shape Completion
+
+Single RGB-D → per-object **distortion diagnosis** → gated **learned completion** →
+full 3D shape + dimensions.  A single view of an object gives a broken 3D shape;
+this pipeline predicts which objects are distorted and completes only those with a
+learned network, beating geometric multi-view fusion.
+
+## Results (GraspNet, 140 objects, chamfer mm ↓)
+
+| method        | chamfer | vs single |
+|---------------|--------:|----------:|
+| single view   |   6.40  |    —      |
+| geometric fusion | 5.44 | 88% (sig) |
+| **single + completion** | **2.99** | 92% (sig) |
+| **diagnosis-gated completion** | **3.12** | 91% (sig) |
+
+Learned completion of a single view beats multi-view geometric fusion; gating it
+by the diagnoser keeps the gain while only completing hard objects.
+
+## Usage
+
+```python
+from gapseg.pipeline import GapSegPipeline
+pipe = GapSegPipeline.from_pretrained("haeing/gapseg", device="cuda")
+
+# rgb: HxWx3 uint8, depth_m: HxW float (metres), K: 3x3
+# instances: [{"inst_id": 1, "mask": HxW bool, "R": 3x3, "t": (3,)}, ...]
+out = pipe.infer(rgb, depth_m, K, instances)
+for o in out:
+    print(o["inst_id"], o["dims_cm"], "completed:", o["completed"])
+```
+
+`R`/`t` (object pose) drive completion; objects without a pose or below the
+diagnosis threshold return their single-view cloud.
+
+## Contents
+- `sq2_gview/best.pt` — the G_view diagnoser (RGB-D → distortion / conditions)
+- `sq3_completion/best.pt` — the PCN shape-completion network