nrl-tracker 1.1.2__py3-none-any.whl → 1.2.0__py3-none-any.whl

{nrl_tracker-1.1.2.dist-info → nrl_tracker-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nrl-tracker
-Version: 1.1.2
+Version: 1.2.0
 Summary: Python port of the U.S. Naval Research Laboratory's Tracker Component Library for target tracking algorithms
 Author: Original: David F. Crouse, Naval Research Laboratory
 Maintainer: Python Port Contributors

{nrl_tracker-1.1.2.dist-info → nrl_tracker-1.2.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pytcl/__init__.py,sha256=40U6PSzLszzIyPQGdJbW3g2kGOAoAW4qzHukjQEcv78,1893
+pytcl/__init__.py,sha256=LFQ_O4Uxr3PayIyh__HjIycG7ZwPGmfGELKpDmx4lfc,1893
 pytcl/logging_config.py,sha256=j7Zrkal5LwUIos-_Dm3cGKUR-jMkFdSZZikJTtzTeoE,8883
 pytcl/assignment_algorithms/__init__.py,sha256=f9V-TkEVmiKYYyth4PTpDfJvA7yYV_ys6Zix-QwWIYY,2136
 pytcl/assignment_algorithms/data_association.py,sha256=tsRxWJZk9aAPmE99BKXGouEpFfZrjPjb4HXvgxFUHhU,11405
@@ -13,7 +13,7 @@ pytcl/astronomical/__init__.py,sha256=Dtf6hqXyKyFL5VP-sqI7m2QGK6l-rqRGxVIhgDuYHO
 pytcl/astronomical/ephemerides.py,sha256=x2500S0rF1D2h0dMR_2BnZaChbBZTooHLdrevttxlAc,16471
 pytcl/astronomical/lambert.py,sha256=Lc8FT1JmpI9WSXsG2s5vIRkSoBSV7r5hd3o2bGh2Ojo,15607
 pytcl/astronomical/orbital_mechanics.py,sha256=8GssRanwTowCl6PJYqmB_SDnNznLUq5gkPa3j6iEo3U,19965
-pytcl/astronomical/reference_frames.py,sha256=GDak7af6BqOwGnCUxkvFoeqd_H2TMubdjG9lGPCoUB4,15799
+pytcl/astronomical/reference_frames.py,sha256=gkbQrhHY_EN0xt8i7m0dIJp67GgpEcDArY7J3YH-Mb8,17981
 pytcl/astronomical/relativity.py,sha256=YPsXLD-VRh-nqs1laC-wKpRO00fflm4GkyLhojPydbo,15441
 pytcl/astronomical/time_systems.py,sha256=Jg0Zaq60hc4Ts1aQtb5bK4KSZhz-uQse8gYC89Y0-TA,15243
 pytcl/atmosphere/__init__.py,sha256=TTVz4hAM48Xd3jr6GKrR2GAABpx2z0aWvtzb9uIQiHk,737
@@ -23,14 +23,15 @@ pytcl/clustering/dbscan.py,sha256=PS6QlOwHFerbZNEb3zcNhN4oNQpgOOw5y0WskQzyKIo,73
 pytcl/clustering/gaussian_mixture.py,sha256=U5U0Z46tZWdTLNdNNNJenoeviwZRAOvexVFYVLt4QMc,22865
 pytcl/clustering/hierarchical.py,sha256=Hw9BFCn5df_ATpJX63R3B31MHz27ztCw9ihMDIlI688,14202
 pytcl/clustering/kmeans.py,sha256=250FQyDol5S_Y4TznNn9cEuE96UDp7wvEkPZJ1DLul8,10697
-pytcl/containers/__init__.py,sha256=-hnqSMKlMugj2RRssx3p_48HWnfqLSrF6BCChsinCOg,1627
+pytcl/containers/__init__.py,sha256=jZAZb0VUft5gjQghfg2S9PD-LsA5xgtXkc0mAS_Gnmk,2428
+pytcl/containers/base.py,sha256=h3h5mJfSn8yTy1waFZRUxJQ9eHQ5npbimadFbFZuuV4,5520
 pytcl/containers/cluster_set.py,sha256=y36D5TNzvCN6xjg6taP2SD_MC-O5iLq9ncBlHsQ5IBs,22723
-pytcl/containers/covertree.py,sha256=1JWqXxoUFLxuMnjwj2qf0iz2uPzdujQYdwJW3l5qsOs,13282
-pytcl/containers/kd_tree.py,sha256=pxRC62RYkqz9zXPz6c1fubmtPPBDLYA5I9AXMAoGanw,16348
+pytcl/containers/covertree.py,sha256=ePIqH1-0CxSFqCwmQ_G6MXPlXs4xH0gsmoZXF8QxhDk,13271
+pytcl/containers/kd_tree.py,sha256=9CKHAzid0DZ879hut8M4dyW_976pIWNLX3uWzELPIu4,18563
 pytcl/containers/measurement_set.py,sha256=87AbdoZIUspn1yJsiMpyQ5LoEVcerUnXefXGGPtFTJg,12654
 pytcl/containers/rtree.py,sha256=gv2EztvPnaAXEa6OoFnOYBY1MfTwjNMYh_BCiIomHJk,15450
 pytcl/containers/track_list.py,sha256=6q9Qgcwm-8H_JqtOCsMssF27av4XaSkhfDl-MWb1ABc,12520
-pytcl/containers/vptree.py,sha256=6fBNHrezkmj7L2nH0-2bONRN92f5cZAhS-5vaI1JZnA,8814
+pytcl/containers/vptree.py,sha256=4tUq0ktafusU1PILZkQxi27CZryKlsHtFbym-vZYQWk,8747
 pytcl/coordinate_systems/__init__.py,sha256=jwYhu_-9AvOeP9WLG9PYtyDwfe0GjxNZ9-xCqiLymW4,3909
 pytcl/coordinate_systems/conversions/__init__.py,sha256=PkNevB78vBw0BkalydJBbQO91AyiMJxKRrgJNt4HsYc,1100
 pytcl/coordinate_systems/conversions/geodetic.py,sha256=qQSnJRt3jg5KiostvzyslPIbfn-1xBluo1r12oavWTQ,15737
@@ -41,10 +42,10 @@ pytcl/coordinate_systems/projections/__init__.py,sha256=eWNtezPO62IUWxv7jymenIXs
 pytcl/coordinate_systems/projections/projections.py,sha256=yODS7n1gA4jsCJcU8EaeclHrbUBsZI9O2M_XJs2HOXs,33169
 pytcl/coordinate_systems/rotations/__init__.py,sha256=nqAz4iJd2hEOX_r7Tz4cE524sShyxdbtcQ5m56RrDLg,1047
 pytcl/coordinate_systems/rotations/rotations.py,sha256=FAYHkShQcpOlWJjtvLfNvtCx-a56pr-cbpo0QjC5W9U,18227
-pytcl/core/__init__.py,sha256=H5JJPS-43DfF1UG7fSgV-VMTcZFBO8GuzDW1lM_1sm4,1152
+pytcl/core/__init__.py,sha256=3GFQX_Q9f7fhmWlA6OQiS6OpM7HWhyT9iQhB8Mhi_kk,1580
 pytcl/core/array_utils.py,sha256=SsgEiAoRCWxAVKq1aa5-nPdOi-2AB6XNObu0IaGClUk,13983
 pytcl/core/constants.py,sha256=lZVDK5zsSR02_4b2Nqx9KDtZT9QaYhkZ9wuoODbifd4,8693
-pytcl/core/validation.py,sha256=WRlzMlUihtqc3XZoWOTFK0sBAZVDIwTMGCiWcX5OZVY,13093
+pytcl/core/validation.py,sha256=nUmG8UmUk85dQ4CxJRipACb8zjsrAJPiyK8ADZN_KvU,23426
 pytcl/dynamic_estimation/__init__.py,sha256=jA5FF6kHYklY5LMOfZaKcCeiPTpVe8vHIMp3ECDOmsc,4582
 pytcl/dynamic_estimation/imm.py,sha256=IbKmouUiyzaYJbhWty63r3n_xV8thD-wd0qgZP1SxOI,22067
 pytcl/dynamic_estimation/information_filter.py,sha256=x7iQwO_iJT1dCSvDws5LqD3yAtjw9QVGUfMPcXn1IA4,17349
@@ -71,9 +72,9 @@ pytcl/dynamic_models/process_noise/polynomial.py,sha256=natfpsdN3qM9VzPeXF_nBpsb
 pytcl/dynamic_models/process_noise/singer.py,sha256=lsJDT6xOvcS_qQKFtgHX0L7Ukpy4D7HgvPT8Q3I0ibU,3901
 pytcl/gravity/__init__.py,sha256=5xNdQSrrkt7-1-JPOYqR38CqvNJ7qKlPyMK36DGm6-I,3693
 pytcl/gravity/clenshaw.py,sha256=1BdxzU8IfGGd68H_U35soIJkiOHphY35e9mLElhPTOg,15364
-pytcl/gravity/egm.py,sha256=QTRuvCiMjuNQdZF163OGwjxuivpGu2dB6E0zQLbKPP8,18083
+pytcl/gravity/egm.py,sha256=47I8nyXNhXUKPkufXahs4JGsBcqhM-9z2xGz0X4JPmU,18422
 pytcl/gravity/models.py,sha256=rdY3Do4M1eRFO74gu3xy-bBn7tox3zM49wYbfnsIQWw,11159
-pytcl/gravity/spherical_harmonics.py,sha256=uZasz-w2K16sWT6xrNIPyTEP6MSlMQSe_BCWpXhRkWY,14722
+pytcl/gravity/spherical_harmonics.py,sha256=IpBh0LW4BQMzJck9Li6yveGlvYigCuXaoApRWDPsWtc,16498
 pytcl/gravity/tides.py,sha256=hef_BGewFGD7dJwg0t09Z6tfWLco_avATLuu66rnTpI,27733
 pytcl/magnetism/__init__.py,sha256=hE2BvberFSmimYuuwCYJ0g7ByxJAdj844vZJNkEotws,2502
 pytcl/magnetism/emm.py,sha256=5Jwl99wvdKYtx1-3LBB7x-w5KT-fqLiRg7uBW0Ai_Gw,22292
@@ -103,7 +104,7 @@ pytcl/mathematical_functions/special_functions/debye.py,sha256=Nchjwkl1vzSL1L7nQ
 pytcl/mathematical_functions/special_functions/elliptic.py,sha256=WyzBkrfZufIR5dUmCKGcxp6KNpVDrU89NGLDyRrZOqQ,7418
 pytcl/mathematical_functions/special_functions/error_functions.py,sha256=a3SS8FYAMRv1KdCmebOZL95yjvVt9gZRF2XOjHvQ9M8,6253
 pytcl/mathematical_functions/special_functions/gamma_functions.py,sha256=xXN_9SCokH10HjE8PpaPKHYVK_RZRHRAbZgR2mZYIAA,10191
-pytcl/mathematical_functions/special_functions/hypergeometric.py,sha256=gKn_tXboEst7pVDiW15IbKFAANM4XVqKtDc1dmWL-2A,9768
+pytcl/mathematical_functions/special_functions/hypergeometric.py,sha256=5C4dXv3XxjyeGGVH-0i22NSLbAqkcPTR3kZ2J_GTles,11364
 pytcl/mathematical_functions/special_functions/lambert_w.py,sha256=ivRc4KH5Lwoxb_yijrJEwG0ITa0hhcYF7_gCfVBBNW4,6855
 pytcl/mathematical_functions/special_functions/marcum_q.py,sha256=OZ5QjIB1e_XvRG8A-3dbZ13YXHtdk2EYVEPaqtgVr14,9580
 pytcl/mathematical_functions/statistics/__init__.py,sha256=dfypStgmnFmOrnWcm-3CEvLinONHraFgx9O66_37bqw,1278
@@ -115,8 +116,8 @@ pytcl/mathematical_functions/transforms/stft.py,sha256=zQapXl-v69_RDPwMqci83jah1
 pytcl/mathematical_functions/transforms/wavelets.py,sha256=dm273Z_t13BlEVSlHTaGE7jR1ocugL7lEkcO499U7bY,21656
 pytcl/misc/__init__.py,sha256=SCHf_lQVfdl2gwUluHBiIloTF8HRH8EkgYfbNr7zOug,33
 pytcl/navigation/__init__.py,sha256=k1_x_FnnPrIzGeNu7zejPtPubIhweBgCfwqlZJEMw0I,6042
-pytcl/navigation/geodesy.py,sha256=M9XXfBTMCRdaWMV2-ViDSTEt94WZnMtxMeJQ1FAgQHY,17227
-pytcl/navigation/great_circle.py,sha256=TtlkWZbzr-HzSt4ultG_h137ZnX0pJZx_87kr3uvpjI,20923
+pytcl/navigation/geodesy.py,sha256=KXRQqOrJGbxWQ4yrZI9jfMDvaoUx_4RL8mTWUHhBJX0,19694
+pytcl/navigation/great_circle.py,sha256=y5YHBie21j1a1ac7OziEgg_jgUT1FpltgkTA5AGFGsk,23251
 pytcl/navigation/ins.py,sha256=OIi8_RjrgEYl0MFpJEFMjIlpgX8DYGTEhdLEvqG-ABU,31151
 pytcl/navigation/ins_gnss.py,sha256=euKF5JGgwmVBsw3jBf7_wa2z1BpZeVbSNmBuwzhGS6c,30157
 pytcl/navigation/rhumb.py,sha256=lr1c3iEXfoOSfIyyXSRWv6He5TlaxEHbJy-dhqM1gRw,18224
@@ -144,8 +145,8 @@ pytcl/trackers/mht.py,sha256=7mwhMmja3ri2wnx7W1wueDGn2r3ArwAxJDPUJ7IZAkQ,20617
 pytcl/trackers/multi_target.py,sha256=hvt89ERhMwpcHcIJeKHnkQSKdE3_LoRiX-gbaGoo300,10516
 pytcl/trackers/single_target.py,sha256=Yy3FwaNTArMWcaod-0HVeiioNV4xLWxNDn_7ZPVqQYs,6562
 pytcl/transponders/__init__.py,sha256=5fL4u3lKCYgPLo5uFeuZbtRZkJPABntuKYGUvVgMMEI,41
-nrl_tracker-1.1.2.dist-info/LICENSE,sha256=rB5G4WppIIUzMOYr2N6uyYlNJ00hRJqE5tie6BMvYuE,1612
-nrl_tracker-1.1.2.dist-info/METADATA,sha256=ILwTHebbvAlAhKGX-O-cWS7rjLiRCaDrkd2fRbU22BE,10145
-nrl_tracker-1.1.2.dist-info/WHEEL,sha256=pL8R0wFFS65tNSRnaOVrsw9EOkOqxLrlUPenUYnJKNo,91
-nrl_tracker-1.1.2.dist-info/top_level.txt,sha256=17megxcrTPBWwPZTh6jTkwTKxX7No-ZqRpyvElnnO-s,6
-nrl_tracker-1.1.2.dist-info/RECORD,,
+nrl_tracker-1.2.0.dist-info/LICENSE,sha256=rB5G4WppIIUzMOYr2N6uyYlNJ00hRJqE5tie6BMvYuE,1612
+nrl_tracker-1.2.0.dist-info/METADATA,sha256=TV1ddsQ8eyXE0y4Y6O5AuUR6glbTc8pkBZ7g2J10uCA,10145
+nrl_tracker-1.2.0.dist-info/WHEEL,sha256=pL8R0wFFS65tNSRnaOVrsw9EOkOqxLrlUPenUYnJKNo,91
+nrl_tracker-1.2.0.dist-info/top_level.txt,sha256=17megxcrTPBWwPZTh6jTkwTKxX7No-ZqRpyvElnnO-s,6
+nrl_tracker-1.2.0.dist-info/RECORD,,

pytcl/__init__.py

@@ -20,7 +20,7 @@ References
        no. 5, pp. 18-27, May 2017.
 """
 
-__version__ = "1.1.2"
+__version__ = "1.2.0"
 __author__ = "Python Port Contributors"
 __original_author__ = "David F. Crouse, Naval Research Laboratory"
 

pytcl/astronomical/reference_frames.py

@@ -21,6 +21,8 @@ References
        A&A, 2003.
 """
 
+import logging
+from functools import lru_cache
 from typing import Tuple
 
 import numpy as np
@@ -28,6 +30,22 @@ from numpy.typing import NDArray
 
 from pytcl.astronomical.time_systems import JD_J2000
 
+# Module logger
+_logger = logging.getLogger("pytcl.astronomical.reference_frames")
+
+# Cache configuration
+_CACHE_JD_DECIMALS = 6  # ~86ms precision for JD quantization
+_CACHE_MAXSIZE = 128  # Max cached epochs
+
+
+def _quantize_jd(jd: float) -> float:
+    """Quantize Julian date for cache key compatibility.
+
+    Rounds to _CACHE_JD_DECIMALS decimal places (~86ms precision).
+    This enables cache hits for nearly identical epochs.
+    """
+    return round(jd, _CACHE_JD_DECIMALS)
+
 
 def julian_centuries_j2000(jd: float) -> float:
     """
@@ -78,6 +96,37 @@ def precession_angles_iau76(T: float) -> Tuple[float, float, float]:
     )
 
 
+@lru_cache(maxsize=_CACHE_MAXSIZE)
+def _precession_matrix_cached(jd_quantized: float) -> tuple:
+    """Cached precession matrix computation (internal).
+
+    Returns tuple of tuples for hashability.
+    """
+    T = julian_centuries_j2000(jd_quantized)
+    zeta, theta, z = precession_angles_iau76(T)
+
+    cos_zeta = np.cos(zeta)
+    sin_zeta = np.sin(zeta)
+    cos_theta = np.cos(theta)
+    sin_theta = np.sin(theta)
+    cos_z = np.cos(z)
+    sin_z = np.sin(z)
+
+    return (
+        (
+            cos_zeta * cos_theta * cos_z - sin_zeta * sin_z,
+            -sin_zeta * cos_theta * cos_z - cos_zeta * sin_z,
+            -sin_theta * cos_z,
+        ),
+        (
+            cos_zeta * cos_theta * sin_z + sin_zeta * cos_z,
+            -sin_zeta * cos_theta * sin_z + cos_zeta * cos_z,
+            -sin_theta * sin_z,
+        ),
+        (cos_zeta * sin_theta, -sin_zeta * sin_theta, cos_theta),
+    )
+
+
 def precession_matrix_iau76(jd: float) -> NDArray[np.floating]:
     """
     Compute IAU 1976 precession matrix from J2000 to date.
@@ -92,34 +141,15 @@ def precession_matrix_iau76(jd: float) -> NDArray[np.floating]:
     P : ndarray
         Precession rotation matrix (3x3).
         Transforms from J2000 (GCRF) to mean of date.
-    """
-    T = julian_centuries_j2000(jd)
-    zeta, theta, z = precession_angles_iau76(T)
 
-    cos_zeta = np.cos(zeta)
-    sin_zeta = np.sin(zeta)
-    cos_theta = np.cos(theta)
-    sin_theta = np.sin(theta)
-    cos_z = np.cos(z)
-    sin_z = np.sin(z)
-
-    P = np.array(
-        [
-            [
-                cos_zeta * cos_theta * cos_z - sin_zeta * sin_z,
-                -sin_zeta * cos_theta * cos_z - cos_zeta * sin_z,
-                -sin_theta * cos_z,
-            ],
-            [
-                cos_zeta * cos_theta * sin_z + sin_zeta * cos_z,
-                -sin_zeta * cos_theta * sin_z + cos_zeta * cos_z,
-                -sin_theta * sin_z,
-            ],
-            [cos_zeta * sin_theta, -sin_zeta * sin_theta, cos_theta],
-        ]
-    )
-
-    return P
+    Notes
+    -----
+    Results are cached for repeated queries at the same epoch.
+    Cache key is quantized to ~86ms precision.
+    """
+    jd_q = _quantize_jd(jd)
+    cached = _precession_matrix_cached(jd_q)
+    return np.array(cached)
 
 
 def nutation_angles_iau80(jd: float) -> Tuple[float, float]:
@@ -203,6 +233,38 @@ def mean_obliquity_iau80(jd: float) -> float:
     return eps0_arcsec * np.pi / (180 * 3600)
 
 
+@lru_cache(maxsize=_CACHE_MAXSIZE)
+def _nutation_matrix_cached(jd_quantized: float) -> tuple:
+    """Cached nutation matrix computation (internal).
+
+    Returns tuple of tuples for hashability.
+    """
+    dpsi, deps = nutation_angles_iau80(jd_quantized)
+    eps0 = mean_obliquity_iau80(jd_quantized)
+    eps = eps0 + deps
+
+    cos_eps0 = np.cos(eps0)
+    sin_eps0 = np.sin(eps0)
+    cos_eps = np.cos(eps)
+    sin_eps = np.sin(eps)
+    cos_dpsi = np.cos(dpsi)
+    sin_dpsi = np.sin(dpsi)
+
+    return (
+        (cos_dpsi, -sin_dpsi * cos_eps0, -sin_dpsi * sin_eps0),
+        (
+            sin_dpsi * cos_eps,
+            cos_dpsi * cos_eps0 * cos_eps + sin_eps0 * sin_eps,
+            cos_dpsi * sin_eps0 * cos_eps - cos_eps0 * sin_eps,
+        ),
+        (
+            sin_dpsi * sin_eps,
+            cos_dpsi * cos_eps0 * sin_eps - sin_eps0 * cos_eps,
+            cos_dpsi * sin_eps0 * sin_eps + cos_eps0 * cos_eps,
+        ),
+    )
+
+
 def nutation_matrix(jd: float) -> NDArray[np.floating]:
     """
     Compute nutation matrix.
@@ -217,35 +279,15 @@ def nutation_matrix(jd: float) -> NDArray[np.floating]:
     N : ndarray
         Nutation rotation matrix (3x3).
         Transforms from mean of date to true of date.
-    """
-    dpsi, deps = nutation_angles_iau80(jd)
-    eps0 = mean_obliquity_iau80(jd)
-    eps = eps0 + deps
 
-    cos_eps0 = np.cos(eps0)
-    sin_eps0 = np.sin(eps0)
-    cos_eps = np.cos(eps)
-    sin_eps = np.sin(eps)
-    cos_dpsi = np.cos(dpsi)
-    sin_dpsi = np.sin(dpsi)
-
-    N = np.array(
-        [
-            [cos_dpsi, -sin_dpsi * cos_eps0, -sin_dpsi * sin_eps0],
-            [
-                sin_dpsi * cos_eps,
-                cos_dpsi * cos_eps0 * cos_eps + sin_eps0 * sin_eps,
-                cos_dpsi * sin_eps0 * cos_eps - cos_eps0 * sin_eps,
-            ],
-            [
-                sin_dpsi * sin_eps,
-                cos_dpsi * cos_eps0 * sin_eps - sin_eps0 * cos_eps,
-                cos_dpsi * sin_eps0 * sin_eps + cos_eps0 * cos_eps,
-            ],
-        ]
-    )
-
-    return N
+    Notes
+    -----
+    Results are cached for repeated queries at the same epoch.
+    Cache key is quantized to ~86ms precision.
+    """
+    jd_q = _quantize_jd(jd)
+    cached = _nutation_matrix_cached(jd_q)
+    return np.array(cached)
 
 
 def earth_rotation_angle(jd_ut1: float) -> float:
@@ -647,6 +689,33 @@ def equatorial_to_ecliptic(
     return R @ r_eq
 
 
+def clear_transformation_cache() -> None:
+    """Clear cached transformation matrices.
+
+    Call this function to clear all cached precession and nutation
+    matrices. Useful when memory is constrained or after processing
+    a batch of observations at different epochs.
+    """
+    _precession_matrix_cached.cache_clear()
+    _nutation_matrix_cached.cache_clear()
+    _logger.debug("Transformation matrix cache cleared")
+
+
+def get_cache_info() -> dict:
+    """Get cache statistics for transformation matrices.
+
+    Returns
+    -------
+    dict
+        Dictionary with 'precession' and 'nutation' keys, each containing
+        CacheInfo namedtuple with hits, misses, maxsize, currsize.
+    """
+    return {
+        "precession": _precession_matrix_cached.cache_info(),
+        "nutation": _nutation_matrix_cached.cache_info(),
+    }
+
+
 __all__ = [
     # Time utilities
     "julian_centuries_j2000",
@@ -674,4 +743,7 @@ __all__ = [
     # Ecliptic/equatorial
     "ecliptic_to_equatorial",
     "equatorial_to_ecliptic",
+    # Cache management
+    "clear_transformation_cache",
+    "get_cache_info",
 ]

pytcl/containers/__init__.py

@@ -3,8 +3,27 @@ Containers module.
 
 This module provides spatial data structures for efficient
 nearest neighbor queries, spatial indexing, and tracking containers.
+
+Spatial Index Hierarchy
+-----------------------
+All spatial index structures inherit from BaseSpatialIndex which defines
+a common interface for k-nearest neighbor and radius queries:
+
+    BaseSpatialIndex (abstract)
+    ├── KDTree - K-dimensional tree (Euclidean space)
+    ├── BallTree - Ball tree variant of KD-tree
+    ├── RTree - Rectangle tree for bounding boxes
+    └── MetricSpatialIndex (abstract)
+        ├── VPTree - Vantage point tree (any metric)
+        └── CoverTree - Cover tree (any metric)
 """
 
+from pytcl.containers.base import (
+    BaseSpatialIndex,
+    MetricSpatialIndex,
+    SpatialQueryResult,
+    validate_query_input,
+)
 from pytcl.containers.cluster_set import (
     ClusterSet,
     ClusterStats,
@@ -33,6 +52,11 @@ from pytcl.containers.track_list import TrackList, TrackListStats, TrackQuery
 from pytcl.containers.vptree import VPNode, VPTree, VPTreeResult
 
 __all__ = [
+    # Base classes
+    "BaseSpatialIndex",
+    "MetricSpatialIndex",
+    "SpatialQueryResult",
+    "validate_query_input",
     # K-D Tree
     "KDNode",
     "NearestNeighborResult",

pytcl/containers/base.py

@@ -0,0 +1,219 @@
+"""
+Base classes for spatial data structures.
+
+This module provides abstract base classes that define the common interface
+for spatial indexing data structures like KD-trees, VP-trees, R-trees, and
+Cover trees.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Callable, List, NamedTuple, Optional
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+# Module logger
+_logger = logging.getLogger("pytcl.containers")
+
+
+class SpatialQueryResult(NamedTuple):
+    """Result of a spatial query.
+
+    Attributes
+    ----------
+    indices : ndarray
+        Indices of matching points in the original data.
+    distances : ndarray
+        Distances to matching points.
+    """
+
+    indices: NDArray[np.intp]
+    distances: NDArray[np.floating]
+
+
+class BaseSpatialIndex(ABC):
+    """
+    Abstract base class for spatial indexing data structures.
+
+    All spatial index implementations (KDTree, VPTree, RTree, CoverTree)
+    should inherit from this class and implement the required methods.
+
+    This provides a consistent interface for:
+    - Building the index from point data
+    - k-nearest neighbor queries
+    - Range/radius queries
+    - Dimension and size introspection
+
+    Parameters
+    ----------
+    data : array_like
+        Data points of shape (n_samples, n_features).
+
+    Attributes
+    ----------
+    data : ndarray
+        The indexed data points.
+    n_samples : int
+        Number of data points.
+    n_features : int
+        Dimensionality of data points.
+    """
+
+    def __init__(self, data: ArrayLike):
+        self.data = np.asarray(data, dtype=np.float64)
+
+        if self.data.ndim != 2:
+            raise ValueError(
+                f"Data must be 2-dimensional (n_samples, n_features), "
+                f"got shape {self.data.shape}"
+            )
+
+        self.n_samples, self.n_features = self.data.shape
+        _logger.debug(
+            "%s initialized with %d points in %d dimensions",
+            self.__class__.__name__,
+            self.n_samples,
+            self.n_features,
+        )
+
+    @abstractmethod
+    def query(
+        self,
+        X: ArrayLike,
+        k: int = 1,
+    ) -> SpatialQueryResult:
+        """
+        Query the index for k nearest neighbors.
+
+        Parameters
+        ----------
+        X : array_like
+            Query points of shape (n_queries, n_features) or (n_features,).
+        k : int, optional
+            Number of nearest neighbors to return. Default is 1.
+
+        Returns
+        -------
+        result : SpatialQueryResult
+            Named tuple with indices and distances of k nearest neighbors
+            for each query point.
+        """
+        pass
+
+    @abstractmethod
+    def query_radius(
+        self,
+        X: ArrayLike,
+        r: float,
+    ) -> List[List[int]]:
+        """
+        Query the index for all points within radius r.
+
+        Parameters
+        ----------
+        X : array_like
+            Query points of shape (n_queries, n_features) or (n_features,).
+        r : float
+            Search radius.
+
+        Returns
+        -------
+        indices : list of list of int
+            For each query point, a list of indices of data points
+            within distance r.
+        """
+        pass
+
+    def __len__(self) -> int:
+        """Return number of indexed points."""
+        return self.n_samples
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"n_samples={self.n_samples}, n_features={self.n_features})"
+        )
+
+
+class MetricSpatialIndex(BaseSpatialIndex):
+    """
+    Base class for metric space spatial indices.
+
+    Extends BaseSpatialIndex with support for custom distance metrics.
+    Used by VP-trees and Cover trees which can work with any metric.
+
+    Parameters
+    ----------
+    data : array_like
+        Data points of shape (n_samples, n_features).
+    metric : callable, optional
+        Distance function with signature metric(x, y) -> float.
+        Default is Euclidean distance.
+    """
+
+    def __init__(
+        self,
+        data: ArrayLike,
+        metric: Optional[Callable[[NDArray, NDArray], float]] = None,
+    ):
+        super().__init__(data)
+
+        if metric is None:
+            self.metric = self._euclidean_distance
+        else:
+            self.metric = metric
+
+    @staticmethod
+    def _euclidean_distance(x: NDArray, y: NDArray) -> float:
+        """Default Euclidean distance metric."""
+        return float(np.sqrt(np.sum((x - y) ** 2)))
+
+
+def validate_query_input(
+    X: ArrayLike,
+    n_features: int,
+) -> NDArray[np.floating]:
+    """
+    Validate and reshape query input.
+
+    Parameters
+    ----------
+    X : array_like
+        Query points.
+    n_features : int
+        Expected number of features.
+
+    Returns
+    -------
+    X : ndarray
+        Validated query array of shape (n_queries, n_features).
+
+    Raises
+    ------
+    ValueError
+        If query has wrong number of features.
+    """
+    X = np.asarray(X, dtype=np.float64)
+
+    if X.ndim == 1:
+        X = X.reshape(1, -1)
+
+    if X.shape[1] != n_features:
+        _logger.warning(
+            "Query feature mismatch: got %d, expected %d", X.shape[1], n_features
+        )
+        raise ValueError(f"Query has {X.shape[1]} features, expected {n_features}")
+
+    _logger.debug(
+        "Validated query input: %d queries, %d features", X.shape[0], X.shape[1]
+    )
+    return X
+
+
+__all__ = [
+    "SpatialQueryResult",
+    "BaseSpatialIndex",
+    "MetricSpatialIndex",
+    "validate_query_input",
+]