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

gri_plot/observables/terrain.py

@@ -0,0 +1,293 @@
+"""Terrain surface from XYZ grid.
+
+This module provides the TerrainSurface class for visualizing terrain.
+"""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from scipy.interpolate import RegularGridInterpolator
+
+from gri_plot.surfaces import ImplicitShape
+from gri_plot.surfaces.mesh import vertices_to_mesh3d
+
+if TYPE_CHECKING:
+    import plotly.graph_objects as go
+    from numpy.typing import NDArray
+
+
+class TerrainSurface(ImplicitShape):
+    """Terrain surface from a grid of XYZ points.
+
+    The terrain is defined by a 2D grid of points in 3D space. This can
+    be used to visualize terrain elevation data or any sheet-like surface.
+
+    This is always treated as a surface (is_volume=False) since the target
+    is expected to be on the terrain surface, not inside a volume.
+
+    Attributes:
+        vertices: Grid vertices, shape (M, N, 3) or (M*N, 3).
+        grid_shape: Shape of the grid (M, N).
+        label: Optional label for legends.
+        is_volume: Always False for terrain surfaces.
+    """
+
+    def __init__(
+        self,
+        vertices: NDArray[np.floating],
+        grid_shape: tuple[int, int] | None = None,
+        label: str | None = None,
+    ) -> None:
+        """Initialize the terrain surface.
+
+        Args:
+            vertices: Grid vertices. Can be:
+                - Shape (M, N, 3): 2D grid of 3D points
+                - Shape (M*N, 3): Flattened grid (requires grid_shape)
+            grid_shape: Shape of the grid (M, N). Required if vertices is flat.
+            label: Optional label for legends.
+
+        Raises:
+            ValueError: If vertices shape is invalid or grid_shape is missing.
+        """
+        vertices = np.asarray(vertices, dtype=np.float64)
+
+        if vertices.ndim == 3:  # noqa: PLR2004 - 3D grid (M, N, 3)
+            self._grid_shape = (vertices.shape[0], vertices.shape[1])
+            self._vertices_grid = vertices
+            self._vertices = vertices.reshape(-1, 3)
+        elif vertices.ndim == 2 and vertices.shape[1] == 3:  # noqa: PLR2004 - flat (M*N, 3)
+            if grid_shape is None:
+                raise ValueError("grid_shape required for flat vertex array")
+            self._grid_shape = grid_shape
+            self._vertices = vertices
+            self._vertices_grid = vertices.reshape(grid_shape[0], grid_shape[1], 3)
+        else:
+            raise ValueError(
+                "vertices must be shape (M, N, 3) or (M*N, 3)",
+            )
+
+        if self._vertices.shape[0] != self._grid_shape[0] * self._grid_shape[1]:
+            raise ValueError(
+                f"Vertex count {self._vertices.shape[0]} does not match "
+                f"grid shape {self._grid_shape}",
+            )
+
+        self._label = label
+        self._faces = self._generate_faces()
+
+        # Set up interpolator for residual_fn
+        self._setup_interpolator()
+
+    def _generate_faces(self) -> NDArray[np.integer]:
+        """Generate triangular faces for the grid."""
+        m, n = self._grid_shape
+        faces = []
+
+        for i in range(m - 1):
+            for j in range(n - 1):
+                idx00 = i * n + j
+                idx01 = i * n + (j + 1)
+                idx10 = (i + 1) * n + j
+                idx11 = (i + 1) * n + (j + 1)
+
+                faces.append([idx00, idx10, idx11])
+                faces.append([idx00, idx11, idx01])
+
+        return np.array(faces, dtype=np.int64)
+
+    def _setup_interpolator(self) -> None:
+        """Set up interpolator for computing residuals.
+
+        Handles both meshgrid orientations:
+        - indexing='xy' (default): x varies along axis 1, y along axis 0
+        - indexing='ij': x varies along axis 0, y along axis 1
+        """
+        # Try to detect orientation by checking which axis has varying x
+        x_along_0 = self._vertices_grid[:, 0, 0]
+        x_along_1 = self._vertices_grid[0, :, 0]
+
+        # Check which axis has more variation in x
+        x_var_0 = np.ptp(x_along_0)  # peak-to-peak along axis 0
+        x_var_1 = np.ptp(x_along_1)  # peak-to-peak along axis 1
+
+        if x_var_0 > x_var_1:
+            # indexing='ij': x varies along axis 0, y along axis 1
+            x_coords = x_along_0
+            y_coords = self._vertices_grid[0, :, 1]
+            z_values = self._vertices_grid[:, :, 2]
+        else:
+            # indexing='xy' (default): x varies along axis 1, y along axis 0
+            x_coords = x_along_1
+            y_coords = self._vertices_grid[:, 0, 1]
+            z_values = self._vertices_grid[:, :, 2].T  # Transpose to match
+
+        self._x_coords = x_coords
+        self._y_coords = y_coords
+
+        # Create interpolator for z values
+        # fill_value=None enables extrapolation (scipy accepts None despite type stubs)
+        self._z_interp = RegularGridInterpolator(
+            (x_coords, y_coords),
+            z_values,
+            method="linear",
+            bounds_error=False,
+            fill_value=None,  # type: ignore[arg-type]
+        )
+
+    @property
+    def vertices(self) -> NDArray[np.floating]:
+        """Get vertices, shape (M*N, 3)."""
+        return self._vertices
+
+    @property
+    def grid_shape(self) -> tuple[int, int]:
+        """Get grid shape (M, N)."""
+        return self._grid_shape
+
+    @property
+    def label(self) -> str | None:
+        """Get the label."""
+        return self._label
+
+    @property
+    def is_volume(self) -> bool:
+        """Terrain surfaces are not volumes (target on terrain surface)."""
+        return False
+
+    def residual_fn(self, xyz: NDArray[np.floating]) -> NDArray[np.floating]:
+        """Compute the terrain residual (vertical distance from surface).
+
+        The residual is z - z_terrain, so:
+        - 0 on the terrain surface
+        - Positive above the terrain
+        - Negative below the terrain
+
+        Args:
+            xyz: Points to evaluate, shape (..., 3).
+
+        Returns:
+            Residual values, shape (...).
+        """
+        xyz = np.asarray(xyz)
+        original_shape = xyz.shape[:-1]
+
+        # Flatten for interpolation
+        flat_xyz = xyz.reshape(-1, 3)
+        xy_points = flat_xyz[:, :2]
+
+        # Interpolate terrain height at each (x, y)
+        z_terrain = self._z_interp(xy_points)
+
+        # Residual is actual z minus terrain z
+        residual = flat_xyz[:, 2] - z_terrain
+
+        return residual.reshape(original_shape)
+
+    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._vertices.min(axis=0), self._vertices.max(axis=0)
+
+    def to_mesh(
+        self,
+        resolution: int | None = None,  # noqa: ARG002 - unused, mesh is pre-computed
+    ) -> tuple[NDArray[np.floating], NDArray[np.integer]]:
+        """Return mesh vertices and faces.
+
+        Args:
+            resolution: Unused (mesh is pre-computed from input grid).
+
+        Returns:
+            Tuple of (vertices, faces).
+        """
+        return self._vertices, self._faces
+
+    def to_trace(
+        self,
+        resolution: int | None = None,  # noqa: ARG002 - unused but required by ABC
+        colorscale: str = "earth",
+        **kwargs,
+    ) -> go.Mesh3d:
+        """Generate a Plotly Mesh3d trace.
+
+        Args:
+            resolution: Unused (included for ABC compatibility).
+            colorscale: Color scale for elevation coloring.
+            **kwargs: Additional arguments for vertices_to_mesh3d.
+
+        Returns:
+            Plotly Mesh3d trace.
+        """
+        # Use z-coordinate for intensity if not specified
+        if "intensity_fn" not in kwargs and "color" not in kwargs:
+            # Default to Z-height intensity (vertices_to_mesh3d does this already)
+            kwargs["colorscale"] = colorscale
+            kwargs["showscale"] = True
+
+        return vertices_to_mesh3d(
+            self._vertices,
+            self._faces,
+            name=self._label,
+            **kwargs,
+        )
+
+    @classmethod
+    def from_xyz_grids(
+        cls,
+        x: NDArray[np.floating],
+        y: NDArray[np.floating],
+        z: NDArray[np.floating],
+        label: str | None = None,
+    ) -> TerrainSurface:
+        """Create terrain from separate X, Y, Z grids.
+
+        Args:
+            x: X coordinates, shape (M, N).
+            y: Y coordinates, shape (M, N).
+            z: Z coordinates, shape (M, N).
+            label: Optional label for legends.
+
+        Returns:
+            TerrainSurface instance.
+        """
+        x = np.asarray(x)
+        y = np.asarray(y)
+        z = np.asarray(z)
+
+        vertices = np.stack([x, y, z], axis=-1)
+        return cls(vertices, label=label)
+
+    @classmethod
+    def from_elevation_grid(
+        cls,
+        x_coords: NDArray[np.floating],
+        y_coords: NDArray[np.floating],
+        elevation: NDArray[np.floating],
+        label: str | None = None,
+    ) -> TerrainSurface:
+        """Create terrain from 1D coordinate arrays and 2D elevation grid.
+
+        Args:
+            x_coords: X coordinates, shape (M,).
+            y_coords: Y coordinates, shape (N,).
+            elevation: Elevation values, shape (M, N).
+            label: Optional label for legends.
+
+        Returns:
+            TerrainSurface instance.
+        """
+        x_grid, y_grid = np.meshgrid(x_coords, y_coords, indexing="ij")
+        return cls.from_xyz_grids(x_grid, y_grid, elevation, label=label)
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return f"TerrainSurface(grid_shape={self._grid_shape})"
+
+
+__all__ = ["TerrainSurface"]

