XCalib 0.1.0__py3-none-any.whl

xcalib/__init__.py

@@ -0,0 +1,75 @@
+"""xcalib — camera-LiDAR cross-modal matching, calibration, and adaptation.
+
+Public API (everything else is internal and may change without notice):
+
+    from xcalib import Matcher
+
+    matcher = Matcher.from_pretrained("crlite", site="a9_dataset_r02_s01")
+    result = matcher.pair(image, point_cloud, bboxes_2d, bboxes_3d)
+    calib = matcher.calibrate(image, point_cloud, bboxes_2d, bboxes_3d,
+                              intrinsics=K)
+    matcher.build("onnx", output_dir="onnx/crlite_a9")
+
+`Matcher` covers pairing/matching, targetless calibration, one-shot
+adaptation, ONNX/TensorRT export, fine-tuning (`.train()`), and pretrained
+weight loading. The module-level `train` / `load_dataset` helpers cover HDF5
+training and public A9 dataset loading; the protocol types document and
+enforce the input contract.
+"""
+
+# Verify torch is importable before any sub-module pulls it in, so the
+# partner sees a Jetson-specific install hint instead of a bare
+# ModuleNotFoundError. No-op when torch is already installed.
+from .utils.torch_check import ensure_torch as _ensure_torch
+_ensure_torch()
+
+from .engine.exporter import BuildResult
+from .engine.matcher import Matcher, MatchResult
+from .oneshot.calibration import CalibrationResult
+from .protocol import (
+    PROTOCOL_VERSION,
+    CameraIntrinsics,
+    ProtocolError,
+    ProtocolViolation,
+    validate_frame_inputs,
+)
+from .visualization import draw_calibration_overlay, draw_matching_overlay
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Core entry point
+    "Matcher",
+    # Lab-side helpers (lazy: keep optional deps out of the base import)
+    "train",
+    "load_dataset",
+    # Result dataclasses
+    "MatchResult",
+    "BuildResult",
+    "CalibrationResult",
+    # Input protocol (partner-facing contract)
+    "PROTOCOL_VERSION",
+    "CameraIntrinsics",
+    "ProtocolError",
+    "ProtocolViolation",
+    "validate_frame_inputs",
+    # Visualization helpers
+    "draw_matching_overlay",
+    "draw_calibration_overlay",
+]
+
+
+def __getattr__(name: str):
+    # PEP 562 lazy exports: `train` pulls h5py (the [train] extra) and
+    # `load_dataset` pulls huggingface_hub network helpers — neither should
+    # tax `import xcalib` for inference-only users.
+    if name == "train":
+        from .engine.trainer import train
+
+        return train
+    if name == "load_dataset":
+        from .hub.datasets import load_dataset
+
+        return load_dataset
+    raise AttributeError(f"module 'xcalib' has no attribute {name!r}")

xcalib/cfg/calibrefine_a9_dataset_r02_s01.yaml

@@ -0,0 +1,10 @@
+# CalibRefine (Pairwise baseline: Bottleneck ResNet + PointNet2 + 2D PE) — A9 r02_s01.
+model: calibrefine
+device: auto
+num_classes: 10
+crop_size: 32
+point_cloud_size: 1024
+token_len: 256
+num_blocks: [2, 2, 2, 2]
+bbox_expansion: 1.25
+weights_path: checkpoints/calibrefine_a9_dataset_r02_s01_best.pth

xcalib/cfg/calibrefine_utc3.yaml

@@ -0,0 +1,10 @@
+# CalibRefine (Pairwise baseline: Bottleneck ResNet + PointNet2 + 2D PE) — UTC3.
+model: calibrefine
+device: auto
+num_classes: 10
+crop_size: 32
+point_cloud_size: 1024
+token_len: 256
+num_blocks: [2, 2, 2, 2]
+bbox_expansion: 1.05
+weights_path: checkpoints/calibrefine_utc3_best.pth

xcalib/cfg/calibrefine_utc4.yaml

@@ -0,0 +1,10 @@
+# CalibRefine (Pairwise baseline: Bottleneck ResNet + PointNet2 + 2D PE) — UTC4.
+model: calibrefine
+device: auto
+num_classes: 10
+crop_size: 32
+point_cloud_size: 1024
+token_len: 256
+num_blocks: [2, 2, 2, 2]
+bbox_expansion: 1.05
+weights_path: checkpoints/calibrefine_utc4_best.pth

xcalib/cfg/crlite_2dpe_a9_dataset_r02_s01.yaml

@@ -0,0 +1,13 @@
+# CRLite-2DPE (ResNet + only 2D sinusoidal PE branch, R1 #6 ablation) — A9 r02_s01.
+model: crlite_2dpe
+device: auto
+num_classes: 10
+crop_size: 32
+point_cloud_size: 1024
+embed_dim: 256
+token_len: 256
+top_k: 10
+max_depth: 100.0
+pe_mode: 2d_only         # forced by CRLite2DPEModel; left here for visibility
+bbox_expansion: 1.25
+weights_path: checkpoints/crlite_2dpe_a9_dataset_r02_s01_best.pth

