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):

pip install sage-superquadric

For local development (editable install, changes take effect immediately):

git clone <repo-url>
cd sage_superquadric_release
pip install -e .

For retraining/evaluation on YCB-Video (optional, adds tqdm):

pip install "sage-superquadric[training]"

Quick start

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.