itinera 0.6.0__tar.gz

itinera-0.6.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / tooling caches
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Build artefacts (plugin zip is built into ../)
+*.zip
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/

itinera-0.6.0/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.

itinera-0.6.0/PKG-INFO

@@ -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/README-pypi.md

@@ -0,0 +1,77 @@
+# 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/core/__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-0.6.0/core/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-0.6.0/core/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-0.6.0/core/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-0.6.0/core/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-0.6.0/core/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-0.6.0/core/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-0.6.0/core/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-0.6.0/core/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-0.6.0/core/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-0.6.0/core/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/metadata.txt

@@ -0,0 +1,36 @@
+[general]
+name=Itinera – Least-Cost Pathways
+qgisMinimumVersion=3.28
+qgisMaximumVersion=4.99
+description=Least-Cost Path, Corridor (LCC), FETE and PDI validation for archaeological movement modelling.
+about=Anisotropic cost-surface analysis using scipy.sparse Dijkstra. Provides Processing algorithms (Slope Cost Surface, Friction Cost Surface, LCP, Stochastic LCP, Corridor, FETE, PDI Validation, Resample DEM) plus an interactive map-click tool for point-to-point LCP. No external pip dependencies required (uses numpy/scipy bundled with QGIS). Released under the MIT licence.
+version=0.6.0
+author=Patrick Leiverkus (DAO)
+email=patrick.leiverkus@uni-oldenburg.de
+homepage=https://github.com/leiverkus/itinera
+tracker=https://github.com/leiverkus/itinera/issues
+repository=https://github.com/leiverkus/itinera
+tags=archaeology,least cost path,corridor,fete,cost surface,movement,tobler,anisotropic
+category=Analysis
+icon=icon.png
+experimental=True
+deprecated=False
+hasProcessingProvider=yes
+changelog=
+    0.6.0 - The pure numpy/scipy core is now also published as the `itinera` PyPI library (pip install itinera), built single-source from core/ via hatchling. No change to the QGIS plugin itself.
+    0.5.9 - Dev tooling: flake8 is now a CI check (max-line-length 88); excluded maintainer/dev-only files (CLAUDE.md, setup.cfg, pytest.ini, requirements-dev.txt) from the packaged zip. No runtime change.
+    0.5.8 - QGIS 4 / Qt6 runtime fixes: the settings dialog crashed on QDialogButtonBox.Ok (now scoped StandardButton), and the LCP output used QVariant.Int which PyQt6 removed (now QMetaType on Qt6, QVariant on Qt5). Verified on QGIS 3.28 and 4.0.
+    0.5.7 - Code hygiene: removed unused imports (flake8 F401) and added a setup.cfg ignoring W503/W504. No behaviour change.
+    0.5.6 - Declared QGIS 4 compatibility via qgisMaximumVersion=4.99 (without it QGIS assumed a 3.99 maximum and marked the plugin incompatible on QGIS 4). Verified loading on QGIS 4.0.
+    0.5.5 - Documentation: added QGIS 3.28+/4.0 and Qt5/Qt6 compatibility badges to the README.
+    0.5.4 - QGIS 4 / Qt6 compatibility: the settings dialog used exec_(), which PyQt6 removed; switched to exec() (works on QGIS 3 and 4). No other changes.
+    0.5.3 - The "Interactive LCP settings…" button now has its own gear icon, distinct from the path icon of the LCP tool button.
+    0.5.2 - Replaced the blank placeholder plugin icon with a real, visible one, so the two interactive-tool buttons are findable on the Plugins toolbar. Clarified in the docs where those buttons live.
+    0.5.1 - Documentation only: README status badges, future-directions wording, and removal of the internal publishing guide from the README and the packaged zip. No code changes.
+    0.5.0 - New "Resample DEM (block mean)" algorithm and a memory pre-flight warning for large DEMs; stochastic_lcp guards against n_iter < 1; added a user manual (docs/MANUAL.md) and verified references (docs/REFERENCES.md, references.bib). Corrected stochastic citation to Lewis 2021.
+    0.4.0 - Interactive LCP tool is now configurable: an "Interactive LCP settings…" toolbar/menu action picks the cost function and neighbourhood (parity with the Processing algorithms); the graph cache rebuilds only when settings change.
+    0.3.0 - New Stochastic least-cost path (Lewis 2023): N Monte-Carlo realisations with spatially-correlated DEM error (RMSE-scaled) and/or random edge dropping, accumulating a probabilistic corridor in [0,1]. Seed for reproducibility; supports the barrier/multiplier raster.
+    0.2.2 - Fix: xy_to_rowcol now floors instead of truncating, so points just west/north of the raster are correctly out of bounds (not wrongly snapped to row/col 0).
+    0.2.1 - Fixes: point layers are reprojected to the DEM CRS before cell lookup (algorithms + map tool); barrier/friction rasters are validated against the DEM CRS and geotransform (not just pixel count); rotated/non-square rasters are rejected with a clear error. Documented PDI limitations.
+    0.2.0 - Optional barrier / multiplier raster on the slope-based algorithms (slope cost surface, LCP, LCC, FETE): edge cost is scaled by the mean of the two cells' values (>1 discourages, <1 prefers, e.g. known roads); NoData or <=0 cells are impassable (cliffs, deep wadis).
+    0.1.0 - Initial release: anisotropic LCP, LCC corridor, FETE, PDI validation, slope & friction cost surfaces, interactive two-click LCP map tool. Pure numpy/scipy/GDAL (no external pip dependencies).

itinera-0.6.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "itinera"
+dynamic = ["version"]
+description = "Anisotropic least-cost path, corridor (LCC), FETE and PDI primitives for movement modelling — pure numpy/scipy."
+readme = "README-pypi.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Patrick Leiverkus", email = "patrick.leiverkus@uni-oldenburg.de" },
+]
+keywords = [
+    "least cost path", "corridor", "fete", "cost surface",
+    "movement", "tobler", "anisotropic", "archaeology",
+]
+dependencies = ["numpy", "scipy"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+
+[project.urls]
+Homepage = "https://github.com/leiverkus/itinera"
+Repository = "https://github.com/leiverkus/itinera"
+Issues = "https://github.com/leiverkus/itinera/issues"
+
+# Single-source the version from metadata.txt (line: version=X.Y.Z).
+[tool.hatch.version]
+path = "metadata.txt"
+pattern = "^version=(?P<version>[^\\s]+)$"
+
+# Wheel: ship the on-disk core/ directory as the import package `itinera`,
+# dropping the one GDAL-dependent module (nothing else imports it).
+[tool.hatch.build.targets.wheel]
+sources = { "core" = "itinera" }
+include = ["core/**/*.py"]
+exclude = ["core/raster_io.py"]
+
+# Sdist: the repo root *is* the QGIS plugin, so allowlist exactly what the
+# library needs — otherwise the tarball would slurp algorithms/, gui/, etc.
+[tool.hatch.build.targets.sdist]
+include = [
+    "core/**/*.py",
+    "metadata.txt",
+    "LICENSE",
+    "README-pypi.md",
+    "pyproject.toml",
+]
+exclude = [
+    "core/raster_io.py",
+    "core/**/__pycache__",
+]