itinera 0.6.0__py3-none-any.whl

itinera/__init__.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""Itinera — anisotropic least-cost path / corridor / FETE primitives.
+
+Pure numpy/scipy, no QGIS and no GDAL. Kept GUI-free so it is unit-testable
+outside QGIS and reused by both the Processing algorithms and the interactive
+map tool. Published to PyPI this is the importable package ``itinera``; inside
+the QGIS plugin it is the private ``core`` package.
+
+Note: ``raster_io`` (GDAL) is intentionally NOT re-exported here, so importing
+this package never pulls in ``osgeo``. The plugin imports ``raster_io`` directly
+where it needs raster I/O.
+"""
+
+from .cost_functions import (
+    tobler, tobler_offpath, herzog, naismith, llobera_sluckin,
+)
+from .conductance import (
+    build_conductance, build_conductance_friction,
+    rowcol_to_node, node_to_rowcol,
+)
+from .lcp import accumulated_cost, least_cost_path
+from .corridor import corridor, corridor_band
+from .fete import fete
+from .validation import pdi
+from .stochastic import (
+    stochastic_lcp, add_dem_error, add_global_stochasticity,
+)
+from .grid_align import (
+    xy_to_rowcol,
+    check_regular_geotransform, assert_regular_geotransform,
+    check_grids_aligned, assert_grids_aligned,
+)
+from .memory import estimate_conductance_bytes, format_bytes
+from .resample import block_reduce_mean
+
+__all__ = [
+    # cost functions
+    "tobler", "tobler_offpath", "herzog", "naismith", "llobera_sluckin",
+    # conductance
+    "build_conductance", "build_conductance_friction",
+    "rowcol_to_node", "node_to_rowcol",
+    # paths
+    "accumulated_cost", "least_cost_path",
+    "corridor", "corridor_band",
+    "fete",
+    # validation
+    "pdi",
+    # stochastic
+    "stochastic_lcp", "add_dem_error", "add_global_stochasticity",
+    # grid / alignment
+    "xy_to_rowcol",
+    "check_regular_geotransform", "assert_regular_geotransform",
+    "check_grids_aligned", "assert_grids_aligned",
+    # memory / resample
+    "estimate_conductance_bytes", "format_bytes",
+    "block_reduce_mean",
+]

itinera/conductance.py

@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+"""Build a sparse anisotropic conductance (cost) matrix from a DEM.
+
+The graph has one node per raster cell. Edges connect each cell to its
+neighbours (4, 8, 16 or 32 connectivity). Edge weight = cost of moving from
+cell A to cell B, evaluated with a directional cost function, so the matrix is
+asymmetric (true anisotropy).
+
+NoData cells are excluded: any edge touching a masked cell is dropped, so they
+become unreachable rather than infinitely cheap.
+"""
+
+import numpy as np
+from scipy.sparse import csr_matrix
+
+
+# Neighbour offset sets. 16/32 use knight-style moves to reduce the
+# "metric distortion" of grid-restricted paths (Llobera-style).
+_OFFSETS = {
+    4: [(-1, 0), (1, 0), (0, -1), (0, 1)],
+    8: [(-1, 0), (1, 0), (0, -1), (0, 1),
+        (-1, -1), (-1, 1), (1, -1), (1, 1)],
+    16: [(-1, 0), (1, 0), (0, -1), (0, 1),
+         (-1, -1), (-1, 1), (1, -1), (1, 1),
+         (-2, -1), (-2, 1), (2, -1), (2, 1),
+         (-1, -2), (-1, 2), (1, -2), (1, 2)],
+}
+
+
+def _edge_blocks(rows, cols, cellsize, neighbours):
+    """Yield (a_idx, b_idx, sl_a, sl_b, dist) for each neighbour offset.
+
+    Shared scaffolding for the conductance builders. ``a_idx``/``b_idx`` are the
+    flat node-index arrays for the two ends of every edge in the block; ``sl_a``
+    /``sl_b`` are the matching ``(slice, slice)`` tuples so callers can slice
+    their own rasters (DEM, friction, NoData mask); ``dist`` is the edge length
+    in metres.
+    """
+    if neighbours not in _OFFSETS:
+        raise ValueError("neighbours must be one of 4, 8, 16")
+
+    idx = np.arange(rows * cols).reshape(rows, cols)
+
+    for dr, dc in _OFFSETS[neighbours]:
+        r0, r1 = max(0, -dr), rows - max(0, dr)
+        c0, c1 = max(0, -dc), cols - max(0, dc)
+
+        sl_a = (slice(r0, r1), slice(c0, c1))
+        sl_b = (slice(r0 + dr, r1 + dr), slice(c0 + dc, c1 + dc))
+
+        dist = cellsize * np.hypot(dr, dc)
+        yield idx[sl_a], idx[sl_b], sl_a, sl_b, dist
+
+
+def build_conductance(dem, cellsize, cost_fn, neighbours=8, nodata_mask=None,
+                      multiplier=None):
+    """Return (matrix, n_rows, n_cols).
+
+    Parameters
+    ----------
+    dem : 2D float ndarray (elevations, metres)
+    cellsize : float (metres per pixel; assumes square pixels)
+    cost_fn : callable(slope, distance) -> cost
+    neighbours : 4, 8 or 16
+    nodata_mask : optional bool 2D ndarray, True where data is invalid
+    multiplier : optional 2D float ndarray (same shape as dem). A per-cell
+        barrier / conductance multiplier applied to the slope cost:
+        edge cost *= mean(multiplier_A, multiplier_B). Values > 1 discourage,
+        values < 1 prefer (e.g. known roads). Cells that are NoData or <= 0 are
+        impassable — every edge touching them is dropped (e.g. cliffs, deep
+        wadis).
+    """
+    rows, cols = dem.shape
+    n = rows * cols
+
+    if nodata_mask is None:
+        nodata_mask = ~np.isfinite(dem)
+
+    if multiplier is not None:
+        if multiplier.shape != dem.shape:
+            raise ValueError("multiplier and dem must have the same shape")
+        mult_invalid = ~np.isfinite(multiplier) | (multiplier <= 0)
+
+    src_all, dst_all, w_all = [], [], []
+
+    for a_idx, b_idx, sl_a, sl_b, dist in _edge_blocks(
+            rows, cols, cellsize, neighbours):
+        slope = (dem[sl_b] - dem[sl_a]) / dist   # directional slope A -> B
+        cost = cost_fn(slope, dist)
+
+        # Drop edges touching NoData on either end.
+        valid = ~(nodata_mask[sl_a] | nodata_mask[sl_b])
+
+        if multiplier is not None:
+            cost = cost * (0.5 * (multiplier[sl_a] + multiplier[sl_b]))
+            valid &= ~(mult_invalid[sl_a] | mult_invalid[sl_b])
+
+        valid &= np.isfinite(cost)
+
+        src_all.append(a_idx[valid])
+        dst_all.append(b_idx[valid])
+        w_all.append(cost[valid])
+
+    src = np.concatenate(src_all)
+    dst = np.concatenate(dst_all)
+    w = np.concatenate(w_all)
+
+    matrix = csr_matrix((w, (src, dst)), shape=(n, n))
+    return matrix, rows, cols
+
+
+def build_conductance_friction(friction, cellsize, neighbours=8,
+                               dem=None, cost_fn=None,
+                               friction_nodata_mask=None):
+    """Build a cost matrix from a friction raster (cost per metre).
+
+    Two modes:
+
+    * **Isotropic** (``dem is None``): edge cost =
+      ``mean(friction_A, friction_B) * distance``. Friction is read as a
+      cost-per-metre, so the matrix is symmetric — correct for a genuinely
+      isotropic surface (this is *not* a forbidden symmetrisation of a slope
+      matrix; see CLAUDE.md constraint 3).
+    * **Combined** (``dem`` and ``cost_fn`` supplied): edge cost =
+      ``mean(friction_A, friction_B) * cost_fn(slope, distance)``. Friction
+      acts as a dimensionless multiplier (1.0 = neutral, >1 harder, <1
+      preferred) on the anisotropic slope cost, so the matrix stays asymmetric.
+
+    Parameters
+    ----------
+    friction : 2D float ndarray (cost per metre, or a multiplier with a DEM)
+    cellsize : float (metres per pixel; assumes square pixels)
+    neighbours : 4, 8 or 16
+    dem : optional 2D float ndarray (elevations, metres), same shape as friction
+    cost_fn : callable(slope, distance) -> cost; required when dem is given
+    friction_nodata_mask : optional bool 2D ndarray, True where invalid
+
+    Returns
+    -------
+    (matrix, n_rows, n_cols)
+    """
+    rows, cols = friction.shape
+    n = rows * cols
+
+    if dem is not None:
+        if dem.shape != friction.shape:
+            raise ValueError("dem and friction must have the same shape")
+        if cost_fn is None:
+            raise ValueError("cost_fn is required when a dem is supplied")
+
+    # Non-positive or non-finite friction is impassable (edge dropped).
+    if friction_nodata_mask is None:
+        friction_nodata_mask = ~np.isfinite(friction) | (friction <= 0)
+    dem_nodata_mask = (~np.isfinite(dem)) if dem is not None else None
+
+    src_all, dst_all, w_all = [], [], []
+
+    for a_idx, b_idx, sl_a, sl_b, dist in _edge_blocks(
+            rows, cols, cellsize, neighbours):
+        fric = 0.5 * (friction[sl_a] + friction[sl_b])
+
+        if dem is None:
+            cost = fric * dist
+        else:
+            slope = (dem[sl_b] - dem[sl_a]) / dist
+            cost = fric * cost_fn(slope, dist)
+
+        valid = ~(friction_nodata_mask[sl_a] | friction_nodata_mask[sl_b])
+        if dem_nodata_mask is not None:
+            valid &= ~(dem_nodata_mask[sl_a] | dem_nodata_mask[sl_b])
+        valid &= np.isfinite(cost)
+
+        src_all.append(a_idx[valid])
+        dst_all.append(b_idx[valid])
+        w_all.append(cost[valid])
+
+    src = np.concatenate(src_all)
+    dst = np.concatenate(dst_all)
+    w = np.concatenate(w_all)
+
+    matrix = csr_matrix((w, (src, dst)), shape=(n, n))
+    return matrix, rows, cols
+
+
+def rowcol_to_node(row, col, n_cols):
+    return row * n_cols + col
+
+
+def node_to_rowcol(node, n_cols):
+    return divmod(node, n_cols)

itinera/corridor.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""Least-cost corridor (LCC).
+
+A corridor is the sum of two accumulated-cost surfaces: one grown from the
+origin, one from the destination. The minimum of that sum traces the optimal
+path; values close to the minimum delineate a band of near-optimal routes
+(Verhagen 2013). Useful when a single line over-states the precision of the
+reconstruction.
+"""
+
+import numpy as np
+from .lcp import accumulated_cost
+
+
+def corridor(matrix, origin, destination):
+    """Return the corridor surface (1D, length = n nodes) and its minimum.
+
+    corridor[i] = cost(origin -> i) + cost(i -> destination via reversed graph)
+    The second term is computed on the transpose, because moving *towards* the
+    destination on an anisotropic surface is the reverse of moving *away* from
+    it.
+    """
+    from_origin = accumulated_cost(matrix, [origin])
+    # Reverse the graph so the second surface measures cost *into* destination.
+    to_dest = accumulated_cost(matrix.transpose().tocsr(), [destination])
+
+    surface = from_origin + to_dest
+    finite = surface[np.isfinite(surface)]
+    minimum = float(finite.min()) if finite.size else np.inf
+    return surface, minimum
+
+
+def corridor_band(surface, minimum, tolerance):
+    """Boolean mask of cells within `tolerance` (absolute cost) of optimum."""
+    return np.isfinite(surface) & (surface <= minimum + tolerance)

