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

gri_plot/__init__.py

@@ -0,0 +1,94 @@
+"""Plotting utilities for GeoSol Research.
+
+This package provides utilities for 2D and 3D visualization using Plotly,
+including scatter plots, geographic maps, and 3D surfaces for geolocation
+observables.
+
+Main components:
+    - scatter: 2D scatter plots with Plotly
+    - scatter_map: Geographic scatter maps
+    - Figure3D: 3D figure for combining surfaces
+    - shapes: Geometric shapes (Ellipsoid, Sphere, Cone, Cylinder)
+    - observables: Geolocation surfaces (TDOA, FDOA, AOA, etc.)
+    - surfaces: Low-level surface utilities
+    - frames: Coordinate frame handling
+"""
+
+# 2D plotting
+# 3D plotting infrastructure
+from .figure3d import DEFAULT_COLORS, Figure3D, plot_surfaces
+from .frames import Bounds, Frame, FrameTransformer
+
+# Observables
+from .observables import (
+    AoaSurface,
+    FdoaSurface,
+    LosSurface,
+    RangeSphere,
+    TdoaSurface,
+    TerrainSurface,
+)
+from .plot_ellipse import plot_ellipse
+from .scatter import scatter
+from .scatter_map import scatter_map
+
+# Shapes
+from .shapes import Cone, Cylinder, Ellipse, Ellipsoid, Sphere
+
+# Shape mesh generators
+from .shapes.meshgen import cone_mesh, cylinder_mesh, ellipsoid_mesh, sphere_mesh
+
+# Surface utilities
+from .surfaces import (
+    ImplicitShape,
+    expand_bounds,
+    merge_bounds,
+)
+from .surfaces.gradients import (
+    axis_value,
+    distance_from_axis,
+    distance_from_line,
+    distance_from_line_segment,
+    distance_from_plane,
+    distance_from_point,
+)
+from .surfaces.mesh import field_to_mesh, grid_to_mesh, vertices_to_mesh3d
+
+__all__ = [
+    "DEFAULT_COLORS",
+    "AoaSurface",
+    "Bounds",
+    "Cone",
+    "Cylinder",
+    "Ellipse",
+    "Ellipsoid",
+    "FdoaSurface",
+    "Figure3D",
+    "Frame",
+    "FrameTransformer",
+    "ImplicitShape",
+    "LosSurface",
+    "RangeSphere",
+    "Sphere",
+    "TdoaSurface",
+    "TerrainSurface",
+    "axis_value",
+    "cone_mesh",
+    "cylinder_mesh",
+    "distance_from_axis",
+    "distance_from_line",
+    "distance_from_line_segment",
+    "distance_from_plane",
+    "distance_from_point",
+    "ellipsoid_mesh",
+    "expand_bounds",
+    "field_to_mesh",
+    "grid_to_mesh",
+    "merge_bounds",
+    "plot_ellipse",
+    "plot_surfaces",
+    "scatter",
+    "scatter_map",
+    "sphere_mesh",
+    "vertices_to_mesh3d",
+]

gri_plot/figure3d.py

