Data Structures Overview

spatialhub.structures defines the standardized return contracts shared across all SpatialHub model adapters. Every adapter returns one of these dataclasses, providing consistent attribute names, array shapes, and helper methods across all perception tasks.

from spatialhub.structures import (
    MatchResult,
    DepthPredictionResult,
    FeatureExtractionResult,
    SegmentationResult,
    PoseEstimationResult,
)

---

Return Contracts Summary

Data Structure	Perception Task	Primary Producing Adapters	Key Fields
MatchResult	Semi-dense Feature Matching	EfficientLoFTR	keypoints_a, keypoints_b, confidence
DepthPredictionResult	Monocular & Multi-View Depth	DepthAnything3	depth, conf, intrinsics, depth_type
FeatureExtractionResult	Feature Extraction & Embeddings	DINOv2	features, embedding_type, l2_normalized
SegmentationResult	Instance Segmentation & AMG	FastSAM, SAM, CNOS	boxes, masks, scores, class_ids
PoseEstimationResult	6D Object Pose Estimation & Tracking	FoundationPose	poses, best_pose, best_score, bbox_3d

---

Architectural Principles

• Plug-and-Play Pipeline Modularity: Standardized return contracts decouple perception models from downstream spatial algorithms (such as Visual SLAM, 3D reconstruction, or pose optimization). Any model producing a MatchResult or DepthPredictionResult can be substituted into downstream geometric pipelines without modifying downstream code.
• Pure NumPy Array Contracts: All coordinate arrays, spatial masks, depth maps, and feature vectors are returned as contiguous NumPy arrays (float32, bool, or uint8).
• Decoupled Visualization: Each result dataclass provides a .visualize() or .visualize_mask() convenience method that delegates directly to stateless visualization routines in spatialhub.utils.viz.
• Batching & Dimension Normalization: Single-sample predictions (such as a single \((4, 4)\) pose matrix) are automatically aligned to standardized batch dimensions on instantiation.