gri_plot/plot_ellipse.py

@@ -0,0 +1,183 @@
+"""2D error ellipse plotting.
+
+This module provides the plot_ellipse() convenience function for rendering
+one or more 2D error ellipses as Plotly figures. Designed for visualizing
+geolocation error ellipses from gri-ell's Ell.ellipse output.
+"""
+
+import math
+from typing import TYPE_CHECKING
+
+import plotly.graph_objects as go
+
+from .figure3d import DEFAULT_COLORS
+
+if TYPE_CHECKING:
+    from .shapes.ellipse import Ellipse
+
+
+def _hex_to_rgba(hex_color: str, alpha: float) -> str:
+    """Convert hex color to rgba string.
+
+    Args:
+        hex_color: Hex color string (e.g., "#1f77b4").
+        alpha: Opacity value between 0 and 1.
+
+    Returns:
+        RGBA color string (e.g., "rgba(31, 119, 180, 0.25)").
+    """
+    h = hex_color.lstrip("#")
+    r, g, b = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+    return f"rgba({r}, {g}, {b}, {alpha})"
+
+
+def _add_ellipse_trace(
+    fig: go.Figure,
+    ellipse: Ellipse,
+    color: str,
+    *,
+    show_axes: bool,
+    single: bool,
+) -> None:
+    """Add traces for a single ellipse to the figure.
+
+    Args:
+        fig: Plotly figure to add traces to.
+        ellipse: Ellipse to render.
+        color: Hex color for this ellipse.
+        show_axes: Whether to draw SMA/SMI annotation lines.
+        single: True if this is the only ellipse (affects axis colors).
+    """
+    east, north = ellipse.boundary()
+
+    # Filled ellipse boundary
+    fig.add_trace(
+        go.Scatter(
+            x=east,
+            y=north,
+            mode="lines",
+            line={"color": color, "width": 2},
+            fill="toself",
+            fillcolor=_hex_to_rgba(color, 0.25),
+            name=ellipse.label or "Ellipse",
+            showlegend=True,
+        ),
+    )
+
+    if not show_axes:
+        return
+
+    # SMA / SMI annotation lines from center
+    ce, cn = ellipse.center
+    sma_rad = math.radians(90.0 - ellipse.ori_deg)
+    smi_rad = sma_rad + math.pi / 2
+
+    # Color convention: single ellipse uses red/orange; multi uses own color
+    if single:
+        sma_color = DEFAULT_COLORS[3]  # red
+        smi_color = DEFAULT_COLORS[1]  # orange
+    else:
+        sma_color = color
+        smi_color = color
+
+    for length, angle, axis_label, line_color in [
+        (ellipse.sma, sma_rad, f"SMA = {ellipse.sma:.0f} m", sma_color),
+        (ellipse.smi, smi_rad, f"SMI = {ellipse.smi:.0f} m", smi_color),
+    ]:
+        dx = length * math.cos(angle)
+        dy = length * math.sin(angle)
+        fig.add_trace(
+            go.Scatter(
+                x=[ce, ce + dx],
+                y=[cn, cn + dy],
+                mode="lines+text",
+                line={"color": line_color, "width": 2, "dash": "dash"},
+                text=["", axis_label],
+                textposition="top right",
+                textfont={"color": line_color, "size": 11},
+                showlegend=False,
+            ),
+        )
+
+
+def plot_ellipse(
+    *ellipses: Ellipse,
+    show_axes: bool = True,
+    title: str | None = None,
+    **kwargs,
+) -> go.Figure:
+    """Plot one or more 2D error ellipses.
+
+    Creates a Plotly figure with filled ellipses rendered in an East/North
+    coordinate frame. Designed for visualizing geolocation error ellipses.
+
+    Args:
+        *ellipses: One or more Ellipse objects to plot.
+        show_axes: If True, draw dashed SMA/SMI annotation lines with
+            length labels. For a single ellipse, uses red (SMA) and
+            orange (SMI). For multiple ellipses, uses each ellipse's
+            own color.
+        title: Optional figure title.
+        **kwargs: Additional arguments passed to fig.update_layout().
+
+    Returns:
+        Plotly Figure object. Call fig.show() to display.
+
+    Raises:
+        ValueError: If no ellipses are provided.
+    """
+    if not ellipses:
+        msg = "At least one Ellipse must be provided"
+        raise ValueError(msg)
+
+    fig = go.Figure()
+    single = len(ellipses) == 1
+
+    for i, ellipse in enumerate(ellipses):
+        color = DEFAULT_COLORS[i % len(DEFAULT_COLORS)]
+        _add_ellipse_trace(
+            fig,
+            ellipse,
+            color,
+            show_axes=show_axes,
+            single=single,
+        )
+
+    # Compute auto-padded range from all ellipses
+    all_east = []
+    all_north = []
+    for ellipse in ellipses:
+        east, north = ellipse.boundary()
+        all_east.extend([east.min(), east.max()])
+        all_north.extend([north.min(), north.max()])
+
+    e_min, e_max = min(all_east), max(all_east)
+    n_min, n_max = min(all_north), max(all_north)
+    e_span = e_max - e_min
+    n_span = n_max - n_min
+    pad = max(e_span, n_span) * 0.15
+
+    layout = {
+        "template": "plotly_dark",
+        "xaxis_title": "East (m)",
+        "yaxis_title": "North (m)",
+        "xaxis": {
+            "scaleanchor": "y",
+            "range": [e_min - pad, e_max + pad],
+        },
+        "yaxis": {
+            "range": [n_min - pad, n_max + pad],
+        },
+    }
+
+    if title is not None:
+        layout["title"] = title
+
+    layout.update(kwargs)
+    fig.update_layout(**layout)
+    return fig
+
+
+__all__ = [
+    "plot_ellipse",
+]

