dcccpy 0.3.0a3__tar.gz → 0.3.0a4__tar.gz

{dcccpy-0.3.0a3/src/dcccpy.egg-info → dcccpy-0.3.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dcccpy
-Version: 0.3.0a3
+Version: 0.3.0a4
 Summary: Python wrapper for the DCCCcore PET biomarker command-line tool
 Author: DCCCSlicer contributors
 License-Expression: CC-BY-NC-ND-4.0
@@ -17,20 +17,50 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: nibabel>=5
 Provides-Extra: linux-runtime
-Requires-Dist: dcccpy-linux-runtime==0.2.0a2; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "linux-runtime"
-Requires-Dist: dcccpy-linux-arm64-runtime==0.2.0a2; (sys_platform == "linux" and platform_machine == "aarch64") and extra == "linux-runtime"
+Requires-Dist: dcccpy-linux-runtime==0.2.0a3; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "linux-runtime"
+Requires-Dist: dcccpy-linux-arm64-runtime==0.2.0a3; (sys_platform == "linux" and platform_machine == "aarch64") and extra == "linux-runtime"
 Provides-Extra: windows-runtime
-Requires-Dist: dcccpy-windows-runtime==0.2.0a2; (sys_platform == "win32" and platform_machine == "AMD64") and extra == "windows-runtime"
+Requires-Dist: dcccpy-windows-runtime==0.2.0a3; (sys_platform == "win32" and platform_machine == "AMD64") and extra == "windows-runtime"
 Provides-Extra: macos-runtime
-Requires-Dist: dcccpy-macos-runtime==0.2.0a2; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "macos-runtime"
+Requires-Dist: dcccpy-macos-runtime==0.2.0a3; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "macos-runtime"
 Provides-Extra: runtime
-Requires-Dist: dcccpy-linux-runtime==0.2.0a2; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "runtime"
-Requires-Dist: dcccpy-linux-arm64-runtime==0.2.0a2; (sys_platform == "linux" and platform_machine == "aarch64") and extra == "runtime"
-Requires-Dist: dcccpy-windows-runtime==0.2.0a2; (sys_platform == "win32" and platform_machine == "AMD64") and extra == "runtime"
-Requires-Dist: dcccpy-macos-runtime==0.2.0a2; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "runtime"
+Requires-Dist: dcccpy-linux-runtime==0.2.0a3; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "runtime"
+Requires-Dist: dcccpy-linux-arm64-runtime==0.2.0a3; (sys_platform == "linux" and platform_machine == "aarch64") and extra == "runtime"
+Requires-Dist: dcccpy-windows-runtime==0.2.0a3; (sys_platform == "win32" and platform_machine == "AMD64") and extra == "runtime"
+Requires-Dist: dcccpy-macos-runtime==0.2.0a3; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "runtime"
 
 # dcccpy
 
+### Native PET segmentation
+
+```python
+import dcccpy
+result = dcccpy.seg("pet.nii.gz", "labels.nii.gz")
+labels = result.load_output()
+```
+
+Requires a DCCCcore build containing the `seg` command and its bundled model.
+The signed integer output matches the input PET's native shape and geometry.
+The default `mode="freesurfer"` returns raw DKT/aseg IDs; `mode="training"`
+returns IDs 0–95. `mode="neurosegmenter"` provides partial regional compatibility:
+brainstem/pons IDs 45/46 are unavailable, so pons SUVR is unsupported.
+Mirror TTA is enabled by default; `tta=False` explicitly changes that protocol.
+Use `threads=4` to select the CPU thread count, `bundle=...` to override the model
+directory, and `debug=True` to save intermediate grids and a transform receipt.
+The approximately 120 MB segmentation model is excluded from PyPI wheels.
+With a slim runtime, the first `seg()` call downloads the separately published
+`DCCCseg-4.6.0-alpha.zip` Release asset, verifies the model SHA-256 and caches it
+under the dcccpy cache directory. A full native installation reuses its bundled
+model. Existing `DCCCPY_AUTO_DOWNLOAD=0` disables implicit downloads; provision
+offline use with `dcccpy.download_seg_model()` or pass `bundle=` pointing to
+the extracted `seg` directory. `DCCCPY_SEG_MODEL_URL` selects a mirror while
+retaining checksum verification.
+An explicit `config=` delegates model selection to that configuration and
+suppresses default-model provisioning. With a slim runtime and a configuration
+that only changes other settings, also pass `bundle=dcccpy.download_seg_model()`.
+An optional `rigid_header=...` must retain the exact native PET values and record
+exactly two rigid steps. Existing output images are refused by the core.
+
 `dcccpy` is a Python wrapper for the `DCCCcore` command-line tool from
 DCCCSlicer. It keeps the native C++ core as the execution engine and provides a
 small Python API for running common PET biomarker workflows.
@@ -212,7 +242,7 @@ the calculation again.
 Release wheels should vendor the matching `DCCCcore` runtime tree before build:
 
 ```bash
-python scripts/vendor_dccccore.py --version 4.5.1-alpha --release-platform ubuntu-latest-x64
+python scripts/vendor_dccccore.py --version 4.6.0-alpha --release-platform ubuntu-latest-x64
 python -m build --wheel
 ```
 
@@ -220,7 +250,7 @@ The Linux ARM64 runtime package uses the corresponding release asset:
 
 ```bash
 cd python/dcccpy-linux-arm64-runtime
-python scripts/vendor_dccccore.py --version 4.5.1-alpha --release-platform ubuntu-latest-arm64
+python scripts/vendor_dccccore.py --version 4.6.0-alpha --release-platform ubuntu-latest-arm64
 python -m build --wheel
 ```
 
@@ -238,7 +268,7 @@ The preferred distribution layout is:
 
 ## Packaging note
 
-The current optional runtime wheels use a PyPI-size profile for DCCCcore version 4.5.1-alpha. They omit the
+The current optional runtime wheels use a PyPI-size profile for DCCCcore version 4.6.0-alpha. They omit the
 `fast_and_acc` registration model/config and the ADAD decoupler ONNX ensemble,
 while keeping the default spatial normalization model and assets needed by
 common Centiloid/CenTauR/CenTauRz workflows.

{dcccpy-0.3.0a3 → dcccpy-0.3.0a4}/README.md

@@ -1,5 +1,35 @@
 # dcccpy
 
+### Native PET segmentation
+
+```python
+import dcccpy
+result = dcccpy.seg("pet.nii.gz", "labels.nii.gz")
+labels = result.load_output()
+```
+
+Requires a DCCCcore build containing the `seg` command and its bundled model.
+The signed integer output matches the input PET's native shape and geometry.
+The default `mode="freesurfer"` returns raw DKT/aseg IDs; `mode="training"`
+returns IDs 0–95. `mode="neurosegmenter"` provides partial regional compatibility:
+brainstem/pons IDs 45/46 are unavailable, so pons SUVR is unsupported.
+Mirror TTA is enabled by default; `tta=False` explicitly changes that protocol.
+Use `threads=4` to select the CPU thread count, `bundle=...` to override the model
+directory, and `debug=True` to save intermediate grids and a transform receipt.
+The approximately 120 MB segmentation model is excluded from PyPI wheels.
+With a slim runtime, the first `seg()` call downloads the separately published
+`DCCCseg-4.6.0-alpha.zip` Release asset, verifies the model SHA-256 and caches it
+under the dcccpy cache directory. A full native installation reuses its bundled
+model. Existing `DCCCPY_AUTO_DOWNLOAD=0` disables implicit downloads; provision
+offline use with `dcccpy.download_seg_model()` or pass `bundle=` pointing to
+the extracted `seg` directory. `DCCCPY_SEG_MODEL_URL` selects a mirror while
+retaining checksum verification.
+An explicit `config=` delegates model selection to that configuration and
+suppresses default-model provisioning. With a slim runtime and a configuration
+that only changes other settings, also pass `bundle=dcccpy.download_seg_model()`.
+An optional `rigid_header=...` must retain the exact native PET values and record
+exactly two rigid steps. Existing output images are refused by the core.
+
 `dcccpy` is a Python wrapper for the `DCCCcore` command-line tool from
 DCCCSlicer. It keeps the native C++ core as the execution engine and provides a
 small Python API for running common PET biomarker workflows.
@@ -181,7 +211,7 @@ the calculation again.
 Release wheels should vendor the matching `DCCCcore` runtime tree before build:
 
 ```bash
-python scripts/vendor_dccccore.py --version 4.5.1-alpha --release-platform ubuntu-latest-x64
+python scripts/vendor_dccccore.py --version 4.6.0-alpha --release-platform ubuntu-latest-x64
 python -m build --wheel
 ```
 
@@ -189,7 +219,7 @@ The Linux ARM64 runtime package uses the corresponding release asset:
 
 ```bash
 cd python/dcccpy-linux-arm64-runtime
-python scripts/vendor_dccccore.py --version 4.5.1-alpha --release-platform ubuntu-latest-arm64
+python scripts/vendor_dccccore.py --version 4.6.0-alpha --release-platform ubuntu-latest-arm64
 python -m build --wheel
 ```
 
@@ -207,7 +237,7 @@ The preferred distribution layout is:
 
 ## Packaging note
 
-The current optional runtime wheels use a PyPI-size profile for DCCCcore version 4.5.1-alpha. They omit the
+The current optional runtime wheels use a PyPI-size profile for DCCCcore version 4.6.0-alpha. They omit the
 `fast_and_acc` registration model/config and the ADAD decoupler ONNX ensemble,
 while keeping the default spatial normalization model and assets needed by
 common Centiloid/CenTauR/CenTauRz workflows.

{dcccpy-0.3.0a3 → dcccpy-0.3.0a4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dcccpy"
-version = "0.3.0a3"
+version = "0.3.0a4"
 description = "Python wrapper for the DCCCcore PET biomarker command-line tool"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -31,16 +31,16 @@ Issues = "https://github.com/tctco/DCCCSlicer/issues"
 
 [project.optional-dependencies]
 linux-runtime = [
-  "dcccpy-linux-runtime==0.2.0a2; sys_platform == 'linux' and platform_machine == 'x86_64'",
-  "dcccpy-linux-arm64-runtime==0.2.0a2; sys_platform == 'linux' and platform_machine == 'aarch64'",
+  "dcccpy-linux-runtime==0.2.0a3; sys_platform == 'linux' and platform_machine == 'x86_64'",
+  "dcccpy-linux-arm64-runtime==0.2.0a3; sys_platform == 'linux' and platform_machine == 'aarch64'",
 ]
-windows-runtime = ["dcccpy-windows-runtime==0.2.0a2; sys_platform == 'win32' and platform_machine == 'AMD64'"]
-macos-runtime = ["dcccpy-macos-runtime==0.2.0a2; sys_platform == 'darwin' and platform_machine == 'arm64'"]
+windows-runtime = ["dcccpy-windows-runtime==0.2.0a3; sys_platform == 'win32' and platform_machine == 'AMD64'"]
+macos-runtime = ["dcccpy-macos-runtime==0.2.0a3; sys_platform == 'darwin' and platform_machine == 'arm64'"]
 runtime = [
-  "dcccpy-linux-runtime==0.2.0a2; sys_platform == 'linux' and platform_machine == 'x86_64'",
-  "dcccpy-linux-arm64-runtime==0.2.0a2; sys_platform == 'linux' and platform_machine == 'aarch64'",
-  "dcccpy-windows-runtime==0.2.0a2; sys_platform == 'win32' and platform_machine == 'AMD64'",
-  "dcccpy-macos-runtime==0.2.0a2; sys_platform == 'darwin' and platform_machine == 'arm64'",
+  "dcccpy-linux-runtime==0.2.0a3; sys_platform == 'linux' and platform_machine == 'x86_64'",
+  "dcccpy-linux-arm64-runtime==0.2.0a3; sys_platform == 'linux' and platform_machine == 'aarch64'",
+  "dcccpy-windows-runtime==0.2.0a3; sys_platform == 'win32' and platform_machine == 'AMD64'",
+  "dcccpy-macos-runtime==0.2.0a3; sys_platform == 'darwin' and platform_machine == 'arm64'",
 ]
 
 [project.scripts]

{dcccpy-0.3.0a3 → dcccpy-0.3.0a4}/src/dcccpy/__init__.py

@@ -15,12 +15,16 @@ from .core import (
     parse_metrics,
     pet_motion_correct,
     rigid,
+    seg,
     run,
     suvr,
 )
 from .runtime import DCCCCORE_VERSION, DCCCcoreDownloadError, DCCCcoreNotFoundError, download_dccccore
+from .segmentation import SegModelDownloadError, download_seg_model
 
 __all__ = [
+    "SegModelDownloadError",
+    "download_seg_model",
     "DCCCResult",
     "DCCCCORE_VERSION",
     "DCCCcoreDownloadError",
@@ -39,6 +43,7 @@ __all__ = [
     "parse_metrics",
     "pet_motion_correct",
     "rigid",
+    "seg",
     "run",
     "suvr",
 ]

{dcccpy-0.3.0a3 → dcccpy-0.3.0a4}/src/dcccpy/core.py

@@ -443,6 +443,48 @@ def rigid(
     return _spatial_command("rigid", input, output, **kwargs)
 
 
+def seg(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    *,
+    mode: str = "freesurfer",
+    threads: int = 4,
+    tta: bool = True,
+    bundle: str | os.PathLike[str] | None = None,
+    rigid_header: str | os.PathLike[str] | None = None,
+    debug: bool = False,
+    config: str | os.PathLike[str] | None = None,
+    check: bool = True,
+    executable: str | os.PathLike[str] | None = None,
+) -> DCCCResult:
+    """Segment one 3-D PET into native-space categorical labels.
+
+    ``freesurfer`` emits raw DKT/aseg IDs, ``training`` IDs 0–95, and
+    ``neurosegmenter`` a partial aggregation without brainstem/pons IDs 45/46.
+    Mirror TTA is enabled by default. ``rigid_header``, when supplied, must
+    retain the input's voxel values after exactly two rigid predictions.
+    """
+    if mode not in ("freesurfer", "training", "neurosegmenter"):
+        raise ValueError("mode must be freesurfer, training, or neurosegmenter")
+    if isinstance(threads, bool) or not isinstance(threads, int) or threads < 1:
+        raise ValueError("threads must be a positive integer")
+    if bundle is None and config is None:
+        from .segmentation import default_seg_bundle
+        executable = dccccore_path(executable=executable)
+        bundle = default_seg_bundle(executable)
+    args: list[object] = ["--mode", mode, "--threads", threads]
+    if not tta:
+        args.append("--no-tta")
+    if debug:
+        args.append("--debug")
+    for flag, path in (("--bundle", bundle), ("--rigid-header", rigid_header),
+                       ("--config", config)):
+        if path is not None:
+            args.extend([flag, _resolve_user_path(path)])
+    return _spatial_command("seg", input, output, extra_args=args,
+                            check=check, executable=executable)
+
+
 def pet_motion_correct(
     input: object,
     output: str | os.PathLike[str] | None = None,

{dcccpy-0.3.0a3 → dcccpy-0.3.0a4}/src/dcccpy/runtime.py

@@ -12,7 +12,7 @@ from pathlib import Path
 from typing import Iterable
 
 
-DCCCCORE_VERSION = "4.5.1-alpha"
+DCCCCORE_VERSION = "4.6.0-alpha"
 RELEASE_REPO = "tctco/DCCCSlicer"
 
 

dcccpy-0.3.0a4/src/dcccpy/segmentation.py

@@ -0,0 +1,123 @@
+"""Optional DCCC Seg model delivery, kept outside PyPI wheels."""
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path, PurePosixPath
+import re
+import shutil
+import stat
+import tempfile
+import urllib.request
+import zipfile
+
+from .runtime import DCCCCORE_VERSION, RELEASE_REPO, auto_download_enabled, cache_root
+
+
+SEG_MODEL_SHA256 = "8ea46dc8eff44e7a6c55b93ec9a353eb676692741d56a47b04c755a3c956faf6"
+MODEL_FILES = ("dccc_seg.onnx", "manifest.json", "grid.json", "plans.json", "dataset.json",
+               "labels.json", "neurosegmenter_mapping.json", "validation.json")
+
+
+class SegModelDownloadError(RuntimeError):
+    """The optional segmentation model could not be provisioned."""
+
+
+def seg_model_dir(version: str = DCCCCORE_VERSION) -> Path:
+    if not re.fullmatch(r"\d+\.\d+\.\d+(?:-[A-Za-z0-9.]+)?", version):
+        raise ValueError("Invalid segmentation model version")
+    return cache_root() / "models" / "seg" / version
+
+
+def _complete(directory: Path) -> bool:
+    return all((directory / name).is_file() for name in MODEL_FILES)
+
+
+def _verified(directory: Path) -> bool:
+    if not _complete(directory):
+        return False
+    digest = hashlib.sha256()
+    with (directory / "dccc_seg.onnx").open("rb") as source:
+        for chunk in iter(lambda: source.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest() == SEG_MODEL_SHA256
+
+
+def download_seg_model(*, version: str = DCCCCORE_VERSION, force: bool = False) -> Path:
+    """Download and verify the optional model; return its cached bundle directory.
+
+    An explicit call provisions offline use even with DCCCPY_AUTO_DOWNLOAD=0.
+    DCCCPY_SEG_MODEL_URL can select a mirrored archive; the model SHA-256 is
+    still enforced. force=True replaces this version's model cache only.
+    """
+    destination = seg_model_dir(version)
+    if not force and _verified(destination):
+        return destination
+    if destination.exists() and not force:
+        raise SegModelDownloadError("Cached segmentation model is incomplete or corrupt; "
+                                    "call download_seg_model(force=True) to repair it")
+    repo = os.environ.get("DCCCPY_RELEASE_REPO", RELEASE_REPO)
+    url = os.environ.get("DCCCPY_SEG_MODEL_URL") or (
+        f"https://github.com/{repo}/releases/download/v{version}/DCCCseg-{version}.zip")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with tempfile.TemporaryDirectory(prefix=".seg-download-", dir=destination.parent) as temporary:
+            temporary = Path(temporary)
+            archive = temporary / "model.zip"
+            with urllib.request.urlopen(url, timeout=120) as response, archive.open("wb") as output:
+                # Bound compressed downloads as well as extracted size.
+                total = 0
+                while True:
+                    chunk = response.read(1024 * 1024)
+                    if not chunk:
+                        break
+                    total += len(chunk)
+                    if total > 200 * 1024 * 1024:
+                        raise SegModelDownloadError("Segmentation model archive exceeds size limit")
+                    output.write(chunk)
+            with zipfile.ZipFile(archive) as source:
+                total = 0
+                for member in source.infolist():
+                    path = PurePosixPath(member.filename)
+                    if (path.is_absolute() or ".." in path.parts or "\\" in member.filename
+                            or not path.parts or path.parts[0] != "seg"
+                            or stat.S_ISLNK(member.external_attr >> 16)):
+                        raise SegModelDownloadError("Unsafe segmentation model archive path")
+                    total += member.file_size
+                    if total > 200 * 1024 * 1024:
+                        raise SegModelDownloadError("Segmentation model expands beyond size limit")
+                for name in MODEL_FILES:
+                    output = temporary / "seg" / name
+                    output.parent.mkdir(parents=True, exist_ok=True)
+                    with source.open("seg/" + name) as handle, output.open("xb") as target:
+                        shutil.copyfileobj(handle, target)
+            staged = temporary / "seg"
+            if not _verified(staged):
+                raise SegModelDownloadError("Segmentation model SHA-256 mismatch")
+            if force and destination.exists():
+                shutil.rmtree(destination)
+            try:
+                staged.rename(destination)
+            except OSError:
+                # Another process may have finished the same version concurrently.
+                if not _verified(destination):
+                    raise
+        return destination
+    except SegModelDownloadError:
+        raise
+    except Exception as exc:
+        raise SegModelDownloadError("Cannot download the DCCC Seg model; provide bundle= with "
+                                    "an extracted DCCCseg Release asset for offline use") from exc
+
+
+def default_seg_bundle(executable: Path) -> Path | None:
+    """Return None for a full native installation, otherwise provision its model."""
+    if _complete(Path(executable).resolve().parent / "assets/models/seg"):
+        return None
+    destination = seg_model_dir()
+    if _verified(destination):
+        return destination
+    if not auto_download_enabled():
+        raise SegModelDownloadError("Segmentation model is absent and automatic download is disabled; "
+                                    "pass bundle= or call download_seg_model() explicitly")
+    return download_seg_model()

{dcccpy-0.3.0a3 → dcccpy-0.3.0a4/src/dcccpy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dcccpy
-Version: 0.3.0a3
+Version: 0.3.0a4
 Summary: Python wrapper for the DCCCcore PET biomarker command-line tool
 Author: DCCCSlicer contributors
 License-Expression: CC-BY-NC-ND-4.0
@@ -17,20 +17,50 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: nibabel>=5
 Provides-Extra: linux-runtime
-Requires-Dist: dcccpy-linux-runtime==0.2.0a2; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "linux-runtime"
-Requires-Dist: dcccpy-linux-arm64-runtime==0.2.0a2; (sys_platform == "linux" and platform_machine == "aarch64") and extra == "linux-runtime"
+Requires-Dist: dcccpy-linux-runtime==0.2.0a3; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "linux-runtime"
+Requires-Dist: dcccpy-linux-arm64-runtime==0.2.0a3; (sys_platform == "linux" and platform_machine == "aarch64") and extra == "linux-runtime"
 Provides-Extra: windows-runtime
-Requires-Dist: dcccpy-windows-runtime==0.2.0a2; (sys_platform == "win32" and platform_machine == "AMD64") and extra == "windows-runtime"
+Requires-Dist: dcccpy-windows-runtime==0.2.0a3; (sys_platform == "win32" and platform_machine == "AMD64") and extra == "windows-runtime"
 Provides-Extra: macos-runtime
-Requires-Dist: dcccpy-macos-runtime==0.2.0a2; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "macos-runtime"
+Requires-Dist: dcccpy-macos-runtime==0.2.0a3; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "macos-runtime"
 Provides-Extra: runtime
-Requires-Dist: dcccpy-linux-runtime==0.2.0a2; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "runtime"
-Requires-Dist: dcccpy-linux-arm64-runtime==0.2.0a2; (sys_platform == "linux" and platform_machine == "aarch64") and extra == "runtime"
-Requires-Dist: dcccpy-windows-runtime==0.2.0a2; (sys_platform == "win32" and platform_machine == "AMD64") and extra == "runtime"
-Requires-Dist: dcccpy-macos-runtime==0.2.0a2; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "runtime"
+Requires-Dist: dcccpy-linux-runtime==0.2.0a3; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "runtime"
+Requires-Dist: dcccpy-linux-arm64-runtime==0.2.0a3; (sys_platform == "linux" and platform_machine == "aarch64") and extra == "runtime"
+Requires-Dist: dcccpy-windows-runtime==0.2.0a3; (sys_platform == "win32" and platform_machine == "AMD64") and extra == "runtime"
+Requires-Dist: dcccpy-macos-runtime==0.2.0a3; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "runtime"
 
 # dcccpy
 
+### Native PET segmentation
+
+```python
+import dcccpy
+result = dcccpy.seg("pet.nii.gz", "labels.nii.gz")
+labels = result.load_output()
+```
+
+Requires a DCCCcore build containing the `seg` command and its bundled model.
+The signed integer output matches the input PET's native shape and geometry.
+The default `mode="freesurfer"` returns raw DKT/aseg IDs; `mode="training"`
+returns IDs 0–95. `mode="neurosegmenter"` provides partial regional compatibility:
+brainstem/pons IDs 45/46 are unavailable, so pons SUVR is unsupported.
+Mirror TTA is enabled by default; `tta=False` explicitly changes that protocol.
+Use `threads=4` to select the CPU thread count, `bundle=...` to override the model
+directory, and `debug=True` to save intermediate grids and a transform receipt.
+The approximately 120 MB segmentation model is excluded from PyPI wheels.
+With a slim runtime, the first `seg()` call downloads the separately published
+`DCCCseg-4.6.0-alpha.zip` Release asset, verifies the model SHA-256 and caches it
+under the dcccpy cache directory. A full native installation reuses its bundled
+model. Existing `DCCCPY_AUTO_DOWNLOAD=0` disables implicit downloads; provision
+offline use with `dcccpy.download_seg_model()` or pass `bundle=` pointing to
+the extracted `seg` directory. `DCCCPY_SEG_MODEL_URL` selects a mirror while
+retaining checksum verification.
+An explicit `config=` delegates model selection to that configuration and
+suppresses default-model provisioning. With a slim runtime and a configuration
+that only changes other settings, also pass `bundle=dcccpy.download_seg_model()`.
+An optional `rigid_header=...` must retain the exact native PET values and record
+exactly two rigid steps. Existing output images are refused by the core.
+
 `dcccpy` is a Python wrapper for the `DCCCcore` command-line tool from
 DCCCSlicer. It keeps the native C++ core as the execution engine and provides a
 small Python API for running common PET biomarker workflows.
@@ -212,7 +242,7 @@ the calculation again.
 Release wheels should vendor the matching `DCCCcore` runtime tree before build:
 
 ```bash
-python scripts/vendor_dccccore.py --version 4.5.1-alpha --release-platform ubuntu-latest-x64
+python scripts/vendor_dccccore.py --version 4.6.0-alpha --release-platform ubuntu-latest-x64
 python -m build --wheel
 ```
 
@@ -220,7 +250,7 @@ The Linux ARM64 runtime package uses the corresponding release asset:
 
 ```bash
 cd python/dcccpy-linux-arm64-runtime
-python scripts/vendor_dccccore.py --version 4.5.1-alpha --release-platform ubuntu-latest-arm64
+python scripts/vendor_dccccore.py --version 4.6.0-alpha --release-platform ubuntu-latest-arm64
 python -m build --wheel
 ```
 
@@ -238,7 +268,7 @@ The preferred distribution layout is:
 
 ## Packaging note
 
-The current optional runtime wheels use a PyPI-size profile for DCCCcore version 4.5.1-alpha. They omit the
+The current optional runtime wheels use a PyPI-size profile for DCCCcore version 4.6.0-alpha. They omit the
 `fast_and_acc` registration model/config and the ADAD decoupler ONNX ensemble,
 while keeping the default spatial normalization model and assets needed by
 common Centiloid/CenTauR/CenTauRz workflows.

{dcccpy-0.3.0a3 → dcccpy-0.3.0a4}/src/dcccpy.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/dcccpy/cli.py
 src/dcccpy/core.py
 src/dcccpy/py.typed
 src/dcccpy/runtime.py
+src/dcccpy/segmentation.py
 src/dcccpy.egg-info/PKG-INFO
 src/dcccpy.egg-info/SOURCES.txt
 src/dcccpy.egg-info/dependency_links.txt
@@ -14,4 +15,5 @@ src/dcccpy.egg-info/entry_points.txt
 src/dcccpy.egg-info/requires.txt
 src/dcccpy.egg-info/top_level.txt
 tests/test_core.py
+tests/test_seg_distribution.py
 tests/test_testpypi_centiloid.py

{dcccpy-0.3.0a3 → dcccpy-0.3.0a4}/src/dcccpy.egg-info/requires.txt

@@ -3,31 +3,31 @@ nibabel>=5
 [linux-runtime]
 
 [linux-runtime:sys_platform == "linux" and platform_machine == "aarch64"]
-dcccpy-linux-arm64-runtime==0.2.0a2
+dcccpy-linux-arm64-runtime==0.2.0a3
 
 [linux-runtime:sys_platform == "linux" and platform_machine == "x86_64"]
-dcccpy-linux-runtime==0.2.0a2
+dcccpy-linux-runtime==0.2.0a3
 
 [macos-runtime]
 
 [macos-runtime:sys_platform == "darwin" and platform_machine == "arm64"]
-dcccpy-macos-runtime==0.2.0a2
+dcccpy-macos-runtime==0.2.0a3
 
 [runtime]
 
 [runtime:sys_platform == "darwin" and platform_machine == "arm64"]
-dcccpy-macos-runtime==0.2.0a2
+dcccpy-macos-runtime==0.2.0a3
 
 [runtime:sys_platform == "linux" and platform_machine == "aarch64"]
-dcccpy-linux-arm64-runtime==0.2.0a2
+dcccpy-linux-arm64-runtime==0.2.0a3
 
 [runtime:sys_platform == "linux" and platform_machine == "x86_64"]
-dcccpy-linux-runtime==0.2.0a2
+dcccpy-linux-runtime==0.2.0a3
 
 [runtime:sys_platform == "win32" and platform_machine == "AMD64"]
-dcccpy-windows-runtime==0.2.0a2
+dcccpy-windows-runtime==0.2.0a3
 
 [windows-runtime]
 
 [windows-runtime:sys_platform == "win32" and platform_machine == "AMD64"]
-dcccpy-windows-runtime==0.2.0a2
+dcccpy-windows-runtime==0.2.0a3

{dcccpy-0.3.0a3 → dcccpy-0.3.0a4}/tests/test_core.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import subprocess
 from pathlib import Path
 import sys
 import types
@@ -20,6 +21,11 @@ from dcccpy.runtime import (
 
 
 def make_fake_dccccore(tmp_path: Path) -> Path:
+    bundle = tmp_path / "assets/models/seg"
+    bundle.mkdir(parents=True, exist_ok=True)
+    for name in ("dccc_seg.onnx", "manifest.json", "grid.json", "plans.json", "dataset.json",
+                 "labels.json", "neurosegmenter_mapping.json", "validation.json"):
+        (bundle / name).write_bytes(b"test runtime resource")
     exe = tmp_path / "DCCCcore"
     exe.write_text(
         "#!/usr/bin/env sh\n"
@@ -46,6 +52,66 @@ def test_parse_metrics() -> None:
     assert metrics == {"fbp": 12.5, "SUVr": 1.23, "ADAD score": -0.2}
 
 
+def test_seg_defaults_and_explicit_options(tmp_path, monkeypatch):
+    fake_args = tmp_path / "args.txt"
+    fake_exe = make_fake_dccccore(tmp_path)
+    monkeypatch.setenv("DCCCPY_FAKE_ARGS", str(fake_args))
+    result = dcccpy.seg("pet.nii", executable=fake_exe)
+    args = fake_args.read_text().splitlines()
+    assert args[0] == "seg"
+    assert args[args.index("--mode") + 1] == "freesurfer"
+    assert args[args.index("--threads") + 1] == "4"
+    assert "--no-tta" not in args
+    assert result.output.exists()
+    result = dcccpy.seg("pet.nii", tmp_path / "labels.nii.gz", mode="training",
+                        threads=2, tta=False, bundle="model bundle",
+                        rigid_header="rigid header.nii.gz", config="config.toml",
+                        debug=True, executable=fake_exe)
+    args = fake_args.read_text().splitlines()
+    assert args[args.index("--mode") + 1] == "training"
+    assert args[args.index("--threads") + 1] == "2"
+    assert args[args.index("--bundle") + 1] == str(Path("model bundle").resolve())
+    assert args[args.index("--rigid-header") + 1] == str(Path("rigid header.nii.gz").resolve())
+    assert args[args.index("--config") + 1] == str(Path("config.toml").resolve())
+    assert "--debug" in args and "--no-tta" in args
+
+
+@pytest.mark.parametrize("kwargs", [{"mode": "bogus"}, {"threads": 0},
+                                    {"threads": 1.5}, {"threads": True}])
+def test_seg_rejects_bad_options(kwargs):
+    with pytest.raises(ValueError):
+        dcccpy.seg("pet.nii", **kwargs)
+
+
+def test_seg_preserves_native_failure(tmp_path):
+    exe = make_fake_dccccore(tmp_path)
+    exe.write_text("#!/bin/sh\nprintf 'invalid segmentation model' >&2\nexit 7\n")
+    exe.chmod(0o755)
+    result = dcccpy.seg("pet.nii", check=False, executable=exe)
+    assert result.returncode == 7
+    assert "invalid segmentation model" in result.stderr
+    assert not result.output.exists()
+    with pytest.raises(subprocess.CalledProcessError) as error:
+        dcccpy.seg("pet.nii", executable=exe)
+    assert error.value.returncode == 7
+
+
+def test_seg_custom_config_does_not_provision_or_override_model(tmp_path, monkeypatch):
+    exe = make_fake_dccccore(tmp_path)
+    (tmp_path / "assets/models/seg/dccc_seg.onnx").unlink()
+    args_file = tmp_path / "args.txt"
+    monkeypatch.setenv("DCCCPY_FAKE_ARGS", str(args_file))
+    monkeypatch.setenv("DCCCPY_AUTO_DOWNLOAD", "0")
+    monkeypatch.setenv("DCCCPY_CACHE_DIR", str(tmp_path / "empty-cache"))
+    config = tmp_path / "custom.toml"
+    config.write_text('[models]\nseg = "offline/custom/dccc_seg.onnx"\n')
+    result = dcccpy.seg("pet.nii", config=config, executable=exe)
+    assert result.returncode == 0
+    args = args_file.read_text().splitlines()
+    assert args[args.index("--config") + 1] == str(config)
+    assert "--bundle" not in args
+
+
 def test_centiloid_omits_output_by_creating_temp_path(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     fake_args = tmp_path / "args.txt"
     fake_exe = make_fake_dccccore(tmp_path)
@@ -142,7 +208,7 @@ def test_dccccore_path_can_disable_auto_download(tmp_path: Path, monkeypatch: py
 
 
 def test_dccccore_path_auto_downloads_to_cache(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    asset_root = tmp_path / "asset" / "DCCCcore-4.5.1-alpha-ubuntu-latest-x64"
+    asset_root = tmp_path / "asset" / "DCCCcore-4.6.0-alpha-ubuntu-latest-x64"
     asset_root.mkdir(parents=True)
     exe = asset_root / "DCCCcore"
     exe.write_text("#!/usr/bin/env sh\nprintf 'fake dccccore\\n'\n")
@@ -150,7 +216,7 @@ def test_dccccore_path_auto_downloads_to_cache(tmp_path: Path, monkeypatch: pyte
 
     archive = tmp_path / "DCCCcore.zip"
     with zipfile.ZipFile(archive, "w") as zf:
-        zf.write(exe, "DCCCcore-4.5.1-alpha-ubuntu-latest-x64/DCCCcore")
+        zf.write(exe, "DCCCcore-4.6.0-alpha-ubuntu-latest-x64/DCCCcore")
 
     monkeypatch.delenv("DCCCPY_DCCCCORE", raising=False)
     monkeypatch.setenv("DCCCPY_AUTO_DOWNLOAD", "1")
@@ -175,7 +241,7 @@ def test_find_existing_dccccore_checks_macos_runtime_package(
     exe.write_text("#!/usr/bin/env sh\n")
     exe.chmod(0o755)
 
-    module = types.SimpleNamespace(DCCCCORE_VERSION="4.5.1-alpha", dccccore_root=lambda: root)
+    module = types.SimpleNamespace(DCCCCORE_VERSION="4.6.0-alpha", dccccore_root=lambda: root)
     monkeypatch.setitem(sys.modules, "dcccpy_macos_runtime", module)
     monkeypatch.setenv("PATH", str(tmp_path / "empty-path"))
 
@@ -186,10 +252,10 @@ def test_linux_arm64_release_platform() -> None:
     assert release_platform("linux-arm64") == "ubuntu-latest-arm64"
 
 
-def test_default_release_targets_dccccore_450_alpha() -> None:
-    assert DCCCCORE_VERSION == "4.5.1-alpha"
+def test_default_release_targets_dccccore_460_alpha() -> None:
+    assert DCCCCORE_VERSION == "4.6.0-alpha"
     assert release_url(platform_name="ubuntu-latest-x64").endswith(
-        "/releases/download/v4.5.1-alpha/DCCCcore-4.5.1-alpha-ubuntu-latest-x64.zip"
+        "/releases/download/v4.6.0-alpha/DCCCcore-4.6.0-alpha-ubuntu-latest-x64.zip"
     )
 
 
@@ -220,7 +286,7 @@ def test_find_existing_dccccore_checks_linux_arm64_runtime_package(
     exe.write_text("#!/usr/bin/env sh\n")
     exe.chmod(0o755)
 
-    module = types.SimpleNamespace(DCCCCORE_VERSION="4.5.1-alpha", dccccore_root=lambda: root)
+    module = types.SimpleNamespace(DCCCCORE_VERSION="4.6.0-alpha", dccccore_root=lambda: root)
     monkeypatch.setitem(sys.modules, "dcccpy_linux_arm64_runtime", module)
     monkeypatch.setenv("PATH", str(tmp_path / "empty-path"))
 

dcccpy-0.3.0a4/tests/test_seg_distribution.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+from pathlib import Path
+import zipfile
+
+import pytest
+
+
+FILES = ("dccc_seg.onnx", "manifest.json", "grid.json", "plans.json", "dataset.json",
+         "labels.json", "neurosegmenter_mapping.json", "validation.json")
+
+
+def import_script(path):
+    spec = importlib.util.spec_from_file_location("release_script", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.fixture
+def distribution(tmp_path, monkeypatch):
+    import dcccpy.segmentation as model
+    archive = tmp_path / "model.zip"
+    with zipfile.ZipFile(archive, "w") as z:
+        for name in FILES:
+            z.writestr("seg/" + name, b"model" if name.endswith(".onnx") else b"{}")
+    monkeypatch.setenv("DCCCPY_CACHE_DIR", str(tmp_path / "cache"))
+    monkeypatch.setenv("DCCCPY_SEG_MODEL_URL", archive.as_uri())
+    monkeypatch.setattr(model, "SEG_MODEL_SHA256", hashlib.sha256(b"model").hexdigest())
+    return model, archive
+
+
+def test_model_download_is_cached_outside_package(distribution):
+    model, archive = distribution
+    directory = model.download_seg_model()
+    assert directory.name == "4.6.0-alpha"
+    assert (directory / "dccc_seg.onnx").read_bytes() == b"model"
+    archive.unlink()
+    assert model.download_seg_model() == directory
+
+
+@pytest.mark.parametrize("kind", ["digest", "traversal", "missing"])
+def test_model_download_rejects_bad_assets(distribution, kind, tmp_path):
+    model, archive = distribution
+    with zipfile.ZipFile(archive, "w") as z:
+        for name in FILES:
+            if kind == "missing" and name == "labels.json":
+                continue
+            z.writestr("seg/" + name, b"wrong" if kind == "digest" else
+                       (b"model" if name.endswith(".onnx") else b"{}"))
+        if kind == "traversal":
+            z.writestr("../escaped", b"bad")
+    with pytest.raises(model.SegModelDownloadError):
+        model.download_seg_model()
+    assert not (tmp_path / "escaped").exists()
+    assert not model.seg_model_dir().exists()
+
+
+def test_bundled_model_and_download_opt_out(distribution, monkeypatch, tmp_path):
+    model, archive = distribution
+    exe = tmp_path / "native" / "DCCCcore"
+    bundle = exe.parent / "assets/models/seg"
+    bundle.mkdir(parents=True)
+    for name in FILES:
+        (bundle / name).write_bytes(b"model" if name.endswith(".onnx") else b"{}")
+    monkeypatch.setenv("DCCCPY_AUTO_DOWNLOAD", "0")
+    assert model.default_seg_bundle(exe) is None
+    (bundle / "dccc_seg.onnx").unlink()
+    with pytest.raises(model.SegModelDownloadError, match="download"):
+        model.default_seg_bundle(exe)
+    cached = model.download_seg_model()  # Explicit provisioning honors user's call.
+    assert model.default_seg_bundle(exe) == cached
+
+
+def test_native_symlink_reuses_real_bundled_model(distribution, monkeypatch, tmp_path):
+    model, _ = distribution
+    native = tmp_path / "native/DCCCcore"
+    bundle = native.parent / "assets/models/seg"
+    bundle.mkdir(parents=True)
+    native.write_text("native executable")
+    for name in FILES:
+        (bundle / name).write_bytes(b"model" if name.endswith(".onnx") else b"{}")
+    link = tmp_path / "bin/DCCCcore"
+    link.parent.mkdir()
+    link.symlink_to(native)
+    monkeypatch.setenv("DCCCPY_AUTO_DOWNLOAD", "0")
+    assert model.default_seg_bundle(link) is None
+
+
+@pytest.mark.parametrize("package", ["linux", "linux-arm64", "macos", "windows"])
+def test_every_runtime_profile_excludes_seg(tmp_path, package):
+    root = Path(__file__).resolve().parents[3]
+    vendor = import_script(root / f"python/dcccpy-{package}-runtime/scripts/vendor_dccccore.py")
+    for profile in vendor.EXCLUDE_PROFILES:
+        dest = tmp_path / profile
+        model = dest / "assets/models/seg/dccc_seg.onnx"
+        rigid = dest / "assets/models/registration/rigid.onnx"
+        model.parent.mkdir(parents=True)
+        rigid.parent.mkdir(parents=True)
+        model.write_bytes(b"bulky optional segmentation")
+        rigid.write_bytes(b"required rigid")
+        vendor.prune_profile(dest, profile)
+        assert not model.exists()
+        assert rigid.exists()
+
+
+def test_model_release_zip_contains_runtime_controls(tmp_path):
+    root = Path(__file__).resolve().parents[3]
+    packer = import_script(root / "scripts/package-seg-model.py")
+    bundle = tmp_path / "source"
+    bundle.mkdir()
+    for name in FILES:
+        (bundle / name).write_bytes(b"model" if name.endswith(".onnx") else b"{}")
+    archive = packer.package_model(bundle, tmp_path / "dist", "4.6.0-alpha")
+    assert archive.name == "DCCCseg-4.6.0-alpha.zip"
+    with zipfile.ZipFile(archive) as z:
+        assert set(z.namelist()) == {"seg/" + name for name in FILES}
+
+
+def test_model_release_preserves_reference_entrypoint(tmp_path):
+    root = Path(__file__).resolve().parents[3]
+    packer = import_script(root / "scripts/package-seg-model.py")
+    bundle = tmp_path / "source"
+    bundle.mkdir()
+    for name in FILES:
+        (bundle / name).write_bytes(b"model" if name.endswith(".onnx") else b"{}")
+    (bundle / "README.md").write_text("See dccc_seg.py for reference inference")
+    (bundle / "dccc_seg.py").write_text("# shipped reference entry point\n")
+    archive = packer.package_model(bundle, tmp_path / "dist", "4.6.0-alpha")
+    with zipfile.ZipFile(archive) as z:
+        assert z.read("seg/dccc_seg.py") == b"# shipped reference entry point\n"
+
+
+def test_release_version_must_match_source():
+    root = Path(__file__).resolve().parents[3]
+    metadata = import_script(root / "scripts/release-metadata.py")
+    cmake = 'project(DCCCcore VERSION 4.6.0)\nset(DCCCCORE_VERSION_SUFFIX "-alpha")\n'
+    assert metadata.release_version(cmake, requested="4.6.0-alpha") == "4.6.0-alpha"
+    assert metadata.release_version(cmake, tag="v4.6.0-alpha") == "4.6.0-alpha"
+    with pytest.raises(ValueError):
+        metadata.release_version(cmake, requested="4.5.1-alpha")
+    with pytest.raises(ValueError):
+        metadata.release_version(cmake, tag="v4.6.0")