ftw-fbp 0.1.0__tar.gz

ftw_fbp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fields of The World
+
+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.

ftw_fbp-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: ftw-fbp
+Version: 0.1.0
+Summary: Field boundary prediction post-processing algorithms
+Author-email: Isaac Corley <isaac.corley@taylorgeospatial.org>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/fieldsoftheworld/fbp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scikit-image>=0.22
+Requires-Dist: scipy>=1.11
+Provides-Extra: fast
+Requires-Dist: numba>=0.60; extra == "fast"
+Requires-Dist: SimpleITK>=2.4; extra == "fast"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: ty>=0.0.1a32; extra == "dev"
+Dynamic: license-file
+
+# fbp
+
+Field boundary prediction post-processing in Python.
+
+`fbp` turns background, field, and boundary predictions into field instances. It
+includes BoundaryVote, the method behind the FTW Global Data 2nd Edition, along with
+watershed, connected-component, and published split-and-merge baselines.
+
+## Install
+
+```sh
+pip install ftw-fbp
+```
+
+The package imports as `fbp`.
+
+For development:
+
+```sh
+git clone https://github.com/fieldsoftheworld/fbp.git
+cd fbp
+uv sync --extra dev
+```
+
+## Use
+
+A method takes a `(H, W)` class map and a `(3, H, W)` array of background, field,
+and boundary probabilities, and returns `int32` instance labels with 0 as background.
+Each method is a frozen dataclass, so its settings can be written out and loaded
+again as plain data.
+
+```python
+from fbp import BoundaryVote
+
+method = BoundaryVote(
+    foreground="not_background",
+    seed_depth=0.01,
+    min_line_support=0.3,
+    min_area_m2=900,
+)
+instances = method(segmentation, probabilities, pixel_area_m2=9.0)
+```
+
+This method takes every pixel where field or boundary wins as foreground and floods
+1 - p(boundary) from seeds at least 0.01 deep. It keeps a proposed split when at
+least 30% of the pixels on the dividing line favor boundary, and drops fields under
+900 m². The class docstrings describe every option.
+
+For rasters too large for one call, `run_windowed` processes `core`-sized windows
+with `halo` pixels of context on each side. The window whose core holds a field's
+centroid keeps that field, and copies of a field that crosses a window boundary are
+merged into one instance.
+
+```python
+from fbp import run_windowed
+
+instances = run_windowed(
+    method,
+    segmentation,
+    probabilities,
+    pixel_area_m2=9.0,
+    core=8192,
+    halo=512,
+)
+```
+
+## FTW Global Data 2nd Edition
+
+`fbp.FTW_2E` is the setting used for the 2nd Edition field boundaries, run on 2.5 m
+probabilities:
+
+```python
+from fbp import FTW_2E
+
+instances = FTW_2E(segmentation, probabilities, pixel_area_m2=6.25)
+```
+
+Besides the BoundaryVote settings above (with `min_line_support=0.5`), it drops
+fields whose mean field probability is under 0.25. It then splits the looser
+foreground of pixels with field probability above 0.10 and adds each resulting field
+that the first pass covers less than half of, which recovers fields whose field
+probability rarely wins the argmax. That second pass is skipped when less than 2% of
+the looser foreground is uncovered. With `fast=True`, the probabilities are rounded
+to the 1/255 grid of the published uint8 rasters, and the watershed runs on integer
+levels. This needs the `fast` extra (SimpleITK and numba):
+
+```sh
+pip install 'ftw-fbp[fast]'
+```
+
+On the published probability rasters, `FTW_2E` reproduces the published raw outlines.
+It matches all 112 fields pixel for pixel on a 10 km window of tile `15TVG_0_0`
+(Iowa), and 647 of 648 fields (99.7% pixel for pixel) on tile `35MRT_0_0` (Rwanda).
+
+## Layout
+
+```text
+src/fbp/core/      geometry and post-processing building blocks
+src/fbp/methods/   the methods, one module each
+tests/             package tests
+```
+
+A new method subclasses `fbp.Method` and implements `split`. Keep paper-specific
+evaluation, results, figures, and LaTeX outside this package.
+
+## Development
+
+```sh
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```

ftw_fbp-0.1.0/README.md

