Enhance project structure and functionality by updating .gitignore, removing setup.py, and adding runtime configuration. Implement new features in CLI and measurement functions, and introduce tests for configuration and ring width measurements.

.gitignore

@@ -1,6 +1,29 @@
-*.pyc
-__pycache__
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
 *.egg-info
+.Python
+.coverage
+.coverage.*
+.hypothesis/
+.ipynb_checkpoints/
+.mypy_cache/
+.nox/
+.pyre/
+.pytest_cache/
+.ruff_cache/
+.tox/
+.venv/
+ENV/
+build/
+dist/
+env/
+htmlcov/
+pip-wheel-metadata/
+site/
+venv/
 *.zip
 .DS_Store
 .cache/

README.md

@@ -15,7 +15,7 @@ It was cloned from the upstream VascX repository on April 20, 2026, and the work
 It now serves as a self-contained fork for running the VascX retinal fundus analysis pipeline, with:
 
 - the VascX model weights tracked in Git LFS
-- the Python package and CLI used to run preprocessing and inference
+- the Python package used to run preprocessing and inference from this repo
 - fork-specific packaging and runtime fixes
 - a root `config.yaml` for controlling overlay layers and colors
 
@@ -25,14 +25,15 @@ This is not the canonical upstream repository. The upstream project remains `Eye
 
 ## What Stays Compatible
 
-- The installed CLI command is still `vascx`
-- The Python package is still `vascx_models`
+- The Python package name is still `vascx_models`
 - The model layout and output structure are kept compatible with the upstream VascX workflow
 
 ## What Changed In This Fork
 
 - Repository identity is now `vascx-fork`
 - The default conda environment name in `environment.yml` and `run.sh` is `vascx-fork`
+- The legacy `setup.py` and installed `vascx` console script were removed
+- Supported entrypoints are `./run.sh` and `python -m vascx_models`
 - Overlay generation can now be configured from the root `config.yaml`
 - Local helper scripts and docs were updated to point at this fork instead of the upstream Hub repo
 - Generated outputs, caches, and other non-repository artifacts are excluded from version control
@@ -52,24 +53,29 @@ conda env create -f environment.yml
 conda activate vascx-fork
 ```
 
-3. Install the runtime dependencies if needed:
+If you update `environment.yml` later, refresh the env with:
 
 ```bash
-pip install retinalysis-fundusprep retinalysis-inference
-pip install -e .
+conda env update -f environment.yml --prune
 ```
 
-If you are managing your own environment, install `torch` and `torchvision` for your platform before running the package.
+If you are managing your own environment instead of using `environment.yml`, install `torch`, `torchvision`, `retinalysis-fundusprep`, and `retinalysis-inference` before running the package.
 
 ## Quick Start
 
 Run the full pipeline:
 
 ```bash
-vascx run DATA_PATH OUTPUT_PATH
+./run.sh
 ```
 
-The entry point is still `vascx` even though the repository is named `vascx-fork`.
+The standard Python entrypoint is:
+
+```bash
+python -m vascx_models run DATA_PATH OUTPUT_PATH
+```
+
+Both entrypoints auto-configure the local cache and model-release directories from the repository checkout.
 
 `DATA_PATH` can be:
 
@@ -79,10 +85,11 @@ The entry point is still `vascx` even though the repository is named `vascx-fork
 Typical examples:
 
 ```bash
-vascx run /path/to/images /path/to/output
-vascx run /path/to/image_list.csv /path/to/output
-vascx run /path/to/preprocessed/images /path/to/output --no-preprocess
-vascx run /path/to/images /path/to/output --no-disc --no-quality --no-fovea --no-overlay
+./run.sh --sample-run
+python -m vascx_models run /path/to/images /path/to/output
+python -m vascx_models run /path/to/image_list.csv /path/to/output
+python -m vascx_models run /path/to/preprocessed/images /path/to/output --no-preprocess
+python -m vascx_models run /path/to/images /path/to/output --no-disc --no-quality --no-fovea --no-overlay
 ```
 
 ## Overlay Configuration
@@ -92,7 +99,7 @@ This fork adds a root-level `config.yaml` for overlay behavior.
 If `config.yaml` exists in the current working directory or repository root, `vascx run` loads it automatically. You can also pass a specific file:
 
 ```bash
