Metadata-Version: 2.4
Name: sage-superquadric
Version: 0.3.0
Summary: SAGE: Superquadric-based Adaptive Geometric Explainability -- explainable, non-neural object vocabulary and grasping
Author: Shreyan Shukla
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: opencv-python>=4.7
Provides-Extra: training
Requires-Dist: tqdm>=4.65; extra == "training"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# SAGE — Superquadric-based Adaptive Geometric Explainability

Explainable, non-neural object vocabulary and grasping via superquadric
concept memory. Objects are represented as superquadric primitives —
geometric shapes defined by a small number of physically interpretable
parameters (size, roundness, taper) — fit directly to real depth-camera
point clouds. A growing vocabulary of object categories is learned
online from confirmed examples, with no gradient descent and no neural
network weights anywhere in the pipeline. Every classification decision
is traceable back to real, named physical measurements.

On YCB-Video (5 categories: box, mug, bowl, can, bottle), the current
locked model reaches **78.4% top-1 accuracy** on a stratified,
video-level held-out split. Full ablations and methodology are in the
accompanying paper draft.

## Install

From PyPI (once published):
```bash
pip install sage-superquadric
```

For local development (editable install, changes take effect immediately):
```bash
git clone <repo-url>
cd sage_superquadric_release
pip install -e .
```

For retraining/evaluation on YCB-Video (optional, adds `tqdm`):
```bash
pip install "sage-superquadric[training]"
```

## Quick start

```python
from sage_superquadric import SAGEModel

model = SAGEModel('trained_ycbv_FINAL.json')

# point_cloud: (N,3) numpy array of real depth points for ONE
# already-segmented object (e.g. from a depth camera + a mask)
result = model.predict(point_cloud, with_grasp=True)

print(result.label)                # e.g. 'mug'
print(result.confidence)           # membership score, argmax-consistent
print(result.top_k)                # [(word, score), ...] ranked alternatives
print(result.fitted_shape)         # the actual fitted superquadric parameters
print(result.grasp_candidates)     # antipodal grasp points, computed directly from geometry
```

## What's in the package

```
sage_superquadric/
  registry.py          -- the vocabulary: online-learned category prototypes
                           (Welford mean/variance, no gradients)
  superquadric.py       -- core shape fitting (nonlinear least-squares)
  graph.py               -- multi-part object representation (e.g. mug body+handle)
  pipeline.py            -- segmentation + fitting -> graph, end to end
  segmentation.py        -- residual-based multi-part clustering
  iterative_segment.py   -- iterative two-part fit refinement
  compute_grasp.py       -- antipodal grasp candidates directly from fitted shape
  color_features.py      -- hue/saturation extraction (optional signal)
  radius_profile.py      -- 5-point radial profile (captures taper/necks)

  ycbv_training/         -- optional: YCB-Video training + evaluation tooling
                             (not needed for basic SAGEModel usage)
```

## Design principles

- **No neural network components.** Every learned "weight" is a real
  physical measurement (a radius in meters, a hue angle in degrees) —
  not an opaque embedding dimension.
- **Online vocabulary growth.** New categories are learned from a
  single confirmed example via closed-form statistical updates, not
  batch retraining.
- **Same representation for recognition and grasping.** No separate
  grasp-prediction network — grasps are computed directly from the
  fitted geometry.
- **Traceable decisions.** Any classification can be decomposed into
  per-dimension distances from the learned prototype (see
  `sage_superquadric/ycbv_training/find_and_explain_errors.py` for the diagnostic
  tool used throughout development).

## Known limitations

- Single-frame inference is subject to partial-view occlusion bias for
  round objects (mitigated for training via multi-view aggregation;
  training requires multiple frames with known relative pose).
- The `bottle` category currently spans multiple real sub-products
  (e.g. mustard bottle, bleach cleanser) under one learned word; see
  the paper's ablation on vocabulary splitting for why this is a
  deliberate choice, not an oversight.
- Confidence scores are not well-calibrated probabilities out of the
  box (`sage_superquadric.ycbv_training.metrics.calibrated_confidence` provides a
  display-only, ranking-preserving correction).

## Status

Vocabulary architecture is locked as of the current version. Active
development is now focused on physical grasping validation.