@@ -0,0 +1,113 @@
+# fbp
+
+Field boundary prediction post-processing in Python.
+
+`fbp` turns background, field, and boundary predictions into field instances. It
+includes BoundaryVote, the method behind the FTW Global Data 2nd Edition, along with
+watershed, connected-component, and published split-and-merge baselines.
+
+## Install
+
+```sh
+pip install ftw-fbp
+```
+
+The package imports as `fbp`.
+
+For development:
+
+```sh
+git clone https://github.com/fieldsoftheworld/fbp.git
+cd fbp
+uv sync --extra dev
+```
+
+## Use
+
+A method takes a `(H, W)` class map and a `(3, H, W)` array of background, field,
+and boundary probabilities, and returns `int32` instance labels with 0 as background.
+Each method is a frozen dataclass, so its settings can be written out and loaded
+again as plain data.
+
+```python
+from fbp import BoundaryVote
+
+method = BoundaryVote(
+    foreground="not_background",
+    seed_depth=0.01,
+    min_line_support=0.3,
+    min_area_m2=900,
+)
+instances = method(segmentation, probabilities, pixel_area_m2=9.0)
+```
+
+This method takes every pixel where field or boundary wins as foreground and floods
+1 - p(boundary) from seeds at least 0.01 deep. It keeps a proposed split when at
+least 30% of the pixels on the dividing line favor boundary, and drops fields under
+900 m². The class docstrings describe every option.
+
+For rasters too large for one call, `run_windowed` processes `core`-sized windows
+with `halo` pixels of context on each side. The window whose core holds a field's
+centroid keeps that field, and copies of a field that crosses a window boundary are
+merged into one instance.
+
+```python
+from fbp import run_windowed
+
+instances = run_windowed(
+    method,
+    segmentation,
+    probabilities,
+    pixel_area_m2=9.0,
+    core=8192,
+    halo=512,
+)
+```
+
+## FTW Global Data 2nd Edition
+
+`fbp.FTW_2E` is the setting used for the 2nd Edition field boundaries, run on 2.5 m
+probabilities:
+
+```python
+from fbp import FTW_2E
+
+instances = FTW_2E(segmentation, probabilities, pixel_area_m2=6.25)
+```
+
+Besides the BoundaryVote settings above (with `min_line_support=0.5`), it drops
+fields whose mean field probability is under 0.25. It then splits the looser
+foreground of pixels with field probability above 0.10 and adds each resulting field
+that the first pass covers less than half of, which recovers fields whose field
+probability rarely wins the argmax. That second pass is skipped when less than 2% of
+the looser foreground is uncovered. With `fast=True`, the probabilities are rounded
+to the 1/255 grid of the published uint8 rasters, and the watershed runs on integer
+levels. This needs the `fast` extra (SimpleITK and numba):
+
+```sh
+pip install 'ftw-fbp[fast]'
+```
+
+On the published probability rasters, `FTW_2E` reproduces the published raw outlines.
+It matches all 112 fields pixel for pixel on a 10 km window of tile `15TVG_0_0`
+(Iowa), and 647 of 648 fields (99.7% pixel for pixel) on tile `35MRT_0_0` (Rwanda).
+
+## Layout
+
+```text
+src/fbp/core/      geometry and post-processing building blocks
+src/fbp/methods/   the methods, one module each
+tests/             package tests
+```
+
+A new method subclasses `fbp.Method` and implements `split`. Keep paper-specific
+evaluation, results, figures, and LaTeX outside this package.
+
+## Development
+
+```sh
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```

ftw_fbp-0.1.0/pyproject.toml