-vascx run DATA_PATH OUTPUT_PATH --config /path/to/config.yaml
+python -m vascx_models run DATA_PATH OUTPUT_PATH --config /path/to/config.yaml
 ```
 
 Default overlay config:
@@ -138,16 +145,20 @@ OUTPUT_PATH/
 ├── overlays/
 ├── bounds.csv
 ├── disc_geometry.csv
+├── ring_vessel_widths.csv
 ├── quality.csv
 └── fovea.csv
 ```
 
+`ring_vessel_widths.csv` is written when both vessel/AV and disc outputs are available. It reports artery/vein width measurements in pixels at centerline crossings of the `2r` and `3r` disc circles.
+
 ## Repository Contents
 
 - `vascx_models/`: package source and CLI
 - `artery_vein/`, `disc/`, `fovea/`, `vessels/`, `quality/`, `odfd/`, `discedge/`: model artifacts
 - `config.yaml`: fork-specific overlay configuration
-- `run.sh`: convenience runner for local execution
+- `run.sh`: primary local runner
+- `tests/`: pytest suite
 - `notebooks/`: preprocessing and inference examples
 
 ## Upstream Reference

environment.yml

@@ -10,10 +10,10 @@ dependencies:
   - pillow=11.*
   - click=8.*
   - pyyaml=6.*
+  - pytest
   - pip:
       - torch==2.11.0
       - torchvision==0.26.0
       - torchaudio==2.11.0
       - retinalysis-fundusprep
       - retinalysis-inference
-      - -e .

run.sh

@@ -10,7 +10,6 @@ TIMESTAMP="$(date +"%Y%m%d_%H%M%S")"
 DEFAULT_OUTPUT_PATH="$REPO_ROOT/output_$TIMESTAMP"
 OUTPUT_PATH="${OUTPUT_PATH:-$DEFAULT_OUTPUT_PATH}"
 N_JOBS="${N_JOBS:-1}"
-MODEL_RELEASES_DIR="$REPO_ROOT/model_releases"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -31,30 +30,18 @@ if [[ ! -d "$INPUT_PATH" ]]; then
   exit 1
 fi
 
