nrl-tracker 1.8.0__py3-none-any.whl → 1.9.0__py3-none-any.whl

pytcl/dynamic_estimation/kalman/types.py

@@ -0,0 +1,98 @@
+"""
+Type definitions for Kalman filter implementations.
+
+This module provides shared NamedTuple types used across multiple Kalman
+filter implementations. Separating types into their own module prevents
+circular imports between filter implementations.
+"""
+
+from typing import NamedTuple
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class SRKalmanState(NamedTuple):
+    """State of a square-root Kalman filter.
+
+    Attributes
+    ----------
+    x : ndarray
+        State estimate.
+    S : ndarray
+        Lower triangular Cholesky factor of covariance (P = S @ S.T).
+    """
+
+    x: NDArray[np.floating]
+    S: NDArray[np.floating]
+
+
+class SRKalmanPrediction(NamedTuple):
+    """Result of square-root Kalman filter prediction step.
+
+    Attributes
+    ----------
+    x : ndarray
+        Predicted state estimate.
+    S : ndarray
+        Lower triangular Cholesky factor of predicted covariance.
+    """
+
+    x: NDArray[np.floating]
+    S: NDArray[np.floating]
+
+
+class SRKalmanUpdate(NamedTuple):
+    """Result of square-root Kalman filter update step.
+
+    Attributes
+    ----------
+    x : ndarray
+        Updated state estimate.
+    S : ndarray
+        Lower triangular Cholesky factor of updated covariance.
+    y : ndarray
+        Innovation (measurement residual).
+    S_y : ndarray
+        Lower triangular Cholesky factor of innovation covariance.
+    K : ndarray
+        Kalman gain.
+    likelihood : float
+        Measurement likelihood (for association).
+    """
+
+    x: NDArray[np.floating]
+    S: NDArray[np.floating]
+    y: NDArray[np.floating]
+    S_y: NDArray[np.floating]
+    K: NDArray[np.floating]
+    likelihood: float
+
+
+class UDState(NamedTuple):
+    """State of a U-D factorization filter.
+
+    The covariance is represented as P = U @ D @ U.T where U is
+    unit upper triangular and D is diagonal.
+
+    Attributes
+    ----------
+    x : ndarray
+        State estimate.
+    U : ndarray
+        Unit upper triangular factor.
+    D : ndarray
+        Diagonal elements (1D array).
+    """
+
+    x: NDArray[np.floating]
+    U: NDArray[np.floating]
+    D: NDArray[np.floating]
+
+
+__all__ = [
+    "SRKalmanState",
+    "SRKalmanPrediction",
+    "SRKalmanUpdate",
+    "UDState",
+]

pytcl/mathematical_functions/signal_processing/detection.py