itinera/cost_functions.py

@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+"""Anisotropic cost functions.
+
+Each function receives the *directional* slope (dz / horizontal_distance,
+i.e. rise over run, signed: positive = uphill in direction of travel) and the
+horizontal distance between the two cell centres in metres. It returns the
+*cost* of traversing that edge (time in seconds, or an abstract cost).
+
+Because slope is directional, A->B and B->A yield different costs => true
+anisotropy. This is the central difference from isotropic MCP approaches.
+"""
+
+import numpy as np
+
+# Small epsilon to avoid division by zero in speed-based functions.
+_EPS = 1e-9
+
+
+def tobler(slope, distance):
+    """Tobler's Hiking Function (1993).
+
+    Walking speed v (km/h) = 6 * exp(-3.5 * |slope + 0.05|), where slope is
+    dh/dx (tan of the angle). Cost returned is travel time in seconds.
+    The +0.05 offset makes the maximum speed occur on a gentle downhill,
+    which is why this is genuinely anisotropic.
+    """
+    speed_kmh = 6.0 * np.exp(-3.5 * np.abs(slope + 0.05))
+    speed_ms = speed_kmh * 1000.0 / 3600.0
+    return distance / (speed_ms + _EPS)
+
+
+def tobler_offpath(slope, distance):
+    """Tobler off-path variant: speed reduced to 0.6 of on-path."""
+    speed_kmh = 0.6 * 6.0 * np.exp(-3.5 * np.abs(slope + 0.05))
+    speed_ms = speed_kmh * 1000.0 / 3600.0
+    return distance / (speed_ms + _EPS)
+
+
+def herzog(slope, distance):
+    """Herzog (2013) metabolic cost function for wheeled/pedestrian movement.
+
+    A symmetric-ish polynomial in slope (here s = dh/dx as a fraction).
+    Returns an abstract metabolic cost scaled by distance.
+    """
+    s = slope
+    # Herzog's sixth-order polynomial (cost per metre), normalised so that
+    # flat ground ~ 1.0.
+    cost_per_m = (1337.8 * s**6 + 278.19 * s**5 - 517.39 * s**4
+                  - 78.199 * s**3 + 93.419 * s**2 + 19.825 * s + 1.64)
+    cost_per_m = np.clip(cost_per_m, _EPS, None)
+    return cost_per_m * distance
+
+
+def naismith(slope, distance):
+    """Naismith's rule (1892) as a time cost.
+
+    Base walking 5 km/h on the flat, plus extra time for ascent. Descent is
+    treated as flat in the classic rule (anisotropic on the uphill side only).
+    """
+    base_ms = 5.0 * 1000.0 / 3600.0
+    horiz_time = distance / base_ms
+    dz = slope * distance  # vertical change over this edge
+    ascent = np.where(dz > 0, dz, 0.0)
+    # Naismith: +1 hour per 600 m ascent => 6 s per metre of climb.
+    return horiz_time + ascent * 6.0
+
+
+def llobera_sluckin(slope, distance):
+    """Llobera & Sluckin (2007) metabolic energy expenditure (kcal-based)."""
+    s = slope
+    e = (2.635 + 17.37 * np.abs(s) + 42.37 * s**2
+         - 21.43 * s**3 + 14.93 * s**4)
+    e = np.clip(e, _EPS, None)
+    return e * distance
+
+
+# Registry consumed by the Processing algorithms (enum order matters for the
+# parameter dropdown, so keep this list stable).
+COST_FUNCTIONS = {
+    "tobler": tobler,
+    "tobler_offpath": tobler_offpath,
+    "herzog": herzog,
+    "naismith": naismith,
+    "llobera_sluckin": llobera_sluckin,
+}
+
+COST_FUNCTION_LABELS = [
+    "Tobler's Hiking Function",
+    "Tobler off-path",
+    "Herzog (metabolic)",
+    "Naismith's rule",
+    "Llobera & Sluckin",
+]
+
+COST_FUNCTION_KEYS = list(COST_FUNCTIONS.keys())