-mkdir -p "$REPO_ROOT/.mplconfig" "$REPO_ROOT/.cache" "$MODEL_RELEASES_DIR" "$OUTPUT_PATH"
-
-for model_path in "$REPO_ROOT"/*/*.pt; do
-  [[ -e "$model_path" ]] || continue
-  if [[ "$model_path" == "$MODEL_RELEASES_DIR"/* ]]; then
-    continue
-  fi
-  ln -sf "$model_path" "$MODEL_RELEASES_DIR/$(basename "$model_path")"
-done
-
-export MPLCONFIGDIR="$REPO_ROOT/.mplconfig"
-export XDG_CACHE_HOME="$REPO_ROOT/.cache"
-export RTNLS_MODEL_RELEASES="$MODEL_RELEASES_DIR"
+mkdir -p "$OUTPUT_PATH"
 
 echo "Running VascX Fork"
 echo "  conda env:   $CONDA_ENV"
 echo "  input path:  $INPUT_PATH"
 echo "  output path: $OUTPUT_PATH"
 echo "  n_jobs:      $N_JOBS"
-echo "  models dir:  $RTNLS_MODEL_RELEASES"
 
 CONDA_BASE="$(conda info --base)"
 # shellcheck disable=SC1091
 source "$CONDA_BASE/etc/profile.d/conda.sh"
 conda activate "$CONDA_ENV"
 
-exec python -c "from vascx_models.cli import cli; cli()" run "$INPUT_PATH" "$OUTPUT_PATH" --n_jobs "$N_JOBS"
+cd "$REPO_ROOT"
+exec python -m vascx_models run "$INPUT_PATH" "$OUTPUT_PATH" --n_jobs "$N_JOBS"

setup.py

@@ -1,36 +0,0 @@
-from setuptools import find_packages, setup
-
-with open("README.md", "r") as fh:
-    long_description = fh.read()
-
-setup(
-    name="vascx_models",
-    # using versioneer for versioning using git tags
-    # https://github.com/python-versioneer/python-versioneer/blob/master/INSTALL.md
-    # version=versioneer.get_version(),
-    # cmdclass=versioneer.get_cmdclass(),
-    author="Jose Vargas",
-    author_email="j.vargasquiros@erasmusmc.nl",
-    description="Retinal analysis toolbox for Python",
-    long_description=long_description,
-    long_description_content_type="text/markdown",
-    packages=find_packages(),
-    include_package_data=True,
-    zip_safe=False,
-    entry_points={
-        "console_scripts": [
-            "vascx = vascx_models.cli:cli",
-        ]
-    },
-    install_requires=[
-        "numpy == 2.*",
-        "pandas == 2.*",
-        "tqdm == 4.*",
-        "Pillow == 11.*",
-        "click==8.*",
-        "PyYAML == 6.*",
-        "retinalysis-fundusprep",
-        "retinalysis-inference",
-    ],
-    python_requires=">=3.10, <3.13",
-)

tests/test_config.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+
+import pytest
+
+from vascx_models.config import load_app_config
+
+
+def test_load_app_config_accepts_aliases_and_colours(tmp_path: Path) -> None:
+    config_path = tmp_path / "config.yaml"
+    config_path.write_text(
+        "\n".join(
+            [
+                "overlay:",
+                "  enabled: false",
+                "  layers:",
+                "    artery: false",
+                "    disc_ring_2r: false",
+                "  colours:",
+                "    veins: '#112233'",
+                "    disc_ring_3r: [4, 5, 6]",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    app_config = load_app_config(config_path)
+
+    assert app_config.source_path == config_path
+    assert app_config.overlay.enabled is False
+    assert app_config.overlay.layers.arteries is False
+    assert app_config.overlay.layers.ring_2r is False
+    assert app_config.overlay.colors.vein == (17, 34, 51)
+    assert app_config.overlay.colors.ring_3r == (4, 5, 6)
+
+
+def test_load_app_config_rejects_unknown_layer(tmp_path: Path) -> None:
+    config_path = tmp_path / "config.yaml"
+    config_path.write_text(
+        "\n".join(
+            [
+                "overlay:",
+                "  layers:",
+                "    unknown_layer: true",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    with pytest.raises(ValueError, match="Unsupported overlay layer"):
+        load_app_config(config_path)

tests/test_ring_widths.py

@@ -0,0 +1,99 @@
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from PIL import Image
+
+from vascx_models.ring_widths import measure_vessel_widths_at_disc_rings
+
+
+def _write_mask(path: Path, array: np.ndarray) -> None:
+    Image.fromarray(array.astype(np.uint8)).save(path)
+
+
+def test_measure_vessel_widths_detects_expected_crossings(tmp_path: Path) -> None:
+    vessels_dir = tmp_path / "vessels"
+    av_dir = tmp_path / "artery_vein"
+    vessels_dir.mkdir()
+    av_dir.mkdir()
+
+    height = width = 160
+    vessel = np.zeros((height, width), dtype=np.uint8)
+    av = np.zeros((height, width), dtype=np.uint8)
+
+    x_center = 80
+    vessel[:, x_center - 3 : x_center + 4] = 1
+    av[:, x_center - 3 : x_center + 4] = 2
+
+    _write_mask(vessels_dir / "sample.png", vessel)
+    _write_mask(av_dir / "sample.png", av)
+
+    geometry_path = tmp_path / "disc_geometry.csv"
+    pd.DataFrame(
+        {
+            "x_disc_center": [80.0],
+            "y_disc_center": [80.0],
+            "disc_radius_px": [20.0],
+            "ring_2r_px": [40.0],
+            "ring_3r_px": [60.0],
+        },
+        index=["sample"],
+    ).to_csv(geometry_path)
+
+    output_path = tmp_path / "ring_vessel_widths.csv"
+    df = measure_vessel_widths_at_disc_rings(
+        vessels_dir=vessels_dir,
+        av_dir=av_dir,
+        disc_geometry_path=geometry_path,
+        output_path=output_path,
+    )
+
+    assert output_path.exists()
+    assert list(df["ring"]) == ["2r", "2r", "3r", "3r"]
+    assert list(df["vessel_type"]) == ["vein", "vein", "vein", "vein"]
+    assert df["width_px"].tolist() == [7.0, 7.0, 7.0, 7.0]
+    assert df["y"].tolist() == [40.0, 120.0, 20.0, 140.0]
+
+
+def test_measure_vessel_widths_writes_empty_csv_when_no_crossings(tmp_path: Path) -> None:
+    vessels_dir = tmp_path / "vessels"
+    av_dir = tmp_path / "artery_vein"
+    vessels_dir.mkdir()
+    av_dir.mkdir()
+
+    empty = np.zeros((64, 64), dtype=np.uint8)
+    _write_mask(vessels_dir / "sample.png", empty)
+    _write_mask(av_dir / "sample.png", empty)
+
+    geometry_path = tmp_path / "disc_geometry.csv"
+    pd.DataFrame(
+        {
+            "x_disc_center": [32.0],
+            "y_disc_center": [32.0],
+            "disc_radius_px": [10.0],
+            "ring_2r_px": [20.0],
+            "ring_3r_px": [30.0],
+        },
+        index=["sample"],
+    ).to_csv(geometry_path)
+
+    output_path = tmp_path / "ring_vessel_widths.csv"
+    df = measure_vessel_widths_at_disc_rings(
+        vessels_dir=vessels_dir,
+        av_dir=av_dir,
+        disc_geometry_path=geometry_path,
+        output_path=output_path,
+    )
+
+    assert output_path.exists()
+    assert df.empty
+    assert list(df.columns) == [
+        "image_id",
+        "ring",
+        "ring_radius_px",
+        "crossing_index",
+        "x",
+        "y",
+        "width_px",
+        "vessel_type",
+    ]

tests/test_runtime.py

@@ -0,0 +1,32 @@
+import os
+from pathlib import Path
+
+from vascx_models import runtime
+
+
+def test_configure_runtime_environment_sets_paths_and_links_models(
+    tmp_path: Path, monkeypatch
+) -> None:
+    package_dir = tmp_path / "vascx_models"
+    package_dir.mkdir()
+    (package_dir / "__init__.py").write_text("", encoding="utf-8")
+
+    weights_dir = tmp_path / "disc"
+    weights_dir.mkdir()
+    model_path = weights_dir / "disc_test.pt"
+    model_path.write_text("model", encoding="utf-8")
+
+    monkeypatch.setattr(runtime, "repo_root", lambda: tmp_path)
+    monkeypatch.delenv("MPLCONFIGDIR", raising=False)
+    monkeypatch.delenv("XDG_CACHE_HOME", raising=False)
+    monkeypatch.delenv("RTNLS_MODEL_RELEASES", raising=False)
+
+    runtime.configure_runtime_environment()
+
+    assert Path(os.environ["MPLCONFIGDIR"]) == tmp_path / ".mplconfig"
+    assert Path(os.environ["XDG_CACHE_HOME"]) == tmp_path / ".cache"
+    assert Path(os.environ["RTNLS_MODEL_RELEASES"]) == tmp_path / "model_releases"
+
+    linked_model = tmp_path / "model_releases" / "disc_test.pt"
+    assert linked_model.is_symlink()
+    assert linked_model.resolve() == model_path.resolve()

vascx_models/__main__.py

@@ -0,0 +1,9 @@
+from .runtime import configure_runtime_environment
+
+configure_runtime_environment()
+
+from .cli import cli
+
+
+if __name__ == "__main__":
+    cli()

vascx_models/cli.py

@@ -9,6 +9,10 @@ from rtnls_fundusprep.cli import _run_preprocessing
 
 from .config import load_app_config
 from .disc_rings import generate_disc_rings
+from .runtime import configure_runtime_environment
+
+configure_runtime_environment()
+
 from .inference import (
     preferred_device,
     run_fovea_detection,
@@ -16,6 +20,7 @@ from .inference import (
     run_segmentation_disc,
     run_segmentation_vessels_and_av,
 )
+from .ring_widths import measure_vessel_widths_at_disc_rings
 from .utils import batch_create_overlays
 
 logger = logging.getLogger(__name__)
@@ -122,6 +127,7 @@ def run(
     quality_path = output_path / "quality.csv" if quality else None
     fovea_path = output_path / "fovea.csv" if fovea else None
     disc_geometry_path = output_path / "disc_geometry.csv" if disc else None
+    ring_widths_path = output_path / "ring_vessel_widths.csv" if disc and vessels else None
 
     # Determine if input is a folder or CSV file
     data_path = Path(data_path)
@@ -220,7 +226,17 @@ def run(
         logger.info("2r disc rings saved to %s", disc_ring_2r_path)
         logger.info("3r disc rings saved to %s", disc_ring_3r_path)
 
-    # Step 5: Run fovea detection if requested
+    # Step 5: Measure vessel widths at 2r and 3r if the required predictions exist
+    if disc and vessels:
+        logger.info("Measuring vessel widths at 2r and 3r disc rings")
+        measure_vessel_widths_at_disc_rings(
+            vessels_dir=vessels_path,
+            av_dir=av_path,
+            disc_geometry_path=disc_geometry_path,
+            output_path=ring_widths_path,
+        )
+
+    # Step 6: Run fovea detection if requested
     df_fovea = None
     if fovea:
         logger.info("Running fovea detection")
@@ -230,7 +246,7 @@ def run(
         df_fovea.to_csv(fovea_path)
         logger.info("Fovea detection results saved to %s", fovea_path)
 
-    # Step 6: Create overlays if requested
+    # Step 7: Create overlays if requested
     if overlay_enabled:
         logger.info("Creating visualization overlays")
 

vascx_models/ring_widths.py

@@ -0,0 +1,429 @@
+import logging
+from pathlib import Path
+from typing import List, Optional, Sequence, Tuple
+
+import numpy as np
+import pandas as pd
+from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+_NEIGHBORS_8: tuple[tuple[int, int], ...] = (
+    (-1, -1),
+    (-1, 0),
+    (-1, 1),
+    (0, -1),
+    (0, 1),
+    (1, -1),
+    (1, 0),
+    (1, 1),
+)
+
+
+def _skeletonize(binary_mask: np.ndarray) -> np.ndarray:
+    """Thin a binary mask to a one-pixel-wide skeleton with Zhang-Suen thinning."""
+    image = binary_mask.astype(np.uint8).copy()
+    if image.ndim != 2:
+        raise ValueError("Expected a 2D binary mask")
+
+    while True:
+        changed = False
+        for step in (0, 1):
+            p2 = image[:-2, 1:-1]
+            p3 = image[:-2, 2:]
+            p4 = image[1:-1, 2:]
+            p5 = image[2:, 2:]
+            p6 = image[2:, 1:-1]
+            p7 = image[2:, :-2]
+            p8 = image[1:-1, :-2]
+            p9 = image[:-2, :-2]
+            p1 = image[1:-1, 1:-1]
+
+            neighbors = p2 + p3 + p4 + p5 + p6 + p7 + p8 + p9
+            transitions = (
+                ((p2 == 0) & (p3 == 1)).astype(np.uint8)
+                + ((p3 == 0) & (p4 == 1)).astype(np.uint8)
+                + ((p4 == 0) & (p5 == 1)).astype(np.uint8)
+                + ((p5 == 0) & (p6 == 1)).astype(np.uint8)
+                + ((p6 == 0) & (p7 == 1)).astype(np.uint8)
+                + ((p7 == 0) & (p8 == 1)).astype(np.uint8)
+                + ((p8 == 0) & (p9 == 1)).astype(np.uint8)
+                + ((p9 == 0) & (p2 == 1)).astype(np.uint8)
+            )
+
+            if step == 0:
+                guard_1 = p2 * p4 * p6 == 0
+                guard_2 = p4 * p6 * p8 == 0
+            else:
+                guard_1 = p2 * p4 * p8 == 0
+                guard_2 = p2 * p6 * p8 == 0
+
+            remove = (
+                (p1 == 1)
+                & (neighbors >= 2)
+                & (neighbors <= 6)
+                & (transitions == 1)
+                & guard_1
+                & guard_2
+            )
+
+            if np.any(remove):
+                image[1:-1, 1:-1][remove] = 0
+                changed = True
+
+        if not changed:
+            break
+
+    return image.astype(bool)
+
+
+def _connected_components(mask: np.ndarray) -> List[np.ndarray]:
+    visited = np.zeros_like(mask, dtype=bool)
+    components: List[np.ndarray] = []
+
+    ys, xs = np.nonzero(mask)
+    for seed_y, seed_x in zip(ys, xs):
+        if visited[seed_y, seed_x]:
+            continue
+
+        stack = [(int(seed_y), int(seed_x))]
+        visited[seed_y, seed_x] = True
+        coords: List[Tuple[int, int]] = []
+
+        while stack:
+            y, x = stack.pop()
+            coords.append((y, x))
+            for dy, dx in _NEIGHBORS_8:
+                ny = y + dy
+                nx = x + dx
+                if ny < 0 or nx < 0 or ny >= mask.shape[0] or nx >= mask.shape[1]:
+                    continue
+                if not mask[ny, nx] or visited[ny, nx]:
+                    continue
+                visited[ny, nx] = True
+                stack.append((ny, nx))
+
+        components.append(np.asarray(coords, dtype=np.int32))
+
+    return components
+
+
+def _local_skeleton_points(
+    skeleton: np.ndarray,
+    point_xy: np.ndarray,
+    radius_px: float,
+) -> np.ndarray:
+    x, y = point_xy
+    height, width = skeleton.shape
+    x_min = max(0, int(np.floor(x - radius_px)))
+    x_max = min(width - 1, int(np.ceil(x + radius_px)))
+    y_min = max(0, int(np.floor(y - radius_px)))
+    y_max = min(height - 1, int(np.ceil(y + radius_px)))
+
+    window = skeleton[y_min : y_max + 1, x_min : x_max + 1]
+    ys, xs = np.nonzero(window)
+    if len(xs) == 0:
+        return np.empty((0, 2), dtype=float)
+
+    xs = xs.astype(float) + float(x_min)
+    ys = ys.astype(float) + float(y_min)
+    deltas = np.column_stack((xs - x, ys - y))
+    keep = np.sum(deltas * deltas, axis=1) <= radius_px * radius_px
+    return np.column_stack((xs[keep], ys[keep]))
+
+
+def _estimate_tangent(points_xy: np.ndarray) -> Optional[np.ndarray]:
+    if len(points_xy) < 2:
+        return None
+
+    centered = points_xy - points_xy.mean(axis=0, keepdims=True)
+    covariance = centered.T @ centered
+    eigenvalues, eigenvectors = np.linalg.eigh(covariance)
+    tangent = eigenvectors[:, int(np.argmax(eigenvalues))]
+    norm = float(np.linalg.norm(tangent))
+    if norm == 0.0:
+        return None
+    return tangent / norm
+
+
+def _sample_mask(mask: np.ndarray, point_xy: np.ndarray) -> float:
+    x, y = point_xy
+    height, width = mask.shape
+    if x < 0 or y < 0 or x > width - 1 or y > height - 1:
+        return 0.0
+
+    x0 = int(np.floor(x))
+    y0 = int(np.floor(y))
+    x1 = min(x0 + 1, width - 1)
+    y1 = min(y0 + 1, height - 1)
+
+    dx = x - x0
+    dy = y - y0
+
+    v00 = float(mask[y0, x0])
+    v10 = float(mask[y0, x1])
+    v01 = float(mask[y1, x0])
+    v11 = float(mask[y1, x1])
+
+    top = v00 * (1.0 - dx) + v10 * dx
+    bottom = v01 * (1.0 - dx) + v11 * dx
+    return top * (1.0 - dy) + bottom * dy
+
+
+def _trace_boundary_distance(
+    vessel_mask: np.ndarray,
+    point_xy: np.ndarray,
+    direction_xy: np.ndarray,
+    step_px: float,
+) -> float:
+    max_distance = float(np.hypot(*vessel_mask.shape)) + 2.0
+    current_value = _sample_mask(vessel_mask, point_xy)
+    if current_value < 0.5:
+        return float("nan")
+
+    t_inside = 0.0
+    steps = int(np.ceil(max_distance / step_px))
+    for step in range(1, steps + 1):
+        t_outside = step * step_px
+        sample_point = point_xy + direction_xy * t_outside
+        if _sample_mask(vessel_mask, sample_point) < 0.5:
+            low = t_inside
+            high = t_outside
+            for _ in range(12):
+                mid = (low + high) / 2.0
+                mid_point = point_xy + direction_xy * mid
+                if _sample_mask(vessel_mask, mid_point) >= 0.5:
+                    low = mid
+                else:
+                    high = mid
+            return low
+        t_inside = t_outside
+
+    return float("nan")
+
+
+def _measure_width_along_normal(
+    vessel_mask: np.ndarray,
+    center_xy: np.ndarray,
+    tangent_xy: np.ndarray,
+    step_px: float,
+) -> float:
+    normal_xy = np.array([-tangent_xy[1], tangent_xy[0]], dtype=float)
+    norm = float(np.linalg.norm(normal_xy))
+    if norm == 0.0:
+        return float("nan")
+    normal_xy /= norm
+
+    positive = _trace_boundary_distance(vessel_mask, center_xy, normal_xy, step_px)
+    negative = _trace_boundary_distance(vessel_mask, center_xy, -normal_xy, step_px)
+    if np.isnan(positive) or np.isnan(negative):
+        return float("nan")
+    return positive + negative
+
+
+def _majority_vessel_type(
+    av_mask: np.ndarray,
+    skeleton: np.ndarray,
+    point_xy: np.ndarray,
+    radius_px: float,
+) -> str:
+    local_points = _local_skeleton_points(skeleton, point_xy, radius_px)
+    if len(local_points) == 0:
+        return "ambiguous"
+
+    xs = np.rint(local_points[:, 0]).astype(int)
+    ys = np.rint(local_points[:, 1]).astype(int)
+    labels = av_mask[ys, xs]
+
+    artery_votes = int(np.sum(labels == 1))
+    vein_votes = int(np.sum(labels == 2))
+    if artery_votes > vein_votes:
+        return "artery"
+    if vein_votes > artery_votes:
+        return "vein"
+
+    x, y = point_xy
+    height, width = av_mask.shape
+    x_min = max(0, int(np.floor(x - radius_px)))
+    x_max = min(width - 1, int(np.ceil(x + radius_px)))
+    y_min = max(0, int(np.floor(y - radius_px)))
+    y_max = min(height - 1, int(np.ceil(y + radius_px)))
+    patch = av_mask[y_min : y_max + 1, x_min : x_max + 1]
+    artery_votes = int(np.sum(patch == 1))
+    vein_votes = int(np.sum(patch == 2))
+    if artery_votes > vein_votes:
+        return "artery"
+    if vein_votes > artery_votes:
+        return "vein"
+    return "ambiguous"
+
+
+def _is_radius_crossing(
+    skeleton: np.ndarray,
+    distances: np.ndarray,
+    center_xy: np.ndarray,
+    target_radius_px: float,
+    search_radius_px: float,
+) -> bool:
+    local_points = _local_skeleton_points(skeleton, center_xy, search_radius_px)
+    if len(local_points) == 0:
+        return False
+
+    xs = np.rint(local_points[:, 0]).astype(int)
+    ys = np.rint(local_points[:, 1]).astype(int)
+    local_distances = distances[ys, xs]
+    return (
+        float(np.min(local_distances)) <= target_radius_px - 0.75
+        and float(np.max(local_distances)) >= target_radius_px + 0.75
+    )
+
+
+def _ring_records_for_image(
+    image_id: str,
+    vessel_mask: np.ndarray,
+    av_mask: np.ndarray,
+    disc_center_xy: np.ndarray,
+    disc_radius_px: float,
+    ring_multipliers: Sequence[float],
+    crossing_band_width_px: float,
+    tangent_window_px: float,
+    label_window_px: float,
+    measurement_step_px: float,
+) -> List[dict]:
+    if not np.any(vessel_mask):
+        return []
+
+    skeleton = _skeletonize(vessel_mask)
+    if not np.any(skeleton):
+        return []
+
+    yy, xx = np.indices(vessel_mask.shape, dtype=float)
+    distances = np.hypot(xx - disc_center_xy[0], yy - disc_center_xy[1])
+
+    records: List[dict] = []
+    for ring_multiplier in ring_multipliers:
+        target_radius_px = float(disc_radius_px * ring_multiplier)
+        band_mask = skeleton & (np.abs(distances - target_radius_px) <= crossing_band_width_px)
+        components = _connected_components(band_mask)
+        crossing_index = 0
+
+        for component in components:
+            component_distances = distances[component[:, 0], component[:, 1]]
+            best_idx = int(np.argmin(np.abs(component_distances - target_radius_px)))
+            y_px = int(component[best_idx, 0])
+            x_px = int(component[best_idx, 1])
+            center_xy = np.array([float(x_px), float(y_px)], dtype=float)
+
+            local_points = _local_skeleton_points(skeleton, center_xy, tangent_window_px)
+            tangent_xy = _estimate_tangent(local_points)
+            if tangent_xy is None:
+                continue
+
+            if not _is_radius_crossing(
+                skeleton=skeleton,
+                distances=distances,
+                center_xy=center_xy,
+                target_radius_px=target_radius_px,
+                search_radius_px=tangent_window_px,
+            ):
+                continue
+
+            width_px = _measure_width_along_normal(
+                vessel_mask=vessel_mask,
+                center_xy=center_xy,
+                tangent_xy=tangent_xy,
+                step_px=measurement_step_px,
+            )
+            if np.isnan(width_px):
+                continue
+
+            crossing_index += 1
+            records.append(
+                {
+                    "image_id": image_id,
+                    "ring": f"{int(ring_multiplier)}r",
+                    "ring_radius_px": target_radius_px,
+                    "crossing_index": crossing_index,
+                    "x": center_xy[0],
+                    "y": center_xy[1],
+                    "width_px": float(width_px),
+                    "vessel_type": _majority_vessel_type(
+                        av_mask=av_mask,
+                        skeleton=skeleton,
+                        point_xy=center_xy,
+                        radius_px=label_window_px,
+                    ),
+                }
+            )
+
+    return records
+
+
+def measure_vessel_widths_at_disc_rings(
+    vessels_dir: Path,
+    av_dir: Path,
+    disc_geometry_path: Path,
+    output_path: Optional[Path] = None,
+    ring_multipliers: Sequence[float] = (2.0, 3.0),
+    crossing_band_width_px: float = 1.5,
+    tangent_window_px: float = 10.0,
+    label_window_px: float = 7.0,
+    measurement_step_px: float = 0.25,
+) -> pd.DataFrame:
+    """Measure vessel widths where centerlines cross the 2r and 3r disc circles."""
+    if not disc_geometry_path.exists():
+        raise FileNotFoundError(f"Disc geometry file not found: {disc_geometry_path}")
+    if not vessels_dir.exists():
+        raise FileNotFoundError(f"Vessels directory not found: {vessels_dir}")
+    if not av_dir.exists():
+        raise FileNotFoundError(f"AV directory not found: {av_dir}")
+
+    df_geometry = pd.read_csv(disc_geometry_path, index_col=0)
+    records: List[dict] = []
+
+    for image_id, row in df_geometry.iterrows():
+        if pd.isna(row["x_disc_center"]) or pd.isna(row["y_disc_center"]) or pd.isna(
+            row["disc_radius_px"]
+        ):
+            logger.warning("Skipping %s because disc geometry is missing", image_id)
+            continue
+
+        vessel_path = vessels_dir / f"{image_id}.png"
+        av_path = av_dir / f"{image_id}.png"
+        if not vessel_path.exists() or not av_path.exists():
+            logger.warning("Skipping %s because vessel or AV mask is missing", image_id)
+            continue
+
+        vessel_mask = np.array(Image.open(vessel_path)) > 0
+        av_mask = np.array(Image.open(av_path))
+        image_records = _ring_records_for_image(
+            image_id=image_id,
+            vessel_mask=vessel_mask,
+            av_mask=av_mask,
+            disc_center_xy=np.array([row["x_disc_center"], row["y_disc_center"]], dtype=float),
+            disc_radius_px=float(row["disc_radius_px"]),
+            ring_multipliers=ring_multipliers,
+            crossing_band_width_px=crossing_band_width_px,
+            tangent_window_px=tangent_window_px,
+            label_window_px=label_window_px,
+            measurement_step_px=measurement_step_px,
+        )
+        records.extend(image_records)
+
+    df_widths = pd.DataFrame.from_records(
+        records,
+        columns=[
+            "image_id",
+            "ring",
+            "ring_radius_px",
+            "crossing_index",
+            "x",
+            "y",
+            "width_px",
+            "vessel_type",
+        ],
+    )
+    if output_path is not None:
+        df_widths.to_csv(output_path, index=False)
+        logger.info("Ring vessel width measurements saved to %s", output_path)
+    return df_widths

vascx_models/runtime.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def configure_runtime_environment() -> None:
+    root = repo_root()
+
+    mplconfigdir = Path(os.environ.setdefault("MPLCONFIGDIR", str(root / ".mplconfig")))
+    cache_dir = Path(os.environ.setdefault("XDG_CACHE_HOME", str(root / ".cache")))
+    model_releases_dir = Path(
+        os.environ.setdefault("RTNLS_MODEL_RELEASES", str(root / "model_releases"))
+    )
+
+    mplconfigdir.mkdir(exist_ok=True, parents=True)
+    cache_dir.mkdir(exist_ok=True, parents=True)
+    model_releases_dir.mkdir(exist_ok=True, parents=True)
+
+    for model_path in root.glob("*/*.pt"):
+        if model_releases_dir in model_path.parents:
+            continue
+
+        symlink_path = model_releases_dir / model_path.name
+        if symlink_path.exists() or symlink_path.is_symlink():
+            try:
+                if symlink_path.resolve() == model_path.resolve():
+                    continue
+            except FileNotFoundError:
+                pass
+            symlink_path.unlink()
+
+        symlink_path.symlink_to(model_path.resolve())