xcalib/cfg/crlite_2dpe_utc3.yaml

@@ -0,0 +1,13 @@
+# CRLite-2DPE (ResNet + only 2D sinusoidal PE branch, R1 #6 ablation) — UTC3.
+model: crlite_2dpe
+device: auto
+num_classes: 10
+crop_size: 32
+point_cloud_size: 1024
+embed_dim: 256
+token_len: 256
+top_k: 10
+max_depth: 100.0
+pe_mode: 2d_only
+bbox_expansion: 1.05
+weights_path: checkpoints/crlite_2dpe_utc3_best.pth

xcalib/cfg/crlite_2dpe_utc4.yaml

@@ -0,0 +1,13 @@
+# CRLite-2DPE (ResNet + only 2D sinusoidal PE branch, R1 #6 ablation) — UTC4.
+model: crlite_2dpe
+device: auto
+num_classes: 10
+crop_size: 32
+point_cloud_size: 1024
+embed_dim: 256
+token_len: 256
+top_k: 10
+max_depth: 100.0
+pe_mode: 2d_only         # forced by CRLite2DPEModel; left here for visibility
+bbox_expansion: 1.05
+weights_path: checkpoints/crlite_2dpe_utc4_best.pth

xcalib/cfg/crlite_a9_dataset_r02_s01.yaml

@@ -0,0 +1,13 @@
+# CRLite (Hybrid two-stage + Enhanced 3D PE) — A9 r02_s01 weights.
+model: crlite
+device: auto
+num_classes: 10
+crop_size: 32
+point_cloud_size: 1024
+embed_dim: 256
+token_len: 256
+top_k: 10
+max_depth: 100.0
+pe_mode: full
+bbox_expansion: 1.25
+weights_path: checkpoints/crlite_a9_dataset_r02_s01_best.pth

xcalib/cfg/crlite_utc3.yaml

@@ -0,0 +1,13 @@
+# CRLite (Hybrid two-stage + Enhanced 3D PE) — UTC3 weights.
+model: crlite
+device: auto
+num_classes: 10
+crop_size: 32
+point_cloud_size: 1024
+embed_dim: 256
+token_len: 256
+top_k: 10
+max_depth: 100.0
+pe_mode: full
+bbox_expansion: 1.05
+weights_path: checkpoints/crlite_utc3_best.pth

xcalib/cfg/crlite_utc4.yaml

@@ -0,0 +1,13 @@
+# CRLite (Hybrid two-stage + Enhanced 3D PE) — UTC4 weights.
+model: crlite
+device: auto
+num_classes: 10
+crop_size: 32
+point_cloud_size: 1024
+embed_dim: 256
+token_len: 256
+top_k: 10
+max_depth: 100.0
+pe_mode: full
+bbox_expansion: 1.05
+weights_path: checkpoints/crlite_utc4_best.pth

xcalib/cfg/crlite_vit_exp1_a9_dataset_r02_s01.yaml

@@ -0,0 +1,19 @@
+# CRLite-ViT Exp1 (Crop ViT + PointNet, no PE) — A9 r02_s01.
+model: crlite_vit_exp1
+device: auto
+num_classes: 10
+crop_size: 64
+point_cloud_size: 1024
+embed_dim: 256
+top_k: 10
+vit:
+  patch_size: 8
+  embed_dim: 256
+  depth: 6
+  num_heads: 8
+  mlp_ratio: 4.0
+  dropout: 0.0
+  attention_dropout: 0.0
+  pool: cls
+bbox_expansion: 1.25
+weights_path: checkpoints/crlite_vit_exp1_a9_dataset_r02_s01_best.pth

xcalib/cfg/crlite_vit_exp1_utc3.yaml

@@ -0,0 +1,19 @@
+# CRLite-ViT Exp1 (Crop ViT + PointNet, no PE) — UTC3.
+model: crlite_vit_exp1
+device: auto
+num_classes: 10
+crop_size: 64
+point_cloud_size: 1024
+embed_dim: 256
+top_k: 10
+vit:
+  patch_size: 8
+  embed_dim: 256
+  depth: 6
+  num_heads: 8
+  mlp_ratio: 4.0
+  dropout: 0.0
+  attention_dropout: 0.0
+  pool: cls
+bbox_expansion: 1.05
+weights_path: checkpoints/crlite_vit_exp1_utc3_best.pth

xcalib/cfg/crlite_vit_exp1_utc4.yaml

@@ -0,0 +1,19 @@
+# CRLite-ViT Exp1 (Crop ViT + PointNet, no PE) — UTC4.
+model: crlite_vit_exp1
+device: auto
+num_classes: 10
+crop_size: 64
+point_cloud_size: 1024
+embed_dim: 256
+top_k: 10
+vit:
+  patch_size: 8
+  embed_dim: 256
+  depth: 6
+  num_heads: 8
+  mlp_ratio: 4.0
+  dropout: 0.0
+  attention_dropout: 0.0
+  pool: cls
+bbox_expansion: 1.05
+weights_path: checkpoints/crlite_vit_exp1_utc4_best.pth

