astra.spatial_index module

ASTRA Core Persistent Spatial Index — KDTree.

Implements a 3D KDTree spatial partitioning structure for O(N log N) conjunction candidate pair generation, replacing the naive O(N²) all-pairs search.

Wraps the ultra-fast C++ scipy.spatial.cKDTree.

class astra.spatial_index.SpatialIndex(half_size_km=50000.0, max_objects_per_node=16)

Bases: object

High-level persistent spatial index for conjunction screening.

Wraps scipy.spatial.cKDTree for robust and extremely fast spatial queries.

Usage:

idx = SpatialIndex() idx.insert(“25544”, np.array([6771.0, 0.0, 0.0])) pairs = idx.query_pairs(threshold_km=50.0)

Parameters:

• half_size_km – Nominal maximum separation (km) for screening workflows. Pass the same value to query_pairs() when you want a consistent radius; it is not applied automatically.

• max_objects_per_node – leafsize for SciPy’s cKDTree (bucket size).

insert(obj_id, position)

Insert or update an object’s position. Thread-safe.

query_radius(point, radius_km)

Find all objects within radius of a point. Thread-safe.

query_pairs(threshold_km=50.0)

Find all pairs of objects within threshold distance. Thread-safe.

PERF-01 Fix: For trajectory-mode indices (where excursions are tracked), uses per-object excursion radii instead of the global max_excursion to bound the KDTree query. The global max approach was dominated by any single HEO object (excursion ~20,000 km), producing a coarse threshold of 50 + 2*20,000 = 40,050 km that pairs the HEO with virtually every object in the catalog. Per-object refinement (step 2 below) already existed and correctly filters these false positives, but the initial query was still O(N²) for HEO-heavy catalogs. The fix tightens the tree query radius to threshold + per-object excursion (not global max), then refines with the tighter condition, giving near-optimal selectivity.

rebuild_for_trajectories(trajectories)

Build a unified spatial index for entire trajectories (high-performance).

Uses the mean position of each trajectory as the center and tracks the maximum excursion from that center. Enables one-shot conjunction screening for the entire propagation window.

property size

Number of objects indexed.

rebuild(positions)

Rebuild the entire index from a fresh position dictionary. Thread-safe.

Silently drops any objects whose position contains NaN or Inf.