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

gri_plot/observables/los.py

@@ -0,0 +1,154 @@
+"""Line of Sight (LOS) ray/cylinder surface.
+
+This module provides the LosSurface class for visualizing line of sight.
+"""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import plotly.graph_objects as go
+
+from gri_plot.shapes.cylinder import Cylinder
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+class LosSurface(Cylinder):
+    """Line of Sight surface rendered as a thin cylinder.
+
+    Represents a line of sight from a collector in a given direction,
+    optionally with a width to indicate uncertainty.
+
+    This class inherits from Cylinder and always has is_volume=True since
+    a LOS measurement defines a volume where the target could be.
+
+    Attributes:
+        start_xyz: Start point (collector position) in XYZ coordinates.
+        direction_xyz: Direction of the LOS (unit vector).
+        length: Length of the LOS ray.
+        width: Width of the cylinder (for visualization).
+        label: Optional label for legends.
+        is_volume: Always True for LOS surfaces.
+    """
+
+    def __init__(
+        self,
+        start_xyz: NDArray[np.floating],
+        direction_xyz: NDArray[np.floating],
+        length: float,
+        width: float | None = None,
+        label: str | None = None,
+    ) -> None:
+        """Initialize the LOS surface.
+
+        Args:
+            start_xyz: Start point, shape (3,).
+            direction_xyz: Direction (will be normalized), shape (3,).
+            length: Length of the LOS in meters.
+            width: Width of the cylinder. If None, uses length/500.
+            label: Optional label for legends.
+
+        Raises:
+            ValueError: If length is not positive.
+        """
+        start = np.asarray(start_xyz, dtype=np.float64)
+        direction = np.asarray(direction_xyz, dtype=np.float64)
+        direction = direction / np.linalg.norm(direction)
+
+        if length <= 0:
+            raise ValueError("length must be positive")
+
+        radius = length / 500 if width is None else float(width)
+
+        # Store start point for convenience properties
+        self._start = start
+
+        # Cylinder is centered, so compute center point
+        center = start + (length / 2) * direction
+
+        # Initialize parent Cylinder
+        super().__init__(
+            center_xyz=center,
+            axis=direction,
+            radius=radius,
+            height=float(length),
+            label=label,
+            as_volume=True,  # LOS is always a volume
+        )
+
+    @property
+    def is_volume(self) -> bool:
+        """LOS surfaces always represent volumes."""
+        return True
+
+    # Convenience aliases for LOS-specific terminology
+    @property
+    def start_xyz(self) -> NDArray[np.floating]:
+        """Get start point."""
+        return self._start
+
+    @property
+    def end_xyz(self) -> NDArray[np.floating]:
+        """Get end point."""
+        return self._start + self.height * self.axis
+
+    @property
+    def direction_xyz(self) -> NDArray[np.floating]:
+        """Get direction (unit vector)."""
+        return self.axis
+
+    @property
+    def length(self) -> float:
+        """Get length."""
+        return self.height
+
+    @property
+    def width(self) -> float:
+        """Get width."""
+        return self.radius
+
+    def to_line_trace(
+        self,
+        color: str | None = None,
+        width: int = 2,
+        **kwargs,
+    ) -> go.Scatter3d:
+        """Generate a simple line trace (for cleaner visualization).
+
+        Args:
+            color: Line color.
+            width: Line width.
+            **kwargs: Additional arguments for go.Scatter3d.
+
+        Returns:
+            Plotly Scatter3d trace.
+        """
+        end = self.end_xyz
+        trace_kwargs: dict = {
+            "x": [self._start[0], end[0]],
+            "y": [self._start[1], end[1]],
+            "z": [self._start[2], end[2]],
+            "mode": "lines",
+            "line": {"width": width},
+        }
+
+        if color is not None:
+            trace_kwargs["line"]["color"] = color
+
+        if self.label:
+            trace_kwargs["name"] = self.label
+            trace_kwargs["showlegend"] = True
+
+        trace_kwargs.update(kwargs)
+        return go.Scatter3d(**trace_kwargs)
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return (
+            f"LosSurface(start={self._start}, direction={self.axis}, "
+            f"length={self.height})"
+        )
+
+
+__all__ = ["LosSurface"]

gri_plot/observables/range_sphere.py

