gri-plot 0.2.3__tar.gz → 0.2.5__tar.gz

{gri_plot-0.2.3 → gri_plot-0.2.5}/CONTRIBUTING.md

@@ -54,12 +54,12 @@ ruff check     # lint
 ruff format    # format
 ```
 
-### Pyright
+### ty
 
-[Pyright](https://microsoft.github.io/pyright/#/) for static type checking:
+[ty](https://docs.astral.sh/ty/) for static type checking:
 
 ```bash
-pyright
+ty check
 ```
 
 ### Pre-commit
@@ -110,4 +110,8 @@ by Astral and add to your `settings.json`:
 }
 ```
 
-Pyright is included in VS Code's Pylance extension by default.
+For type checking in VS Code, install the
+[ty extension](https://marketplace.visualstudio.com/items?itemName=astral-sh.ty)
+by Astral. To avoid conflicts with Pylance, either let ty disable the Python
+language server (the default) or keep Pylance and set
+`"ty.disableLanguageServices": true` to use ty for diagnostics only.

{gri_plot-0.2.3 → gri_plot-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gri-plot
-Version: 0.2.3
+Version: 0.2.5
 Summary: 3D geolocation visualization and 2D plotting utilities built on Plotly
 Project-URL: Homepage, https://geosolresearch.com
 Project-URL: Repository, https://gitlab.com/geosol-foss/python/gri-plot
@@ -19,8 +19,8 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.12
 Requires-Dist: gri-utils>=0.3.3
 Requires-Dist: numpy>=2.3.3
+Requires-Dist: pillow>=11.0.0
 Requires-Dist: plotly>=6.3.0
-Requires-Dist: scikit-image>=0.25.0
 Description-Content-Type: text/markdown
 
 [![GeoSol Research Logo](https://geosolresearch.com/logos/foss_logo.png "GeoSol Research")](https://geosolresearch.com)
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 
 ## Overview
 
-This library renders implicit surfaces (TDOA hyperboloids, FDOA iso-Doppler surfaces, AOA cones, range spheres, terrain) and geometric shapes (ellipsoids, spheres, cones, cylinders) as interactive 3D meshes. It also provides shorthand functions for 2D scatter plots and geographic maps.
+This library renders parametric geometric shapes (ellipsoids, spheres, cones, cylinders) and observable surfaces that inherit from them (AOA cones, line-of-sight rays, range spheres) as interactive 3D meshes. It also provides shorthand functions for 2D scatter plots and geographic maps.
 
 ## Installation
 
@@ -86,14 +86,12 @@ Scene builder for composing 3D visualizations from multiple surfaces and points:
 - **`add_surface()`**: Add any `ImplicitShape` (shapes or observables)
 - **`add_points()`**: Add labeled scatter points
 - **`add_line()`**: Add line segments connecting points
-- **`add_intersection()`**: Highlight where multiple surfaces intersect
 - **`plot_surfaces()`**: Convenience function for quick multi-surface plots
 - Method chaining, automatic color cycling from D3 palette, `plotly_dark` template
 
 ```python
 from gri_plot import Figure3D
 from gri_plot.shapes import Sphere
-from gri_plot.observables import TdoaSurface
 import numpy as np
 
 fig = Figure3D()
@@ -113,7 +111,7 @@ Coordinate frame handling for 3D display:
 
 ## Shapes
 
-Geometric primitives implementing the `ImplicitShape` ABC. Each supports parametric mesh generation (fast, exact geometry) and implicit residual evaluation (for intersection calculations).
+Geometric primitives implementing the `ImplicitShape` ABC. Each supports parametric mesh generation (fast, exact geometry) and implicit residual evaluation.
 
 - **Ellipsoid**: From center + covariance matrix, or center + semi-axes + rotation matrix
 - **Sphere**: From center + radius
@@ -123,31 +121,23 @@ Geometric primitives implementing the `ImplicitShape` ABC. Each supports paramet
 
 ## Observables
 
-Geolocation-specific surfaces for visualizing measurement iso-surfaces. Some inherit from shapes (reusing parametric rendering), others use marching cubes for mesh extraction.
+Geolocation-specific surfaces that inherit from parametric shapes:
 
-- **TdoaSurface**: TDOA hyperboloid where range_1 - range_2 = c x tdoa, from two collector positions + time difference
-- **FdoaSurface**: FDOA iso-Doppler surface from two collector positions/velocities + carrier frequency + frequency difference
 - **AoaSurface**: AOA cone (extends Cone) from collector position + measured direction + angular error
 - **LosSurface**: Line of sight ray (extends Cylinder) from start point + direction + length; also provides `to_line_trace()` for simple line rendering
 - **RangeSphere**: Range/TOA sphere (extends Sphere) from collector position + range measurement
-- **TerrainSurface**: Terrain from XYZ vertex grid with interpolated residual evaluation; factory methods `from_xyz_grids()` and `from_elevation_grid()`
 
 ## Surfaces
 
-Low-level infrastructure for implicit surface rendering:
+Low-level infrastructure for shape rendering:
 
 - **ImplicitShape ABC**: Interface requiring `residual_fn()`, `get_bounds_xyz()`, `to_mesh()`, `to_trace()`, `is_volume`, `label`; also provides `contains()` for point-in-shape testing
-- **Mesh utilities**: `field_to_mesh()` (marching cubes with Newton-Raphson surface projection and adaptive refinement), `grid_to_mesh()` (parametric grid triangulation), `vertices_to_mesh3d()` (vertices/faces to Plotly Mesh3d trace)
-- **IntersectionField**: Euclidean distance in residual space for highlighting multi-surface intersections; distinguishes volumes (interior contribution) from surfaces (boundary contribution)
-- **Gradient functions**: Intensity calculators for mesh coloring -- `distance_from_point`, `distance_from_line`, `distance_from_line_segment`, `distance_from_plane`, `distance_from_axis`, `axis_value`
+- **Mesh utilities**: `grid_to_mesh()` (parametric grid triangulation), `vertices_to_mesh3d()` (vertices/faces to Plotly Mesh3d trace)
 
 ## Dependencies
 
 - **plotly**: Interactive 2D and 3D visualization
-- **matplotlib**: Static plot support
 - **numpy**: Array operations
-- **scipy**: Marching cubes mesh extraction
-- **scikit-image**: Additional mesh processing
 - **gri-utils**: Coordinate conversions and constants
 
 

{gri_plot-0.2.3 → gri_plot-0.2.5}/README.md

@@ -6,7 +6,7 @@
 
 ## Overview
 
-This library renders implicit surfaces (TDOA hyperboloids, FDOA iso-Doppler surfaces, AOA cones, range spheres, terrain) and geometric shapes (ellipsoids, spheres, cones, cylinders) as interactive 3D meshes. It also provides shorthand functions for 2D scatter plots and geographic maps.
+This library renders parametric geometric shapes (ellipsoids, spheres, cones, cylinders) and observable surfaces that inherit from them (AOA cones, line-of-sight rays, range spheres) as interactive 3D meshes. It also provides shorthand functions for 2D scatter plots and geographic maps.
 
 ## Installation
 
@@ -61,14 +61,12 @@ Scene builder for composing 3D visualizations from multiple surfaces and points:
 - **`add_surface()`**: Add any `ImplicitShape` (shapes or observables)
 - **`add_points()`**: Add labeled scatter points
 - **`add_line()`**: Add line segments connecting points
-- **`add_intersection()`**: Highlight where multiple surfaces intersect
 - **`plot_surfaces()`**: Convenience function for quick multi-surface plots
 - Method chaining, automatic color cycling from D3 palette, `plotly_dark` template
 
 ```python
 from gri_plot import Figure3D
 from gri_plot.shapes import Sphere
-from gri_plot.observables import TdoaSurface
 import numpy as np
 
 fig = Figure3D()
@@ -88,7 +86,7 @@ Coordinate frame handling for 3D display:
 
 ## Shapes
 
-Geometric primitives implementing the `ImplicitShape` ABC. Each supports parametric mesh generation (fast, exact geometry) and implicit residual evaluation (for intersection calculations).
+Geometric primitives implementing the `ImplicitShape` ABC. Each supports parametric mesh generation (fast, exact geometry) and implicit residual evaluation.
 
 - **Ellipsoid**: From center + covariance matrix, or center + semi-axes + rotation matrix
 - **Sphere**: From center + radius
@@ -98,31 +96,23 @@ Geometric primitives implementing the `ImplicitShape` ABC. Each supports paramet
 
 ## Observables
 
-Geolocation-specific surfaces for visualizing measurement iso-surfaces. Some inherit from shapes (reusing parametric rendering), others use marching cubes for mesh extraction.
+Geolocation-specific surfaces that inherit from parametric shapes:
 
-- **TdoaSurface**: TDOA hyperboloid where range_1 - range_2 = c x tdoa, from two collector positions + time difference
-- **FdoaSurface**: FDOA iso-Doppler surface from two collector positions/velocities + carrier frequency + frequency difference
 - **AoaSurface**: AOA cone (extends Cone) from collector position + measured direction + angular error
 - **LosSurface**: Line of sight ray (extends Cylinder) from start point + direction + length; also provides `to_line_trace()` for simple line rendering
 - **RangeSphere**: Range/TOA sphere (extends Sphere) from collector position + range measurement
-- **TerrainSurface**: Terrain from XYZ vertex grid with interpolated residual evaluation; factory methods `from_xyz_grids()` and `from_elevation_grid()`
 
 ## Surfaces
 
-Low-level infrastructure for implicit surface rendering:
+Low-level infrastructure for shape rendering:
 
 - **ImplicitShape ABC**: Interface requiring `residual_fn()`, `get_bounds_xyz()`, `to_mesh()`, `to_trace()`, `is_volume`, `label`; also provides `contains()` for point-in-shape testing
-- **Mesh utilities**: `field_to_mesh()` (marching cubes with Newton-Raphson surface projection and adaptive refinement), `grid_to_mesh()` (parametric grid triangulation), `vertices_to_mesh3d()` (vertices/faces to Plotly Mesh3d trace)
-- **IntersectionField**: Euclidean distance in residual space for highlighting multi-surface intersections; distinguishes volumes (interior contribution) from surfaces (boundary contribution)
-- **Gradient functions**: Intensity calculators for mesh coloring -- `distance_from_point`, `distance_from_line`, `distance_from_line_segment`, `distance_from_plane`, `distance_from_axis`, `axis_value`
+- **Mesh utilities**: `grid_to_mesh()` (parametric grid triangulation), `vertices_to_mesh3d()` (vertices/faces to Plotly Mesh3d trace)
 
 ## Dependencies
 
 - **plotly**: Interactive 2D and 3D visualization
-- **matplotlib**: Static plot support
 - **numpy**: Array operations
-- **scipy**: Marching cubes mesh extraction
-- **scikit-image**: Additional mesh processing
 - **gri-utils**: Coordinate conversions and constants
 
 

{gri_plot-0.2.3 → gri_plot-0.2.5}/gri_plot/__init__.py

@@ -1,21 +1,22 @@
 """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.
+including scatter plots, geographic maps, and parametric 3D shapes 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
+    - observables: Parametric geolocation surfaces (AOA, LOS, Range)
+    - surfaces: ImplicitShape ABC and mesh trace utilities
     - frames: Coordinate frame handling
 """
 
 # 2D plotting
 # 3D plotting infrastructure
+from .basemap import BasemapStyle, add_offline_basemap
 from .figure3d import DEFAULT_COLORS, Figure3D, plot_surfaces
 from .figure_map import FigureMap, MapStyle
 from .frames import Bounds, Frame, FrameTransformer
@@ -23,13 +24,11 @@ from .frames import Bounds, Frame, FrameTransformer
 # Observables
 from .observables import (
     AoaSurface,
-    FdoaSurface,
     LosSurface,
     RangeSphere,
-    TdoaSurface,
-    TerrainSurface,
 )
 from .plot_ellipse import plot_ellipse
+from .polylines import split_at_antimeridian
 from .scatter import scatter
 from .scatter_map import scatter_map
 
@@ -45,25 +44,17 @@ from .surfaces import (
     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
+from .surfaces.mesh import grid_to_mesh, vertices_to_mesh3d
 
 __all__ = [
     "DEFAULT_COLORS",
     "AoaSurface",
+    "BasemapStyle",
     "Bounds",
     "Cone",
     "Cylinder",
     "Ellipse",
     "Ellipsoid",
-    "FdoaSurface",
     "Figure3D",
     "FigureMap",
     "Frame",
@@ -73,19 +64,11 @@ __all__ = [
     "MapStyle",
     "RangeSphere",
     "Sphere",
-    "TdoaSurface",
-    "TerrainSurface",
-    "axis_value",
+    "add_offline_basemap",
     "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",
@@ -93,5 +76,6 @@ __all__ = [
     "scatter",
     "scatter_map",
     "sphere_mesh",
+    "split_at_antimeridian",
     "vertices_to_mesh3d",
 ]

gri_plot-0.2.5/gri_plot/_heatmap_image.py

@@ -0,0 +1,132 @@
+"""PNG heatmap image generation for map-figure overlays.
+
+Plotly's ``Scattermap`` cannot host a ``go.Heatmap`` trace because heatmaps
+live in a Cartesian plot area, not a map. The workaround this module
+implements is to encode the scalar field as an RGBA PNG (base64 data URI)
+and add it to ``layout.map.layers`` as an ``sourcetype="image"`` entry.
+
+The work this module does:
+
+* colorscale sampling into a 256-entry lookup table;
+* a Mercator pre-resample of the lat axis so the image aligns with the
+  basemap at non-equatorial latitudes (the image-layer is stretched
+  linearly in Mercator y; our grid is linear in geodetic latitude);
+* a Gaussian blur on the alpha channel so the footprint mask's hard
+  per-cell edges fade smoothly at the boundary.
+
+All functions here are private helpers for ``FigureMap.add_heatmap_image``.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import math
+from typing import TYPE_CHECKING
+
+import numpy as np
+import plotly.colors as pc
+from PIL import Image, ImageFilter
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+LUT_SIZE = 256
+
+
+def _colorscale_lut(name: str, n: int = LUT_SIZE) -> NDArray[np.uint8]:
+    """Sample a named Plotly colorscale into an (n, 3) uint8 RGB lookup table."""
+    samples = pc.sample_colorscale(name, np.linspace(0.0, 1.0, n))
+    rows = [
+        [int(c) for c in s.removeprefix("rgb(").rstrip(")").split(",")] for s in samples
+    ]
+    return np.array(rows, dtype=np.uint8)
+
+
+def _mercator_remap(
+    values: NDArray[np.floating],
+    lat_axis: NDArray[np.floating],
+) -> NDArray[np.floating]:
+    """Resample a (M, N) grid so rows are linearly spaced in Mercator y.
+
+    The input ``values`` are assumed to be on a grid whose row i has
+    latitude ``lat_axis[i]`` in degrees (linear in geodetic latitude).
+    Returns an array of the same shape whose row i corresponds to a
+    latitude linearly spaced in Mercator y between the endpoints of
+    ``lat_axis``. This is what the Plotly image layer expects when its
+    ``coordinates`` corners are geodetic lat/lon.
+    """
+    m = len(lat_axis)
+    y_min = math.log(math.tan(math.pi / 4.0 + math.radians(float(lat_axis[0])) / 2.0))
+    y_max = math.log(math.tan(math.pi / 4.0 + math.radians(float(lat_axis[-1])) / 2.0))
+    target_y = np.linspace(y_min, y_max, m)
+    target_lat = np.degrees(2.0 * (np.arctan(np.exp(target_y)) - math.pi / 4.0))
+    src_idx = np.interp(target_lat, lat_axis, np.arange(m, dtype=np.float64))
+    src_lo = np.floor(src_idx).astype(np.int64)
+    src_hi = np.minimum(src_lo + 1, m - 1)
+    frac = (src_idx - src_lo)[:, None]
+    return (1.0 - frac) * values[src_lo] + frac * values[src_hi]
+
+
+def values_to_png_data_uri(  # noqa: PLR0913
+    values: NDArray[np.floating],
+    lat_axis: NDArray[np.floating],
+    colorscale: str,
+    *,
+    alpha: float,
+    symmetric: bool,
+    blur_px: float,
+    value_range: tuple[float, float] | None,
+) -> tuple[str, float, float]:
+    """Render a lat/lon-gridded scalar field to a PNG data URI.
+
+    Args:
+        values: Scalar field, shape (M, N). NaN cells are rendered
+            transparent.
+        lat_axis: Latitude per row in degrees, shape (M,). Used both to
+            pick the input-row colormap and to Mercator-resample before
+            encoding.
+        colorscale: Plotly colorscale name.
+        alpha: Opacity (0-1) for finite cells.
+        symmetric: When True and the values span zero, expand the color
+            range to be symmetric about zero. Useful for diverging
+            colorscales on signed fields (TDOA-dot).
+        blur_px: Gaussian blur radius (pixels) applied to the alpha
+            channel only. Softens the per-cell stair-step at the mask
+            edge without blurring the color data. Set to 0 to disable.
+        value_range: Explicit (vmin, vmax) override. Takes precedence
+            over ``symmetric`` and the implicit min/max.
+
+    Returns:
+        Tuple of (data URI string, vmin, vmax).
+    """
+    v = np.asarray(values, dtype=np.float64)
+    if value_range is not None:
+        vmin, vmax = value_range
+    else:
+        vmin, vmax = float(np.nanmin(v)), float(np.nanmax(v))
+        if symmetric and vmin < 0.0 < vmax:
+            vabs = max(abs(vmin), abs(vmax))
+            vmin, vmax = -vabs, vabs
+
+    v_remap = _mercator_remap(v, np.asarray(lat_axis, dtype=np.float64))
+    finite = np.isfinite(v_remap)
+    v_safe = np.where(finite, v_remap, vmin)
+    denom = vmax - vmin if vmax > vmin else 1.0
+    norm = np.clip((v_safe - vmin) / denom, 0.0, 1.0)
+    idx = (norm * (LUT_SIZE - 1)).astype(np.int32)
+
+    rgb = _colorscale_lut(colorscale)[idx]
+    a = np.where(finite, int(alpha * 255), 0).astype(np.uint8)
+    rgba = np.dstack([rgb, a])[::-1, :, :]  # flip rows so lat increases upward
+
+    img = Image.fromarray(rgba, mode="RGBA")
+    if blur_px > 0:
+        r_ch, g_ch, b_ch, a_ch = img.split()
+        a_ch = a_ch.filter(ImageFilter.GaussianBlur(radius=blur_px))
+        img = Image.merge("RGBA", (r_ch, g_ch, b_ch, a_ch))
+
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    uri = "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode("ascii")
+    return uri, vmin, vmax