gri-plot 0.2.0.post1__py3-none-any.whl

gri_plot/frames.py

@@ -0,0 +1,181 @@
+"""Frame definitions and coordinate transformations.
+
+This module provides coordinate frame handling for 3D visualization using
+gri-utils for coordinate conversions.
+"""
+
+from enum import Enum
+from typing import TYPE_CHECKING, NamedTuple
+
+import numpy as np
+from gri_utils.conversion import get_enu, lla_to_xyz, translate_enu, xyz_to_lla
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+class Frame(Enum):
+    """Coordinate frame for 3D visualization.
+
+    Attributes:
+        XYZ: Earth-Centered Earth-Fixed (ECEF) Cartesian coordinates in meters.
+        ENU: East-North-Up local tangent plane coordinates in meters.
+        LLA: Latitude, Longitude, Altitude (degrees, degrees, meters).
+    """
+
+    XYZ = "xyz"
+    ENU = "enu"
+    LLA = "lla"
+
+
+class Bounds(NamedTuple):
+    """Axis-aligned bounding box in a specific frame.
+
+    Attributes:
+        min_corner: Minimum corner of the bounding box, shape (3,).
+        max_corner: Maximum corner of the bounding box, shape (3,).
+        frame: Coordinate frame of the bounds.
+        origin_xyz: Origin in XYZ coordinates, required for ENU frame.
+    """
+
+    min_corner: NDArray[np.floating]
+    max_corner: NDArray[np.floating]
+    frame: Frame = Frame.XYZ
+    origin_xyz: NDArray[np.floating] | None = None
+
+
+class FrameTransformer:
+    """Transforms coordinates between frames.
+
+    All internal computation is done in XYZ (ECEF). This class handles
+    conversion to/from the display frame.
+
+    Attributes:
+        display_frame: Target frame for visualization.
+        origin_xyz: Origin for ENU frame in XYZ coordinates.
+    """
+
+    def __init__(
+        self,
+        display_frame: Frame = Frame.XYZ,
+        origin_xyz: NDArray[np.floating] | None = None,
+    ) -> None:
+        """Initialize the frame transformer.
+
+        Args:
+            display_frame: Target frame for visualization.
+            origin_xyz: Origin in XYZ, required if display_frame is ENU.
+
+        Raises:
+            ValueError: If display_frame is ENU but origin_xyz is not provided.
+        """
+        if display_frame == Frame.ENU and origin_xyz is None:
+            raise ValueError("origin_xyz is required for ENU display frame")
+
+        self.display_frame = display_frame
+        self.origin_xyz = np.asarray(origin_xyz) if origin_xyz is not None else None
+
+    def to_display(self, xyz: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Transform XYZ coordinates to display frame.
+
+        Args:
+            xyz: Coordinates in XYZ (ECEF), shape (..., 3).
+
+        Returns:
+            Coordinates in display frame, shape (..., 3).
+        """
+        xyz = np.asarray(xyz)
+
+        if self.display_frame == Frame.XYZ:
+            return xyz
+        if self.display_frame == Frame.ENU:
+            if self.origin_xyz is None:  # pragma: no cover
+                raise RuntimeError("origin_xyz required for ENU frame")
+            return get_enu(self.origin_xyz, xyz)
+        if self.display_frame == Frame.LLA:
+            return xyz_to_lla(xyz)
+        raise ValueError(f"Unknown display frame: {self.display_frame}")
+
+    def from_display(self, coords: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Transform display frame coordinates to XYZ.
+
+        Args:
+            coords: Coordinates in display frame, shape (..., 3).
+
+        Returns:
+            Coordinates in XYZ (ECEF), shape (..., 3).
+        """
+        coords = np.asarray(coords)
+
+        if self.display_frame == Frame.XYZ:
+            return coords
+        if self.display_frame == Frame.ENU:
+            if self.origin_xyz is None:  # pragma: no cover
+                raise RuntimeError("origin_xyz required for ENU frame")
+            return translate_enu(self.origin_xyz, coords)
+        if self.display_frame == Frame.LLA:
+            return lla_to_xyz(coords)
+        raise ValueError(f"Unknown display frame: {self.display_frame}")
+
+    def transform_bounds(self, bounds_xyz: tuple[NDArray, NDArray]) -> Bounds:
+        """Transform XYZ bounds to display frame.
+
+        For non-linear transforms (LLA), this samples the bounding box to
+        find the actual extent in the display frame.
+
+        Args:
+            bounds_xyz: Tuple of (min_corner, max_corner) in XYZ.
+
+        Returns:
+            Bounds in the display frame.
+        """
+        min_xyz, max_xyz = np.asarray(bounds_xyz[0]), np.asarray(bounds_xyz[1])
+
+        if self.display_frame == Frame.XYZ:
+            return Bounds(min_xyz, max_xyz, Frame.XYZ, None)
+
+        if self.display_frame == Frame.ENU:
+            min_enu = self.to_display(min_xyz)
+            max_enu = self.to_display(max_xyz)
+            # Ensure min < max
+            actual_min = np.minimum(min_enu, max_enu)
+            actual_max = np.maximum(min_enu, max_enu)
+            return Bounds(actual_min, actual_max, Frame.ENU, self.origin_xyz)
+
+        if self.display_frame == Frame.LLA:
+            # Sample corners of the bounding box
+            corners = np.array(
+                [
+                    [min_xyz[0], min_xyz[1], min_xyz[2]],
+                    [min_xyz[0], min_xyz[1], max_xyz[2]],
+                    [min_xyz[0], max_xyz[1], min_xyz[2]],
+                    [min_xyz[0], max_xyz[1], max_xyz[2]],
+                    [max_xyz[0], min_xyz[1], min_xyz[2]],
+                    [max_xyz[0], min_xyz[1], max_xyz[2]],
+                    [max_xyz[0], max_xyz[1], min_xyz[2]],
+                    [max_xyz[0], max_xyz[1], max_xyz[2]],
+                ],
+            )
+            lla_corners = self.to_display(corners)
+            return Bounds(
+                lla_corners.min(axis=0),
+                lla_corners.max(axis=0),
+                Frame.LLA,
+                None,
+            )
+
+        raise ValueError(f"Unknown display frame: {self.display_frame}")
+
+    def get_axis_labels(self) -> tuple[str, str, str]:
+        """Get axis labels for the display frame.
+
+        Returns:
+            Tuple of (x_label, y_label, z_label) for the display frame.
+        """
+        if self.display_frame == Frame.XYZ:
+            return ("X (m)", "Y (m)", "Z (m)")
+        if self.display_frame == Frame.ENU:
+            return ("East (m)", "North (m)", "Up (m)")
+        if self.display_frame == Frame.LLA:
+            return ("Latitude (deg)", "Longitude (deg)", "Altitude (m)")
+        raise ValueError(f"Unknown display frame: {self.display_frame}")

gri_plot/observables/__init__.py

@@ -0,0 +1,21 @@
+"""Observable surface classes for geolocation visualization.
+
+This module provides surfaces for visualizing TDOA, FDOA, AOA, and other
+geolocation observables.
+"""
+
+from .aoa import AoaSurface
+from .fdoa import FdoaSurface
+from .los import LosSurface
+from .range_sphere import RangeSphere
+from .tdoa import TdoaSurface
+from .terrain import TerrainSurface
+
+__all__ = [
+    "AoaSurface",
+    "FdoaSurface",
+    "LosSurface",
+    "RangeSphere",
+    "TdoaSurface",
+    "TerrainSurface",
+]

gri_plot/observables/aoa.py

@@ -0,0 +1,123 @@
+"""AOA (Angle of Arrival) cone surface.
+
+This module provides the AoaSurface class for visualizing AOA measurements.
+"""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from gri_plot.shapes.cone import Cone
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+class AoaSurface(Cone):
+    """AOA cone surface representing an angle of arrival measurement.
+
+    The cone extends from the collector in the measured direction. If an
+    error radius is specified, a cone with that half-angle is rendered;
+    otherwise, a thin cone (line-like) is shown.
+
+    For 1D AOA (azimuth only), use a half-plane or cylinder instead.
+
+    This class inherits from Cone and always has is_volume=True since
+    an AOA measurement defines a volume where the target could be.
+
+    Attributes:
+        collector_xyz: Collector position in XYZ coordinates.
+        direction_xyz: Measured direction (unit vector).
+        error_rad: Angular error (half-angle) in radians.
+        max_range: Maximum range to extend the cone.
+        label: Optional label for legends.
+        is_volume: Always True for AOA surfaces.
+    """
+
+    def __init__(
+        self,
+        collector_xyz: NDArray[np.floating],
+        direction_xyz: NDArray[np.floating],
+        error_rad: float | None = None,
+        max_range: float = 1e6,
+        label: str | None = None,
+    ) -> None:
+        """Initialize the AOA surface.
+
+        Args:
+            collector_xyz: Collector position, shape (3,).
+            direction_xyz: Measured direction (will be normalized), shape (3,).
+            error_rad: Angular error (half-angle) in radians. If None or very
+                small, renders a thin cone.
+            max_range: Maximum range to extend the cone in meters.
+            label: Optional label for legends.
+
+        Raises:
+            ValueError: If max_range is not positive.
+        """
+        # Normalize direction
+        direction = np.asarray(direction_xyz, dtype=np.float64)
+        direction = direction / np.linalg.norm(direction)
+
+        # Minimum half-angle for visualization
+        min_angle = 0.01  # ~0.5 degrees
+        if error_rad is None or error_rad < min_angle:
+            half_angle = min_angle
+            self._is_exact = True
+        else:
+            half_angle = float(error_rad)
+            self._is_exact = False
+
+        if max_range <= 0:
+            raise ValueError("max_range must be positive")
+
+        # Initialize parent Cone
+        super().__init__(
+            apex_xyz=np.asarray(collector_xyz, dtype=np.float64),
+            axis=direction,
+            half_angle=half_angle,
+            height=float(max_range),
+            label=label,
+            as_volume=True,  # AOA is always a volume
+        )
+
+    @property
+    def is_volume(self) -> bool:
+        """AOA surfaces always represent volumes."""
+        return True
+
+    @property
+    def is_exact(self) -> bool:
+        """Whether this represents an exact AOA (no error specified)."""
+        return self._is_exact
+
+    # Convenience aliases for AOA-specific terminology
+    @property
+    def collector_xyz(self) -> NDArray[np.floating]:
+        """Get collector position."""
+        return self.apex_xyz
+
+    @property
+    def direction_xyz(self) -> NDArray[np.floating]:
+        """Get measured direction (unit vector)."""
+        return self.axis
+
+    @property
+    def error_rad(self) -> float:
+        """Get angular error in radians."""
+        return self.half_angle
+
+    @property
+    def max_range(self) -> float:
+        """Get maximum range."""
+        return self.height
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return (
+            f"AoaSurface(collector={self.apex_xyz}, "
+            f"direction={self.axis}, error={self.half_angle:.4f}rad)"
+        )
+
+
+__all__ = ["AoaSurface"]

gri_plot/observables/fdoa.py

@@ -0,0 +1,254 @@
+"""FDOA (Frequency Difference of Arrival) iso-Doppler surface.
+
+This module provides the FdoaSurface class for visualizing FDOA measurements.
+"""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from gri_utils import constants
+
+from gri_plot.surfaces import ImplicitShape, expand_bounds
+from gri_plot.surfaces.mesh import field_to_mesh, vertices_to_mesh3d
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import plotly.graph_objects as go
+    from numpy.typing import NDArray
+
+
+class FdoaSurface(ImplicitShape):
+    """FDOA iso-Doppler surface for frequency difference of arrival.
+
+    The surface represents all points where the difference in Doppler shift
+    between two collectors equals the measured FDOA.
+
+    The Doppler shift at collector i is:
+        f_doppler_i = f_tx * (v_i . r_hat_i) / c
+
+    where r_hat_i is the unit vector from emitter to collector i.
+
+    The FDOA is then:
+        fdoa = f_doppler_1 - f_doppler_2
+             = (f_tx / c) * (v_1 . r_hat_1 - v_2 . r_hat_2)
+
+    Attributes:
+        c1_xyz: First collector position in XYZ coordinates.
+        c2_xyz: Second collector position in XYZ coordinates.
+        c1_vel: First collector velocity in XYZ coordinates (m/s).
+        c2_vel: Second collector velocity in XYZ coordinates (m/s).
+        fdoa_hz: FDOA measurement in Hz.
+        freq_hz: Carrier frequency in Hz.
+        bounds_xyz: Bounding box for visualization.
+        label: Optional label for legends.
+        is_volume: Always False for FDOA surfaces (target on iso-doppler surface).
+    """
+
+    def __init__(  # noqa: PLR0913 - FDOA requires two positions + two velocities + freq
+        self,
+        c1_xyz: NDArray[np.floating],
+        c2_xyz: NDArray[np.floating],
+        c1_vel: NDArray[np.floating],
+        c2_vel: NDArray[np.floating],
+        fdoa_hz: float,
+        freq_hz: float,
+        bounds_xyz: tuple[NDArray[np.floating], NDArray[np.floating]] | None = None,
+        label: str | None = None,
+    ) -> None:
+        """Initialize the FDOA surface.
+
+        Args:
+            c1_xyz: First collector position, shape (3,).
+            c2_xyz: Second collector position, shape (3,).
+            c1_vel: First collector velocity, shape (3,).
+            c2_vel: Second collector velocity, shape (3,).
+            fdoa_hz: FDOA measurement in Hz.
+            freq_hz: Carrier frequency in Hz (must be positive).
+            bounds_xyz: Optional bounding box for visualization.
+            label: Optional label for legends.
+
+        Raises:
+            ValueError: If freq_hz is not positive.
+        """
+        self._c1 = np.asarray(c1_xyz, dtype=np.float64)
+        self._c2 = np.asarray(c2_xyz, dtype=np.float64)
+        self._v1 = np.asarray(c1_vel, dtype=np.float64)
+        self._v2 = np.asarray(c2_vel, dtype=np.float64)
+        self._fdoa = float(fdoa_hz)
+
+        if freq_hz <= 0:
+            raise ValueError("freq_hz must be positive")
+        self._freq = float(freq_hz)
+
+        self._label = label
+
+        # Precompute scaling factor
+        self._scale = self._freq / constants.C
+
+        # Compute default bounds if not provided
+        if bounds_xyz is None:
+            self._bounds_xyz = self._compute_default_bounds()
+        else:
+            self._bounds_xyz = (
+                np.asarray(bounds_xyz[0], dtype=np.float64),
+                np.asarray(bounds_xyz[1], dtype=np.float64),
+            )
+
+    def _compute_default_bounds(
+        self,
+    ) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+        """Compute default bounding box from collector positions."""
+        baseline = np.linalg.norm(self._c2 - self._c1)
+        padding = baseline * 2
+
+        min_corner = np.minimum(self._c1, self._c2) - padding
+        max_corner = np.maximum(self._c1, self._c2) + padding
+
+        return min_corner, max_corner
+
+    @property
+    def c1_xyz(self) -> NDArray[np.floating]:
+        """Get first collector position."""
+        return self._c1
+
+    @property
+    def c2_xyz(self) -> NDArray[np.floating]:
+        """Get second collector position."""
+        return self._c2
+
+    @property
+    def c1_vel(self) -> NDArray[np.floating]:
+        """Get first collector velocity."""
+        return self._v1
+
+    @property
+    def c2_vel(self) -> NDArray[np.floating]:
+        """Get second collector velocity."""
+        return self._v2
+
+    @property
+    def fdoa_hz(self) -> float:
+        """Get FDOA in Hz."""
+        return self._fdoa
+
+    @property
+    def freq_hz(self) -> float:
+        """Get carrier frequency in Hz."""
+        return self._freq
+
+    @property
+    def label(self) -> str | None:
+        """Get the label."""
+        return self._label
+
+    @property
+    def is_volume(self) -> bool:
+        """FDOA surfaces are not volumes (target on iso-doppler surface)."""
+        return False
+
+    def residual_fn(self, xyz: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Compute the FDOA residual.
+
+        The residual is the computed FDOA minus the measured FDOA,
+        normalized by the maximum possible FDOA for numerical stability.
+
+        Args:
+            xyz: Points to evaluate, shape (..., 3).
+
+        Returns:
+            Residual values, shape (...).
+        """
+        xyz = np.asarray(xyz)
+
+        # Unit vectors from emitter to collectors
+        diff1 = self._c1 - xyz
+        diff2 = self._c2 - xyz
+
+        r1 = np.linalg.norm(diff1, axis=-1, keepdims=True)
+        r2 = np.linalg.norm(diff2, axis=-1, keepdims=True)
+
+        # Avoid division by zero
+        r1 = np.maximum(r1, 1e-10)
+        r2 = np.maximum(r2, 1e-10)
+
+        r_hat_1 = diff1 / r1
+        r_hat_2 = diff2 / r2
+
+        # Doppler shifts (negative because we're measuring approaching/receding)
+        # When collector moves toward emitter (positive v.r_hat), frequency increases
+        doppler_1 = self._scale * np.einsum("i,...i->...", self._v1, r_hat_1)
+        doppler_2 = self._scale * np.einsum("i,...i->...", self._v2, r_hat_2)
+
+        computed_fdoa = doppler_1 - doppler_2
+
+        # Normalize by maximum possible FDOA (based on velocity magnitudes)
+        max_fdoa = self._scale * (np.linalg.norm(self._v1) + np.linalg.norm(self._v2))
+        if max_fdoa > 0:
+            return (computed_fdoa - self._fdoa) / max_fdoa
+        return computed_fdoa - self._fdoa
+
+    def get_bounds_xyz(
+        self,
+    ) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+        """Get bounding box in XYZ coordinates.
+
+        Returns:
+            Tuple of (min_corner, max_corner).
+        """
+        return self._bounds_xyz
+
+    def to_mesh(
+        self,
+        resolution: int | None = None,
+    ) -> tuple[NDArray[np.floating], NDArray[np.integer]]:
+        """Generate mesh vertices and faces.
+
+        Args:
+            resolution: Grid resolution. If None, uses field_to_mesh default.
+
+        Returns:
+            Tuple of (vertices, faces).
+        """
+        bounds = expand_bounds(self._bounds_xyz, 1.05)
+        if resolution is None:
+            return field_to_mesh(self.residual_fn, bounds)
+        return field_to_mesh(self.residual_fn, bounds, resolution=resolution)
+
+    def to_trace(
+        self,
+        resolution: int | None = None,
+        intensity_fn: Callable[[NDArray[np.floating]], NDArray[np.floating]]
+        | None = None,
+        **kwargs,
+    ) -> go.Mesh3d:
+        """Generate a Plotly Mesh3d trace.
+
+        Args:
+            resolution: Grid resolution. If None, uses field_to_mesh default.
+            intensity_fn: Optional function to compute vertex intensities for
+                coloring. Takes vertices (N, 3) and returns intensities (N,).
+                If None, defaults to Z-coordinate coloring.
+            **kwargs: Additional arguments for vertices_to_mesh3d.
+
+        Returns:
+            Plotly Mesh3d trace.
+        """
+        vertices, faces = self.to_mesh(resolution)
+        return vertices_to_mesh3d(
+            vertices,
+            faces,
+            intensity_fn=intensity_fn,
+            name=self._label,
+            **kwargs,
+        )
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return (
+            f"FdoaSurface(c1={self._c1}, c2={self._c2}, "
+            f"fdoa={self._fdoa}Hz, freq={self._freq}Hz)"
+        )
+
+
+__all__ = ["FdoaSurface"]