ramify 1.1.0__tar.gz

ramify-1.1.0/.github/workflows/publish.yml

@@ -0,0 +1,15 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish --trusted-publishing automatic

ramify-1.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Project Directory Structure
+*.pdf
+cache/
+data/
+run.py
+output
+
+profile_run.py
+
+*.gpkg-wal
+*.gpkg-shm
+*.tif.aux.xml
+
+# vim
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+
+# snakemake
+.snakemake/
+
+# R
+*.rds
+.RData
+.Rhistory
+
+
+# Python
+__pycache__/
+*.py[cod]
+.python-version
+.ipynb_checkpoints
+
+
+# Operating System Metadata
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+.AppleDB
+.AppleDesktop
+.DS_Store
+.AppleDouble
+.LSOverride
+Network Trash Folder
+Temporary Items
+.apdisk

ramify-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Koehl
+
+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.

ramify-1.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: ramify
+Version: 1.1.0
+Summary: Segment and measure binary branching shapes: centerline extraction, hierarchical space partitioning, and width interpolation
+License-File: LICENSE
+Keywords: centerline,geomorphology,medial-axis,morphometry,raster,river,segmentation,skeleton,valley,width
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.12
+Requires-Dist: geopandas
+Requires-Dist: networkx
+Requires-Dist: numpy
+Requires-Dist: rasterio
+Requires-Dist: rioxarray
+Requires-Dist: scikit-image
+Requires-Dist: scipy
+Requires-Dist: shapely
+Requires-Dist: xarray
+Provides-Extra: dev
+Requires-Dist: matplotlib; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ramify
+
+Characterize binary branching shapes (e.g. rivers, floodplains, glaciers,
+roots, veins...). Given a shape mask, a root point, and (optionally) branch
+tips, `ramify` extracts a topology-aware centerline network, decomposes it into
+hierarchically ordered paths, allocates every pixel of the shape to its path,
+and estimates local width everywhere.
+
+![graphical abstract](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/abstract.png)
+
+## Install
+
+```bash
+pip install ramify
+```
+
+Development (clone, then sync with dev extras):
+
+```bash
+git clone https://github.com/avkoehl/ramify.git
+cd ramify
+uv sync --extra dev
+```
+
+## Usage
+
+```python
+import ramify
+from ramify.data import load
+
+mask, root, tips = load()                       # bundled toy dataset
+
+net = ramify.extract(mask, root, tips=tips)     # centerline network of ordered paths
+regions = ramify.allocate(mask, net.rasterize(by="path"))
+widths = ramify.region_widths(mask, net.rasterize(), regions)
+
+net.segments                                    # DataFrame: segment_id, path_id, strahler,
+                                                #   length, weight, downstream_segment_id
+regions                                         # labeled raster: each pixel -> its path
+widths                                          # float raster: local width everywhere
+```
+
+Inputs are `np.ndarray` (with `pixel_size=`) or georeferenced `xr.DataArray`;
+outputs match the input type. `root` and `tips` are `(row, col)` pixel coordinates.
+
+## Components
+
+Each individual component is presented below.
+
+### Centerlines
+
+```python
+net = ramify.extract(mask, root, tips=tips)
+```
+
+Skeletonizes the mask, routes from each tip to the root (pruning everything else),
+and decomposes the network into ordered paths — `path_id == 1` is the mainstem.
+
+
+![extract with tips](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/extract_tips.png)
+
+```python
+net = ramify.extract(mask, root)
+```
+
+Without tips, every skeleton endpoint becomes a tip.
+
+![extract auto tips](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/extract_auto.png)
+
+Tips and root can often be derived automatically — glacier branch tips
+[Kienholz et al.,
+2014](https://tc.copernicus.org/articles/8/503/2014/tc-8-503-2014.pdf), channel
+initiation points, or the lowest point on the boundary as the root — or simply
+digitized in GIS software.
+
+
+### Partitioning
+
+```python
+regions = ramify.allocate(mask, net.rasterize(by="path"))
+```
+
+Assigns every pixel to a path: paths claim territory in priority order, each limited
+by the local shape radius, so wide branches claim proportionally more space at junctions.
+
+![allocate](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/allocate.png)
+
+```python
+regions = ramify.voronoi(mask, net.rasterize(by="path"))
+```
+
+Nearest-centerline partition — no ordering, no radius limits.
+
+![voronoi](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/voronoi.png)
+
+```python
+seg_regions = ramify.subdivide(regions, net)
+```
+
+Subdivides each path's territory further: within a territory, every pixel goes to
+its nearest centerline segment of that same path.
+
+![subdivide](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/subdivide.png)
+
+### Widths
+
+Exact widths (twice the distance to the boundary) are taken at the centerline and
+interpolated across the shape. That interpolation runs either over the whole shape
+or independently within each region, which keeps junction-zone pixels from
+averaging between a branch and its mainstem:
+
+```python
+w = ramify.widths(mask, net.rasterize())
+w = ramify.region_widths(mask, net.rasterize(), regions)
+```
+
+![widths domain](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/widths_domain.png)
+
+Either call also takes `method="nearest"`, which gives each pixel the width of its
+nearest centerline pixel instead of diffusing smoothly from it — piecewise
+constant, and much faster:
+
+```python
+w = ramify.widths(mask, net.rasterize(), method="nearest")
+```
+
+![widths nearest](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/widths_nearest.png)
+
+## Open boundaries
+
+Everything above measures local half-width as the distance from each pixel to the
+shape's boundary, and that half-width drives three things: which branch is the
+mainstem, how far each path claims territory, and the width field. By default
+every boundary pixel is treated as a **wall**. Sometimes part of the boundary is
+not a real wall — the shape is truncated by open water, the data extent, or
+another medium — and treating it as one makes the half-width collapse to zero
+there.
+
+Pass `open_boundary`: a binary mask, on the same grid as the shape, marking the
+non-wall (void) pixels. Distances are then measured only to the remaining real
+walls. It is optional — omitted, every boundary is a wall (the behaviour above) —
+and accepted by `extract`, `allocate`, `widths`, and `region_widths`. Give it to
+every step, so all three stages measure against the same walls:
+
+```python
+net = ramify.extract(mask, root, tips=tips, open_boundary=open_boundary)
+regions = ramify.allocate(mask, net.rasterize(by="path"), open_boundary=open_boundary)
+widths = ramify.region_widths(mask, net.rasterize(), regions,
+                              open_boundary=open_boundary)
+```
+
+Below, the same mask, root, and tips are reused, but the void past the outlet is
+marked open (shaded red), and the outlet `widths` no longer taper to the cut edge.
+Mark a region with depth rather than a thin skin along the boundary: distances are
+measured *through* the open void, so a one-pixel rind would only push the wall out
+by one pixel. 
+
+![open boundary](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/open_boundary.png)
+
+Only the widths are shown because on this shape the partitioning didn't change.

ramify-1.1.0/README.md

@@ -0,0 +1,160 @@
+# ramify
+
+Characterize binary branching shapes (e.g. rivers, floodplains, glaciers,
+roots, veins...). Given a shape mask, a root point, and (optionally) branch
+tips, `ramify` extracts a topology-aware centerline network, decomposes it into
+hierarchically ordered paths, allocates every pixel of the shape to its path,
+and estimates local width everywhere.
+
+![graphical abstract](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/abstract.png)
+
+## Install
+
+```bash
+pip install ramify
+```
+
+Development (clone, then sync with dev extras):
+
+```bash
+git clone https://github.com/avkoehl/ramify.git
+cd ramify
+uv sync --extra dev
+```
+
+## Usage
+
+```python
+import ramify
+from ramify.data import load
+
+mask, root, tips = load()                       # bundled toy dataset
+
+net = ramify.extract(mask, root, tips=tips)     # centerline network of ordered paths
+regions = ramify.allocate(mask, net.rasterize(by="path"))
+widths = ramify.region_widths(mask, net.rasterize(), regions)
+
+net.segments                                    # DataFrame: segment_id, path_id, strahler,
+                                                #   length, weight, downstream_segment_id
+regions                                         # labeled raster: each pixel -> its path
+widths                                          # float raster: local width everywhere
+```
+
+Inputs are `np.ndarray` (with `pixel_size=`) or georeferenced `xr.DataArray`;
+outputs match the input type. `root` and `tips` are `(row, col)` pixel coordinates.
+
+## Components
+
+Each individual component is presented below.
+
+### Centerlines
+
+```python
+net = ramify.extract(mask, root, tips=tips)
+```
+
+Skeletonizes the mask, routes from each tip to the root (pruning everything else),
+and decomposes the network into ordered paths — `path_id == 1` is the mainstem.
+
+
+![extract with tips](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/extract_tips.png)
+
+```python
+net = ramify.extract(mask, root)
+```
+
+Without tips, every skeleton endpoint becomes a tip.
+
+![extract auto tips](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/extract_auto.png)
+
+Tips and root can often be derived automatically — glacier branch tips
+[Kienholz et al.,
+2014](https://tc.copernicus.org/articles/8/503/2014/tc-8-503-2014.pdf), channel
+initiation points, or the lowest point on the boundary as the root — or simply
+digitized in GIS software.
+
+
+### Partitioning
+
+```python
+regions = ramify.allocate(mask, net.rasterize(by="path"))
+```
+
+Assigns every pixel to a path: paths claim territory in priority order, each limited
+by the local shape radius, so wide branches claim proportionally more space at junctions.
+
+![allocate](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/allocate.png)
+
+```python
+regions = ramify.voronoi(mask, net.rasterize(by="path"))
+```
+
+Nearest-centerline partition — no ordering, no radius limits.
+
+![voronoi](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/voronoi.png)
+
+```python
+seg_regions = ramify.subdivide(regions, net)
+```
+
+Subdivides each path's territory further: within a territory, every pixel goes to
+its nearest centerline segment of that same path.
+
+![subdivide](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/subdivide.png)
+
+### Widths
+
+Exact widths (twice the distance to the boundary) are taken at the centerline and
+interpolated across the shape. That interpolation runs either over the whole shape
+or independently within each region, which keeps junction-zone pixels from
+averaging between a branch and its mainstem:
+
+```python
+w = ramify.widths(mask, net.rasterize())
+w = ramify.region_widths(mask, net.rasterize(), regions)
+```
+
+![widths domain](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/widths_domain.png)
+
+Either call also takes `method="nearest"`, which gives each pixel the width of its
+nearest centerline pixel instead of diffusing smoothly from it — piecewise
+constant, and much faster:
+
+```python
+w = ramify.widths(mask, net.rasterize(), method="nearest")
+```
+
+![widths nearest](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/widths_nearest.png)
+
+## Open boundaries
+
+Everything above measures local half-width as the distance from each pixel to the
+shape's boundary, and that half-width drives three things: which branch is the
+mainstem, how far each path claims territory, and the width field. By default
+every boundary pixel is treated as a **wall**. Sometimes part of the boundary is
+not a real wall — the shape is truncated by open water, the data extent, or
+another medium — and treating it as one makes the half-width collapse to zero
+there.
+
+Pass `open_boundary`: a binary mask, on the same grid as the shape, marking the
+non-wall (void) pixels. Distances are then measured only to the remaining real
+walls. It is optional — omitted, every boundary is a wall (the behaviour above) —
+and accepted by `extract`, `allocate`, `widths`, and `region_widths`. Give it to
+every step, so all three stages measure against the same walls:
+
+```python
+net = ramify.extract(mask, root, tips=tips, open_boundary=open_boundary)
+regions = ramify.allocate(mask, net.rasterize(by="path"), open_boundary=open_boundary)
+widths = ramify.region_widths(mask, net.rasterize(), regions,
+                              open_boundary=open_boundary)
+```
+
+Below, the same mask, root, and tips are reused, but the void past the outlet is
+marked open (shaded red), and the outlet `widths` no longer taper to the cut edge.
+Mark a region with depth rather than a thin skin along the boundary: distances are
+measured *through* the open void, so a one-pixel rind would only push the wall out
+by one pixel. 
+
+![open boundary](https://raw.githubusercontent.com/avkoehl/ramify/main/assets/open_boundary.png)
+
+Only the widths are shown because on this shape the partitioning didn't change.

ramify-1.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ramify"
+version = "1.1.0"
+description = "Segment and measure binary branching shapes: centerline extraction, hierarchical space partitioning, and width interpolation"
+keywords = [
+    "centerline",
+    "skeleton",
+    "medial-axis",
+    "segmentation",
+    "raster",
+    "geomorphology",
+    "river",
+    "valley",
+    "morphometry",
+    "width",
+]
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+dependencies = [
+    "numpy",
+    "scipy",
+    "scikit-image",
+    "networkx",
+    "rasterio",
+    "shapely",
+    "geopandas",
+    "xarray",
+    "rioxarray",
+]
+
+[project.optional-dependencies]
+dev = [
+    "matplotlib",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ramify"]
+
+[tool.hatch.build.targets.wheel.shared-data]
+"ramify/data" = "ramify/data"

ramify-1.1.0/ramify/__init__.py

@@ -0,0 +1,13 @@
+from .centerline import extract, Network
+from .partition import allocate, voronoi, subdivide
+from .width import widths, region_widths
+
+__all__ = [
+    "extract",
+    "Network",
+    "allocate",
+    "voronoi",
+    "subdivide",
+    "widths",
+    "region_widths",
+]

ramify-1.1.0/ramify/_io.py

@@ -0,0 +1,107 @@
+# _io.py
+from dataclasses import dataclass
+import numpy as np
+
+
+@dataclass
+class GridMeta:
+    """Everything needed to reconstruct an xr.DataArray from a numpy result."""
+
+    coords: dict
+    dims: tuple
+    crs: object | None
+    transform: object | None
+
+
+def unwrap(arr, pixel_size=None):
+    """
+    Accept np.ndarray or xr.DataArray.
+    Returns (values: np.ndarray, pixel_size: float, meta: GridMeta | None).
+    """
+    try:
+        import xarray as xr
+
+        is_xr = isinstance(arr, xr.DataArray)
+    except ImportError:
+        is_xr = False
+
+    if not is_xr:
+        return np.asarray(arr), float(pixel_size or 1.0), None
+
+    meta = GridMeta(
+        coords=arr.coords,
+        dims=arr.dims,
+        crs=getattr(arr.rio, "crs", None) if hasattr(arr, "rio") else None,
+        transform=arr.rio.transform() if hasattr(arr, "rio") else None,
+    )
+    if pixel_size is None and meta.transform is not None:
+        pixel_size = abs(
+            meta.transform.a
+        )  # from affine transform, assumes square pixels
+    return arr.values, float(pixel_size or 1.0), meta
+
+
+def wrap(values, meta):
+    """np.ndarray + meta -> xr.DataArray; passthrough if meta is None."""
+    if meta is None:
+        return values
+    import xarray as xr
+
+    out = xr.DataArray(values, coords=meta.coords, dims=meta.dims)
+    if meta.crs is not None:
+        out.rio.write_crs(meta.crs, inplace=True)
+        out.rio.write_transform(meta.transform, inplace=True)
+    return out
+
+
+def region_groups(label_arr, mask_bool=None):
+    """Group a labeled raster's pixels by label, in one pass.
+
+    Yields ``(label, flat_idx)`` per positive label, ascending, where
+    ``flat_idx`` indexes the raveled grid; ``mask_bool`` optionally restricts
+    which pixels count. This replaces the ``label_arr == label`` scan a
+    per-region loop would otherwise do, which costs the whole grid once per
+    region. The sort is stable, so each group's indices come out ascending --
+    callers rely on that for ``searchsorted`` neighbour lookups and for
+    reading off a bounding box.
+    """
+    positive = label_arr > 0
+    flat = np.flatnonzero(positive if mask_bool is None else positive & mask_bool)
+    if flat.size == 0:
+        return
+    labels = label_arr.ravel()[flat]
+    order = np.argsort(labels, kind="stable")
+    flat = flat[order]
+    labels = labels[order]
+    starts = np.flatnonzero(np.r_[True, labels[1:] != labels[:-1]])
+    for lo, hi in zip(starts, np.append(starts[1:], flat.size)):
+        yield int(labels[lo]), flat[lo:hi]
+
+
+def edt_field(mask_bool, open_boundary):
+    """Foreground array for the local-half-width distance transform.
+
+    ``distance_transform_edt`` of the returned array gives, at each shape pixel,
+    the distance to the nearest *wall*. By default (``open_boundary is None``)
+    every non-shape pixel is a wall -- the original behaviour. When
+    ``open_boundary`` is given, its truthy pixels are treated as void (open,
+    not a wall): they join the shape as foreground, so half-widths are measured
+    only to the remaining real walls. Accepts np.ndarray or xr.DataArray.
+    """
+    if open_boundary is None:
+        return mask_bool
+    open_arr, _, _ = unwrap(open_boundary)
+    open_bool = np.asarray(open_arr) > 0
+    if open_bool.shape != mask_bool.shape:
+        raise ValueError(
+            f"open_boundary shape {open_bool.shape} does not match "
+            f"mask shape {mask_bool.shape}"
+        )
+    field = mask_bool | open_bool
+    if field.all():
+        import warnings
+
+        warnings.warn(
+            "open_boundary leaves no wall pixels; local half-widths will be zero"
+        )
+    return field