xcalib/cfg/crlite_vit_exp3_a9_dataset_r02_s01.yaml

@@ -0,0 +1,21 @@
+# CRLite-ViT Exp3 (Crop ViT + PointNet + Enhanced 3D PE) — A9 r02_s01.
+model: crlite_vit_exp3
+device: auto
+num_classes: 10
+crop_size: 64
+point_cloud_size: 1024
+embed_dim: 256
+token_len: 256
+max_depth: 100.0
+top_k: 10
+vit:
+  patch_size: 8
+  embed_dim: 256
+  depth: 6
+  num_heads: 8
+  mlp_ratio: 4.0
+  dropout: 0.0
+  attention_dropout: 0.0
+  pool: cls
+bbox_expansion: 1.25
+weights_path: checkpoints/crlite_vit_exp3_a9_dataset_r02_s01_best.pth

xcalib/cfg/crlite_vit_exp3_utc3.yaml

@@ -0,0 +1,21 @@
+# CRLite-ViT Exp3 (Crop ViT + PointNet + Enhanced 3D PE) — UTC3.
+model: crlite_vit_exp3
+device: auto
+num_classes: 10
+crop_size: 64
+point_cloud_size: 1024
+embed_dim: 256
+token_len: 256
+max_depth: 100.0
+top_k: 10
+vit:
+  patch_size: 8
+  embed_dim: 256
+  depth: 6
+  num_heads: 8
+  mlp_ratio: 4.0
+  dropout: 0.0
+  attention_dropout: 0.0
+  pool: cls
+bbox_expansion: 1.05
+weights_path: checkpoints/crlite_vit_exp3_utc3_best.pth

xcalib/cfg/crlite_vit_exp3_utc4.yaml

@@ -0,0 +1,21 @@
+# CRLite-ViT Exp3 (Crop ViT + PointNet + Enhanced 3D PE) — UTC4.
+model: crlite_vit_exp3
+device: auto
+num_classes: 10
+crop_size: 64
+point_cloud_size: 1024
+embed_dim: 256
+token_len: 256
+max_depth: 100.0
+top_k: 10
+vit:
+  patch_size: 8
+  embed_dim: 256
+  depth: 6
+  num_heads: 8
+  mlp_ratio: 4.0
+  dropout: 0.0
+  attention_dropout: 0.0
+  pool: cls
+bbox_expansion: 1.05
+weights_path: checkpoints/crlite_vit_exp3_utc4_best.pth

xcalib/cfg/crlite_vit_exp4_utc3.yaml

@@ -0,0 +1,32 @@
+# CRLite-ViT Exp4 (ViT + Structure-Aware GNN), UTC3 weights.
+#
+# Replaces absolute position encoding with two relational GNNs (camera-side
+# over 2D bboxes, LiDAR-side over 3D centers). State-dict keys match the
+# trained checkpoint exactly.
+model: crlite_vit_exp4
+device: auto
+crop_size: 64
+point_cloud_size: 1024
+embed_dim: 256
+top_k: 10
+image_width: 1920
+image_height: 1080
+
+vit:
+  patch_size: 8
+  embed_dim: 256
+  depth: 6
+  num_heads: 8
+  mlp_ratio: 4.0
+  dropout: 0.0
+  attention_dropout: 0.0
+  pool: cls
+
+gnn:
+  edge_dim: 8
+  hidden_dim: 128
+  num_layers: 2
+  k_neighbors: 4
+  dropout: 0.1
+
+weights_path: checkpoints/crlite_vit_exp4_utc3_best.pth

xcalib/cfg/crlite_vit_exp4_utc4.yaml

@@ -0,0 +1,32 @@
+# CRLite-ViT Exp4 (ViT + Structure-Aware GNN), UTC4 weights.
+#
+# Replaces absolute position encoding with two relational GNNs (camera-side
+# over 2D bboxes, LiDAR-side over 3D centers). State-dict keys match the
+# trained checkpoint exactly.
+model: crlite_vit_exp4
+device: auto
+crop_size: 64
+point_cloud_size: 1024
+embed_dim: 256
+top_k: 10
+image_width: 1920
+image_height: 1080
+
+vit:
+  patch_size: 8
+  embed_dim: 256
+  depth: 6
+  num_heads: 8
+  mlp_ratio: 4.0
+  dropout: 0.0
+  attention_dropout: 0.0
+  pool: cls
+
+gnn:
+  edge_dim: 8
+  hidden_dim: 128
+  num_layers: 2
+  k_neighbors: 4
+  dropout: 0.1
+
+weights_path: checkpoints/crlite_vit_exp4_utc4_best.pth