itinera/fete.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""From-Everywhere-To-Everywhere (FETE), White & Barber (2012).
+
+Compute least-cost paths between every pair of input points and accumulate how
+often each cell is traversed. High-traffic cells indicate "natural" movement
+corridors that emerge from the terrain rather than from any single O/D pair.
+"""
+
+import numpy as np
+from itertools import combinations
+from .lcp import least_cost_path
+
+
+def fete(matrix, nodes, n_cells, progress=None):
+    """Return a 1D traversal-frequency array (length = n_cells).
+
+    Parameters
+    ----------
+    matrix : sparse conductance matrix
+    nodes : list of node indices (the input points)
+    n_cells : total number of raster cells
+    progress : optional callable(fraction_0_to_1) for UI feedback
+    """
+    freq = np.zeros(n_cells, dtype=np.float64)
+    pairs = list(combinations(nodes, 2))
+    total = len(pairs)
+
+    for k, (a, b) in enumerate(pairs):
+        path, cost = least_cost_path(matrix, a, b)
+        for node in path:
+            freq[node] += 1.0
+        if progress and total:
+            progress((k + 1) / total)
+
+    return freq

itinera/grid_align.py

@@ -0,0 +1,80 @@
+# -*- coding: utf-8 -*-
+"""Geo-grid regularity and alignment checks — pure Python, no GDAL/QGIS.
+
+Kept GUI-free so it is unit-testable outside QGIS. ``RasterGrid`` (the GDAL
+layer in ``core/raster_io.py``) and the Processing algorithm wrappers call into
+these helpers to fail loudly on rasters that would otherwise produce silently
+wrong indices.
+
+A GDAL geotransform is the 6-tuple
+``(x_origin, pixel_width, row_rotation, y_origin, col_rotation, pixel_height)``.
+``RasterGrid.xy_to_rowcol`` and the slope/distance maths assume an axis-aligned
+(unrotated, north-up) grid with square pixels.
+"""
+
+import math
+
+# Relative tolerance (fraction of a pixel) for comparing origins / pixel sizes.
+_ALIGN_TOL = 1e-6
+# Squareness check is a little more lenient — real DEMs carry rounding noise.
+_SQUARE_TOL = 1e-3
+
+
+def xy_to_rowcol(gt, x, y):
+    """Map map coordinates (x, y) to integer (row, col) indices.
+
+    Uses ``math.floor`` (not ``int``) so coordinates just outside the raster to
+    the west or north map to -1, not 0 — ``int`` truncates toward zero and would
+    wrongly report such points as the first row/column (inside the grid).
+    Assumes a north-up, unrotated geotransform (``gt[2] == gt[4] == 0``).
+    """
+    col = math.floor((x - gt[0]) / gt[1])
+    row = math.floor((y - gt[3]) / gt[5])
+    return row, col
+
+
+def check_regular_geotransform(gt, square_tol=_SQUARE_TOL):
+    """Return ``(ok, reason)`` for an axis-aligned, square-pixel geotransform."""
+    if gt[2] != 0.0 or gt[4] != 0.0:
+        return False, "raster is rotated (geotransform rotation terms non-zero)"
+    px, py = abs(gt[1]), abs(gt[5])
+    if px == 0.0 or py == 0.0:
+        return False, "raster has a zero pixel dimension"
+    if abs(px - py) > square_tol * max(px, py):
+        return False, "raster pixels are not square (%.6g x %.6g)" % (px, py)
+    return True, ""
+
+
+def assert_regular_geotransform(gt, square_tol=_SQUARE_TOL):
+    """Raise ValueError unless the geotransform is north-up, unrotated, square."""
+    ok, reason = check_regular_geotransform(gt, square_tol)
+    if not ok:
+        raise ValueError(
+            "Unsupported raster: %s. Itinera assumes north-up, unrotated, "
+            "square pixels in a projected CRS (metres)." % reason)
+
+
+def check_grids_aligned(gt_a, shape_a, gt_b, shape_b, align_tol=_ALIGN_TOL):
+    """Return ``(ok, reason)``: same shape, origin and pixel size.
+
+    ``shape_*`` are ``(rows, cols)`` tuples; ``gt_*`` are GDAL 6-tuples.
+    """
+    if tuple(shape_a) != tuple(shape_b):
+        return False, ("raster sizes differ (%dx%d vs %dx%d)" % (
+            shape_a[0], shape_a[1], shape_b[0], shape_b[1]))
+    tol = align_tol * max(abs(gt_a[1]), abs(gt_a[5]), 1.0)
+    for i, name in ((0, "x-origin"), (1, "pixel width"),
+                    (3, "y-origin"), (5, "pixel height")):
+        if abs(gt_a[i] - gt_b[i]) > tol:
+            return False, "%s differs (%.10g vs %.10g)" % (name, gt_a[i], gt_b[i])
+    return True, ""
+
+
+def assert_grids_aligned(gt_a, shape_a, gt_b, shape_b, what,
+                         align_tol=_ALIGN_TOL):
+    """Raise ValueError unless grid B aligns with reference grid A."""
+    ok, reason = check_grids_aligned(gt_a, shape_a, gt_b, shape_b, align_tol)
+    if not ok:
+        raise ValueError(
+            "%s must share the same grid as the DEM (identical extent, "
+            "resolution and origin): %s." % (what, reason))

itinera/lcp.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""Least-cost path and accumulated-cost computation."""
+
+import numpy as np
+from scipy.sparse.csgraph import dijkstra
+
+
+def accumulated_cost(matrix, sources):
+    """Cumulative least-cost surface from one or more source nodes.
+
+    Returns a 1D array (length = n nodes) of minimum cost to reach each node
+    from the nearest source. Unreachable nodes are np.inf.
+    """
+    dist = dijkstra(matrix, directed=True, indices=sources, min_only=True)
+    return dist
+
+
+def least_cost_path(matrix, origin, destination):
+    """Return the node sequence of the cheapest path origin -> destination.
+
+    Uses Dijkstra with predecessor tracking. Returns (nodes, total_cost).
+    nodes is a list from origin to destination (inclusive); empty if no path.
+    """
+    dist, predecessors = dijkstra(
+        matrix, directed=True, indices=origin,
+        return_predecessors=True, min_only=False,
+    )
+    total = float(dist[destination])
+    if not np.isfinite(total):
+        return [], np.inf
+
+    # Walk predecessors back from destination to origin.
+    path = []
+    node = destination
+    guard = 0
+    max_steps = matrix.shape[0] + 1
+    while node != origin and node >= 0:
+        path.append(int(node))
+        node = int(predecessors[node])
+        guard += 1
+        if guard > max_steps:
+            return [], np.inf
+    path.append(int(origin))
+    path.reverse()
+    return path, total