gri_plot/scatter.py

@@ -0,0 +1,76 @@
+"""Simple helper to externalize the plotly scattergram. Make it a one-liner."""
+
+from collections.abc import Sequence
+
+import numpy as np
+import plotly.graph_objects as go
+
+
+def scatter(*trace_info: Sequence, **kwargs) -> None:
+    """Scattergram with x defined or not. kwargs passed to update_layout.
+
+    Pass in info like:
+    scatter((y,))
+    scatter((y1,), (y2,))
+    scatter((y1,), (y2,), layout_args)
+    scatter((y1, trace_args), (y2,), layout_args)
+    scatter((x,y))
+    scatter((x1,y1), (x2,y2))
+    scatter((x1,y1), (x2,y2), layout_args)
+    scatter((x1,y1), (x2,y2, trace_args), layout_args)
+
+    Args:
+        trace_info: sequnces or tuples of sequences. If just single sequences (or
+            ndarrays) it plots the sequence as the y. If passed as tuples, uses seq[0]
+            for x and seq[1] for y. If a dictionary is passed, it will be passed through
+            to scatter as kwargs.
+        kwargs: Additional arguments to pass to update_layout like:
+            title="Plot Title", yaxis_range=[0,None], xaxis_title="Time (s)"
+    """
+    traces = _gather_data(trace_info)
+
+    fig = go.Figure()
+    fig.add_traces(traces)
+    fig.update_layout(template="plotly_dark", **kwargs)
+    fig.show()
+
+
+def _check_xdef(trace_info: Sequence) -> bool:
+    """Verify whether all or none have x defined and have only 2 or 3 args."""
+    if len(trace_info) == 0:
+        raise ValueError("No data passed in")
+    # All inputs are sequences of data
+    if any(not isinstance(t, Sequence) for t in trace_info):
+        raise ValueError("Inputs must be sequences of data like (y,) or (x,y,kwargs)")
+
+    x_def = False
+    if len(trace_info[0]) > 1 and isinstance(trace_info[0][1], (Sequence, np.ndarray)):
+        x_def = True
+    for t in trace_info:
+        if x_def:
+            if len(t) == 1 or not isinstance(t[1], (Sequence, np.ndarray)):
+                raise ValueError("All or no traces must have x defined")
+            if len(t) > 3:  # noqa: PLR2004 - trace is (x, y, kwargs)
+                raise ValueError("Extra information passed. Should be  (x,y,**args)")
+        else:
+            if len(t) > 1 and isinstance(t[1], (Sequence | np.ndarray)):
+                raise ValueError("All or no traces must have x defined")
+            if len(t) > 2:  # noqa: PLR2004 - trace is (y, kwargs)
+                raise ValueError("Extra information passed. Should be  (x,y,**args)")
+    return x_def
+
+
+def _gather_data(trace_info: Sequence) -> list[go.Scatter]:
+    """Gather all the traces for the plot."""
+    x_def = _check_xdef(trace_info)
+    traces: list[go.Scatter] = []
+    t_len = 2 if x_def else 1
+    for idx, t in enumerate(trace_info):
+        trace_args = {} if len(t) == t_len else t[-1]
+        if "name" not in trace_args:
+            trace_args["name"] = f"D{idx}"
+        if x_def:
+            traces.append(go.Scatter(x=t[0], y=t[1], **trace_args))
+        else:
+            traces.append(go.Scatter(y=t[0], **trace_args))
+    return traces