@@ -0,0 +1,124 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ftw-fbp"
+version = "0.1.0"
+description = "Field boundary prediction post-processing algorithms"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Isaac Corley", email = "isaac.corley@taylorgeospatial.org" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+    "numpy>=1.26",
+    "scikit-image>=0.22",
+    "scipy>=1.11",
+]
+
+[project.optional-dependencies]
+# For fast=True: integer h-maxima and a bucket-queue watershed.
+fast = [
+    "numba>=0.60",
+    "SimpleITK>=2.4",
+]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.15",
+    "ty>=0.0.1a32",
+]
+
+[project.urls]
+Repository = "https://github.com/fieldsoftheworld/fbp"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W", "I", "N", "UP", "B", "C4", "SIM", "RET", "PTH",
+    "ARG", "RUF", "ANN", "D", "PL", "TID", "PIE", "TRY", "NPY",
+]
+ignore = ["FA100", "FA102", "N806", "PLR2004", "TRY003", "RUF046"]
+extend-safe-fixes = []
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D100", "D101", "D102", "D103", "D107", "ARG001", "ARG002", "ARG005"]
+"src/fbp/methods/boundaryvote.py" = ["PLR0912", "PLR0913", "PLR0915"]
+"src/fbp/core/merge.py" = ["PLR0913", "PLR0917"]
+"src/fbp/windowed.py" = ["PLR0913"]  # run_windowed mirrors run() plus window options
+
+[tool.ruff.lint.isort]
+known-first-party = ["fbp"]
+required-imports = []
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "parents"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+skip-magic-trailing-comma = false
+docstring-code-format = true
+
+[tool.pytest.ini_options]
+minversion = "8"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+filterwarnings = ["default"]
+
+[tool.coverage.run]
+source = ["fbp"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+exclude_also = [
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[tool.ty.environment]
+python-version = "3.12"
+root = ["src", "tests"]
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.ty.rules]
+possibly-unresolved-reference = "error"
+possibly-missing-attribute = "error"
+possibly-missing-implicit-call = "error"
+division-by-zero = "error"
+redundant-cast = "error"
+unused-ignore-comment = "error"
+unresolved-import = "warn"
+
+[tool.ty.terminal]
+output-format = "concise"

ftw_fbp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ftw_fbp-0.1.0/src/fbp/__init__.py

@@ -0,0 +1,35 @@
+"""Field boundary prediction post-processing algorithms."""
+
+from fbp.methods import (
+    FTW_2E,
+    BoundaryVote,
+    ClosedComponents,
+    Components,
+    ExtentBoundaryThreshold,
+    FTPWatershed,
+    GaussianMixture,
+    IterativeWatershed,
+    Method,
+    OrientedWatershed,
+    StochasticWatershed,
+    UltrametricContours,
+    ftp_pipeline,
+)
+from fbp.windowed import run_windowed
+
+__all__ = [
+    "FTW_2E",
+    "BoundaryVote",
+    "ClosedComponents",
+    "Components",
+    "ExtentBoundaryThreshold",
+    "FTPWatershed",
+    "GaussianMixture",
+    "IterativeWatershed",
+    "Method",
+    "OrientedWatershed",
+    "StochasticWatershed",
+    "UltrametricContours",
+    "ftp_pipeline",
+    "run_windowed",
+]

ftw_fbp-0.1.0/src/fbp/core/__init__.py

@@ -0,0 +1 @@
+"""Shared geometry primitives every post-processing method is built from."""

ftw_fbp-0.1.0/src/fbp/core/fast_morph.py

@@ -0,0 +1,169 @@
+"""Integer versions of the two scikit-image calls that dominate BoundaryVote's runtime.
+
+On 5,120 x 5,120 production windows, ``h_maxima`` and ``watershed`` take 92% of
+BoundaryVote's time. When the surface is on the 1/255 grid of the uint8 probability
+rasters, both can run on integer levels.
+
+``h_maxima_itk`` uses ITK grayscale reconstruction by dilation. It gives the same
+result as scikit-image, checked on 5k and 9k windows, and runs about 10x faster on one
+thread. ``watershed_bucket`` floods with a bucket queue in O(N) under scikit-image's
+rules. Marker pixels of equal cost leave the queue in scan order rather than heap
+order, so the lines move only at exact ties (99.99% of pixels agree).
+
+Both reject surfaces that are not on the 1/255 grid. ``quantize_prob`` rounds a float
+softmax onto it, which is what storing it as uint8 does. ``Method(fast=True)`` does
+both.
+"""
+
+import numpy as np
+
+try:
+    import SimpleITK as sitk  # noqa: N813  (the package's own conventional alias)
+    from numba import njit
+except ImportError as e:
+    raise ImportError(
+        "fast=True needs the fast backend: pip install 'ftw-fbp[fast]'"
+    ) from e
+from skimage.morphology._util import _offsets_to_raveled_neighbors
+
+LEVELS = 255.0
+
+
+def quantize_prob(prob: np.ndarray) -> np.ndarray:
+    """Softmax rounded to 1/255 steps per class, as the uint8 production rasters do."""
+    return (np.rint(prob.astype(np.float32) * LEVELS) / LEVELS).astype(np.float32)
+
+
+def _to_levels(x: np.ndarray, name: str) -> np.ndarray:
+    u = np.rint(x * LEVELS)
+    if np.abs(x * LEVELS - u).max() > 0.25:  # fp16 error is ~0.06 levels
+        raise ValueError(
+            f"{name} is not on the 1/255 grid; quantize it with quantize_prob"
+        )
+    return u.astype(np.uint8)
+
+
+def h_maxima_itk(image: np.ndarray, h: float, footprint: None = None) -> np.ndarray:
+    """``skimage.morphology.h_maxima`` for a [0, 1] surface on the 1/255 grid."""
+    if footprint is not None:
+        raise ValueError("only the default (full) footprint is supported")
+    img = _to_levels(image, "h_maxima input")
+    h_lv = int(np.ceil(h * LEVELS - 1e-9))  # residue >= h  <=>  levels >= ceil(h*255)
+    if h_lv > int(img.max()) - int(img.min()):
+        return np.zeros(img.shape, np.uint8)
+    marker = np.clip(img.astype(np.int16) - h_lv, 0, 255).astype(np.uint8)
+    f = sitk.ReconstructionByDilationImageFilter()
+    f.SetFullyConnected(True)
+    # GetArrayFromImage (a copy): a view of the temporary result can be freed under us.
+    rec = sitk.GetArrayFromImage(
+        f.Execute(sitk.GetImageFromArray(marker), sitk.GetImageFromArray(img))
+    )
+    return ((img.astype(np.int16) - rec) >= h_lv).astype(np.uint8)
+
+
+@njit(cache=True)
+def _bucket_kernel(img, locs, structure, mask, output):  # noqa: ANN001, ANN202, PLR0912, PLR0915
+    cap = max(1024, 4 * locs.shape[0])
+    ix = np.empty(cap, np.int64)
+    sr = np.empty(cap, np.int64)
+    nx = np.full(cap, -1, np.int64)
+    head = np.full(256, -1, np.int64)
+    tail = np.full(256, -1, np.int64)
+    n = 0
+    for k in range(locs.shape[0]):
+        v = img[locs[k]]
+        ix[n] = locs[k]
+        sr[n] = locs[k]
+        nx[n] = -1
+        if head[v] < 0:
+            head[v] = n
+        else:
+            nx[tail[v]] = n
+        tail[v] = n
+        n += 1
+    cur = 0
+    while cur < 256:
+        e = head[cur]
+        if e < 0:
+            cur += 1
+            continue
+        head[cur] = nx[e]
+        if head[cur] < 0:
+            tail[cur] = -1
+        ei, es = ix[e], sr[e]
+        if output[ei] and ei != es:
+            continue
+        lab = output[es]
+        diff = False
+        if not mask[ei]:
+            diff = True
+        else:
+            for q in range(structure.shape[0]):
+                nb = structure[q] + ei
+                if mask[nb]:
+                    nl = output[nb]
+                    if nl != 0 and nl != lab:  # noqa: PLR1714  (numba: keep it scalar)
+                        mask[ei] = False
+                        diff = True
+                        break
+        if not diff:
+            output[ei] = lab
+        for q in range(structure.shape[0]):
+            nb = structure[q] + ei
+            if not mask[nb] or output[nb]:
+                continue
+            v = img[nb]
+            if v < cur:  # noqa: PLR1730  skimage: cost >= the popping pixel's cost
+                v = cur
+            if n == cap:
+                cap *= 2
+                a = np.empty(cap, np.int64)
+                a[:n] = ix[:n]
+                ix = a
+                a = np.empty(cap, np.int64)
+                a[:n] = sr[:n]
+                sr = a
+                a = np.full(cap, -1, np.int64)
+                a[:n] = nx[:n]
+                nx = a
+            ix[n] = nb
+            sr[n] = es
+            nx[n] = -1
+            if head[v] < 0:
+                head[v] = n
+            else:
+                nx[tail[v]] = n
+            tail[v] = n
+            n += 1
+
+
+def watershed_bucket(
+    image: np.ndarray,
+    markers: np.ndarray | None = None,
+    mask: np.ndarray | None = None,
+    watershed_line: bool = True,
+    connectivity: int = 1,
+) -> np.ndarray:
+    """Skimage's ``watershed(image, markers, mask=mask, watershed_line=True)``.
+
+    For ``image = -surface`` with ``surface`` on the 1/255 grid.
+    """
+    if not watershed_line or connectivity != 1:
+        raise ValueError("only watershed_line=True, connectivity=1 is implemented")
+    if markers is None or mask is None:
+        raise ValueError("markers and mask are required")
+    lv = _to_levels(image + 1.0, "watershed input")  # -(1 - pb) + 1 = pb
+    img = np.pad(lv, 1)
+    msk = np.pad(mask.astype(bool), 1).ravel()
+    out = np.pad(markers.astype(np.int32), 1)
+    st = _offsets_to_raveled_neighbors(
+        img.shape, np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]], bool), center=(1, 1)
+    )
+    _bucket_kernel(
+        img.ravel(),
+        np.flatnonzero(out).astype(np.int64),
+        st.astype(np.int64),
+        msk,
+        out.ravel(),
+    )
+    return out[1:-1, 1:-1].copy()