SpatialHub

A high-performance, zero-PyTorch spatial AI and perception library providing unified ONNX Runtime inference adapters for computer vision and 3D spatial computing models.

Key Principles

• Zero-PyTorch Inference: Core runtime paths execute exclusively on ONNX Runtime with pure NumPy and OpenCV vector operations.
• Unified Return Contracts: Standardized dataclass outputs across all model families (MatchResult, DepthPredictionResult, FeatureExtractionResult, SegmentationResult, PoseEstimationResult).
• Automatic Weight Management: Downloads, verifies, and caches pretrained .onnx weight binaries seamlessly from Hugging Face Hub.
• Hardware Acceleration: Native support for CPU, CUDA, and TensorRT execution providers with runtime fallback verification.
• ModernGL GPU Rendering: Built-in headless offscreen G-buffer and batched atlas renderer for CAD model template matching and 6D pose estimation.

Supported Models

Installation

Requires Python 3.12+.

pip install spatialhub

For GPU acceleration (CUDA / TensorRT):

pip install "spatialhub[gpu]"

For 3D CAD mesh processing and ModernGL rendering:

pip install "spatialhub[render]"

Quickstart

from spatialhub import FoundationPose, EfficientLoFTR, DepthAnything3, DINOV2, FastSAM, SAM, CNOS

# 1. 6D Object Pose Estimation (FoundationPose)
est = FoundationPose(
    model_path="mesh.obj",
    model_unit="mm",
    scorer_weights="scorer.onnx",
    refiner_weights="refiner.onnx"
)
pose_res = est.estimate(rgb=rgb_img, depth=depth_img, K=cam_K, mask=obj_mask)
pose_res.visualize(draw_bbox=True, draw_axes=True, save_path="pose.png")

# 2. Feature Matching (EfficientLoFTR)
matcher = EfficientLoFTR()
match_res = matcher.match("img1.jpg", "img2.jpg", max_dim=1024)
match_res.visualize(top_k=50, save_path="matches.png")

# 3. Depth Estimation (Depth Anything 3)
estimator = DepthAnything3(model_name="da3_base")
depth_res = estimator.estimate_depth(images=["view1.png", "view2.png"])
depth_viz = estimator.visualize(depth_res.depth[0])

# 4. Feature Embeddings (DINOv2)
dino = DINOV2(model_variant="dinov2_vitl14")
feat_res = dino.extract_features("image.png", l2_normalize=True)

# 5. Proposal Segmentation (FastSAM)
fastsam = FastSAM(model_variant="FastSAM-x")
seg_res = fastsam.generate_masks("scene.png", conf_threshold=0.3)
seg_res.visualize_mask(save_path="fastsam_masks.png")

Reproducible ONNX Export Workflow

Each model directory under src/spatialhub/models/<model>/ contains an isolated environment configuration and export_onnx.py script to re-export custom ONNX graphs:

cd src/spatialhub/models/efficient_loftr
uv sync
uv run python export_onnx.py --checkpoint weights/model.ckpt --output-path weights/model.onnx

See the Reproducible ONNX Export Guide for complete documentation.

License

Core SpatialHub code is released under the Apache 2.0 License. Pretrained model weights and submodule architectures maintain their respective original licenses.