gri_plot/scatter_map.py

@@ -0,0 +1,93 @@
+"""Basic lat/lon plot to a scatter_map in plotly."""
+
+from typing import TYPE_CHECKING
+
+import plotly.graph_objects as go
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    import numpy as np
+
+# TODO lots of cleanup to do here
+
+
+def scatter_map(*args: Sequence[Sequence[float]] | np.ndarray, **kwargs) -> None:
+    """Make a plot from lists of lat/lon.
+
+    Takes a list of lats and a list of lons as the first two indexes, or a row of lats
+    and a row of lons. If your data is in numpy colums, just pass arr.T. If your list is
+    lat/lon pairs, then something like np.asarray(arr).T should work.
+
+    For example, pass in scatter_map((lats1,lons1),(lats2,lons2))
+    To get to ((lats,lons)) from ((lat,lon),...), use np.asarray(arr).T
+
+    Args:
+        args(Sequence[Sequence[float]] | np.ndarray): any number of sequences or arrays
+            where the first two rows are lat and lon
+        kwargs: Any arguments to pass to plotly.express.scater_map like:
+            zoom(1-20), height(pixel height of map), width(pixel height of width). Also
+            can use a list of marker_sizes(diameters) and marker_colors(plotly colors)
+            but must be the same length as *args
+    """
+    marker_sizes = kwargs.get("marker_sizes")
+    marker_colors = kwargs.get("marker_colors")
+    fig = go.Figure()
+    traces = [
+        go.Scattermap(
+            lat=arg[0],
+            lon=arg[1],
+            mode="markers",
+            marker={
+                "size": marker_sizes[idx] if marker_sizes else None,
+                "color": marker_colors[idx] if marker_colors else None,
+                "sizemode": "diameter",
+            },
+        )
+        for idx, arg in enumerate(args)
+    ]
+    fig.add_traces(traces)
+    center = _center(*args)
+
+    # fig.update_layout(map_style="open-street-map")
+    # fig.update_layout(map_style="carto-darkmatter")
+    # fig.update_layout(map_style="satellite-streets")
+    # fig.update_layout(map_style="satellite")
+    # fig.update_layout(map_style="streets")
+    # fig.update_layout(map_style="carto-voyager")
+    # fig.update_layout(map_style="carto-positron")
+    # s = "https://gis.apfo.usda.gov/arcgis/rest/services/NAIP/USDA_CONUS_PRIME/ImageServer/tile/{z}/{y}/{x}"
+    # s = "https://basemap.nationalmap.gov/arcgis/rest/services/USGSImageryOnly/MapServer/tile/{z}/{y}/{x}"
+    s = "https://services.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}"
+    fig.update_layout(
+        template="plotly_dark",
+        map_style="white-bg",
+        map_layers=[
+            {
+                "below": "traces",
+                "sourcetype": "raster",
+                "sourceattribution": "ArcGIS Online",
+                "source": [s],
+                "maxzoom": 18,
+            },
+        ],
+        map_zoom=kwargs.get("zoom"),
+        map_center=center,
+        height=kwargs.get("height"),
+        width=kwargs.get("width"),
+    )
+    fig.show()
+
+
+def _center(*args: Sequence[Sequence[float]] | np.ndarray) -> dict[str, float]:
+    """Get the center lat/lon of the data."""
+    min_lat = 999
+    min_lon = 999
+    max_lat = -999
+    max_lon = -999
+    for arg in args:
+        min_lat = min(min_lat, *arg[0])
+        max_lat = max(max_lat, *arg[0])
+        min_lon = min(min_lon, *arg[1])
+        max_lon = max(max_lon, *arg[1])
+    return {"lat": (min_lat + max_lat) / 2, "lon": (min_lon + max_lon) / 2}

gri_plot/shapes/__init__.py

@@ -0,0 +1,19 @@
+"""Geometric shape classes for visualization.
+
+This module provides classes for common shapes that can be rendered
+as either parametric meshes, isosurfaces, or 2D boundaries.
+"""
+
+from .cone import Cone
+from .cylinder import Cylinder
+from .ellipse import Ellipse
+from .ellipsoid import Ellipsoid
+from .sphere import Sphere
+
+__all__ = [
+    "Cone",
+    "Cylinder",
+    "Ellipse",
+    "Ellipsoid",
+    "Sphere",
+]