@@ -0,0 +1,476 @@
+"""3D Figure class for combining multiple surfaces.
+
+This module provides the Figure3D class for building complex 3D visualizations
+by combining multiple Surface objects with coordinate frame transformation.
+"""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import plotly.graph_objects as go
+
+from .frames import Frame, FrameTransformer
+from .surfaces import ImplicitShape, expand_bounds, merge_bounds
+from .surfaces.intersection import IntersectionField
+from .surfaces.mesh import field_to_mesh, vertices_to_mesh3d
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from numpy.typing import NDArray
+
+
+# Default Plotly colors (Plotly's qualitative D3 palette)
+DEFAULT_COLORS = [
+    "#1f77b4",  # blue
+    "#ff7f0e",  # orange
+    "#2ca02c",  # green
+    "#d62728",  # red
+    "#9467bd",  # purple
+    "#8c564b",  # brown
+    "#e377c2",  # pink
+    "#7f7f7f",  # gray
+    "#bcbd22",  # olive
+    "#17becf",  # cyan
+]
+
+
+def _hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
+    """Convert hex color to RGB tuple."""
+    hex_color = hex_color.lstrip("#")
+    return (
+        int(hex_color[0:2], 16),
+        int(hex_color[2:4], 16),
+        int(hex_color[4:6], 16),
+    )
+
+
+def _color_to_gradient(color: str) -> list[list]:
+    """Create a gradient colorscale from a single color.
+
+    Creates a colorscale that goes from a darker version of the color
+    to a lighter version, giving a gradient effect within one hue.
+
+    Args:
+        color: Hex color string (e.g., "#1f77b4").
+
+    Returns:
+        Plotly colorscale list [[0, dark], [0.5, base], [1, light]].
+    """
+    r, g, b = _hex_to_rgb(color)
+
+    # Create darker version (50% darker)
+    dark_r = int(r * 0.5)
+    dark_g = int(g * 0.5)
+    dark_b = int(b * 0.5)
+    dark = f"rgb({dark_r},{dark_g},{dark_b})"
+
+    # Base color
+    base = f"rgb({r},{g},{b})"
+
+    # Create lighter version (50% toward white)
+    light_r = int(r + (255 - r) * 0.5)
+    light_g = int(g + (255 - g) * 0.5)
+    light_b = int(b + (255 - b) * 0.5)
+    light = f"rgb({light_r},{light_g},{light_b})"
+
+    return [[0, dark], [0.5, base], [1, light]]
+
+
+class Figure3D:
+    """3D figure for combining multiple surfaces with frame transformation.
+
+    This class manages a collection of 3D surfaces and provides methods for
+    adding surfaces, points, and rendering the final visualization.
+
+    Attributes:
+        display_frame: Coordinate frame for display.
+        origin_xyz: Origin for ENU frame transformations.
+    """
+
+    def __init__(
+        self,
+        display_frame: Frame = Frame.XYZ,
+        origin_xyz: NDArray[np.floating] | None = None,
+        title: str | None = None,
+    ) -> None:
+        """Initialize the 3D figure.
+
+        Args:
+            display_frame: Coordinate frame for visualization.
+            origin_xyz: Origin in XYZ coordinates, required for ENU frame.
+            title: Optional title for the figure.
+
+        Raises:
+            ValueError: If display_frame is ENU but origin_xyz is not provided.
+        """
+        self._transformer = FrameTransformer(display_frame, origin_xyz)
+        self._title = title
+        self._traces: list[go.Scatter3d | go.Mesh3d] = []
+        self._surface_bounds: list[tuple[NDArray, NDArray]] = []
+        self._color_index = 0
+
+    @property
+    def display_frame(self) -> Frame:
+        """Get the display frame."""
+        return self._transformer.display_frame
+
+    @property
+    def origin_xyz(self) -> NDArray[np.floating] | None:
+        """Get the origin in XYZ coordinates."""
+        return self._transformer.origin_xyz
+
+    def _next_color(self) -> str:
+        """Get the next color from the default palette."""
+        color = DEFAULT_COLORS[self._color_index % len(DEFAULT_COLORS)]
+        self._color_index += 1
+        return color
+
+    def add_surface(
+        self,
+        surface: ImplicitShape,
+        resolution: int | None = None,
+        color: str | None = None,
+        opacity: float = 0.7,
+        **kwargs,
+    ) -> Figure3D:
+        """Add a surface to the figure.
+
+        Args:
+            surface: ImplicitShape object to visualize.
+            resolution: Mesh resolution. If None, uses field_to_mesh default.
+            color: Base color for single-color gradient. If None, uses full
+                Viridis colorscale. For multiple surfaces, pick colors from
+                DEFAULT_COLORS to distinguish them (e.g., color=DEFAULT_COLORS[0]).
+            opacity: Surface opacity (0-1).
+            **kwargs: Additional arguments passed to the surface's to_trace().
+
+        Returns:
+            Self for method chaining.
+
+        """
+        # If no color specified, use full Viridis gradient
+        # If color specified, create a single-color gradient from that color
+        colorscale = "Viridis" if color is None else _color_to_gradient(color)
+
+        # Get bounds in XYZ
+        bounds_xyz = surface.get_bounds_xyz()
+        self._surface_bounds.append(bounds_xyz)
+
+        # Generate Mesh3d trace with the surface's native method
+        trace = surface.to_trace(
+            resolution=resolution,
+            colorscale=colorscale,
+            opacity=opacity,
+            **kwargs,
+        )
+
+        if self.display_frame != Frame.XYZ:
+            trace = self._transform_trace(trace)
+
+        self._traces.append(trace)
+        return self
+
+    def add_points(
+        self,
+        points_xyz: NDArray[np.floating],
+        labels: Sequence[str] | None = None,
+        color: str | None = None,
+        size: int = 8,
+        symbol: str = "circle",
+        **kwargs,
+    ) -> Figure3D:
+        """Add scatter points to the figure.
+
+        Args:
+            points_xyz: Points in XYZ coordinates, shape (N, 3).
+            labels: Optional labels for each point.
+            color: Point color. If None, uses next color from palette.
+            size: Marker size.
+            symbol: Marker symbol.
+            **kwargs: Additional arguments for go.Scatter3d.
+
+        Returns:
+            Self for method chaining.
+        """
+        points_xyz = np.asarray(points_xyz)
+        if points_xyz.ndim == 1:
+            points_xyz = points_xyz.reshape(1, 3)
+
+        if color is None:
+            color = self._next_color()
+
+        # Transform to display frame
+        points_display = self._transformer.to_display(points_xyz)
+
+        # Update bounds
+        min_corner = points_xyz.min(axis=0)
+        max_corner = points_xyz.max(axis=0)
+        self._surface_bounds.append((min_corner, max_corner))
+
+        trace_kwargs = {
+            "x": points_display[:, 0],
+            "y": points_display[:, 1],
+            "z": points_display[:, 2],
+            "mode": "markers+text" if labels else "markers",
+            "marker": {"size": size, "color": color, "symbol": symbol},
+        }
+
+        if labels:
+            trace_kwargs["text"] = list(labels)
+            trace_kwargs["textposition"] = "top center"
+
+        trace_kwargs.update(kwargs)
+        self._traces.append(go.Scatter3d(**trace_kwargs))
+        return self
+
+    def add_line(
+        self,
+        points_xyz: NDArray[np.floating],
+        color: str | None = None,
+        width: int = 2,
+        name: str | None = None,
+        **kwargs,
+    ) -> Figure3D:
+        """Add a line connecting points.
+
+        Args:
+            points_xyz: Points in XYZ coordinates, shape (N, 3).
+            color: Line color. If None, uses next color from palette.
+            width: Line width.
+            name: Trace name for legend.
+            **kwargs: Additional arguments for go.Scatter3d.
+
+        Returns:
+            Self for method chaining.
+        """
+        points_xyz = np.asarray(points_xyz)
+
+        if color is None:
+            color = self._next_color()
+
+        # Transform to display frame
+        points_display = self._transformer.to_display(points_xyz)
+
+        # Update bounds
+        min_corner = points_xyz.min(axis=0)
+        max_corner = points_xyz.max(axis=0)
+        self._surface_bounds.append((min_corner, max_corner))
+
+        trace_kwargs = {
+            "x": points_display[:, 0],
+            "y": points_display[:, 1],
+            "z": points_display[:, 2],
+            "mode": "lines",
+            "line": {"width": width, "color": color},
+        }
+
+        if name is not None:
+            trace_kwargs["name"] = name
+            trace_kwargs["showlegend"] = True
+
+        trace_kwargs.update(kwargs)
+        self._traces.append(go.Scatter3d(**trace_kwargs))
+        return self
+
+    def _transform_trace(
+        self,
+        trace: go.Scatter3d | go.Mesh3d,
+    ) -> go.Scatter3d | go.Mesh3d:
+        """Transform trace coordinates from XYZ to display frame.
+
+        Args:
+            trace: Plotly trace with x, y, z data.
+
+        Returns:
+            New trace with transformed coordinates.
+        """
+        x = np.asarray(trace.x)
+        y = np.asarray(trace.y)
+        z = np.asarray(trace.z)
+
+        xyz = np.column_stack([x.ravel(), y.ravel(), z.ravel()])
+        transformed = self._transformer.to_display(xyz)
+
+        # Create a copy with updated coordinates
+        trace_dict = trace.to_plotly_json()
+        trace_dict["x"] = transformed[:, 0].reshape(x.shape)
+        trace_dict["y"] = transformed[:, 1].reshape(y.shape)
+        trace_dict["z"] = transformed[:, 2].reshape(z.shape)
+
+        # Reconstruct the trace
+        trace_type = type(trace)
+        return trace_type(**trace_dict)
+
+    def add_intersection(  # noqa: PLR0913 - intersection has many visual options
+        self,
+        *surfaces: ImplicitShape,
+        threshold: float = 1.5,
+        steepness: float | None = None,
+        resolution: int | None = None,
+        color: str | None = None,
+        opacity: float = 0.8,
+        label: str | None = None,
+        **kwargs,
+    ) -> Figure3D:
+        """Add an intersection visualization for multiple implicit surfaces.
+
+        Highlights regions where multiple surfaces intersect by computing a
+        combined "closeness" field. Single-surface regions are hidden (below
+        threshold), while multi-surface intersections are progressively
+        highlighted.
+
+        Args:
+            *surfaces: ImplicitSurface objects to intersect. Must be at least 2.
+            threshold: Value subtracted from combined closeness. Default 1.5
+                hides single-surface regions while showing 2+ intersections.
+            steepness: Exponential falloff rate. If None, auto-computed based
+                on number of surfaces to ensure good visual gradient.
+            resolution: Mesh resolution. If None, uses field_to_mesh default.
+            color: Base color for gradient. If None, uses next palette color.
+            opacity: Surface opacity (0-1).
+            label: Optional label for legends.
+            **kwargs: Additional arguments passed to the Mesh3d trace.
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            ValueError: If fewer than 2 surfaces provided.
+        """
+        intersection = IntersectionField(
+            surfaces,
+            threshold=threshold,
+            steepness=steepness,
+        )
+
+        # Get bounds and add to tracking
+        bounds_xyz = intersection.get_bounds_xyz()
+        self._surface_bounds.append(bounds_xyz)
+
+        # Determine color
+        if color is None:
+            color = self._next_color()
+        colorscale = _color_to_gradient(color)
+
+        # Generate mesh using marching cubes via field_to_mesh
+        bounds = expand_bounds(bounds_xyz, 1.05)
+        if resolution is None:
+            vertices, faces = field_to_mesh(intersection.residual_fn, bounds)
+        else:
+            vertices, faces = field_to_mesh(
+                intersection.residual_fn,
+                bounds,
+                resolution=resolution,
+            )
+
+        # Create Mesh3d trace
+        trace = vertices_to_mesh3d(
+            vertices,
+            faces,
+            colorscale=colorscale,
+            opacity=opacity,
+            name=label,
+            **kwargs,
+        )
+
+        if self.display_frame != Frame.XYZ:
+            trace = self._transform_trace(trace)
+
+        self._traces.append(trace)
+        return self
+
+    def get_bounds_xyz(
+        self,
+    ) -> tuple[NDArray[np.floating], NDArray[np.floating]] | None:
+        """Get combined bounds of all surfaces in XYZ.
+
+        Returns:
+            Tuple of (min_corner, max_corner) or None if no surfaces added.
+        """
+        if not self._surface_bounds:
+            return None
+        return merge_bounds(*self._surface_bounds)
+
+    def build(self) -> go.Figure:
+        """Build the Plotly Figure.
+
+        Returns:
+            Plotly Figure object.
+        """
+        fig = go.Figure(data=self._traces)
+
+        # Get axis labels
+        x_label, y_label, z_label = self._transformer.get_axis_labels()
+
+        # Configure layout
+        layout_kwargs = {
+            "template": "plotly_dark",
+            "scene": {
+                "xaxis_title": x_label,
+                "yaxis_title": y_label,
+                "zaxis_title": z_label,
+                "aspectmode": "data",
+            },
+        }
+
+        if self._title:
+            layout_kwargs["title"] = self._title
+
+        fig.update_layout(**layout_kwargs)
+        return fig
+
+    def show(self, **kwargs) -> None:
+        """Build and display the figure.
+
+        Args:
+            **kwargs: Additional arguments passed to fig.show().
+        """
+        fig = self.build()
+        fig.show(**kwargs)
+
+    def write_html(self, path: str, **kwargs) -> None:
+        """Build and save the figure as HTML.
+
+        Args:
+            path: Output file path.
+            **kwargs: Additional arguments passed to fig.write_html().
+        """
+        fig = self.build()
+        fig.write_html(path, **kwargs)
+
+
+def plot_surfaces(
+    *surfaces: ImplicitShape,
+    display_frame: Frame = Frame.XYZ,
+    origin_xyz: NDArray[np.floating] | None = None,
+    title: str | None = None,
+    resolution: int | None = None,
+    **kwargs,
+) -> go.Figure:
+    """Quick function to plot multiple surfaces.
+
+    Args:
+        *surfaces: Surface objects to plot.
+        display_frame: Coordinate frame for visualization.
+        origin_xyz: Origin for ENU frame.
+        title: Figure title.
+        resolution: Mesh resolution. If None, uses field_to_mesh default.
+        **kwargs: Additional arguments passed to add_surface.
+
+    Returns:
+        Plotly Figure object.
+    """
+    fig = Figure3D(display_frame=display_frame, origin_xyz=origin_xyz, title=title)
+
+    for surface in surfaces:
+        fig.add_surface(surface, resolution=resolution, **kwargs)
+
+    return fig.build()
+
+
+__all__ = [
+    "DEFAULT_COLORS",
+    "Figure3D",
+    "plot_surfaces",
+]