@@ -0,0 +1,74 @@
+"""Range sphere surface for TOA/range observables.
+
+This module provides the RangeSphere class for visualizing range measurements.
+"""
+
+from typing import TYPE_CHECKING
+
+from gri_plot.shapes.sphere import Sphere
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+class RangeSphere(Sphere):
+    """Range sphere representing a TOA or direct range measurement.
+
+    The sphere is centered on a collector at the measured range distance.
+    This is essentially a Sphere with collector/range semantics.
+
+    This class inherits from Sphere and always has is_volume=True since
+    a range measurement defines a volume where the target could be.
+
+    Attributes:
+        collector_xyz: Collector position in XYZ coordinates.
+        range_m: Range in meters.
+        label: Optional label for legends.
+        is_volume: Always True for range spheres.
+    """
+
+    def __init__(
+        self,
+        collector_xyz: NDArray,
+        range_m: float,
+        label: str | None = None,
+    ) -> None:
+        """Initialize the range sphere.
+
+        Args:
+            collector_xyz: Collector position, shape (3,).
+            range_m: Range measurement in meters (positive).
+            label: Optional label for legends.
+
+        Raises:
+            ValueError: If range_m is not positive.
+        """
+        super().__init__(
+            center_xyz=collector_xyz,
+            radius=range_m,
+            label=label,
+            as_volume=True,  # Range sphere is always a volume
+        )
+
+    @property
+    def is_volume(self) -> bool:
+        """Range spheres always represent volumes."""
+        return True
+
+    # Convenience aliases for range-specific terminology
+    @property
+    def collector_xyz(self) -> NDArray:
+        """Get collector position."""
+        return self.center_xyz
+
+    @property
+    def range_m(self) -> float:
+        """Get range in meters."""
+        return self.radius
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return f"RangeSphere(collector={self.center_xyz}, range={self.radius}m)"
+
+
+__all__ = ["RangeSphere"]

gri_plot/observables/tdoa.py

@@ -0,0 +1,201 @@
+"""TDOA (Time Difference of Arrival) hyperboloid surface.
+
+This module provides the TdoaSurface class for visualizing TDOA isosurfaces.
+"""
+
+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 TdoaSurface(ImplicitShape):
+    """TDOA hyperboloid surface where range_1 - range_2 = c * tdoa.
+
+    The surface represents all points where the difference in range to two
+    collectors equals the measured TDOA times the speed of light.
+
+    Attributes:
+        c1_xyz: First collector position in XYZ coordinates.
+        c2_xyz: Second collector position in XYZ coordinates.
+        tdoa_seconds: TDOA measurement in seconds (r1 - r2 = c * tdoa).
+        bounds_xyz: Bounding box for visualization.
+        label: Optional label for legends.
+        is_volume: Always False for TDOA surfaces (target on hyperboloid).
+    """
+
+    def __init__(
+        self,
+        c1_xyz: NDArray[np.floating],
+        c2_xyz: NDArray[np.floating],
+        tdoa_seconds: float,
+        bounds_xyz: tuple[NDArray[np.floating], NDArray[np.floating]] | None = None,
+        label: str | None = None,
+    ) -> None:
+        """Initialize the TDOA surface.
+
+        Args:
+            c1_xyz: First collector position, shape (3,).
+            c2_xyz: Second collector position, shape (3,).
+            tdoa_seconds: TDOA in seconds. Positive means signal arrived at
+                c1 first (r1 < r2), negative means c2 first.
+            bounds_xyz: Optional bounding box for visualization. If None,
+                computed automatically from collector positions.
+            label: Optional label for legends.
+        """
+        self._c1 = np.asarray(c1_xyz, dtype=np.float64)
+        self._c2 = np.asarray(c2_xyz, dtype=np.float64)
+        self._tdoa = float(tdoa_seconds)
+        self._label = label
+
+        # Range difference
+        self._range_diff = self._tdoa * 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.
+
+        The bounds are set to encompass both collectors with padding.
+        """
+        baseline = np.linalg.norm(self._c2 - self._c1)
+        # Extend by 2x baseline in each direction
+        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 tdoa_seconds(self) -> float:
+        """Get TDOA in seconds."""
+        return self._tdoa
+
+    @property
+    def range_difference(self) -> float:
+        """Get range difference in meters (r1 - r2)."""
+        return self._range_diff
+
+    @property
+    def label(self) -> str | None:
+        """Get the label."""
+        return self._label
+
+    @property
+    def is_volume(self) -> bool:
+        """TDOA surfaces are not volumes (target on hyperboloid surface)."""
+        return False
+
+    def residual_fn(self, xyz: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Compute the TDOA residual.
+
+        The residual is (r1 - r2) - (c * tdoa), normalized by baseline,
+        so 0 on the surface, positive on the c1 side, negative on the c2 side.
+
+        Args:
+            xyz: Points to evaluate, shape (..., 3).
+
+        Returns:
+            Residual values, shape (...).
+        """
+        xyz = np.asarray(xyz)
+
+        r1 = np.linalg.norm(xyz - self._c1, axis=-1)
+        r2 = np.linalg.norm(xyz - self._c2, axis=-1)
+
+        # Normalize by baseline for numerical stability
+        baseline = np.linalg.norm(self._c2 - self._c1)
+        if baseline > 0:
+            return (r1 - r2 - self._range_diff) / baseline
+        return r1 - r2 - self._range_diff
+
+    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"TdoaSurface(c1={self._c1}, c2={self._c2}, tdoa={self._tdoa:.9f}s)"
+
+
+__all__ = ["TdoaSurface"]