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

{gri_plot-0.2.4 → 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.4 → gri_plot-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gri-plot
-Version: 0.2.4
+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,6 +19,7 @@ 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
 Description-Content-Type: text/markdown
 

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

@@ -16,6 +16,7 @@ Main components:
 
 # 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
@@ -27,6 +28,7 @@ from .observables import (
     RangeSphere,
 )
 from .plot_ellipse import plot_ellipse
+from .polylines import split_at_antimeridian
 from .scatter import scatter
 from .scatter_map import scatter_map
 
@@ -47,6 +49,7 @@ from .surfaces.mesh import grid_to_mesh, vertices_to_mesh3d
 __all__ = [
     "DEFAULT_COLORS",
     "AoaSurface",
+    "BasemapStyle",
     "Bounds",
     "Cone",
     "Cylinder",
@@ -61,6 +64,7 @@ __all__ = [
     "MapStyle",
     "RangeSphere",
     "Sphere",
+    "add_offline_basemap",
     "cone_mesh",
     "cylinder_mesh",
     "ellipsoid_mesh",
@@ -72,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

gri_plot-0.2.5/gri_plot/basemap.py

@@ -0,0 +1,307 @@
+"""Offline Natural Earth basemap for Plotly figures.
+
+Provides political boundaries (admin-0 countries, admin-1 states/provinces)
+from bundled Natural Earth data, with no network access at render time.
+Intended as a fallback for environments where online tile providers (CARTO,
+ArcGIS, OSM) are unreachable.
+
+Example::
+
+    import plotly.graph_objects as go
+    from gri_plot import add_offline_basemap, BasemapStyle
+
+    fig = go.Figure()
+    fig.add_trace(go.Scattermap(lat=[40.7], lon=[-74.0], mode="markers"))
+    add_offline_basemap(fig, style=BasemapStyle.DARK)
+    fig.show()
+
+The bundled data lives in ``gri_plot/data/natural_earth_boundaries.npz`` and
+is generated by ``scripts/build_basemap_data.py``. Admin-0 is Natural Earth
+1:50m; admin-1 is 1:10m decimated via Douglas-Peucker for compactness.
+"""
+
+from __future__ import annotations
+
+import base64
+import enum
+import functools
+import io
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+import plotly.graph_objects as go
+from PIL import Image
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+_DATA_PATH = Path(__file__).parent / "data" / "natural_earth_boundaries.npz"
+SCATTERMAP = "scattermap"
+SCATTERGEO = "scattergeo"
+_VALID_BACKENDS = (SCATTERMAP, SCATTERGEO)
+
+
+class BasemapStyle(enum.Enum):
+    """Color style for the offline basemap.
+
+    The ``_COUNTRIES`` variants draw only admin-0 (country) boundaries for a
+    less busy look; the plain variants also draw admin-1 (state/province).
+
+    Attributes:
+        DARK: Dark background with light country + state borders.
+        LIGHT: Light background with dark country + state borders.
+        DARK_COUNTRIES: Dark background with country borders only.
+        LIGHT_COUNTRIES: Light background with country borders only.
+    """
+
+    DARK = "dark"
+    LIGHT = "light"
+    DARK_COUNTRIES = "dark_countries"
+    LIGHT_COUNTRIES = "light_countries"
+
+
+@dataclass(frozen=True)
+class _Palette:
+    """Color palette shared across a color family (dark or light)."""
+
+    background: str
+    admin0_color: str
+    admin1_color: str
+    admin0_width: float
+    admin1_width: float
+
+
+_DARK_PALETTE = _Palette(
+    background="#14181c",
+    admin0_color="rgba(140, 155, 170, 0.55)",
+    admin1_color="rgba(90, 100, 115, 0.35)",
+    admin0_width=0.8,
+    admin1_width=0.4,
+)
+
+_LIGHT_PALETTE = _Palette(
+    background="#f2f2f2",
+    admin0_color="rgba(40, 40, 40, 0.75)",
+    admin1_color="rgba(110, 110, 110, 0.45)",
+    admin0_width=0.8,
+    admin1_width=0.4,
+)
+
+# Map each style to (palette, include_admin1). Decoupling lets the color
+# family and the "detail level" vary independently.
+_STYLE_SPEC: dict[BasemapStyle, tuple[_Palette, bool]] = {
+    BasemapStyle.DARK: (_DARK_PALETTE, True),
+    BasemapStyle.LIGHT: (_LIGHT_PALETTE, True),
+    BasemapStyle.DARK_COUNTRIES: (_DARK_PALETTE, False),
+    BasemapStyle.LIGHT_COUNTRIES: (_LIGHT_PALETTE, False),
+}
+
+
+@functools.lru_cache(maxsize=1)
+def _load_boundaries() -> dict[str, NDArray[np.float32]]:
+    """Load bundled Natural Earth boundary arrays from NPZ.
+
+    Cached so repeated calls share one in-memory copy.
+
+    Returns:
+        Mapping of array names (admin0_lon, admin0_lat, admin1_lon,
+        admin1_lat) to float32 arrays with NaN separators between rings.
+
+    Raises:
+        FileNotFoundError: If the bundled NPZ is missing from the wheel.
+    """
+    if not _DATA_PATH.is_file():
+        msg = (
+            f"offline basemap data not found at {_DATA_PATH}; regenerate with "
+            "scripts/build_basemap_data.py"
+        )
+        raise FileNotFoundError(msg)
+    with np.load(_DATA_PATH) as data:
+        return {k: data[k].copy() for k in data.files}
+
+
+@functools.lru_cache(maxsize=8)
+def _solid_color_png_data_uri(hex_color: str) -> str:
+    """Encode a 1x1 solid-color PNG as a base64 data URI.
+
+    Used as the "background" pseudo-tile under Scattermap figures, since
+    Plotly has no offline dark map_style.
+
+    Args:
+        hex_color: Color as ``#RRGGBB``.
+
+    Returns:
+        A ``data:image/png;base64,...`` URI.
+    """
+    h = hex_color.lstrip("#")
+    rgb = (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+    buf = io.BytesIO()
+    Image.new("RGB", (1, 1), rgb).save(buf, format="PNG")
+    return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def _world_fill_layer(hex_color: str) -> dict:
+    """Build a Plotly map image layer that fills the world with a solid color.
+
+    Mercator projections clip near the poles; we extend slightly beyond the
+    safe bound so there is no sliver of default white visible at high latitudes.
+    """
+    return {
+        "below": "traces",
+        "sourcetype": "image",
+        "source": _solid_color_png_data_uri(hex_color),
+        "coordinates": [
+            [-180.0, 89.0],
+            [180.0, 89.0],
+            [180.0, -89.0],
+            [-180.0, -89.0],
+        ],
+    }
+
+
+def _make_boundary_trace(  # noqa: PLR0913
+    lon: NDArray[np.float32],
+    lat: NDArray[np.float32],
+    *,
+    color: str,
+    width: float,
+    backend: str,
+    name: str,
+) -> go.Scattermap | go.Scattergeo:
+    """Build a single boundary polyline trace for the chosen backend."""
+    kwargs = {
+        "lon": lon,
+        "lat": lat,
+        "mode": "lines",
+        "line": {"color": color, "width": width},
+        "hoverinfo": "skip",
+        "showlegend": False,
+        "name": name,
+    }
+    if backend == SCATTERGEO:
+        return go.Scattergeo(**kwargs)
+    return go.Scattermap(**kwargs)
+
+
+def add_offline_basemap(  # noqa: PLR0913
+    fig: go.Figure,
+    *,
+    style: BasemapStyle = BasemapStyle.DARK,
+    backend: str = SCATTERMAP,
+    admin0_color: str | None = None,
+    admin1_color: str | None = None,
+    admin0_width: float | None = None,
+    admin1_width: float | None = None,
+) -> go.Figure:
+    """Add offline Natural Earth boundaries to a Plotly figure in-place.
+
+    Inserts admin-1 (state/province) then admin-0 (country) border traces
+    at the front of ``fig.data`` so any existing data traces render above
+    the basemap. For the Scattermap backend, also installs a solid-color
+    world image layer to provide the background color (Plotly's built-in
+    dark map styles require online tile access).
+
+    Args:
+        fig: Target figure; modified in place.
+        style: Color style (see :class:`BasemapStyle`). Determines the
+            background color and the palette defaults for border colors and
+            widths.
+        backend: Which Plotly trace family to use. Must match the traces
+            already on ``fig``: use ``"scattermap"`` for Scattermap-based
+            figures, ``"scattergeo"`` for Scattergeo-based figures.
+        admin0_color: Override the style's default country border color.
+            Any Plotly color string (``"#rrggbb"``, ``"rgba(r, g, b, a)"``,
+            named color). ``None`` uses the style default.
+        admin1_color: Override the style's default state/province border
+            color. Ignored when ``style`` is a ``*_COUNTRIES`` variant since
+            admin-1 is not drawn in that case.
+        admin0_width: Override the country border line width in pixels.
+        admin1_width: Override the state/province border line width.
+
+    Returns:
+        The same figure, for chaining.
+
+    Raises:
+        ValueError: If backend is not recognized.
+        FileNotFoundError: If the bundled basemap NPZ is missing.
+    """
+    if backend not in _VALID_BACKENDS:
+        msg = f"backend must be one of {_VALID_BACKENDS}, got {backend!r}"
+        raise ValueError(msg)
+
+    data = _load_boundaries()
+    palette, include_admin1 = _STYLE_SPEC[style]
+    a0_color = admin0_color if admin0_color is not None else palette.admin0_color
+    a1_color = admin1_color if admin1_color is not None else palette.admin1_color
+    a0_width = admin0_width if admin0_width is not None else palette.admin0_width
+    a1_width = admin1_width if admin1_width is not None else palette.admin1_width
+
+    # admin-1 first so admin-0 draws on top for emphasis at shared borders.
+    border_traces: list[go.Scattermap | go.Scattergeo] = []
+    if include_admin1:
+        border_traces.append(
+            _make_boundary_trace(
+                data["admin1_lon"],
+                data["admin1_lat"],
+                color=a1_color,
+                width=a1_width,
+                backend=backend,
+                name="basemap_admin1",
+            ),
+        )
+    border_traces.append(
+        _make_boundary_trace(
+            data["admin0_lon"],
+            data["admin0_lat"],
+            color=a0_color,
+            width=a0_width,
+            backend=backend,
+            name="basemap_admin0",
+        ),
+    )
+
+    # Append then reorder so basemap renders under any existing traces.
+    # Plotly only permits fig.data reassignment for permutations of itself,
+    # so we add first and then permute.
+    n_existing = len(fig.data)
+    fig.add_traces(border_traces)
+    n_borders = len(border_traces)
+    new_order = (
+        *range(n_existing, n_existing + n_borders),
+        *range(n_existing),
+    )
+    fig.data = tuple(fig.data[i] for i in new_order)
+
+    if backend == SCATTERMAP:
+        existing_layers = list(fig.layout.map.layers or [])
+        fig.update_layout(map_style="white-bg")
+        # Direct assignment rather than update_layout(map_layers=...); the
+        # latter does an element-wise merge with the existing tuple, which
+        # turns any pre-existing layer (e.g. an add_heatmap_image overlay)
+        # at index 0 into a mash-up of itself and the new world_fill.
+        fig.layout.map.layers = (
+            _world_fill_layer(palette.background),
+            *existing_layers,
+        )
+    else:
+        fig.update_layout(
+            geo={
+                "bgcolor": palette.background,
+                "showland": False,
+                "showocean": False,
+                "showcoastlines": False,
+                "showcountries": False,
+                "showsubunits": False,
+                "showframe": False,
+            },
+        )
+    return fig
+
+
+__all__ = [
+    "BasemapStyle",
+    "add_offline_basemap",
+]

{gri_plot-0.2.4 → gri_plot-0.2.5}/gri_plot/figure3d.py

@@ -217,7 +217,7 @@ class Figure3D:
         }
 
         if labels:
-            trace_kwargs["text"] = list(labels)
+            trace_kwargs["text"] = list(labels)  # ty: ignore[invalid-assignment]
             trace_kwargs["textposition"] = "top center"
 
         trace_kwargs.update(kwargs)
@@ -267,7 +267,7 @@ class Figure3D:
 
         if name is not None:
             trace_kwargs["name"] = name
-            trace_kwargs["showlegend"] = True
+            trace_kwargs["showlegend"] = True  # ty: ignore[invalid-assignment]
 
         trace_kwargs.update(kwargs)
         self._traces.append(go.Scatter3d(**trace_kwargs))