@@ -1045,3 +1045,22 @@ def snr_loss(
         raise ValueError(f"Unknown method: {method}")
 
     return float(loss_db)
+
+
+__all__ = [
+    # Result Types
+    "CFARResult",
+    "CFARResult2D",
+    # Threshold and Detection Probability
+    "threshold_factor",
+    "detection_probability",
+    # CFAR Detectors
+    "cfar_ca",
+    "cfar_go",
+    "cfar_so",
+    "cfar_os",
+    "cfar_2d",
+    # Utilities
+    "cluster_detections",
+    "snr_loss",
+]

pytcl/mathematical_functions/transforms/wavelets.py

@@ -25,13 +25,14 @@ from typing import Any, Callable, List, NamedTuple, Optional, Union
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
-# Try to import pywavelets for DWT support
-try:
-    import pywt
+from pytcl.core.optional_deps import is_available
+
+# Use the unified availability check
+PYWT_AVAILABLE = is_available("pywt")
 
-    PYWT_AVAILABLE = True
-except ImportError:
-    PYWT_AVAILABLE = False
+# Import pywavelets if available (for use in functions)
+if PYWT_AVAILABLE:
+    import pywt
 
 
 # =============================================================================

pytcl/plotting/coordinates.py

@@ -10,15 +10,13 @@ from typing import Any, List, Optional, Tuple
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
-try:
-    import plotly.graph_objects as go
-    from plotly.subplots import make_subplots
+from pytcl.core.optional_deps import is_available, requires
 
-    HAS_PLOTLY = True
-except ImportError:
-    HAS_PLOTLY = False
+# Lazy flag for backward compatibility
+HAS_PLOTLY = is_available("plotly")
 
 
+@requires("plotly", extra="visualization")
 def plot_coordinate_axes_3d(
     origin: ArrayLike = (0, 0, 0),
     rotation_matrix: Optional[ArrayLike] = None,
@@ -28,7 +26,7 @@ def plot_coordinate_axes_3d(
     line_width: int = 4,
     showlegend: bool = True,
     name_prefix: str = "",
-) -> List["go.Scatter3d"]:
+) -> List[Any]:
     """
     Create Plotly traces for 3D coordinate axes.
 
@@ -56,8 +54,7 @@ def plot_coordinate_axes_3d(
     traces : list of go.Scatter3d
         List of three Plotly traces for the axes.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    import plotly.graph_objects as go
 
     origin = np.asarray(origin, dtype=np.float64)
     if rotation_matrix is None:
@@ -90,12 +87,13 @@ def plot_coordinate_axes_3d(
     return traces
 
 
+@requires("plotly", extra="visualization")
 def plot_rotation_comparison(
     R1: ArrayLike,
     R2: ArrayLike,
     labels: Tuple[str, str] = ("Original", "Rotated"),
     title: str = "Rotation Comparison",
-) -> "go.Figure":
+) -> Any:
     """
     Compare two rotation matrices by visualizing their coordinate frames.
 
@@ -115,8 +113,7 @@ def plot_rotation_comparison(
     fig : go.Figure
         Plotly figure.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    import plotly.graph_objects as go
 
     fig = go.Figure()
 
@@ -152,11 +149,12 @@ def plot_rotation_comparison(
     return fig
 
 
+@requires("plotly", extra="visualization")
 def plot_euler_angles(
     angles: ArrayLike,
     sequence: str = "ZYX",
     title: Optional[str] = None,
-) -> "go.Figure":
+) -> Any:
     """
     Visualize Euler angle rotations step by step.
 
@@ -174,8 +172,7 @@ def plot_euler_angles(
     fig : go.Figure
         Plotly figure with subplots showing each rotation step.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    from plotly.subplots import make_subplots
 
     angles = np.asarray(angles)
 
@@ -257,12 +254,13 @@ def plot_euler_angles(
     return fig
 
 
+@requires("plotly", extra="visualization")
 def plot_quaternion_interpolation(
     q_start: ArrayLike,
     q_end: ArrayLike,
     n_steps: int = 10,
     title: str = "Quaternion SLERP Interpolation",
-) -> "go.Figure":
+) -> Any:
     """
     Visualize quaternion interpolation (SLERP) between two orientations.
 
@@ -282,8 +280,7 @@ def plot_quaternion_interpolation(
     fig : go.Figure
         Plotly figure with animation.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    import plotly.graph_objects as go
 
     q_start = np.asarray(q_start)
     q_end = np.asarray(q_end)
@@ -410,6 +407,7 @@ def plot_quaternion_interpolation(
     return fig
 
 
+@requires("plotly", extra="visualization")
 def plot_spherical_grid(
     r: float = 1.0,
     n_lat: int = 10,
@@ -417,7 +415,7 @@ def plot_spherical_grid(
     color: str = "lightblue",
     opacity: float = 0.5,
     title: str = "Spherical Coordinate Grid",
-) -> "go.Figure":
+) -> Any:
     """
     Plot a spherical coordinate grid.
 
@@ -441,8 +439,7 @@ def plot_spherical_grid(
     fig : go.Figure
         Plotly figure.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    import plotly.graph_objects as go
 
     # Generate sphere surface
     theta = np.linspace(0, 2 * np.pi, n_lon)
@@ -485,6 +482,7 @@ def plot_spherical_grid(
     return fig
 
 
+@requires("plotly", extra="visualization")
 def plot_points_spherical(
     points_spherical: ArrayLike,
     r_idx: int = 0,
@@ -494,7 +492,7 @@ def plot_points_spherical(
     size: int = 5,
     name: str = "Points",
     title: str = "Points in Spherical Coordinates",
-) -> "go.Figure":
+) -> Any:
     """
     Plot points given in spherical coordinates.
 
@@ -522,8 +520,7 @@ def plot_points_spherical(
     fig : go.Figure
         Plotly figure.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    import plotly.graph_objects as go
 
     points = np.asarray(points_spherical)
     r = points[:, r_idx]
@@ -567,12 +564,13 @@ def plot_points_spherical(
     return fig
 
 
+@requires("plotly", extra="visualization")
 def plot_coordinate_transform(
     points_original: ArrayLike,
     points_transformed: ArrayLike,
     transform_name: str = "Transform",
     title: Optional[str] = None,
-) -> "go.Figure":
+) -> Any:
     """
     Visualize a coordinate transformation between two point sets.
 
@@ -592,8 +590,8 @@ def plot_coordinate_transform(
     fig : go.Figure
         Plotly figure with two subplots.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    import plotly.graph_objects as go
+    from plotly.subplots import make_subplots
 
     points_original = np.asarray(points_original)
     points_transformed = np.asarray(points_transformed)

pytcl/plotting/ellipses.py

@@ -5,17 +5,15 @@ This module provides functions for visualizing uncertainty as ellipses
 in 2D and 3D spaces, commonly used in tracking and estimation applications.
 """
 
-from typing import List, Optional, Tuple
+from typing import Any, List, Optional, Tuple
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
-try:
-    import plotly.graph_objects as go
+from pytcl.core.optional_deps import is_available, requires
 
-    HAS_PLOTLY = True
-except ImportError:
-    HAS_PLOTLY = False
+# Lazy flag for backward compatibility
+HAS_PLOTLY = is_available("plotly")
 
 
 def covariance_ellipse_points(
@@ -240,6 +238,7 @@ def confidence_region_radius(n_dims: int, confidence: float = 0.95) -> float:
     return np.sqrt(chi2_val)
 
 
+@requires("plotly", extra="visualization")
 def plot_covariance_ellipse(
     mean: ArrayLike,
     cov: ArrayLike,
@@ -249,7 +248,7 @@ def plot_covariance_ellipse(
     opacity: float = 0.3,
     name: Optional[str] = None,
     showlegend: bool = True,
-) -> "go.Scatter":
+) -> Any:
     """
     Create a Plotly trace for a covariance ellipse.
 
@@ -279,11 +278,10 @@ def plot_covariance_ellipse(
 
     Raises
     ------
-    ImportError
+    DependencyError
         If plotly is not installed.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    import plotly.graph_objects as go
 
     x, y = covariance_ellipse_points(mean, cov, n_std=n_std)
 
@@ -309,6 +307,7 @@ def plot_covariance_ellipse(
         )
 
 
+@requires("plotly", extra="visualization")
 def plot_covariance_ellipses(
     means: List[ArrayLike],
     covariances: List[ArrayLike],
@@ -316,7 +315,7 @@ def plot_covariance_ellipses(
     colors: Optional[List[str]] = None,
     opacity: float = 0.3,
     show_centers: bool = True,
-) -> "go.Figure":
+) -> Any:
     """
     Create a figure with multiple covariance ellipses.
 
@@ -340,8 +339,7 @@ def plot_covariance_ellipses(
     fig : go.Figure
         Plotly figure with the ellipses.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    import plotly.graph_objects as go
 
     fig = go.Figure()
 
@@ -394,6 +392,7 @@ def plot_covariance_ellipses(
     return fig
 
 
+@requires("plotly", extra="visualization")
 def plot_covariance_ellipsoid(
     mean: ArrayLike,
     cov: ArrayLike,
@@ -401,7 +400,7 @@ def plot_covariance_ellipsoid(
     color: str = "blue",
     opacity: float = 0.5,
     name: Optional[str] = None,
-) -> "go.Surface":
+) -> Any:
     """
     Create a Plotly surface trace for a 3D covariance ellipsoid.
 
@@ -425,8 +424,7 @@ def plot_covariance_ellipsoid(
     trace : go.Surface
         Plotly surface trace for the ellipsoid.
     """
-    if not HAS_PLOTLY:
-        raise ImportError("plotly is required for plotting functions")
+    import plotly.graph_objects as go
 
     x, y, z = covariance_ellipsoid_points(mean, cov, n_std=n_std)
 

pytcl/plotting/metrics.py

@@ -10,14 +10,16 @@ from typing import List, Optional
 import numpy as np
 from numpy.typing import ArrayLike
 
-try:
+from pytcl.core.optional_deps import is_available
+
+# Use the unified availability check
+HAS_PLOTLY = is_available("plotly")
+
+# Import plotly if available (for use in functions)
+if HAS_PLOTLY:
     import plotly.graph_objects as go
     from plotly.subplots import make_subplots
 
-    HAS_PLOTLY = True
-except ImportError:
-    HAS_PLOTLY = False
-
 
 def plot_rmse_over_time(
     errors: ArrayLike,

pytcl/plotting/tracks.py

@@ -10,15 +10,16 @@ from typing import Any, Dict, List, Optional
 import numpy as np
 from numpy.typing import ArrayLike
 
-try:
-    import plotly.graph_objects as go
-    from plotly.subplots import make_subplots
+from pytcl.core.optional_deps import is_available
+from pytcl.plotting.ellipses import covariance_ellipse_points
 
-    HAS_PLOTLY = True
-except ImportError:
-    HAS_PLOTLY = False
+# Use the unified availability check
+HAS_PLOTLY = is_available("plotly")
 
-from pytcl.plotting.ellipses import covariance_ellipse_points
+# Import plotly if available (for use in functions)
+if HAS_PLOTLY:
+    import plotly.graph_objects as go
+    from plotly.subplots import make_subplots
 
 
 def plot_trajectory_2d(

pytcl/terrain/loaders.py

@@ -26,6 +26,8 @@ from typing import Any, NamedTuple, Optional
 import numpy as np
 from numpy.typing import NDArray
 
+from pytcl.core.exceptions import DependencyError
+
 from .dem import DEMGrid
 
 # Model parameters
@@ -306,11 +308,13 @@ def parse_gebco_netcdf(
     """
     try:
         import netCDF4 as nc
-    except ImportError:
-        raise ImportError(
-            "netCDF4 is required for loading GEBCO files.\n"
-            "Install with: pip install netCDF4"
-        )
+    except ImportError as e:
+        raise DependencyError(
+            "netCDF4 is required for loading GEBCO files.",
+            package="netCDF4",
+            feature="NetCDF file reading",
+            install_command="pip install pytcl[terrain]",
+        ) from e
 
     # Set defaults for global extent
     if lat_min is None:
@@ -554,7 +558,7 @@ def load_gebco(
     ------
     FileNotFoundError
         If the GEBCO file is not found.
-    ImportError
+    DependencyError
         If netCDF4 is not installed.
 
     Examples