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

gri_plot/surfaces/__init__.py

@@ -0,0 +1,171 @@
+"""Surface ABC and base utilities for 3D visualization.
+
+This module defines the ImplicitShape ABC that all plottable shapes must implement.
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    import plotly.graph_objects as go
+    from numpy.typing import NDArray
+
+
+class ImplicitShape(ABC):
+    """Base class for all plottable 3D shapes and observables.
+
+    This ABC provides a unified interface for shapes that can be:
+    - Evaluated via an implicit function (residual_fn)
+    - Rendered as a Plotly Mesh3d trace
+    - Used in intersection calculations
+
+    Residual convention:
+        - residual < 0: inside the shape
+        - residual = 0: on the boundary
+        - residual > 0: outside the shape
+
+    The is_volume property determines intersection behavior:
+        - True: interior (residual < 0) is the solution region
+        - False: boundary (residual = 0) is the solution locus
+    """
+
+    @property
+    @abstractmethod
+    def is_volume(self) -> bool:
+        """Whether this shape represents a volume (True) or surface (False).
+
+        Volumes contribute to intersection everywhere inside (residual < 0).
+        Surfaces contribute based on distance from boundary (|residual|).
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def label(self) -> str | None:
+        """Optional label for the shape in legends."""
+        ...
+
+    @abstractmethod
+    def residual_fn(self, xyz: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Evaluate the implicit function at given points.
+
+        Args:
+            xyz: Points to evaluate, shape (..., 3).
+
+        Returns:
+            Residual values, shape (...). Negative inside, zero on boundary,
+            positive outside.
+        """
+        ...
+
+    @abstractmethod
+    def get_bounds_xyz(
+        self,
+    ) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+        """Get axis-aligned bounding box in XYZ coordinates.
+
+        Returns:
+            Tuple of (min_corner, max_corner), each shape (3,).
+        """
+        ...
+
+    @abstractmethod
+    def to_mesh(
+        self,
+        resolution: int | None = None,
+    ) -> tuple[NDArray[np.floating], NDArray[np.integer]]:
+        """Generate mesh vertices and faces.
+
+        Args:
+            resolution: Number of samples per dimension. If None, uses
+                shape-specific default.
+
+        Returns:
+            Tuple of (vertices, faces) where:
+                - vertices: shape (N, 3) array of vertex positions
+                - faces: shape (M, 3) array of triangle indices
+        """
+        ...
+
+    @abstractmethod
+    def to_trace(
+        self,
+        resolution: int | None = None,
+        **kwargs,
+    ) -> go.Mesh3d:
+        """Generate a Plotly Mesh3d trace for visualization.
+
+        Args:
+            resolution: Mesh resolution. If None, uses shape-specific default.
+            **kwargs: Additional arguments for the trace.
+
+        Returns:
+            Plotly Mesh3d trace.
+        """
+        ...
+
+    def contains(self, xyz: NDArray[np.floating]) -> NDArray[np.bool_]:
+        """Test if points are inside the shape.
+
+        Args:
+            xyz: Points to test, shape (..., 3).
+
+        Returns:
+            Boolean array, shape (...). True if inside (residual < 0).
+        """
+        return self.residual_fn(xyz) < 0
+
+
+def merge_bounds(
+    *bounds: tuple[NDArray[np.floating], NDArray[np.floating]],
+) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+    """Merge multiple bounding boxes into one.
+
+    Args:
+        *bounds: Tuples of (min_corner, max_corner), each shape (3,).
+
+    Returns:
+        Tuple of (min_corner, max_corner) encompassing all inputs.
+
+    Raises:
+        ValueError: If no bounds are provided.
+    """
+    if not bounds:
+        raise ValueError("At least one bounds tuple required")
+
+    all_mins = np.array([b[0] for b in bounds])
+    all_maxs = np.array([b[1] for b in bounds])
+
+    return all_mins.min(axis=0), all_maxs.max(axis=0)
+
+
+def expand_bounds(
+    bounds: tuple[NDArray[np.floating], NDArray[np.floating]],
+    factor: float = 1.1,
+) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+    """Expand bounds by a factor around their center.
+
+    Args:
+        bounds: Tuple of (min_corner, max_corner), each shape (3,).
+        factor: Expansion factor (1.0 = no change, 1.1 = 10% expansion).
+
+    Returns:
+        Expanded bounds tuple.
+    """
+    min_corner, max_corner = np.asarray(bounds[0]), np.asarray(bounds[1])
+    center = (min_corner + max_corner) / 2
+    half_extent = (max_corner - min_corner) / 2
+
+    return center - half_extent * factor, center + half_extent * factor
+
+
+from .intersection import IntersectionField  # noqa: E402
+
+__all__ = [
+    "ImplicitShape",
+    "IntersectionField",
+    "expand_bounds",
+    "merge_bounds",
+]

gri_plot/surfaces/gradients/__init__.py

@@ -0,0 +1,39 @@
+"""Intensity functions for mesh coloring.
+
+This module provides factory functions that create intensity calculators
+for coloring 3D mesh vertices. Each function returns a callable that takes
+a vertex array and returns intensity values.
+
+Example::
+
+    from gri_plot.surfaces.gradients import distance_from_axis, distance_from_line
+    from gri_plot.surfaces.mesh import vertices_to_mesh3d
+
+    # Color by distance from Z=0 (axis 2)
+    trace = vertices_to_mesh3d(
+        verts, faces,
+        intensity_fn=distance_from_axis(2, center=0.0),
+        colorbar_title="|Z| (m)",
+    )
+
+    # Color by distance from baseline between two collectors
+    trace = vertices_to_mesh3d(
+        verts, faces,
+        intensity_fn=distance_from_line(c1, c2),
+        colorbar_title="Baseline distance (m)",
+    )
+"""
+
+from .axis import axis_value, distance_from_axis
+from .line import distance_from_line, distance_from_line_segment
+from .plane import distance_from_plane
+from .point import distance_from_point
+
+__all__ = [
+    "axis_value",
+    "distance_from_axis",
+    "distance_from_line",
+    "distance_from_line_segment",
+    "distance_from_plane",
+    "distance_from_point",
+]

gri_plot/surfaces/gradients/axis.py

@@ -0,0 +1,74 @@
+"""Axis-based intensity functions."""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from numpy.typing import NDArray
+
+
+def axis_value(
+    axis: int = 2,
+) -> Callable[[NDArray[np.floating]], NDArray[np.floating]]:
+    """Create function that returns raw axis coordinate value.
+
+    Args:
+        axis: Which axis index (0, 1, or 2 for X, Y, Z respectively).
+
+    Returns:
+        Function that maps vertices (N, 3) to coordinate values (N,).
+
+    Example::
+
+        # Color vertices by their Z coordinate
+        intensity_fn = axis_value(2)
+        intensities = intensity_fn(vertices)
+    """
+    if axis not in (0, 1, 2):
+        msg = f"axis must be 0, 1, or 2, got {axis}"
+        raise ValueError(msg)
+
+    def fn(vertices: NDArray[np.floating]) -> NDArray[np.floating]:
+        return vertices[:, axis]
+
+    return fn
+
+
+def distance_from_axis(
+    axis: int = 2,
+    center: float = 0.0,
+) -> Callable[[NDArray[np.floating]], NDArray[np.floating]]:
+    """Create function that computes distance from an axis value.
+
+    This produces symmetric coloring around a reference value. Useful for
+    showing distance from a ground plane (Z=0) or similar reference.
+
+    Args:
+        axis: Which axis index (0, 1, or 2 for X, Y, Z respectively).
+        center: The reference value on that axis.
+
+    Returns:
+        Function that maps vertices (N, 3) to |axis_value - center| (N,).
+
+    Example::
+
+        # Color by distance from ground (Z=0)
+        intensity_fn = distance_from_axis(2, center=0.0)
+
+        # Color by distance from X=1000
+        intensity_fn = distance_from_axis(0, center=1000.0)
+    """
+    if axis not in (0, 1, 2):
+        msg = f"axis must be 0, 1, or 2, got {axis}"
+        raise ValueError(msg)
+
+    def fn(vertices: NDArray[np.floating]) -> NDArray[np.floating]:
+        return np.abs(vertices[:, axis] - center)
+
+    return fn
+
+
+__all__ = ["axis_value", "distance_from_axis"]

gri_plot/surfaces/gradients/line.py

@@ -0,0 +1,86 @@
+"""Line-based intensity functions."""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from numpy.typing import NDArray
+
+
+def distance_from_line(
+    point1: NDArray[np.floating],
+    point2: NDArray[np.floating],
+) -> Callable[[NDArray[np.floating]], NDArray[np.floating]]:
+    """Create function that computes perpendicular distance from an infinite line.
+
+    The line extends infinitely in both directions through the two points.
+
+    Args:
+        point1: First point on line, shape (3,).
+        point2: Second point on line, shape (3,).
+
+    Returns:
+        Function that maps vertices (N, 3) to perpendicular distances (N,).
+
+    Example::
+
+        # Color by distance from baseline between two collectors
+        intensity_fn = distance_from_line(collector1_xyz, collector2_xyz)
+    """
+    p1 = np.asarray(point1, dtype=np.float64)
+    p2 = np.asarray(point2, dtype=np.float64)
+    line_vec = p2 - p1
+    line_len = np.linalg.norm(line_vec)
+    line_dir = line_vec / line_len
+
+    def fn(vertices: NDArray[np.floating]) -> NDArray[np.floating]:
+        to_vert = vertices - p1
+        # Project onto line direction
+        proj_len = np.dot(to_vert, line_dir)
+        proj_point = p1 + np.outer(proj_len, line_dir)
+        return np.linalg.norm(vertices - proj_point, axis=1)
+
+    return fn
+
+
+def distance_from_line_segment(
+    point1: NDArray[np.floating],
+    point2: NDArray[np.floating],
+) -> Callable[[NDArray[np.floating]], NDArray[np.floating]]:
+    """Create function that computes distance from a line segment.
+
+    Unlike distance_from_line, this clamps to the segment endpoints.
+    Points beyond the endpoints measure distance to the nearest endpoint.
+
+    Args:
+        point1: Start of segment, shape (3,).
+        point2: End of segment, shape (3,).
+
+    Returns:
+        Function that maps vertices (N, 3) to distances (N,).
+
+    Example::
+
+        # Color by distance from a finite baseline segment
+        intensity_fn = distance_from_line_segment(start_xyz, end_xyz)
+    """
+    p1 = np.asarray(point1, dtype=np.float64)
+    p2 = np.asarray(point2, dtype=np.float64)
+    line_vec = p2 - p1
+    line_len_sq = np.dot(line_vec, line_vec)
+
+    def fn(vertices: NDArray[np.floating]) -> NDArray[np.floating]:
+        to_vert = vertices - p1
+        # Parameter t along segment, clamped to [0, 1]
+        t = np.dot(to_vert, line_vec) / line_len_sq
+        t = np.clip(t, 0, 1)
+        proj_point = p1 + np.outer(t, line_vec)
+        return np.linalg.norm(vertices - proj_point, axis=1)
+
+    return fn
+
+
+__all__ = ["distance_from_line", "distance_from_line_segment"]

gri_plot/surfaces/gradients/plane.py

@@ -0,0 +1,53 @@
+"""Plane-based intensity functions."""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from numpy.typing import NDArray
+
+
+def distance_from_plane(
+    normal: NDArray[np.floating],
+    point_on_plane: NDArray[np.floating],
+) -> Callable[[NDArray[np.floating]], NDArray[np.floating]]:
+    """Create function that computes absolute distance from a plane.
+
+    The plane is defined by a normal vector and a point on the plane.
+
+    Args:
+        normal: Plane normal vector (will be normalized), shape (3,).
+        point_on_plane: Any point on the plane, shape (3,).
+
+    Returns:
+        Function that maps vertices (N, 3) to absolute distances (N,).
+
+    Example::
+
+        # Color by height above ground (horizontal plane at Z=0)
+        intensity_fn = distance_from_plane(
+            normal=np.array([0, 0, 1]),
+            point_on_plane=np.array([0, 0, 0]),
+        )
+
+        # Color by distance from a tilted reference plane
+        intensity_fn = distance_from_plane(
+            normal=np.array([1, 1, 1]),  # Will be normalized
+            point_on_plane=center_xyz,
+        )
+    """
+    normal = np.asarray(normal, dtype=np.float64)
+    normal = normal / np.linalg.norm(normal)
+    point_on_plane = np.asarray(point_on_plane, dtype=np.float64)
+    d = -np.dot(normal, point_on_plane)
+
+    def fn(vertices: NDArray[np.floating]) -> NDArray[np.floating]:
+        return np.abs(np.dot(vertices, normal) + d)
+
+    return fn
+
+
+__all__ = ["distance_from_plane"]

gri_plot/surfaces/gradients/point.py

@@ -0,0 +1,40 @@
+"""Point-based intensity functions."""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from numpy.typing import NDArray
+
+
+def distance_from_point(
+    point: NDArray[np.floating],
+) -> Callable[[NDArray[np.floating]], NDArray[np.floating]]:
+    """Create function that computes Euclidean distance from a point.
+
+    Args:
+        point: Reference point, shape (3,).
+
+    Returns:
+        Function that maps vertices (N, 3) to distances (N,).
+
+    Example::
+
+        # Color by distance from origin
+        intensity_fn = distance_from_point(np.array([0, 0, 0]))
+
+        # Color by distance from sensor location
+        intensity_fn = distance_from_point(sensor_xyz)
+    """
+    point = np.asarray(point, dtype=np.float64)
+
+    def fn(vertices: NDArray[np.floating]) -> NDArray[np.floating]:
+        return np.linalg.norm(vertices - point, axis=1)
+
+    return fn
+
+
+__all__ = ["distance_from_point"]

gri_plot/surfaces/intersection.py

@@ -0,0 +1,217 @@
+"""Intersection field for visualizing where multiple implicit shapes meet.
+
+This module provides the IntersectionField class for highlighting regions
+where multiple implicit shapes intersect. The intersection is computed using
+Euclidean distance in residual space, giving a smooth tube-like volume around
+the intersection curve/region.
+"""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+# Import directly to avoid circular import
+from gri_plot.surfaces import merge_bounds
+
+if TYPE_CHECKING:
+    from gri_plot.surfaces import ImplicitShape
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from numpy.typing import NDArray
+
+
+class IntersectionField:
+    """Combined field showing where multiple implicit shapes intersect.
+
+    Computes the Euclidean distance to the intersection of multiple shapes.
+    For surfaces, this is sqrt(sum of squared residuals), giving a smooth
+    tube-like volume around the intersection curve. A radius parameter
+    controls the tube thickness.
+
+    Shapes are treated differently based on their is_volume property:
+    - Surfaces (is_volume=False): Use |residual| as distance to surface
+    - Volumes (is_volume=True): Use max(0, residual) as distance outside
+
+    Attributes:
+        shapes: The implicit shapes being intersected.
+        radius: Tube radius - distance from intersection where residual = 0.
+    """
+
+    def __init__(
+        self,
+        shapes: Sequence[ImplicitShape],
+        radius: float | None = None,
+        # Legacy parameters for backward compatibility
+        threshold: float | None = None,
+        steepness: float | None = None,
+    ) -> None:
+        """Initialize the intersection field.
+
+        Args:
+            shapes: Sequence of ImplicitShape objects to intersect.
+                Must have at least 2 shapes.
+            radius: Tube radius around the intersection. Points within this
+                distance of the intersection curve have negative residual.
+                If None, auto-computed as 5% of bounds diagonal.
+            threshold: Deprecated, use radius instead.
+            steepness: Deprecated, ignored.
+
+        Raises:
+            ValueError: If fewer than 2 shapes provided.
+        """
+        if len(shapes) < 2:  # noqa: PLR2004 - intersection requires >= 2 shapes
+            raise ValueError("IntersectionField requires at least 2 shapes")
+
+        self._shapes = list(shapes)
+
+        # Compute characteristic scale from bounds
+        bounds = self._compute_bounds()
+        extent = bounds[1] - bounds[0]
+        self._scale = float(np.linalg.norm(extent))
+        if self._scale == 0:
+            self._scale = 1.0
+
+        # Handle radius - either explicit or auto-computed
+        # The radius is in "residual space" - the same units as residual_fn outputs.
+        # For normalized residuals (like TDOA), typical values are 0.01-0.5.
+        # For spatial residuals (like distance to sphere), values are in meters.
+        if radius is not None:
+            self._radius = float(radius)
+        else:
+            # Default: 0.1 in residual space
+            # This works well for normalized residuals (TDOA, etc.)
+            # For spatial residuals, user should specify radius explicitly
+            self._radius = 0.1
+
+        # Keep for backward compatibility (though not used in new approach)
+        self._threshold = threshold if threshold is not None else 1.5
+        self._steepness = steepness if steepness is not None else 9.0
+
+        self._label: str | None = None
+
+    @property
+    def shapes(self) -> list[ImplicitShape]:
+        """Get the list of shapes."""
+        return self._shapes
+
+    # Backward compatibility alias
+    @property
+    def surfaces(self) -> list[ImplicitShape]:
+        """Get the list of shapes (deprecated, use shapes instead)."""
+        return self._shapes
+
+    @property
+    def radius(self) -> float:
+        """Get the tube radius."""
+        return self._radius
+
+    @property
+    def threshold(self) -> float:
+        """Get the threshold value (deprecated)."""
+        return self._threshold
+
+    @property
+    def steepness(self) -> float:
+        """Get the steepness parameter (deprecated)."""
+        return self._steepness
+
+    @property
+    def label(self) -> str | None:
+        """Get the optional label."""
+        return self._label
+
+    @label.setter
+    def label(self, value: str | None) -> None:
+        """Set the label."""
+        self._label = value
+
+    def distance_to_intersection(
+        self,
+        xyz: NDArray[np.floating],
+    ) -> NDArray[np.floating]:
+        """Compute Euclidean distance to the intersection.
+
+        For surfaces, computes sqrt(sum of squared residuals), which gives
+        the distance to the intersection curve/region in residual space.
+
+        For volumes, uses max(0, residual) so points inside contribute 0.
+
+        Args:
+            xyz: Points to evaluate, shape (..., 3).
+
+        Returns:
+            Distance values, shape (...). Zero exactly on the intersection,
+            positive elsewhere.
+        """
+        xyz = np.asarray(xyz)
+        sum_sq = np.zeros(xyz.shape[:-1], dtype=np.float64)
+
+        for shape in self._shapes:
+            residual = shape.residual_fn(xyz)
+
+            if shape.is_volume:
+                # Volume: only count distance if outside (residual > 0)
+                distance = np.maximum(0.0, residual)
+            else:
+                # Surface: distance is |residual|
+                distance = np.abs(residual)
+
+            sum_sq += distance * distance
+
+        return np.sqrt(sum_sq)
+
+    def residual_fn(self, xyz: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Compute the intersection field residual.
+
+        Returns distance_to_intersection - radius, so:
+        - Negative inside the tube (within radius of intersection)
+        - Zero on the tube surface
+        - Positive outside the tube
+
+        Args:
+            xyz: Points to evaluate, shape (..., 3).
+
+        Returns:
+            Residual values, shape (...).
+        """
+        return self.distance_to_intersection(xyz) - self._radius
+
+    # Keep for backward compatibility
+    def combined_closeness(self, xyz: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Compute closeness to intersection (deprecated).
+
+        This method is kept for backward compatibility but now uses the
+        Euclidean distance approach internally.
+
+        Args:
+            xyz: Points to evaluate, shape (..., 3).
+
+        Returns:
+            Closeness values based on distance to intersection.
+        """
+        distance = self.distance_to_intersection(xyz)
+        # Convert distance to closeness using exponential falloff
+        # Normalize by radius so closeness ~ 1 at the intersection
+        return np.exp(-distance / self._radius)
+
+    def _compute_bounds(
+        self,
+    ) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+        """Compute combined bounding box from all shapes."""
+        all_bounds = [s.get_bounds_xyz() for s in self._shapes]
+        return merge_bounds(*all_bounds)
+
+    def get_bounds_xyz(
+        self,
+    ) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+        """Get combined bounding box from all shapes.
+
+        Returns:
+            Tuple of (min_corner, max_corner) encompassing all shapes.
+        """
+        return self._compute_bounds()
+
+
+__all__ = ["IntersectionField"]