supervoxel-splitter 0.1.0__tar.gz

supervoxel_splitter-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[fast,dev]"
+
+      - name: Run tests with coverage
+        run: pytest --cov=supervoxel_splitter --cov-report=xml tests/
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  validate-tag:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Reject non-SemVer tag
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          re='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(\+([0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*))?$'
+          [[ "$TAG" =~ $re ]] || { echo "Tag '$TAG' is not SemVer (vMAJOR.MINOR.PATCH[-pre][+build])"; exit 1; }
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [test, validate-tag]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

supervoxel_splitter-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Editors
+.devcontainer/
+.vscode/
+*.code-workspace
+.claude/

supervoxel_splitter-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 26.1.0
+    hooks:
+      - id: black
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: pytest
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true

supervoxel_splitter-0.1.0/LICENSE

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

supervoxel_splitter-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE
+include README.md

supervoxel_splitter-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: supervoxel-splitter
+Version: 0.1.0
+Summary: Pluggable supervoxel splitting algorithms with a uniform interface.
+License: MIT License
+        
+        Copyright (c) 2026 CAVE
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/CAVEconnectome/supervoxel-splitter
+Project-URL: Issues, https://github.com/CAVEconnectome/supervoxel-splitter/issues
+Project-URL: Source, https://github.com/CAVEconnectome/supervoxel-splitter
+Keywords: connectomics,segmentation,supervoxel,watershed,geodesic,image-processing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy>=1.6
+Requires-Dist: fastremap
+Requires-Dist: connected-components-3d
+Requires-Dist: scikit-image
+Requires-Dist: edt
+Provides-Extra: fast
+Requires-Dist: dijkstra3d; extra == "fast"
+Provides-Extra: learned
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# supervoxel-splitter
+
+[![codecov](https://codecov.io/gh/CAVEconnectome/supervoxel-splitter/graph/badge.svg)](https://codecov.io/gh/CAVEconnectome/supervoxel-splitter)
+
+Pluggable supervoxel-splitting algorithms behind a uniform `Splitter` interface.
+
+## What it does
+
+Given a 3-D foreground mask, source seeds, and sink seeds, return a labeled
+volume that partitions the foreground into a source side and a sink side.
+Useful for proofreading workflows that need to split a single supervoxel
+without touching the rest of the segmentation.
+
+The package ships multiple techniques behind the same `Splitter` protocol:
+
+- **GeodesicSplitter** — anisotropic geodesic carve via an EDT-derived speed
+  field. Default technique; preserves the neck-aware behavior used in
+  PyChunkedGraph today.
+- **WatershedSplitter** — seeded watershed on the distance transform.
+- **NoopSplitter** — reference implementation; documents the protocol shape
+  for downstream plugin authors (e.g. a learned splitter).
+
+## Install
+
+Requires Python 3.14 or newer.
+
+```
+pip install supervoxel-splitter           # core
+pip install "supervoxel-splitter[fast]"   # adds dijkstra3d as the geodesic backend
+```
+
+## The uniform interface
+
+Every splitter satisfies the same `Splitter` protocol. Technique-specific
+knobs live on the constructor; `split()` itself stays clean.
+
+```python
+from supervoxel_splitter import GeodesicSplitter
+
+splitter = GeodesicSplitter(backend="dj3d")
+result = splitter.split(
+    mask=foreground_3d_bool,
+    sources=src_seeds_xyz,
+    sinks=snk_seeds_xyz,
+    voxel_size=(4.0, 4.0, 40.0),
+)
+
+# result.labels: uint8 in {0, SOURCE, SINK, STRAY}
+# result.side_of_label: {SOURCE: 1, SINK: 2}
+# result.diagnostics: per-stage timings, label counts, etc.
+```
+
+Plugin authors implement the protocol structurally — no base class to
+inherit:
+
+```python
+class MyLearnedSplitter:
+    def __init__(self, *, model_path):
+        ...
+    def split(self, mask, sources, sinks, *,
+              voxel_size=(1.0, 1.0, 1.0),
+              vol_order="xyz", vox_order="xyz", seed_order="xyz"):
+        ...
+        return SplitResult(...)
+
+assert isinstance(MyLearnedSplitter(model_path="..."), Splitter)
+```
+
+## Boundary
+
+The package knows nothing about ChunkedGraph, BigTable, IDs, or edges. It
+takes voxels in and gives labels back. New-ID minting, edge updates, and
+persistence are the consumer's responsibility.
+
+## Status
+
+v0.1.0 covers `GeodesicSplitter`. `WatershedSplitter` and `NoopSplitter` ship
+as small reference impls demonstrating the protocol; production-quality
+parity with geodesic is out of scope for v0.1.0.
+
+## License
+
+MIT.

supervoxel_splitter-0.1.0/README.md

@@ -0,0 +1,83 @@
+# supervoxel-splitter
+
+[![codecov](https://codecov.io/gh/CAVEconnectome/supervoxel-splitter/graph/badge.svg)](https://codecov.io/gh/CAVEconnectome/supervoxel-splitter)
+
+Pluggable supervoxel-splitting algorithms behind a uniform `Splitter` interface.
+
+## What it does
+
+Given a 3-D foreground mask, source seeds, and sink seeds, return a labeled
+volume that partitions the foreground into a source side and a sink side.
+Useful for proofreading workflows that need to split a single supervoxel
+without touching the rest of the segmentation.
+
+The package ships multiple techniques behind the same `Splitter` protocol:
+
+- **GeodesicSplitter** — anisotropic geodesic carve via an EDT-derived speed
+  field. Default technique; preserves the neck-aware behavior used in
+  PyChunkedGraph today.
+- **WatershedSplitter** — seeded watershed on the distance transform.
+- **NoopSplitter** — reference implementation; documents the protocol shape
+  for downstream plugin authors (e.g. a learned splitter).
+
+## Install
+
+Requires Python 3.14 or newer.
+
+```
+pip install supervoxel-splitter           # core
+pip install "supervoxel-splitter[fast]"   # adds dijkstra3d as the geodesic backend
+```
+
+## The uniform interface
+
+Every splitter satisfies the same `Splitter` protocol. Technique-specific
+knobs live on the constructor; `split()` itself stays clean.
+
+```python
+from supervoxel_splitter import GeodesicSplitter
+
+splitter = GeodesicSplitter(backend="dj3d")
+result = splitter.split(
+    mask=foreground_3d_bool,
+    sources=src_seeds_xyz,
+    sinks=snk_seeds_xyz,
+    voxel_size=(4.0, 4.0, 40.0),
+)
+
+# result.labels: uint8 in {0, SOURCE, SINK, STRAY}
+# result.side_of_label: {SOURCE: 1, SINK: 2}
+# result.diagnostics: per-stage timings, label counts, etc.
+```
+
+Plugin authors implement the protocol structurally — no base class to
+inherit:
+
+```python
+class MyLearnedSplitter:
+    def __init__(self, *, model_path):
+        ...
+    def split(self, mask, sources, sinks, *,
+              voxel_size=(1.0, 1.0, 1.0),
+              vol_order="xyz", vox_order="xyz", seed_order="xyz"):
+        ...
+        return SplitResult(...)
+
+assert isinstance(MyLearnedSplitter(model_path="..."), Splitter)
+```
+
+## Boundary
+
+The package knows nothing about ChunkedGraph, BigTable, IDs, or edges. It
+takes voxels in and gives labels back. New-ID minting, edge updates, and
+persistence are the consumer's responsibility.
+
+## Status
+
+v0.1.0 covers `GeodesicSplitter`. `WatershedSplitter` and `NoopSplitter` ship
+as small reference impls demonstrating the protocol; production-quality
+parity with geodesic is out of scope for v0.1.0.
+
+## License
+
+MIT.

supervoxel_splitter-0.1.0/codecov.yml

@@ -0,0 +1,11 @@
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 1%
+        informational: true
+    patch:
+      default:
+        target: 75%
+        informational: true

supervoxel_splitter-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=64", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "supervoxel-splitter"
+dynamic = ["version"]
+requires-python = ">=3.14"
+description = "Pluggable supervoxel splitting algorithms with a uniform interface."
+readme = "README.md"
+license = { file = "LICENSE" }
+keywords = [
+    "connectomics",
+    "segmentation",
+    "supervoxel",
+    "watershed",
+    "geodesic",
+    "image-processing",
+]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "numpy",
+    "scipy>=1.6",
+    "fastremap",
+    "connected-components-3d",
+    "scikit-image",
+    "edt",
+]
+
+[project.urls]
+Homepage = "https://github.com/CAVEconnectome/supervoxel-splitter"
+Issues = "https://github.com/CAVEconnectome/supervoxel-splitter/issues"
+Source = "https://github.com/CAVEconnectome/supervoxel-splitter"
+
+[project.optional-dependencies]
+fast = ["dijkstra3d"]
+learned = []
+dev = ["pytest", "pytest-cov", "black", "pre-commit", "build"]
+
+[tool.setuptools.packages.find]
+include = ["supervoxel_splitter*"]
+
+[tool.setuptools_scm]
+fallback_version = "0.0.0.dev0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

supervoxel_splitter-0.1.0/setup.cfg

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

supervoxel_splitter-0.1.0/supervoxel_splitter/__init__.py

@@ -0,0 +1,29 @@
+"""Pluggable supervoxel-splitting algorithms behind a uniform `Splitter`
+protocol. See `api.py` for the protocol shapes and `state.py` for
+`SplitResult`.
+"""
+
+from .api import (
+    SOURCE,
+    SINK,
+    STRAY,
+    Splitter,
+    SeedPrep,
+)
+from .geodesic import GeodesicSplitter, RidgeConnectPrep
+from .learned import NoopSplitter
+from .state import SplitResult
+from .watershed import WatershedSplitter
+
+__all__ = [
+    "SOURCE",
+    "SINK",
+    "STRAY",
+    "Splitter",
+    "SeedPrep",
+    "SplitResult",
+    "GeodesicSplitter",
+    "RidgeConnectPrep",
+    "WatershedSplitter",
+    "NoopSplitter",
+]