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:

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

pip install medics-ext-retinal-layer-segmentation

Verifying Installation

To verify that the model file reassembly works correctly:

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:

   "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:

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:

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())"