Metadata-Version: 2.1
Name: medics-ext-retinal-layer-segmentation
Version: 2026.8.5.1
Summary: Retinal Layer Segmentation extension for MedICS
Author-email: Extension Developer <developer@example.com>
License: MIT
Project-URL: Homepage, https://github.com/your-github-username/medics-ext-retinal-layer-segmentation
Project-URL: Documentation, https://github.com/your-github-username/medics-ext-retinal-layer-segmentation/blob/main/README.md
Project-URL: Repository, https://github.com/your-github-username/medics-ext-retinal-layer-segmentation.git
Project-URL: Issues, https://github.com/your-github-username/medics-ext-retinal-layer-segmentation/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: medics
Requires-Dist: PySide6==6.8.2.1
Requires-Dist: numpy>=1.20.0
Requires-Dist: vtk>=9.3.1
Requires-Dist: GPUtil==1.4.0
Requires-Dist: onnxruntime==1.18.1; sys_platform == "darwin"
Requires-Dist: onnxruntime-gpu==1.18.1; sys_platform == "linux" or sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

# MedICS Extension: Retinal Layer Segmentation

AI-based retinal layer segmentation for OCT / OCTA volumes, built as a MedICS
extension. It automatically detects the anatomical layers of the retina from
optical coherence tomography data and provides interactive tools to review,
correct, quantify, and export the results.

## Overview

This extension turns an OCT volume into a fully segmented retina. It runs a
deep-learning model (ONNX, executed with ONNX Runtime) on each B-scan to detect
up to **14 retinal boundaries**, then reconstructs the boundaries into smooth
layer curves, detects intraretinal fluid, and builds a 3D representation of the
layers across the whole volume.

Everything runs inside a dedicated "OCT Analyzer" window:

- **Load data** from the MedICS workspace, from files on disk, or by dragging
  files onto the window (OCT, OCTA and existing segmentation data).
- **Run AI segmentation** with one click, optionally accelerated by a GPU
  (CUDA / DirectML / CoreML) with automatic CPU fallback.
- **Review and edit** the detected boundaries with a curve editor, layer
  visibility toggles, and a manual corrector.
- **Interpolate** the segmentation between sparse B-scans for a dense volume.
- **Visualize** the result as B-scans with overlaid curves, en-face views, and
  an interactive 3D surface reconstruction (VTK).
- **Export** the layer curves, fluid mask, and data back to the MedICS
  workspace or to files for downstream analysis.

The segmentation is computed locally — OCT/OCTA images never leave the
machine.

## Supported layer boundaries

The model detects the following anatomical boundaries in each B-scan:

| # | Boundary     | #  | Boundary   |
|---|--------------|----|------------|
| 0 | PVD          | 7  | ELM        |
| 1 | ILM          | 8  | EZ         |
| 2 | NFL/GCL      | 9  | EZ/IZ      |
| 3 | GCL/IPL      | 10 | IZ/RPE     |
| 4 | IPL/INL      | 11 | RPE/BM     |
| 5 | INL/OPL      | 12 | SAT/HAL    |
| 6 | OPL/ONL      | 13 | CHOROID    |

Each boundary can be toggled on/off individually for display and export, and
any boundary may be edited manually after segmentation.

## Features

- One-click AI segmentation of OCT/OCTA volumes (ONNX Runtime).
- Up to 14 automatically detected retinal layer boundaries.
- Intraretinal fluid detection with an optional fluid volume mask.
- Interactive curve editor for manual refinement of any boundary.
- Layer-by-layer visibility control and "Select All" convenience.
- Interpolation between sparse B-scans (configurable step) with restart.
- 3D surface / en-face visualization of the segmented volume (VTK).
- Preprocessing controls: flattening (None / Fitting / RPE-BM), axis permute,
  axis flip, ROI (manual or auto), and scan resolution update.
- B-frame navigation across the volume (frame index, total frames).
- Sparse data mode for memory-efficient processing of large volumes.
- GPU acceleration via CUDA, DirectML, or CoreML, with CPU fallback and a
  device selector.