itinera/memory.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+"""Rough memory estimates for the in-RAM conductance matrix.
+
+The whole graph is held in memory (one node per cell, up to ``neighbours``
+directed edges per cell), so large DEMs can exhaust RAM. These pure helpers let
+the algorithm wrappers warn before that happens and let users size a clip or a
+resample factor. Pure Python — unit-testable outside QGIS.
+"""
+
+# Soft threshold above which the wrappers warn the user (cells = rows * cols).
+# At 8-neighbour this is already ~1 GB of matrix + build temporaries; treat it
+# as "clip or resample first" rather than a hard limit.
+RECOMMENDED_MAX_CELLS = 4_000_000
+
+
+def estimate_conductance_bytes(rows, cols, neighbours):
+    """Estimate peak bytes to build the sparse conductance matrix.
+
+    Counts the CSR storage (float64 weights + int32 indices + int32 indptr) plus
+    the transient COO build arrays (int64 src/dst + float64 weights) that exist
+    during construction. An upper-ish estimate (border edges are not subtracted)
+    — meant for an order-of-magnitude warning, not exact accounting.
+    """
+    n_cells = rows * cols
+    n_edges = n_cells * neighbours          # upper bound (ignores borders)
+    csr = n_edges * (8 + 4) + (n_cells + 1) * 4
+    build = n_edges * (8 + 8 + 8)           # src + dst + weight temporaries
+    return csr + build
+
+
+def format_bytes(n):
+    """Human-readable byte count (e.g. '1.2 GB')."""
+    value = float(n)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if value < 1024.0 or unit == "TB":
+            return "%.1f %s" % (value, unit)
+        value /= 1024.0

