isolines 0.1.0__py3-none-any.whl

isolines/__init__.py

@@ -0,0 +1,74 @@
+"""isolines: contour lines and filled contours (isobands) from grids and points.
+
+Quick start::
+
+    import numpy as np
+    import isolines
+
+    yy, xx = np.mgrid[0:50, 0:50]
+    z = np.hypot(xx - 25, yy - 25)              # a cone
+    lines = isolines.contour_lines(z, [5, 10, 15])
+    bands = isolines.isobands(z, [0, 5, 10, 15])
+    isolines.write_geojson("contours.geojson", lines + bands)
+"""
+
+from ._version import __version__
+from .contours import ContourLine, IsoBand, contour_lines, format_label, isobands
+from .geometry import (
+    assemble_polygons,
+    chaikin,
+    douglas_peucker,
+    line_length,
+    orient_polygon,
+    point_in_ring,
+    signed_area,
+    validate_polygon,
+)
+from .interpolate import GridSpec, idw, linear, nearest, points_to_grid
+from .io import (
+    Raster,
+    load_grid,
+    read_ascii_grid,
+    read_points_csv,
+    read_raster,
+    to_geojson,
+    write_ascii_grid,
+    write_geojson,
+)
+from .levels import interval_levels, nice_interval, nice_levels
+from .transform import GeoTransform, as_geotransform
+
+__all__ = [
+    "__version__",
+    "ContourLine",
+    "IsoBand",
+    "contour_lines",
+    "isobands",
+    "format_label",
+    "GeoTransform",
+    "as_geotransform",
+    "interval_levels",
+    "nice_interval",
+    "nice_levels",
+    "GridSpec",
+    "idw",
+    "nearest",
+    "linear",
+    "points_to_grid",
+    "Raster",
+    "load_grid",
+    "read_ascii_grid",
+    "write_ascii_grid",
+    "read_raster",
+    "read_points_csv",
+    "to_geojson",
+    "write_geojson",
+    "signed_area",
+    "line_length",
+    "point_in_ring",
+    "chaikin",
+    "douglas_peucker",
+    "assemble_polygons",
+    "orient_polygon",
+    "validate_polygon",
+]

isolines/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

isolines/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

isolines/cli.py