- Drag-and-drop data loading, plus loading from the MedICS workspace or files.
- Save results to files or transfer curves/masks back to the MedICS workspace.
- Data resolution helper for aligning volumes acquired at different scales.

## Installation

### From PyPI

```bash
pip install medics-ext-retinal-layer-segmentation
```

### Verifying Installation

To verify that the model file reassembly works correctly:

```bash
python test_reassembly.py
```

## Usage

1. Install MedICS and this extension.
2. Launch MedICS: `python -m medics`.
3. Open the extension from the Extensions menu (a valid, non-free MedICS token
   is required; free or invalid tokens are blocked with a warning dialog).
4. Load an OCT volume — pick it from the workspace, click the file buttons on
   the **File** tab, or drag it onto the window. Optionally load matching OCTA
   or existing segmentation data as well.
5. Optionally adjust preprocessing on the side panel (flatten, permute, flip,
   ROI, resolution).
6. Click **Run AI Segmentation** in the side panel and choose the compute
   device.
7. Review the detected boundaries, toggle layers on/off, and use the curve
   editor or corrector to refine any boundary if needed.
8. Use **Save to WS** to transfer `oct_data`, `octa_data`, and `seg_data` back
   into the MedICS workspace, or **Save** to write results to files.

## Model distribution (maintainers)

The model folder is published with the GitHub Actions workflow
`.github/workflows/release-model.yml`. **It pushes the model folder to the
separate model_zoo repository**
(`https://github.com/Medical-Image-Computing-Suite/model_zoo.git`) — no GitHub
release is created.

1. **Set up the token** (once): create a Personal Access Token with `repo` scope
   that can write to `Medical-Image-Computing-Suite/model_zoo`, and store it as a
   repository secret named `MODEL_ZOO_TOKEN` in this repository's settings.
2. **Trigger the workflow** (Actions → "Publish Model to model_zoo" → Run workflow),
   optionally changing the target `model_zoo` branch (default `main`).
3. The workflow validates the chunk MD5 checksums against `layersegmodel.meta.json`,
   clones `model_zoo`, and replaces the **model-specific directory**
   `medics_ext_retinal_layer_segmentation/layersegmodel/` (chunks + metadata)
   with this repo's, then commits & pushes.
4. The download URL in `medics_ext_retinal_layer_segmentation/extension.json`
   points at this model's own directory in `model_zoo`. It is stable and needs
   no per-release updates:

   ```json
   "model_download_url": "https://raw.githubusercontent.com/Medical-Image-Computing-Suite/model_zoo/main/medics_ext_retinal_layer_segmentation/layersegmodel"
   ```

   The extension downloads each `layersegmodel.part*` chunk from this URL on
   first use and reassembles `layersegmodel.enc` from them. **Only this model's
   chunks are fetched** — the model_zoo repository stores many models side by
   side, each under its own `medics_ext_retinal_layer_segmentation/<model>`
   directory, so other models' files are never downloaded. The model must be
   pushed to `model_zoo` at least once (run the workflow) before the download
   works.

The model is distributed as the individual chunk files (each well under GitHub's
100 MB per-file limit) rather than a single archive, because a ~107 MB zip cannot
be committed to a GitHub repository. If you prefer to do it manually instead of
using the workflow:

```bash
git clone https://github.com/Medical-Image-Computing-Suite/model_zoo.git
DEST=model_zoo/medics_ext_retinal_layer_segmentation/layersegmodel
rm -rf "$DEST"
mkdir -p "$DEST"
cp medics_ext_retinal_layer_segmentation/model/chunks/* "$DEST/"
cd model_zoo
git add -A
git commit -m "Update retinal layer segmentation model"
git push origin main
```

When the model weights change, regenerate the chunks and their MD5 metadata first:

```bash
python split_model_file.py            # splits medics_ext_retinal_layer_segmentation/model/layersegmodel.enc
python -c "from medics_ext_retinal_layer_segmentation.utils.model_reassembly import ensure_model_ready; print(ensure_model_ready())"
```
