pycerr 2.0.0__tar.gz

pycerr-2.0.0/.github/workflows/_version_tmp.py

@@ -0,0 +1,17 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.1.test000+ghash'
+__version_tuple__ = version_tuple = (0, 1, 'test000', 'ghash')
+

pycerr-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,82 @@
+name: Publish to PyPI
+
+# Release flow:
+#   * Manual run (Actions -> "Publish to PyPI" -> Run workflow, optionally from a
+#     tag) publishes to TestPyPI - use this as a dry run.
+#   * Pushing a version tag publishes to PyPI, e.g.:
+#       git tag -a v0.7.0 -m "v0.7.0" && git push origin v0.7.0
+# setuptools_scm derives the version from the tag, so the PyPI version matches
+# the tag exactly (v0.7.0 -> 0.7.0).
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:          # manual run -> TestPyPI dry run
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # full history + tags so setuptools_scm sees the tag
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+      - name: Validate metadata and long description
+        run: twine check dist/*
+      - name: Show version being published
+        run: ls -l dist/
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI (dry run)
+    needs: build
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    # The TestPyPI Trusted Publisher must reference this environment name.
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/pycerr
+    permissions:
+      id-token: write             # OIDC token for Trusted Publishing (no API token)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # Don't fail a re-run if this dev version was already uploaded
+          # (TestPyPI filenames are immutable).
+          skip-existing: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    # The PyPI Trusted Publisher must reference this environment name.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pycerr
+    permissions:
+      id-token: write             # OIDC token for Trusted Publishing (no API token)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pycerr-2.0.0/.github/workflows/python-package.yml

@@ -0,0 +1,51 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python package
+
+on:
+  push:
+    branches: [ "testing", "main" ]
+  pull_request:
+    branches: [ "testing", "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install system libraries for Qt / headless GUI tests
+      # The viewer import smoke tests load napari / PyQt5, which need Qt system
+      # libraries and a virtual X display (xvfb) on the headless runner.
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y xvfb libegl1 libopengl0 libdbus-1-3 \
+          libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 libxcb-image0 \
+          libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 \
+          libxcb-xinerama0
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        cp .github/workflows/_version_tmp.py cerr/_version.py
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      # Run under xvfb so the napari / PyQt5 import tests have a display.
+      run: |
+        xvfb-run -a pytest -v

pycerr-2.0.0/.gitignore

@@ -0,0 +1,48 @@
+# Byte-compiled / optimized / cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+wheels/
+*.egg
+*.egg-info/
+.eggs/
+
+# setuptools_scm generates this from a git tag / CI temp file
+cerr/_version.py
+
+# Test & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Sphinx build output
+docs/_build/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Editors / IDEs
+.idea/
+.vscode/
+*.swp
+*~
+
+# OS cruft
+.DS_Store
+Thumbs.db
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Local test artifacts written to the repo root
+/scan_from_cerr.nii.gz

pycerr-2.0.0/.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs_old/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs_old in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+    install:
+    - requirements: docs/requirements.txt

pycerr-2.0.0/CLAUDE.md

@@ -0,0 +1,112 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+pyCERR (Python-based Computational Environment for Radiological Research) is a medical imaging library for processing, visualizing, and analyzing radiological data. It supports DICOM, NIfTI, and HDF5 I/O, and provides tools for radiomics, dose-volume histogram analysis, and deformable image registration.
+
+## Development Commands
+
+### Installation
+```bash
+conda create -y --name pycerr python=3.11
+conda activate pycerr
+pip install -e ".[napari]"
+```
+
+### Running Tests
+```bash
+# All tests
+pytest tests/
+
+# Single test file
+pytest tests/test_ibsi1_features.py
+
+# Single test function
+pytest tests/test_ibsi1_features.py::test_function_name
+```
+
+### Linting
+```bash
+# Syntax errors and undefined names (enforced in CI)
+flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+
+# Style check (max line length 127, max complexity 10)
+flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+```
+
+### Building Docs
+```bash
+cd docs && make html
+```
+
+## Architecture
+
+### Central Data Container: `PlanC`
+
+All imaging data lives in a `PlanC` instance (defined in `cerr/plan_container.py`). It holds lists of domain objects:
+
+- `planC.scan` — volumetric images (CT, MR, PT, US, NM)
+- `planC.structure` — segmentations (RTSTRUCT, SEG)
+- `planC.dose` — dose distributions (RTDOSE)
+- `planC.beams` — treatment plans (RTPLAN)
+- `planC.deform` — deformable registration results
+- `planC.header` — metadata (version, creation date)
+
+### Key Modules
+
+| Module | Purpose |
+|--------|---------|
+| `cerr/plan_container.py` | PlanC container + all I/O (DICOM, NIfTI, H5, pickle) |
+| `cerr/dataclasses/` | Domain dataclasses: `scan.py`, `structure.py`, `dose.py`, `beams.py`, `deform.py` |
+| `cerr/radiomics/` | IBSI-compliant texture/radiomic features and filters |
+| `cerr/contour/` | Contour processing and rasterization (polygon → mask) |
+| `cerr/viewer.py` | Interactive napari-based 2D/3D visualization |
+| `cerr/dvh.py` | Dose-Volume Histogram calculation |
+| `cerr/registration/` | Deformable image registration via plastimatch |
+| `cerr/dcm_export/` | DICOM export (RTSTRUCT, RTDOSE IODs) |
+| `cerr/utils/` | AI pipeline setup, image processing, masking, UID generation |
+| `cerr/roe/` | Radiomics Outcome Explorer (dosimetric models) |
+| `cerr/datasets/` | IBSI radiomics phantoms and reference values for validation |
+
+### Typical Data Flow
+
+```
+loadDcmDir(dcmDir) → PlanC
+  ├─ Scan: DICOM pixels → coordinate transforms → optionally SUV (PET)
+  ├─ Structure: DICOM contour points → coordinate transform → lazy rasterization
+  ├─ Dose: DICOM dose grid → coordinate transform
+  └─ Beams: RTPLAN fields
+
+PlanC → process:
+  ├─ radiomics.ibsi1.computeScalarFeatures(scanNum, structNum, settingsFile, planC)
+  ├─ dvh.getDVH(structNum, doseNum, planC)
+  └─ registration.register.register_scans(planC, ...)
+
+PlanC → export:
+  ├─ saveToH5(planC, h5File)   # HDF5 serialization
+  ├─ scan.saveNii(fileName)    # NIfTI export
+  └─ dcm_export/               # DICOM RT export
+```
+
+### Coordinate Systems
+
+Each `Scan` object carries three transformation matrices:
+- `Image2PhysicalTransM` — voxel indices → DICOM physical space (mm)
+- `Image2VirtualPhysicalTransM` — voxel indices → pyCERR virtual space
+- `cerrToDcmTransM` — pyCERR virtual → DICOM physical
+
+pyCERR's virtual coordinate system differs from DICOM's: it uses a right-handed system with `(x, y, z)` = `(col, row, slice)` ordering. Conversion happens in `convertDcmToCerrVirtualCoords()` inside each dataclass loader.
+
+### Contour Rasterization
+
+Structure contour points are stored as polygon vertices (DICOM format). Rasterization to binary masks is performed lazily via `cerr/contour/rasterseg.py` — masks are computed on demand, not pre-stored. Use `structure.getStructureMask3M(structNum, scanNum, planC)` to get a 3D mask array.
+
+### Radiomics
+
+Radiomics feature extraction is IBSI-compliant (International Biomarker Standardization Initiative). The `cerr/datasets/` directory contains the IBSI phantoms and reference values used in `tests/test_ibsi1_features.py` and `test_ibsi2_features.py` to validate correctness. Settings are passed via JSON files in `cerr/radiomics/settings/`.
+
+## CI
+
+GitHub Actions (`.github/workflows/python-package.yml`) runs linting and pytest on Python 3.9–3.12 (Ubuntu). Tests download reference data from external URLs; network access is required for the test suite.