@@ -0,0 +1,172 @@
+"""Command-line interface: ``isolines lines|bands|grid``."""
+
+from __future__ import annotations
+
+import argparse
+import math
+import sys
+from typing import List, Optional, Sequence
+
+import numpy as np
+
+from ._version import __version__
+from .contours import contour_lines, isobands
+from .interpolate import points_to_grid
+from .io import Raster, load_grid, read_points_csv, write_ascii_grid, write_geojson
+from .levels import interval_levels, nice_levels
+
+
+def _floats(text: str) -> List[float]:
+    out = []
+    for part in text.split(","):
+        part = part.strip().lower()
+        if part in ("-inf", "inf", "+inf"):
+            out.append(float(part))
+        elif part:
+            out.append(float(part))
+    return out
+
+
+def _add_input(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "input",
+        help="grid (.asc, .npy, or any raster via the 'raster' extra) or a point CSV (.csv)",
+    )
+    p.add_argument("--band", type=int, default=1, help="raster band (default 1)")
+    p.add_argument("--nodata", type=float, help="extra no-data value")
+    g = p.add_argument_group("point CSV input")
+    g.add_argument("--x-col", default="x")
+    g.add_argument("--y-col", default="y")
+    g.add_argument("--value-col", default="value")
+    g.add_argument("--cell-size", type=float, help="grid cell size for point input")
+    g.add_argument("--method", choices=["idw", "nearest", "linear"], default="idw")
+    g.add_argument("--power", type=float, default=2.0, help="IDW power (default 2)")
+    g.add_argument("--radius", type=float, help="IDW search radius / nearest max distance")
+    g.add_argument("--margin", type=float, default=0.0, help="grid margin around the points")
+
+
+def _load(args: argparse.Namespace) -> Raster:
+    if str(args.input).lower().endswith(".csv"):
+        if not args.cell_size:
+            raise SystemExit("point CSV input needs --cell-size")
+        x, y, v = read_points_csv(args.input, args.x_col, args.y_col, args.value_col)
+        kwargs = {}
+        if args.method == "idw":
+            kwargs = {"power": args.power, "radius": args.radius}
+        elif args.method == "nearest":
+            kwargs = {"max_distance": args.radius}
+        z, gt = points_to_grid(
+            x, y, v, args.cell_size, method=args.method, margin=args.margin, **kwargs
+        )
+        return Raster(z, gt)
+    return load_grid(args.input, args.band)
+
+
+def _add_output(p: argparse.ArgumentParser) -> None:
+    p.add_argument("-o", "--output", required=True, help="output GeoJSON path")
+    p.add_argument("--smooth", type=int, default=0, help="Chaikin iterations (default 0)")
+    p.add_argument("--simplify", type=float, default=0.0, help="Douglas-Peucker tolerance")
+    p.add_argument("--precision", type=int, help="round coordinates to N decimals")
+    p.add_argument("--label-format", default="{:g}", help="label pattern (default {:g})")
+
+
+def _levels(args: argparse.Namespace, z: np.ndarray, attr: str) -> List[float]:
+    explicit = getattr(args, attr)
+    if explicit:
+        return _floats(explicit)
+    finite = z[np.isfinite(z)]
+    if finite.size == 0:
+        return []
+    if args.interval:
+        return interval_levels(float(finite.min()), float(finite.max()), args.interval, args.base)
+    return nice_levels(finite)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="isolines",
+        description="Contour lines and filled contours (isobands) as GeoJSON.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_lines = sub.add_parser("lines", help="contour lines (LineString features)")
+    _add_input(p_lines)
+    p_lines.add_argument("--levels", help="comma-separated levels")
+    p_lines.add_argument("--interval", type=float, help="contour interval")
+    p_lines.add_argument("--base", type=float, default=0.0, help="interval offset (default 0)")
+    p_lines.add_argument("--min-length", type=float, default=0.0, help="drop shorter lines")
+    _add_output(p_lines)
+
+    p_bands = sub.add_parser("bands", help="filled contours (MultiPolygon features)")
+    _add_input(p_bands)
+    p_bands.add_argument("--breaks", help="comma-separated band limits; -inf/inf allowed")
+    p_bands.add_argument("--interval", type=float, help="band width")
+    p_bands.add_argument("--base", type=float, default=0.0, help="interval offset (default 0)")
+    p_bands.add_argument(
+        "--open-ends",
+        action="store_true",
+        help="add -inf and inf so values outside the breaks are covered too",
+    )
+    p_bands.add_argument("--min-area", type=float, default=0.0, help="drop smaller rings")
+    _add_output(p_bands)
+
+    p_grid = sub.add_parser("grid", help="interpolate a point CSV to an Esri ASCII grid")
+    p_grid.add_argument("input", help="point CSV")
+    p_grid.add_argument("-o", "--output", required=True, help="output .asc path")
+    p_grid.add_argument("--x-col", default="x")
+    p_grid.add_argument("--y-col", default="y")
+    p_grid.add_argument("--value-col", default="value")
+    p_grid.add_argument("--cell-size", type=float, required=True)
+    p_grid.add_argument("--method", choices=["idw", "nearest", "linear"], default="idw")
+    p_grid.add_argument("--power", type=float, default=2.0)
+    p_grid.add_argument("--radius", type=float)
+    p_grid.add_argument("--margin", type=float, default=0.0)
+    p_grid.add_argument("--band", type=int, default=1, help=argparse.SUPPRESS)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        raster = _load(args)
+        if args.command == "grid":
+            assert raster.transform is not None
+            write_ascii_grid(args.output, raster.z, raster.transform)
+            print(f"wrote {raster.z.shape[0]} x {raster.z.shape[1]} grid to {args.output}")
+            return 0
+        common = {
+            "transform": raster.transform,
+            "nodata": args.nodata,
+            "smooth": args.smooth,
+            "simplify": args.simplify,
+            "label_format": args.label_format,
+        }
+        if args.command == "lines":
+            levels = _levels(args, raster.z, "levels")
+            items: list = (
+                contour_lines(raster.z, levels, min_length=args.min_length, **common)
+                if levels
+                else []
+            )
+            kind = "lines"
+        else:
+            breaks = _levels(args, raster.z, "breaks")
+            if args.open_ends:
+                breaks = sorted(set(breaks) | {-math.inf, math.inf})
+            if len(breaks) < 2:
+                raise ValueError("need at least two breaks (try --open-ends)")
+            items = isobands(raster.z, breaks, min_area=args.min_area, **common)
+            kind = "bands"
+        write_geojson(args.output, items, precision=args.precision)
+        print(f"wrote {len(items)} {kind} to {args.output}")
+        if raster.crs:
+            print(f"coordinates are in {raster.crs}")
+        return 0
+    except (OSError, ValueError, ImportError) as exc:
+        print(f"isolines: error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

isolines/contours.py

@@ -0,0 +1,342 @@
+"""Public contouring API: contour lines and filled contours (isobands)."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+
+from .geometry import (
+    assemble_polygons,
+    chaikin,
+    dedupe,
+    douglas_peucker,
+    line_length,
+    orient_polygon,
+    signed_area,
+)
+from .marching import Key, MarchingGrid, chain_rings, chain_segments
+from .transform import GeoTransform, as_geotransform
+
+__all__ = ["ContourLine", "IsoBand", "contour_lines", "isobands", "format_label"]
+
+ArrayLike = Any
+Mapper = Callable[[np.ndarray], np.ndarray]
+# Rings smaller than this (in grid cells) only arise around single nodes that
+# lie exactly on a level (see marching.T_EPS) and are dropped.
+_DEGENERATE = 1e-5
+
+
+def format_label(value: Optional[float], label_format: str = "{:g}") -> str:
+    """Format a level for a label; infinite or missing values give ``""``."""
+    if value is None or not math.isfinite(value):
+        return ""
+    return label_format.format(value)
+
+
+def _json_number(value: float) -> Optional[float]:
+    return float(value) if math.isfinite(value) else None
+
+
+def _round(coords: np.ndarray, precision: Optional[int]) -> list:
+    arr = coords if precision is None else np.round(coords, precision)
+    out: list = arr.tolist()
+    return out
+
+
+@dataclass
+class ContourLine:
+    """One continuous contour line.
+
+    ``coords`` is an ``(n, 2)`` array in output coordinates. Lines are
+    oriented with higher values on the left. ``closed`` lines repeat their
+    first position at the end.
+    """
+
+    level: float
+    coords: np.ndarray
+    closed: bool
+    label: str = ""
+
+    @property
+    def length(self) -> float:
+        """Polyline length in output units."""
+        return line_length(self.coords)
+
+    def to_feature(self, precision: Optional[int] = None) -> Dict[str, Any]:
+        """GeoJSON ``Feature`` with a ``LineString`` geometry."""
+        return {
+            "type": "Feature",
+            "geometry": {"type": "LineString", "coordinates": _round(self.coords, precision)},
+            "properties": {
+                "level": float(self.level),
+                "label": self.label,
+                "closed": self.closed,
+                "length": self.length,
+            },
+        }
+
+
+@dataclass
+class IsoBand:
+    """All polygons where ``lower <= z < upper``.
+
+    ``polygons`` is a list of polygons; each polygon is a list of closed rings,
+    exterior first (counter-clockwise) then holes (clockwise), following
+    RFC 7946 section 3.1.6.
+    """
+
+    lower: float
+    upper: float
+    polygons: List[List[np.ndarray]] = field(default_factory=list)
+    label: str = ""
+
+    @property
+    def area(self) -> float:
+        """Total area (exteriors minus holes) in squared output units."""
+        return float(
+            sum(
+                abs(signed_area(r)) * (1 if i == 0 else -1)
+                for poly in self.polygons
+                for i, r in enumerate(poly)
+            )
+        )
+
+    def to_feature(self, precision: Optional[int] = None) -> Dict[str, Any]:
+        """GeoJSON ``Feature`` with a ``MultiPolygon`` geometry."""
+        return {
+            "type": "Feature",
+            "geometry": {
+                "type": "MultiPolygon",
+                "coordinates": [[_round(r, precision) for r in poly] for poly in self.polygons],
+            },
+            "properties": {
+                "lower": _json_number(self.lower),
+                "upper": _json_number(self.upper),
+                "label": self.label,
+                "area": self.area,
+            },
+        }
+
+
+# --------------------------------------------------------------------- helpers
+def _prepare(z: ArrayLike, nodata: Optional[float]) -> np.ndarray:
+    if np.ma.isMaskedArray(z):
+        arr = np.ma.filled(np.ma.asarray(z).astype(float), np.nan)
+    else:
+        arr = np.array(z, dtype=float, copy=True)
+    if nodata is not None and not (isinstance(nodata, float) and math.isnan(nodata)):
+        arr[arr == nodata] = np.nan
+    arr[~np.isfinite(arr)] = np.nan
+    return arr
+
+
+def _make_mapper(
+    shape: Tuple[int, int],
+    x: Optional[ArrayLike],
+    y: Optional[ArrayLike],
+    transform: Optional[Union[GeoTransform, Sequence[float], Any]],
+    pixel_is_area: bool,
+) -> Mapper:
+    nrows, ncols = shape
+    if transform is not None:
+        if x is not None or y is not None:
+            raise ValueError("give either transform or x/y coordinates, not both")
+        gt = as_geotransform(transform)
+        off = 0.5 if pixel_is_area else 0.0
+
+        def map_gt(pts: np.ndarray) -> np.ndarray:
+            wx, wy = gt.apply(pts[:, 0] + off, pts[:, 1] + off)
+            return np.column_stack([wx, wy])
+
+        return map_gt
+    xs = np.arange(ncols, dtype=float) if x is None else np.asarray(x, dtype=float)
+    ys = np.arange(nrows, dtype=float) if y is None else np.asarray(y, dtype=float)
+    if xs.shape != (ncols,) or ys.shape != (nrows,):
+        raise ValueError(f"x must have {ncols} values and y {nrows} values (one per column/row)")
+    for name, v in (("x", xs), ("y", ys)):
+        d = np.diff(v)
+        if not (np.all(d > 0) or np.all(d < 0)):
+            raise ValueError(f"{name} coordinates must be strictly monotonic")
+    cols = np.arange(ncols, dtype=float)
+    rows = np.arange(nrows, dtype=float)
+
+    def map_xy(pts: np.ndarray) -> np.ndarray:
+        return np.column_stack([np.interp(pts[:, 0], cols, xs), np.interp(pts[:, 1], rows, ys)])
+
+    return map_xy
+
+
+def _orientation(mapper: Mapper) -> float:
+    p = mapper(np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0]]))
+    return float(
+        (p[1, 0] - p[0, 0]) * (p[2, 1] - p[0, 1]) - (p[1, 1] - p[0, 1]) * (p[2, 0] - p[0, 0])
+    )
+
+
+def _levels(levels: Union[float, Sequence[float], np.ndarray], allow_inf: bool) -> List[float]:
+    vals = np.atleast_1d(np.asarray(levels, dtype=float))
+    if np.isnan(vals).any():
+        raise ValueError("levels must not contain NaN")
+    if not allow_inf and not np.isfinite(vals).all():
+        raise ValueError("contour levels must be finite")
+    return sorted({float(v) for v in vals})
+
+
+# ------------------------------------------------------------------------ API
+def contour_lines(
+    z: ArrayLike,
+    levels: Union[float, Sequence[float], np.ndarray],
+    *,
+    x: Optional[ArrayLike] = None,
+    y: Optional[ArrayLike] = None,
+    transform: Optional[Any] = None,
+    nodata: Optional[float] = None,
+    pixel_is_area: bool = True,
+    smooth: int = 0,
+    simplify: float = 0.0,
+    min_length: float = 0.0,
+    label_format: str = "{:g}",
+) -> List[ContourLine]:
+    """Extract contour lines from a 2-D grid with marching squares.
+
+    Parameters
+    ----------
+    z:
+        2-D array, ``z[row, col]``. NaN, infinities, masked values and
+        ``nodata`` are treated as no-data; lines stop at no-data cells.
+    levels:
+        One level or a sequence of levels (sorted and de-duplicated).
+    x, y:
+        Optional 1-D, strictly monotonic coordinates of the columns and rows.
+    transform:
+        Optional affine georeferencing: a :class:`GeoTransform`, a GDAL
+        6-tuple or a rasterio ``Affine``. With ``pixel_is_area=True``
+        (default, GDAL/rasterio convention) the value of ``z[i, j]`` is placed
+        at the centre of pixel ``(i, j)``. Without ``x``/``y``/``transform``,
+        output coordinates are ``(col, row)`` indices.
+    smooth:
+        Number of Chaikin smoothing iterations (0 = off).
+    simplify:
+        Douglas-Peucker tolerance in output units (0 = off).
+    min_length:
+        Drop lines shorter than this (output units).
+    label_format:
+        ``str.format`` pattern for the ``label`` attribute.
+
+    Returns
+    -------
+    list of :class:`ContourLine`, ordered by level, oriented with higher
+    values on the left; lines touching the grid or no-data edge are open,
+    others closed.
+    """
+    arr = _prepare(z, nodata)
+    lv = _levels(levels, allow_inf=False)
+    grid = MarchingGrid(arr)
+    mapper = _make_mapper(arr.shape, x, y, transform, pixel_is_area)
+    flip = _orientation(mapper) < 0
+    out: List[ContourLine] = []
+    for k, level in enumerate(lv):
+        segs = grid.level_segments(k, level)
+        if not segs:
+            continue
+        for keys, closed in chain_segments(segs):
+            idx_pts = grid.key_coords(keys, lv)
+            if closed and np.ptp(idx_pts, axis=0).max() < _DEGENERATE:
+                continue  # ring around a single node lying exactly on the level
+            pts = dedupe(mapper(idx_pts))
+            if flip:
+                pts = pts[::-1].copy()
+            if smooth:
+                pts = chaikin(pts, smooth, closed)
+            if simplify:
+                pts = douglas_peucker(pts, simplify, closed)
+            if len(pts) < 2 or (closed and len(pts) < 4):
+                continue
+            line = ContourLine(level, pts, closed, format_label(level, label_format))
+            if min_length and line.length < min_length:
+                continue
+            out.append(line)
+    return out
+
+
+def isobands(
+    z: ArrayLike,
+    breaks: Union[Sequence[float], np.ndarray],
+    *,
+    x: Optional[ArrayLike] = None,
+    y: Optional[ArrayLike] = None,
+    transform: Optional[Any] = None,
+    nodata: Optional[float] = None,
+    pixel_is_area: bool = True,
+    smooth: int = 0,
+    simplify: float = 0.0,
+    min_area: float = 0.0,
+    keep_empty: bool = False,
+    label_format: str = "{:g}",
+) -> List[IsoBand]:
+    """Filled contours: polygons with holes for each band ``[b_k, b_(k+1))``.
+
+    ``breaks`` are the band limits (at least two; ``-inf``/``inf`` allowed for
+    open-ended bands). Band boundaries are the oriented marching-squares
+    contours of the two limits plus the edge of the valid (non-no-data) grid
+    domain, so the bands of all intervals tile the valid domain without gaps
+    or overlaps. Polygons are returned with RFC 7946 orientation (exterior
+    counter-clockwise, holes clockwise) in output coordinates.
+
+    ``smooth`` and ``simplify`` are applied ring by ring; they are not
+    topology-preserving, so neighbouring bands may then slightly overlap.
+    Other parameters as in :func:`contour_lines`. Rings with an area
+    ``<= min_area`` (squared output units) are dropped.
+    """
+    arr = _prepare(z, nodata)
+    b = _levels(breaks, allow_inf=True)
+    if len(b) < 2:
+        raise ValueError("isobands needs at least two distinct breaks")
+    grid = MarchingGrid(arr)
+    mapper = _make_mapper(arr.shape, x, y, transform, pixel_is_area)
+    out: List[IsoBand] = []
+    for k in range(len(b) - 1):
+        lo, hi = b[k], b[k + 1]
+        segs = grid.band_segments(k, lo, k + 1, hi)
+        polygons: List[List[np.ndarray]] = []
+        if segs:
+            keys: List[Key] = list({key for seg in segs for key in seg})
+            xy = grid.key_coords(keys, b)
+            coords_of = {key: (float(p[0]), float(p[1])) for key, p in zip(keys, xy)}
+            rings_idx = []
+            for ring in chain_rings(segs, coords_of):
+                pts = dedupe(np.array([coords_of[key] for key in ring]))
+                if len(pts) >= 4:
+                    rings_idx.append(pts)
+            for poly in assemble_polygons(rings_idx, min_area=_DEGENERATE**2):
+                world: List[np.ndarray] = []
+                for ring_no, wring in enumerate(orient_polygon([mapper(r) for r in poly])):
+                    r = dedupe(wring)
+                    if smooth:
+                        r = chaikin(r, smooth, closed=True)
+                    if simplify:
+                        r = douglas_peucker(r, simplify, closed=True)
+                    if len(r) < 4 or abs(signed_area(r)) <= min_area:
+                        if ring_no == 0:
+                            break
+                        continue
+                    world.append(r)
+                if world:
+                    polygons.append(orient_polygon(world))
+        if polygons or keep_empty:
+            label = (
+                format_label(lo, label_format) + "–" + format_label(hi, label_format)
+                if math.isfinite(lo) and math.isfinite(hi)
+                else (
+                    f"< {format_label(hi, label_format)}"
+                    if math.isfinite(hi)
+                    else f">= {format_label(lo, label_format)}"
+                    if math.isfinite(lo)
+                    else "all"
+                )
+            )
+            out.append(IsoBand(lo, hi, polygons, label))
+    return out