zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/classify.py

@@ -0,0 +1,379 @@
+"""Colour ramps and classification for analysis results.
+
+Equal-interval, quantile and Fisher-Jenks natural breaks, categories by
+frequency, and the colour ramps used by the plugin's viewer.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Iterable, Optional, Sequence
+
+__all__ = [
+    "QUALITATIVE",
+    "RAMPS",
+    "RAMP_LABELS",
+    "breaks_for",
+    "categories",
+    "class_of",
+    "equal_breaks",
+    "fmt",
+    "hex_to_rgb",
+    "jenks_breaks",
+    "quantile_breaks",
+    "ramp_color",
+    "ramp_stops",
+    "rgb_to_hex",
+]
+
+RAMPS: dict[str, list[str]] = {
+    "viridis": [
+        "#440154",
+        "#482878",
+        "#3e4989",
+        "#31688e",
+        "#26828e",
+        "#1f9e89",
+        "#35b779",
+        "#6ece58",
+        "#b5de2b",
+        "#fde725",
+    ],
+    "magma": [
+        "#000004",
+        "#1c1044",
+        "#4f127b",
+        "#812581",
+        "#b5367a",
+        "#e55964",
+        "#fb8761",
+        "#fec287",
+        "#fcfdbf",
+    ],
+    "inferno": [
+        "#000004",
+        "#1f0c48",
+        "#550f6d",
+        "#88226a",
+        "#ba3655",
+        "#e35933",
+        "#f98e09",
+        "#f9cb35",
+        "#fcffa4",
+    ],
+    "rdylbu": [
+        "#a50026",
+        "#d73027",
+        "#f46d43",
+        "#fdae61",
+        "#fee090",
+        "#ffffbf",
+        "#e0f3f8",
+        "#abd9e9",
+        "#74add1",
+        "#4575b4",
+        "#313695",
+    ],
+    "spectral": [
+        "#9e0142",
+        "#d53e4f",
+        "#f46d43",
+        "#fdae61",
+        "#fee08b",
+        "#ffffbf",
+        "#e6f598",
+        "#abdda4",
+        "#66c2a5",
+        "#3288bd",
+        "#5e4fa2",
+    ],
+    "rdbu": [
+        "#67001f",
+        "#b2182b",
+        "#d6604d",
+        "#f4a582",
+        "#fddbc7",
+        "#f7f7f7",
+        "#d1e5f0",
+        "#92c5de",
+        "#4393c3",
+        "#2166ac",
+        "#053061",
+    ],
+    "blues": [
+        "#f7fbff",
+        "#deebf7",
+        "#c6dbef",
+        "#9ecae1",
+        "#6baed6",
+        "#4292c6",
+        "#2171b5",
+        "#08519c",
+        "#08306b",
+    ],
+    "reds": [
+        "#fff5f0",
+        "#fee0d2",
+        "#fcbba1",
+        "#fc9272",
+        "#fb6a4a",
+        "#ef3b2c",
+        "#cb181d",
+        "#a50f15",
+        "#67000d",
+    ],
+    "greens": [
+        "#f7fcf5",
+        "#e5f5e0",
+        "#c7e9c0",
+        "#a1d99b",
+        "#74c476",
+        "#41ab5d",
+        "#238b45",
+        "#006d2c",
+        "#00441b",
+    ],
+    "terrain": [
+        "#2b6b3f",
+        "#5f9a4f",
+        "#a8c47a",
+        "#e9dfa3",
+        "#d2b47c",
+        "#a47b55",
+        "#8a7a72",
+        "#f2f2f2",
+    ],
+    "greys": [
+        "#000000",
+        "#262626",
+        "#4d4d4d",
+        "#737373",
+        "#969696",
+        "#bdbdbd",
+        "#d9d9d9",
+        "#f0f0f0",
+        "#ffffff",
+    ],
+}
+QUALITATIVE: list[str] = [
+    "#4e79a7",
+    "#f28e2b",
+    "#e15759",
+    "#76b7b2",
+    "#59a14f",
+    "#edc948",
+    "#b07aa1",
+    "#ff9da7",
+    "#9c755f",
+    "#bab0ac",
+    "#1f77b4",
+    "#ff7f0e",
+    "#2ca02c",
+    "#d62728",
+    "#9467bd",
+    "#8c564b",
+    "#e377c2",
+    "#7f7f7f",
+    "#bcbd22",
+    "#17becf",
+]
+RAMP_LABELS: dict[str, str] = {
+    "viridis": "Viridis",
+    "magma": "Magma",
+    "inferno": "Inferno",
+    "rdylbu": "Red-Yellow-Blue",
+    "spectral": "Spectral",
+    "rdbu": "Red-Blue",
+    "blues": "Blues",
+    "reds": "Reds",
+    "greens": "Greens",
+    "terrain": "Terrain",
+    "greys": "Greys",
+}
+
+
+def hex_to_rgb(hex_color: Optional[str]) -> list[float]:
+    """``'#rrggbb'`` (or ``'#rgb'``) to ``[r, g, b]`` in ``0..1``."""
+    h = str(hex_color or "#cccccc").replace("#", "")
+    if len(h) == 3:
+        h = "".join(ch + ch for ch in h)
+    try:
+        v = int(h[:6], 16)
+    except ValueError:
+        v = 0
+    return [((v >> 16) & 255) / 255, ((v >> 8) & 255) / 255, (v & 255) / 255]
+
+
+def _round_half_up(x: float) -> int:
+    return int(math.floor(x + 0.5))
+
+
+def rgb_to_hex(rgb: Sequence[float]) -> str:
+    """``[r, g, b]`` in ``0..1`` to ``'#rrggbb'``."""
+    return "#" + "".join(f"{_round_half_up(max(0.0, min(1.0, x)) * 255):02x}" for x in rgb[:3])
+
+
+def ramp_stops(name: str) -> list[list[float]]:
+    """Ramp stops as RGB triples; a name ending in ``-r`` is reversed."""
+    name = str(name)
+    reversed_ = name.endswith("-r")
+    key = name[:-2] if reversed_ else name
+    stops = [hex_to_rgb(h) for h in RAMPS.get(key, RAMPS["viridis"])]
+    return stops[::-1] if reversed_ else stops
+
+
+def ramp_color(stops: Sequence[Sequence[float]], t: float) -> list[float]:
+    """Colour at ``t`` in ``[0, 1]`` along a ramp (stops from :func:`ramp_stops`)."""
+    tt = t if isinstance(t, (int, float)) and math.isfinite(t) else 0.0
+    v = max(0.0, min(1.0, tt)) * (len(stops) - 1)
+    i = min(len(stops) - 2, int(math.floor(v)))
+    f = v - i
+    return [stops[i][k] + (stops[i + 1][k] - stops[i][k]) * f for k in range(3)]
+
+
+def _to_float(v: Any) -> Optional[float]:
+    if v is None or v == "":
+        return None
+    try:
+        x = float(v)
+    except (TypeError, ValueError):
+        return None
+    return x if math.isfinite(x) else None
+
+
+def _finite_sorted(values: Iterable[Any]) -> list[float]:
+    out = [x for x in (_to_float(v) for v in values) if x is not None]
+    return sorted(out)
+
+
+def equal_breaks(values: Iterable[Any], k: int) -> list[float]:
+    """``k`` equal-interval classes: ``k + 1`` break values."""
+    s = _finite_sorted(values)
+    if not s:
+        return []
+    lo, hi = s[0], s[-1]
+    return [lo + ((hi - lo) * i) / k for i in range(k + 1)]
+
+
+def quantile_breaks(values: Iterable[Any], k: int) -> list[float]:
+    """``k`` quantile classes: ``k + 1`` break values."""
+    s = _finite_sorted(values)
+    if not s:
+        return []
+    out = [s[0]]
+    for i in range(1, k):
+        out.append(s[min(len(s) - 1, (i * len(s)) // k)])
+    out.append(s[-1])
+    return out
+
+
+def jenks_breaks(values: Iterable[Any], k: int) -> list[float]:
+    """Fisher-Jenks natural breaks on at most 3000 sampled values."""
+    full = _finite_sorted(values)
+    s = full
+    if not s:
+        return []
+    if len(s) > 3000:
+        step = len(s) / 3000
+        s = [full[int(math.floor(i * step))] for i in range(3000)]
+        s.append(full[-1])
+    n = len(s)
+    k = max(1, min(k, len(set(s))))
+    inf = math.inf
+    lower = [[0] * (k + 1) for _ in range(n + 1)]
+    variance = [[inf] * (k + 1) for _ in range(n + 1)]
+    for j in range(1, k + 1):
+        lower[1][j] = 1
+        variance[1][j] = 0.0
+    for l_ in range(2, n + 1):
+        total = 0.0
+        total_sq = 0.0
+        w = 0
+        v = 0.0
+        var_l = variance[l_]
+        low_l = lower[l_]
+        for m in range(1, l_ + 1):
+            i3 = l_ - m + 1
+            val = s[i3 - 1]
+            w += 1
+            total += val
+            total_sq += val * val
+            v = total_sq - (total * total) / w
+            i4 = i3 - 1
+            if i4 != 0:
+                var_i4 = variance[i4]
+                for j in range(2, k + 1):
+                    cand = v + var_i4[j - 1]
+                    if var_l[j] >= cand:
+                        low_l[j] = i3
+                        var_l[j] = cand
+        low_l[1] = 1
+        var_l[1] = v
+    breaks = [0.0] * (k + 1)
+    breaks[k] = s[n - 1]
+    breaks[0] = s[0]
+    idx = n
+    for j in range(k, 1, -1):
+        ident = lower[idx][j] - 2
+        breaks[j - 1] = s[max(0, ident)]
+        idx = lower[idx][j] - 1
+    return breaks
+
+
+def breaks_for(method: str, values: Iterable[Any], k: int) -> list[float]:
+    """Breaks by ``method``: ``'quantile'``, ``'jenks'`` or equal interval (default)."""
+    if method == "quantile":
+        return quantile_breaks(values, k)
+    if method == "jenks":
+        return jenks_breaks(values, k)
+    return equal_breaks(values, k)
+
+
+def class_of(value: Any, breaks: Sequence[float]) -> int:
+    """Class index ``0..k-1`` of a value for breaks ``[b0..bk]``, or ``-1``."""
+    v = _to_float(value)
+    if v is None or len(breaks) < 2:
+        return -1
+    for i in range(1, len(breaks) - 1):
+        if v < breaks[i]:
+            return i - 1
+    return len(breaks) - 2
+
+
+def _key(v: Any) -> str:
+    if v is None or v == "":
+        return "(empty)"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, float) and v.is_integer():
+        return str(int(v))
+    return str(v)
+
+
+def categories(values: Iterable[Any], limit: int = 20) -> list[dict[str, Any]]:
+    """Distinct values by frequency, most common first (at most ``limit``)."""
+    counts: dict[str, int] = {}
+    for v in values:
+        key = _key(v)
+        counts[key] = counts.get(key, 0) + 1
+    ordered = sorted(counts.items(), key=lambda kv: -kv[1])[:limit]
+    return [{"value": value, "count": count} for value, count in ordered]
+
+
+def fmt(v: Any, unit: str = "") -> str:
+    """Short number formatting for legends (``'–'`` for non-finite values)."""
+    if not isinstance(v, (int, float)) or isinstance(v, bool) or not math.isfinite(v):
+        return "–"
+    if float(v).is_integer():
+        s = f"{int(v):,}"
+    else:
+        a = abs(v)
+        if a >= 1000:
+            s = f"{_round_half_up(v):,}"
+        elif a >= 100:
+            s = f"{v:.0f}"
+        elif a >= 10:
+            s = f"{v:.1f}"
+        else:
+            s = f"{v:.2f}"
+    return f"{s} {unit}" if unit else s