itinera/resample.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""NoData-aware block-mean downsampling of a DEM (pure numpy).
+
+Reducing a DEM by an integer factor cuts the cell count (and therefore the
+conductance-matrix RAM) by ``factor**2`` — a simple way to fit a large DEM in
+memory when clipping is not an option. Block-mean is a reasonable elevation
+downsample; NoData (NaN) cells are ignored per block, and a fully-NoData block
+stays NaN.
+"""
+
+import numpy as np
+
+
+def block_reduce_mean(dem, factor):
+    """Return ``dem`` downsampled by an integer ``factor`` via block mean.
+
+    The array is trimmed to a whole multiple of ``factor`` in each dimension
+    (trailing rows/cols that don't fill a block are dropped). NaN is treated as
+    NoData and excluded from each block's mean; an all-NaN block yields NaN.
+    ``factor == 1`` returns the input unchanged.
+    """
+    if factor < 1:
+        raise ValueError("factor must be >= 1")
+    if factor == 1:
+        return dem
+
+    rows, cols = dem.shape
+    r2 = (rows // factor) * factor
+    c2 = (cols // factor) * factor
+    if r2 == 0 or c2 == 0:
+        raise ValueError("factor is larger than the DEM")
+
+    trimmed = dem[:r2, :c2]
+    mask = np.isfinite(trimmed)
+    vals = np.where(mask, trimmed, 0.0)
+
+    br, bc = r2 // factor, c2 // factor
+    s = vals.reshape(br, factor, bc, factor).sum(axis=(1, 3))
+    n = mask.reshape(br, factor, bc, factor).sum(axis=(1, 3))
+
+    out = np.full((br, bc), np.nan, dtype=np.float64)
+    nonzero = n > 0
+    out[nonzero] = s[nonzero] / n[nonzero]
+    return out

itinera/stochastic.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""Stochastic least-cost paths (Lewis 2021).
+
+Two sources of uncertainty are modelled and combined over N Monte-Carlo
+realisations to produce a *probabilistic corridor* — the fraction of iterations
+in which each cell lies on the least-cost path:
+
+* **DEM error** — a vertical-accuracy (RMSE) error field is added to the DEM
+  each iteration, so the slope (and therefore the cost surface) varies.
+* **Global stochasticity** — edges are randomly dropped each iteration, modelling
+  unmodelled local impassability.
+
+Both are pure numpy/scipy and reuse the deterministic core (`build_conductance`,
+`least_cost_path`), so there is no duplicated path logic.
+
+Note on the DEM-error model: ``leastcostpath`` (R) simulates spatially
+autocorrelated error with a variogram (gstat). Without that dependency we
+approximate it (Hunter & Goodchild 1997 style): white Gaussian noise smoothed
+with a Gaussian kernel whose sigma encodes the autocorrelation range, then
+rescaled so the field's standard deviation equals the target RMSE.
+"""
+
+import numpy as np
+from scipy.ndimage import gaussian_filter
+from scipy.sparse import csr_matrix
+
+from .conductance import build_conductance
+from .lcp import least_cost_path
+
+
+def add_dem_error(dem, rmse, autocorr_range, cellsize, rng):
+    """Return ``dem`` plus a spatially-correlated Gaussian error field.
+
+    Parameters
+    ----------
+    dem : 2D float ndarray (elevations, metres); NoData as NaN is preserved.
+    rmse : float, target vertical RMSE in metres (<= 0 returns ``dem`` unchanged).
+    autocorr_range : float, spatial autocorrelation range in metres (0 = white
+        noise, no smoothing).
+    cellsize : float, metres per pixel.
+    rng : numpy.random.Generator.
+    """
+    if rmse <= 0:
+        return dem
+
+    finite = np.isfinite(dem)
+    noise = rng.standard_normal(dem.shape)
+
+    sigma = (autocorr_range / cellsize) if (autocorr_range > 0 and cellsize) else 0.0
+    if sigma > 0:
+        noise = gaussian_filter(noise, sigma=sigma, mode="nearest")
+
+    # Rescale so the error over the valid area has standard deviation = rmse.
+    std = noise[finite].std() if finite.any() else 0.0
+    if std > 0:
+        noise = noise / std * rmse
+
+    out = dem.copy()
+    out[finite] = dem[finite] + noise[finite]
+    return out
+
+
+def add_global_stochasticity(matrix, drop_fraction, rng):
+    """Return a copy of ``matrix`` with a random fraction of edges removed.
+
+    Each directed edge is independently dropped with probability
+    ``drop_fraction`` (0 returns the matrix unchanged; 1 removes every edge).
+    Dropping edges can disconnect origin from destination in a given
+    realisation — that iteration then contributes no path, which is the intended
+    behaviour.
+    """
+    if drop_fraction <= 0:
+        return matrix
+    coo = matrix.tocoo(copy=False)
+    keep = rng.random(coo.data.shape[0]) >= drop_fraction
+    return csr_matrix(
+        (coo.data[keep], (coo.row[keep], coo.col[keep])), shape=coo.shape)
+
+
+def stochastic_lcp(dem, cellsize, cost_fn, origin, destinations, n_iter, rng,
+                   rmse=0.0, autocorr_range=0.0, drop_fraction=0.0,
+                   neighbours=8, multiplier=None, progress=None):
+    """Probabilistic least-cost corridor over N stochastic realisations.
+
+    Returns ``(prob, n_cells)`` where ``prob[i]`` is the fraction of the
+    ``n_iter`` realisations in which cell ``i`` lay on a least-cost path from
+    ``origin`` to any of ``destinations`` (a value in [0, 1]).
+
+    When ``rmse <= 0`` the conductance matrix is built once and reused (only edge
+    dropping varies); otherwise it is rebuilt each iteration on a freshly
+    perturbed DEM. ``progress`` is an optional callable(fraction_0_to_1).
+    """
+    if n_iter < 1:
+        raise ValueError("n_iter must be >= 1")
+
+    rows, cols = dem.shape
+    n_cells = rows * cols
+    if np.isscalar(destinations):
+        destinations = [destinations]
+
+    static_matrix = None
+    if rmse <= 0:
+        static_matrix, _, _ = build_conductance(
+            dem, cellsize, cost_fn, neighbours=neighbours, multiplier=multiplier)
+
+    freq = np.zeros(n_cells, dtype=np.float64)
+
+    for k in range(n_iter):
+        if static_matrix is None:
+            dem_k = add_dem_error(dem, rmse, autocorr_range, cellsize, rng)
+            matrix = build_conductance(
+                dem_k, cellsize, cost_fn,
+                neighbours=neighbours, multiplier=multiplier)[0]
+        else:
+            matrix = static_matrix
+
+        if drop_fraction > 0:
+            matrix = add_global_stochasticity(matrix, drop_fraction, rng)
+
+        on_path = np.zeros(n_cells, dtype=bool)
+        for dest in destinations:
+            nodes, _ = least_cost_path(matrix, origin, dest)
+            on_path[nodes] = True
+        freq[on_path] += 1.0
+
+        if progress:
+            progress((k + 1) / n_iter)
+
+    return freq / n_iter, n_cells

itinera/validation.py

@@ -0,0 +1,61 @@
+# -*- coding: utf-8 -*-
+"""Path Deviation Index (PDI) validation.
+
+Jan Lewis / Goodchild: the PDI measures how far a modelled path deviates from
+a reference path (e.g. a known Roman road). It is the area between the two
+polylines divided by the length of the reference path -> mean perpendicular
+deviation in map units. Lower is better.
+
+This module works on coordinate sequences (Nx2 arrays), independent of the
+raster graph, so it can validate any two lines.
+
+Limitations
+-----------
+The area is computed with the shoelace formula on the single polygon formed by
+``modelled`` followed by ``reference`` reversed. This is only a faithful
+"area between the lines" when the two polylines are *similar and roughly
+parallel*: they should share orientation (both digitised in the same
+direction), not self-intersect, and not cross each other. For lines that cross,
+diverge strongly, or double back, the closing polygon self-intersects and the
+shoelace area partially cancels, so the PDI is no longer a meaningful mean
+deviation. Both coordinate sequences must be in the same projected CRS (metres);
+the index is in those map units. A topologically robust area-between-lines
+(handling self-intersections) would need geometry operations beyond the
+numpy-only core and is out of scope — pre-check inputs accordingly.
+"""
+
+import numpy as np
+
+
+def _polyline_length(coords):
+    d = np.diff(coords, axis=0)
+    return float(np.sum(np.hypot(d[:, 0], d[:, 1])))
+
+
+def _area_between(path_a, path_b):
+    """Approximate area between two polylines via the shoelace formula on the
+    closed polygon formed by A followed by reversed B."""
+    poly = np.vstack([path_a, path_b[::-1]])
+    x, y = poly[:, 0], poly[:, 1]
+    return 0.5 * abs(np.dot(x, np.roll(y, -1)) - np.dot(y, np.roll(x, -1)))
+
+
+def pdi(modelled, reference):
+    """Return the Path Deviation Index.
+
+    Parameters
+    ----------
+    modelled, reference : Nx2 / Mx2 arrays of (x, y) coordinates.
+
+    Returns
+    -------
+    dict with keys: pdi, area, reference_length.
+    """
+    modelled = np.asarray(modelled, dtype=float)
+    reference = np.asarray(reference, dtype=float)
+
+    area = _area_between(modelled, reference)
+    ref_len = _polyline_length(reference)
+    value = area / ref_len if ref_len > 0 else np.inf
+
+    return {"pdi": value, "area": area, "reference_length": ref_len}

itinera-0.6.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: itinera
+Version: 0.6.0
+Summary: Anisotropic least-cost path, corridor (LCC), FETE and PDI primitives for movement modelling — pure numpy/scipy.
+Project-URL: Homepage, https://github.com/leiverkus/itinera
+Project-URL: Repository, https://github.com/leiverkus/itinera
+Project-URL: Issues, https://github.com/leiverkus/itinera/issues
+Author-email: Patrick Leiverkus <patrick.leiverkus@uni-oldenburg.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anisotropic,archaeology,corridor,cost surface,fete,least cost path,movement,tobler
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Requires-Dist: numpy
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+# Itinera
+
+Anisotropic **least-cost path** (LCP), **corridor** (LCC),
+**From-Everywhere-To-Everywhere** (FETE), **stochastic / probabilistic** paths
+and **Path Deviation Index** (PDI) primitives for movement modelling — a pure
+**numpy / scipy** library extracted from the
+[Itinera QGIS plugin](https://github.com/leiverkus/itinera).
+
+Cost is **directional** (uphill ≠ downhill): each DEM cell becomes a graph node,
+edge weights come from a directional cost function of the signed slope, so the
+conductance matrix is **asymmetric** — true anisotropy. Paths are solved with
+`scipy.sparse.csgraph.dijkstra`.
+
+```bash
+pip install itinera
+```
+
+Only `numpy` and `scipy` are required.
+
+## Quick start
+
+```python
+import numpy as np
+from itinera import build_conductance, least_cost_path, tobler, rowcol_to_node
+
+# A small DEM (elevations in metres) on a 10 m grid.
+dem = np.random.default_rng(0).random((50, 50)) * 100.0
+
+matrix, rows, cols = build_conductance(
+    dem, cellsize=10.0, cost_fn=tobler, neighbours=8)
+
+origin = rowcol_to_node(0, 0, cols)
+dest = rowcol_to_node(49, 49, cols)
+path, total_cost = least_cost_path(matrix, origin, dest)  # path = node indices
+```
+
+Turn node indices back into (row, col) with `node_to_rowcol(node, cols)`.
+
+## What's included
+
+- **Cost functions**: `tobler`, `tobler_offpath`, `herzog`, `naismith`,
+  `llobera_sluckin` — each `(slope, distance) -> cost`.
+- **Conductance**: `build_conductance` (slope, optional barrier/multiplier),
+  `build_conductance_friction` (friction raster, optional DEM).
+- **Paths**: `accumulated_cost`, `least_cost_path`, `corridor` / `corridor_band`,
+  `fete`.
+- **Stochastic**: `stochastic_lcp`, `add_dem_error`, `add_global_stochasticity`.
+- **Validation**: `pdi`.
+- **Grid helpers**: `xy_to_rowcol`, `check_/assert_regular_geotransform`,
+  `check_/assert_grids_aligned`.
+- **Utilities**: `estimate_conductance_bytes`, `format_bytes`,
+  `block_reduce_mean`.
+
+## Scope: bring your own raster I/O
+
+This is a numerics library — it works on **numpy arrays + a GDAL-style
+geotransform tuple**. It does **not** depend on GDAL and does **not** read or
+write raster files. Load your DEM with whatever you already use
+(`rasterio`, `osgeo.gdal`, `xarray`/`rioxarray`, …) and pass the array in.
+
+Use a **projected CRS in metres** so slope and distance are metric.
+
+## Relation to the QGIS plugin
+
+The same code ships inside the
+[Itinera QGIS plugin](https://github.com/leiverkus/itinera) (where it is the
+plugin's private `core` package, plus QGIS/GDAL wrappers). The PyPI package and
+the QGIS plugin share the top-level import name `itinera`; they are meant for
+**separate environments**. Don't `pip install itinera` into the Python
+interpreter that runs QGIS — the plugin already bundles this code, and the two
+would shadow each other on `sys.path`.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). References for the methods (Tobler, Naismith,
+Herzog, Llobera & Sluckin, White & Barber, Lewis, Goodchild & Hunter) are in
+[`docs/REFERENCES.md`](https://github.com/leiverkus/itinera/blob/main/docs/REFERENCES.md).

itinera-0.6.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+itinera/__init__.py,sha256=_KAUjG_G1rU3jMLRt9IbYj5d0VqL0iBlWBz4t1hH2C0,1971
+itinera/conductance.py,sha256=gayKVtFWLiWukzDd0Irpt7BMz84d1RTRRngsEjFiqXA,6962
+itinera/corridor.py,sha256=W0p6nTm6rOOXT_KsVra48Uq6TzeuYDJ38-I-rufZLUQ,1378
+itinera/cost_functions.py,sha256=KQNtmw1npRZJaTUKFcuS5WtZEx5icE3cSkCqe-yIiPA,3231
+itinera/fete.py,sha256=Ofxykon4kxodIoAzqDXMu-QP_SlA-o9BJiVyrhCOvqI,1113
+itinera/grid_align.py,sha256=QnAHlipZlLeNgwjRXh0sGCUHZ8sECY7hU19tycN59nw,3399
+itinera/lcp.py,sha256=AvkAhxKzqNdFeGGhEIuiLZeCNtubRL_DH2pRM7VOJiU,1413
+itinera/memory.py,sha256=Su66yXOpFQ8oVS0E2SQUcBv6C3cTcdTjLpCwnhc2Ff0,1587
+itinera/resample.py,sha256=HvsTqKOFwLr3ih0wXNVLo7ffcfZq0jXHPiyev81q5Ds,1526
+itinera/stochastic.py,sha256=EpozGW2QM4G7x-xE446D5uS1FxtpEFHQrm2a_HKZzT0,4891
+itinera/validation.py,sha256=Ebee9sTEFgGQk9dCLR2J-KwhVxG0W8bWU1TR9zTF6UM,2344
+itinera-0.6.0.dist-info/METADATA,sha256=u47DNKzM6Tg-SVSjeLeFw2Y4wzPDX2IfGO8aN4no-V0,4101
+itinera-0.6.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+itinera-0.6.0.dist-info/licenses/LICENSE,sha256=fseWi5ej02eIb3nyWOsK_MIuBfK5uOFipv5WCGkrwCQ,1074
+itinera-0.6.0.dist-info/RECORD,,

itinera-0.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

itinera-0.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Leiverkus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.