[!IMPORTANT]
The entire VascX pipeline, including feature extraction is available here:
retinalysis-vascx . A new preprint presenting the pipeline is
available here . We will stop supporting this repository and move to the new one linked above. We will keep updating the models and pipeline there.
👁️ VascX models
This repository contains the instructions for using the VascX models from the paper
VascX Models: Model Ensembles for Retinal Vascular Analysis from Color Fundus Images .
The model weights are in
huggingface .
🛠️ Installation
To install the entire fundus analysis pipeline including fundus preprocessing, model inference code and vascular biomarker extraction:
Create a conda or virtualenv virtual environment, or otherwise ensure a clean environment.
🚀 vascx run Command
The run command provides a comprehensive pipeline for processing fundus images, performing various analyses, and creating visualizations.
Usage
vascx run DATA_PATH OUTPUT_PATH [OPTIONS]Arguments
DATA_PATH: Path to input data. Can be either:
A directory containing fundus images
A CSV file with a 'path' column containing paths to images
OUTPUT_PATH: Directory where processed results will be stored
Options
Option Default Description --preprocess/--no-preprocess--preprocessRun preprocessing to standardize images for model input --vessels/--no-vessels--vesselsRun vessel segmentation and artery-vein classification --disc/--no-disc--discRun optic disc segmentation --quality/--no-quality--qualityRun image quality assessment --fovea/--no-fovea--foveaRun fovea detection --overlay/--no-overlay--overlayCreate visualization overlays combining all results --n_jobs4Number of preprocessing workers for parallel processing
📁 Output Structure
When run with default options, the command creates the following structure in OUTPUT_PATH:
OUTPUT_PATH/
├── preprocessed_rgb/ # Standardized fundus images
├── vessels/ # Vessel segmentation results
├── artery_vein/ # Artery-vein classification
├── disc/ # Optic disc segmentation
├── overlays/ # Visualization images
├── bounds.csv # Image boundary information
├── quality.csv # Image quality scores
└── fovea.csv # Fovea coordinates🔄 Processing Stages
Preprocessing :
Standardizes input images for consistent analysis
Outputs preprocessed images and boundary information
Quality Assessment :
Evaluates image quality with three quality metrics (q1, q2, q3)
Higher scores indicate better image quality
Vessel Segmentation and Artery-Vein Classification :
Identifies blood vessels in the retina
Classifies vessels as arteries (1) or veins (2) with intersections (3)
Optic Disc Segmentation :
Identifies the optic disc location and boundaries
Fovea Detection :
Determines the coordinates of the fovea (center of vision)
Visualization Overlays :
Creates color-coded images showing:
Arteries in red
Veins in blue
Optic disc in white
Fovea marked with yellow X
💻 Examples
Process a directory of images with all analyses:
vascx run /path/to/images /path/to/outputProcess specific images listed in a CSV:
vascx run /path/to/image_list.csv /path/to/outputOnly run preprocessing and vessel segmentation:
vascx run /path/to/images /path/to/output --no-disc --no-quality --no-fovea --no-overlaySkip preprocessing on already preprocessed images:
vascx run /path/to/preprocessed/images /path/to/output --no-preprocessIncrease parallel processing workers:
vascx run /path/to/images /path/to/output --n_jobs 8📝 Notes
The CSV input must contain a 'path' column with image file paths
If the CSV includes an 'id' column, these IDs will be used instead of filenames
When --no-preprocess is used, input images must already be in the proper format
The overlay visualization requires at least one analysis component to be enabled
📓 Notebooks
For more advanced usage, we have Jupyter notebooks showing how preprocessing and inference are run.
To speed up re-execution of vascx we recommend to run the preprocessing and segmentation steps separately:
Preprocessing. See
this notebook . This step is CPU-heavy and benefits from parallelization (see notebook).
Inference. See
this notebook . All models can be ran in a single GPU with >10GB VRAM.
