vascx 1.0__tar.gz

vascx-1.0/.gitattributes

@@ -0,0 +1,3 @@
+*.ipynb filter=nbstripout
+*.zpln filter=nbstripout
+*.ipynb diff=ipynb

vascx-1.0/.gitignore

@@ -0,0 +1,8 @@
+*.pyc
+__pycache__
+*.egg-info
+*.zip
+/samples/*
+!/samples/figures
+!/samples/fundus/original
+/paper/

vascx-1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: vascx
+Version: 1.0
+Summary: Retinal analysis toolbox for Python
+Author-email: Jose Vargas <j.vargasquiros@erasmusmc.nl>
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy==2.*
+Requires-Dist: pandas==2.*
+Requires-Dist: scikit-learn==1.*
+Requires-Dist: scipy==1.*
+Requires-Dist: opencv-python==4.*
+Requires-Dist: matplotlib==3.*
+Requires-Dist: joblib==1.*
+Requires-Dist: tqdm==4.*
+Requires-Dist: Pillow==11.*
+Requires-Dist: click==8.*
+Requires-Dist: sknw==0.14
+Requires-Dist: sortedcontainers==2.4.0
+Requires-Dist: scikit-image==0.24.0
+Requires-Dist: retinalysis-enface
+Requires-Dist: retinalysis-fundusprep
+Provides-Extra: test
+Requires-Dist: pytest==8.*; extra == "test"
+Requires-Dist: pyarrow==22.*; extra == "test"
+Requires-Dist: PyYAML==6.*; extra == "test"
+
+## VascX retinal vascular analysis
+
+VascX was created for the extraction of vascular features from fundus image segmentations.
+
+**Important!** This repository contains the feature extraction part of the VascX pipeline.
+
+For details about our segmentation models please refer our [models repository](https://github.com/Eyened/rtnls_vascx_models) an its related open access paper [VascX Models: Deep Ensembles for Retinal Vascular Analysis From Color Fundus Images](https://tvst.arvojournals.org/article.aspx?articleid=2810436)
+
+### Installation
+
+To install the entire fundus analysis pipeline including fundus preprocessing, model inference code and vascular biomarker extraction:
+
+1. Create a virtual environment, or otherwise ensure a clean environment.
+
+2. Install VascX:
+
+```
+pip install retinalysis-vascx
+```
+
+### Usage
+
+To speed up re-execution of VascX we recommend to run the segmentation and feature extraction steps separately:
+
+To run on the provided samples folder in our git repository:
+
+```
+git clone git@github.com:Eyened/retinalysis-vascx.git rtnls_vascx
+cd rtnls_vascx
+vascx run-models ./samples/fundus/original/ /path/to/segmentations
+vascx calc-biomarkers /path/to/segmentations /path/to/features.csv --feature_set full --n-jobs 8 --logfile /path/to/logfile.txt
+```
+
+Note that `vascx run-models` will write segmentations and other model predictions to `/path/to/segmentations`, which will have the following structure:
+
+```
+/path/to/segmentations
+  - preprocessed_rgb/ - preprocessed fundus images
+  - artery_vein/ - artery-vein model segmentations
+  - vessels/ - vessel model segmentations
+  - disc/ - optic disc model segmentations
+  - overlays/ - optional overlays showing the segmentations
+  - bounds.csv - contains the bounds of the fundus image
+  - fovea.csv - model predictions of the fovea locations for each image
+  - quality.csv - model estimations of CFI quality
+```
+
+The folders above will contain images with matching filenames.
+
+
+We also provide notebooks for running the three stages:
+
+1. Preprocessing. See [this notebook](./notebooks/0_preprocess.ipynb). This step is CPU-heavy and benefits from parallelization (see notebook).
+
+2. Inference. See [this notebook](./notebooks/1_segment_preprocessed.ipynb). All models can be ran in a single GPU with >10GB VRAM.
+
+3. Feature extraction. See [this notebook](./notebooks/2_feature_extraction.ipynb). This step is CPU-heavy again and benefits from parallelization (see notebook).
+
+
+
+### Implementation
+
+
+
+VascX processes vessel segmentations through four main stages, each producing different data representations:
+
+- **Input masks**: `np.ndarray[bool]` per layer; optic disc and fovea metadata from segmentation models.
+
+- **Stage 1 - Binary/skeleton**: 
+  - `binary`: filled vessel mask after disc masking
+  - `binary_nodisc`: vessel mask without disc region
+  - `skeleton`: skeletonized vessel centerlines using skimage skeletonization
+
+- **Stage 2 - Undirected graph**: 
+  - NetworkX `Graph` with skeleton pixels as nodes
+  - `Segment` objects stored on edges containing skeleton points and geometric properties
+  - Each segment represents a vessel segment between junction points
+
+- **Stage 3 - Directed digraph**: 
+  - NetworkX `DiGraph` with flow direction from optic disc outward
+  - `trees`: root nodes representing vessel trees emanating from disc
+  - `nodes`: `Endpoint` and `Bifurcation` objects with spatial positions
+  - `segments`: directed vessel segments with computed properties (diameter, length, etc.)
+
+- **Stage 4 - Resolved vessels**: 
+  - Merged vessel graph after running vessel resolution algorithm
+  - `resolved_segments`: final vessel segments after merging short segments
+  - Segment-to-pixel mapping for spatial feature computation
+
+Biomarker families use different representations: mask-based features use `binary`; topology features use `digraph` and `nodes`; morphological features use `segments` with computed diameters; spatial features use segment-to-pixel mappings.
+
+### Biomarkers
+
+VascX computes retinal vascular biomarkers from standardized representations (binary masks, undirected/directed graphs, resolved vessels). Below we describe each feature with the exact quantity being estimated and the equations used. Throughout, B denotes the stage‑1 binary vessel mask, S the set of eligible directed segments with lengths \(\ell_i\), and R an analysis region of interest; cardinalities count pixels, and distances are in pixels unless noted.
+
+**VascularDensity.** The fraction of retinal area occupied by vessels in R, computed on the binary mask B:
+
+$$
+D \,=\, \frac{|B \cap R|}{|R|}.
+$$
+
+![](samples/figures/vascular_density.png)
+
+**BifurcationCount.** The count of branching points in the directed graph (stage‑3). Let $\mathcal{B}$ be the set of bifurcation nodes with positions $p_b$:
+
+$$
+C \,=\, \sum_{b \in \mathcal{B}} \mathbf{1}[p_b \in R].
+$$
+
+![](samples/figures/bifurcation_count.png)
+
+**BifurcationAngles.** For each bifurcation $b$ at position $p_b$, outgoing branch directions are estimated by sampling the branches' splines at distance $\delta$ from the node along each branch at points $q_1$ and $q_2$. Unit vectors $(u_b, v_b)$ are defined from the bifurcation point to the sample points:
+
+$$
+u_b = \frac{q_1 - p_b}{\|q_1 - p_b\|}, \quad v_b = \frac{q_2 - p_b}{\|q_2 - p_b\|},
+$$
+
+and the bifurcation angle is defined as the angle between these vectors:
+
+$$
+\theta_b \,=\, \arccos(u_b \cdot v_b), \quad \theta_b \in [0^\circ, 180^\circ].
+$$
+
+Angles exceeding 160° are discarded as non-bifurcating continuations. Summary statistics (e.g., mean/median) are reported across valid nodes.
+
+![](samples/figures/bifurcation_angles.png)
+
+**Caliber.** For each segment $i$, diameters are sampled along a spline fitted to its skeleton by projecting spline normals to the vessel boundary on B. The per‑segment diameter is the median along its arclength. The reported caliber aggregates over eligible segments (length $\ell_i \ge \ell_{\min}$):
+
+$$
+\operatorname{Caliber} \,=\, g\big(\{ d_i : i \in S \}\big),
+$$
+
+where \(g\) is a robust statistic (typically the median).
+
+![](samples/figures/caliber.png)
+
+**Tortuosity.** Three complementary measures are provided per segment (or per resolved vessel). Let $L_{\text{arc},i}$ be arclength and $L_{\text{chord},i}$ the end‑to‑end Euclidean distance.
+
+- Distance factor:
+
+$$
+T_i^{\text{DF}} \,=\, \frac{L_{\text{arc},i}}{L_{\text{chord},i}}.
+$$
+
+- Curvature‑based measure, using planar curvature $\kappa_i(s)$ and OD–fovea distance $d_{ODF}$ for scale normalization:
+
+$$
+T_i^{\kappa} \,=\, \frac{1}{L_{\text{arc},i}} \int_0^{L_{\text{arc},i}} \big|\kappa_i(s)\big| \, ds \; \cdot \; d_{ODF}.
+$$
+
+- Inflection count (number of curvature sign changes along the centerline):
+
+$$
+T_i^{\text{INF}} \,=\, N^{(i)}_{\text{inflections}}.
+$$
+
+When reporting a single score over multiple segments, length‑weighted aggregation may be used for normalization:
+
+$$
+T_{\text{tot}} \,=\, \sum_{i \in S} \left( \frac{\ell_i}{\sum_{j \in S} \ell_j} \right) t_i,
+$$
+
+with $t_i$ any of the measures above.
+
+![](samples/figures/tortuosity.png)
+
+**CRE (Central Retinal Equivalents).** Concentric circles centered at the optic disc are intersected with the vessel network. At each radius $r$, up to $M$ crossings with the largest segment median diameters are retained and recursively reduced via the Hubbard rule with a modality‑dependent constant $c$ (arteries: 0.88; veins: 0.95):
+
+$$
+ d \leftarrow c\,\sqrt{d_1^2 + d_2^2}
+$$
+
+applied pairwise until a single equivalent caliber $d_r$ remains. The final CRE is the median of $\{d_r\}$ across radii.
+
+![](samples/figures/cre.png)
+
+**TemporalAngle.** On each concentric circle of radius \(r\), the two dominant temporal vessels are identified by diameter and spatial continuity. The angle at the disc center is
+
+$$
+\theta_r \,=\, \angle\big(\overline{OD\,p_1(r)},\, \overline{OD\,p_2(r)}\big),
+$$
+
+and the reported value is the median over radii.
+
+![](samples/figures/temporal_angle.png)
+
+**Sparsity.** Let $\mathrm{DT}(x)$ represent the distance transform over $R$, ie. the normalized Euclidean distance to the nearest vessel pixel (scaled by $d_{ODF}$). Over pixels in R we report either the mean or the largest local maximum:
+
+$$
+S_{\text{mean}} \,=\, \frac{1}{|R|} \sum_{x \in R} \mathrm{DT}(x), \qquad
+S_{\max} \,=\, \max_{x \in R \cap \text{local maxima}} \mathrm{DT}(x).
+$$
+
+![](samples/figures/sparsity_max.png)
+
+**VarianceOfLaplacian.** For the fundus image $I$ (grayscale), compute the discrete Laplacian $L = \Delta I$. Image sharpness is summarized as the variance over R:
+
+$$
+\operatorname{Var}\{ L(x) : x \in R \}.
+$$
+
+**DiscFoveaDistance.** With optic disc center $c_{OD}$ and fovea position $p_f$,
+
+$$
+ d_{ODF} \,=\, \lVert c_{OD} - p_f \rVert_2.
+$$
+
+
+### Feature localisation
+
+VascX localises feature computations using anatomical references and predefined grids:
+
+- **Anatomical anchoring**
+  - The optic disc mask and fovea position orient geometry (e.g., OD–fovea axis) and define a retinal mask.
+  - All region masks are intersected with the retinal mask; features operate only on visible retina.
+
+- **Predefined grids** (`rtnls_enface/rtnls_enface/grids`)
+  - `EllipseGrid`: ellipse centered midway between disc and fovea, major axis along OD–fovea. Fields: `FullGrid`, `Superior`, `Inferior`.
+  - `CircleGrid`: disc–fovea–centered circle (radius derived from OD–fovea distance and disc size). Fields: `FullGrid`, `Superior`, `Inferior`.
+  - `ETDRSGrid`: classic ETDRS layout with rings (`Center`, `Inner`, `Outer`), quadrants (`Superior`, `Inferior`, `Nasal`, `Temporal`, plus `Left`/`Right`), and subfields (`CSF`, `SIM`, `NIM`, `TIM`, `IIM`, `SOM`, `NOM`, `TOM`, `IOM`).
+  - `HemifieldGrid`: superior/inferior half-planes split relative to the OD–fovea axis. Fields: `FullGrid`, `Superior`, `Inferior`.
+  - `DiscCenteredGrid`: disc-anchored rings (`inner`, `center`, `outer`) and quadrants (`superior`, `inferior`, `nasal`, `temporal`, plus `left`/`right`), taking laterality into account.
+
+- **Bounds and visibility (CFI bounds)**
+  - For a chosen field, the platform evaluates the fraction within bounds using `grid_field_fraction_in_bounds` (and `grid_field_masks_and_fraction`).
+  - If the fraction in-bounds is too small (typically < 0.5), many features skip computation and return `None` to avoid out-of-frame bias.
+  - Visualizers plot the requested field overlayed on the image; computations always respect in-bounds masking.
+
+Ready-to-run feature sets are available under `vascx/fundus/feature_sets` (e.g., `full`, `bergmann`, `quality`) and can be selected by name when using `extract_in_parallel`. To generate feature descriptions alongside extraction:
+
+Ready-to-run feature sets are available under `vascx/fundus/feature_sets` (e.g., `full`, `bergmann`, `quality`) and can be selected by name when using `extract_in_parallel`. To generate feature descriptions alongside extraction:
+
+```python
+df = extract_in_parallel(examples, "full", n_jobs=8, descriptions_output_path="feature_descriptions_full.txt")
+```
+
+
+## Citation
+
+If you use VascX, please cite our paper:
+
+Jose Vargas Quiros, Bart Liefers, Karin A. van Garderen, Jeroen P. Vermeulen, Caroline Klaver; VascX Models: Deep Ensembles for Retinal Vascular Analysis From Color Fundus Images. Trans. Vis. Sci. Tech. 2025;14(7):19. https://doi.org/10.1167/tvst.14.7.19.

vascx-1.0/README.md

@@ -0,0 +1,243 @@
+## VascX retinal vascular analysis
+
+VascX was created for the extraction of vascular features from fundus image segmentations.
+
+**Important!** This repository contains the feature extraction part of the VascX pipeline.
+
+For details about our segmentation models please refer our [models repository](https://github.com/Eyened/rtnls_vascx_models) an its related open access paper [VascX Models: Deep Ensembles for Retinal Vascular Analysis From Color Fundus Images](https://tvst.arvojournals.org/article.aspx?articleid=2810436)
+
+### Installation
+
+To install the entire fundus analysis pipeline including fundus preprocessing, model inference code and vascular biomarker extraction:
+
+1. Create a virtual environment, or otherwise ensure a clean environment.
+
+2. Install VascX:
+
+```
+pip install retinalysis-vascx
+```
+
+### Usage
+
+To speed up re-execution of VascX we recommend to run the segmentation and feature extraction steps separately:
+
+To run on the provided samples folder in our git repository:
+
+```
+git clone git@github.com:Eyened/retinalysis-vascx.git rtnls_vascx
+cd rtnls_vascx
+vascx run-models ./samples/fundus/original/ /path/to/segmentations
+vascx calc-biomarkers /path/to/segmentations /path/to/features.csv --feature_set full --n-jobs 8 --logfile /path/to/logfile.txt
+```
+
+Note that `vascx run-models` will write segmentations and other model predictions to `/path/to/segmentations`, which will have the following structure:
+
+```
+/path/to/segmentations
+  - preprocessed_rgb/ - preprocessed fundus images
+  - artery_vein/ - artery-vein model segmentations
+  - vessels/ - vessel model segmentations
+  - disc/ - optic disc model segmentations
+  - overlays/ - optional overlays showing the segmentations
+  - bounds.csv - contains the bounds of the fundus image
+  - fovea.csv - model predictions of the fovea locations for each image
+  - quality.csv - model estimations of CFI quality
+```
+
+The folders above will contain images with matching filenames.
+
+
+We also provide notebooks for running the three stages:
+
+1. Preprocessing. See [this notebook](./notebooks/0_preprocess.ipynb). This step is CPU-heavy and benefits from parallelization (see notebook).
+
+2. Inference. See [this notebook](./notebooks/1_segment_preprocessed.ipynb). All models can be ran in a single GPU with >10GB VRAM.
+
+3. Feature extraction. See [this notebook](./notebooks/2_feature_extraction.ipynb). This step is CPU-heavy again and benefits from parallelization (see notebook).
+
+
+
+### Implementation
+
+
+
+VascX processes vessel segmentations through four main stages, each producing different data representations:
+
+- **Input masks**: `np.ndarray[bool]` per layer; optic disc and fovea metadata from segmentation models.
+
+- **Stage 1 - Binary/skeleton**: 
+  - `binary`: filled vessel mask after disc masking
+  - `binary_nodisc`: vessel mask without disc region
+  - `skeleton`: skeletonized vessel centerlines using skimage skeletonization
+
+- **Stage 2 - Undirected graph**: 
+  - NetworkX `Graph` with skeleton pixels as nodes
+  - `Segment` objects stored on edges containing skeleton points and geometric properties
+  - Each segment represents a vessel segment between junction points
+
+- **Stage 3 - Directed digraph**: 
+  - NetworkX `DiGraph` with flow direction from optic disc outward
+  - `trees`: root nodes representing vessel trees emanating from disc
+  - `nodes`: `Endpoint` and `Bifurcation` objects with spatial positions
+  - `segments`: directed vessel segments with computed properties (diameter, length, etc.)
+
+- **Stage 4 - Resolved vessels**: 
+  - Merged vessel graph after running vessel resolution algorithm
+  - `resolved_segments`: final vessel segments after merging short segments
+  - Segment-to-pixel mapping for spatial feature computation
+
+Biomarker families use different representations: mask-based features use `binary`; topology features use `digraph` and `nodes`; morphological features use `segments` with computed diameters; spatial features use segment-to-pixel mappings.
+
+### Biomarkers
+
+VascX computes retinal vascular biomarkers from standardized representations (binary masks, undirected/directed graphs, resolved vessels). Below we describe each feature with the exact quantity being estimated and the equations used. Throughout, B denotes the stage‑1 binary vessel mask, S the set of eligible directed segments with lengths \(\ell_i\), and R an analysis region of interest; cardinalities count pixels, and distances are in pixels unless noted.
+
+**VascularDensity.** The fraction of retinal area occupied by vessels in R, computed on the binary mask B:
+
+$$
+D \,=\, \frac{|B \cap R|}{|R|}.
+$$
+
+![](samples/figures/vascular_density.png)
+
+**BifurcationCount.** The count of branching points in the directed graph (stage‑3). Let $\mathcal{B}$ be the set of bifurcation nodes with positions $p_b$:
+
+$$
+C \,=\, \sum_{b \in \mathcal{B}} \mathbf{1}[p_b \in R].
+$$
+
+![](samples/figures/bifurcation_count.png)
+
+**BifurcationAngles.** For each bifurcation $b$ at position $p_b$, outgoing branch directions are estimated by sampling the branches' splines at distance $\delta$ from the node along each branch at points $q_1$ and $q_2$. Unit vectors $(u_b, v_b)$ are defined from the bifurcation point to the sample points:
+
+$$
+u_b = \frac{q_1 - p_b}{\|q_1 - p_b\|}, \quad v_b = \frac{q_2 - p_b}{\|q_2 - p_b\|},
+$$
+
+and the bifurcation angle is defined as the angle between these vectors:
+
+$$
+\theta_b \,=\, \arccos(u_b \cdot v_b), \quad \theta_b \in [0^\circ, 180^\circ].
+$$
+
+Angles exceeding 160° are discarded as non-bifurcating continuations. Summary statistics (e.g., mean/median) are reported across valid nodes.
+
+![](samples/figures/bifurcation_angles.png)
+
+**Caliber.** For each segment $i$, diameters are sampled along a spline fitted to its skeleton by projecting spline normals to the vessel boundary on B. The per‑segment diameter is the median along its arclength. The reported caliber aggregates over eligible segments (length $\ell_i \ge \ell_{\min}$):
+
+$$
+\operatorname{Caliber} \,=\, g\big(\{ d_i : i \in S \}\big),
+$$
+
+where \(g\) is a robust statistic (typically the median).
+
+![](samples/figures/caliber.png)
+
+**Tortuosity.** Three complementary measures are provided per segment (or per resolved vessel). Let $L_{\text{arc},i}$ be arclength and $L_{\text{chord},i}$ the end‑to‑end Euclidean distance.
+
+- Distance factor:
+
+$$
+T_i^{\text{DF}} \,=\, \frac{L_{\text{arc},i}}{L_{\text{chord},i}}.
+$$
+
+- Curvature‑based measure, using planar curvature $\kappa_i(s)$ and OD–fovea distance $d_{ODF}$ for scale normalization:
+
+$$
+T_i^{\kappa} \,=\, \frac{1}{L_{\text{arc},i}} \int_0^{L_{\text{arc},i}} \big|\kappa_i(s)\big| \, ds \; \cdot \; d_{ODF}.
+$$
+
+- Inflection count (number of curvature sign changes along the centerline):
+
+$$
+T_i^{\text{INF}} \,=\, N^{(i)}_{\text{inflections}}.
+$$
+
+When reporting a single score over multiple segments, length‑weighted aggregation may be used for normalization:
+
+$$
+T_{\text{tot}} \,=\, \sum_{i \in S} \left( \frac{\ell_i}{\sum_{j \in S} \ell_j} \right) t_i,
+$$
+
+with $t_i$ any of the measures above.
+
+![](samples/figures/tortuosity.png)
+
+**CRE (Central Retinal Equivalents).** Concentric circles centered at the optic disc are intersected with the vessel network. At each radius $r$, up to $M$ crossings with the largest segment median diameters are retained and recursively reduced via the Hubbard rule with a modality‑dependent constant $c$ (arteries: 0.88; veins: 0.95):
+
+$$
+ d \leftarrow c\,\sqrt{d_1^2 + d_2^2}
+$$
+
+applied pairwise until a single equivalent caliber $d_r$ remains. The final CRE is the median of $\{d_r\}$ across radii.
+
+![](samples/figures/cre.png)
+
+**TemporalAngle.** On each concentric circle of radius \(r\), the two dominant temporal vessels are identified by diameter and spatial continuity. The angle at the disc center is
+
+$$
+\theta_r \,=\, \angle\big(\overline{OD\,p_1(r)},\, \overline{OD\,p_2(r)}\big),
+$$
+
+and the reported value is the median over radii.
+
+![](samples/figures/temporal_angle.png)
+
+**Sparsity.** Let $\mathrm{DT}(x)$ represent the distance transform over $R$, ie. the normalized Euclidean distance to the nearest vessel pixel (scaled by $d_{ODF}$). Over pixels in R we report either the mean or the largest local maximum:
+
+$$
+S_{\text{mean}} \,=\, \frac{1}{|R|} \sum_{x \in R} \mathrm{DT}(x), \qquad
+S_{\max} \,=\, \max_{x \in R \cap \text{local maxima}} \mathrm{DT}(x).
+$$
+
+![](samples/figures/sparsity_max.png)
+
+**VarianceOfLaplacian.** For the fundus image $I$ (grayscale), compute the discrete Laplacian $L = \Delta I$. Image sharpness is summarized as the variance over R:
+
+$$
+\operatorname{Var}\{ L(x) : x \in R \}.
+$$
+
+**DiscFoveaDistance.** With optic disc center $c_{OD}$ and fovea position $p_f$,
+
+$$
+ d_{ODF} \,=\, \lVert c_{OD} - p_f \rVert_2.
+$$
+
+
+### Feature localisation
+
+VascX localises feature computations using anatomical references and predefined grids:
+
+- **Anatomical anchoring**
+  - The optic disc mask and fovea position orient geometry (e.g., OD–fovea axis) and define a retinal mask.
+  - All region masks are intersected with the retinal mask; features operate only on visible retina.
+
+- **Predefined grids** (`rtnls_enface/rtnls_enface/grids`)
+  - `EllipseGrid`: ellipse centered midway between disc and fovea, major axis along OD–fovea. Fields: `FullGrid`, `Superior`, `Inferior`.
+  - `CircleGrid`: disc–fovea–centered circle (radius derived from OD–fovea distance and disc size). Fields: `FullGrid`, `Superior`, `Inferior`.
+  - `ETDRSGrid`: classic ETDRS layout with rings (`Center`, `Inner`, `Outer`), quadrants (`Superior`, `Inferior`, `Nasal`, `Temporal`, plus `Left`/`Right`), and subfields (`CSF`, `SIM`, `NIM`, `TIM`, `IIM`, `SOM`, `NOM`, `TOM`, `IOM`).
+  - `HemifieldGrid`: superior/inferior half-planes split relative to the OD–fovea axis. Fields: `FullGrid`, `Superior`, `Inferior`.
+  - `DiscCenteredGrid`: disc-anchored rings (`inner`, `center`, `outer`) and quadrants (`superior`, `inferior`, `nasal`, `temporal`, plus `left`/`right`), taking laterality into account.
+
+- **Bounds and visibility (CFI bounds)**
+  - For a chosen field, the platform evaluates the fraction within bounds using `grid_field_fraction_in_bounds` (and `grid_field_masks_and_fraction`).
+  - If the fraction in-bounds is too small (typically < 0.5), many features skip computation and return `None` to avoid out-of-frame bias.
+  - Visualizers plot the requested field overlayed on the image; computations always respect in-bounds masking.
+
+Ready-to-run feature sets are available under `vascx/fundus/feature_sets` (e.g., `full`, `bergmann`, `quality`) and can be selected by name when using `extract_in_parallel`. To generate feature descriptions alongside extraction:
+
+Ready-to-run feature sets are available under `vascx/fundus/feature_sets` (e.g., `full`, `bergmann`, `quality`) and can be selected by name when using `extract_in_parallel`. To generate feature descriptions alongside extraction:
+
+```python
+df = extract_in_parallel(examples, "full", n_jobs=8, descriptions_output_path="feature_descriptions_full.txt")
+```
+
+
+## Citation
+
+If you use VascX, please cite our paper:
+
+Jose Vargas Quiros, Bart Liefers, Karin A. van Garderen, Jeroen P. Vermeulen, Caroline Klaver; VascX Models: Deep Ensembles for Retinal Vascular Analysis From Color Fundus Images. Trans. Vis. Sci. Tech. 2025;14(7):19. https://doi.org/10.1167/tvst.14.7.19.

vascx-1.0/notebooks/0_preprocess.ipynb

@@ -0,0 +1,131 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "import pandas as pd\n",
+    "from matplotlib import pyplot as plt\n",
+    "from rtnls_fundusprep.preprocessor import parallel_preprocess"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Preprocessing\n",
+    "\n",
+    "This code will preprocess the images and write .png files with the square fundus image and the contrast enhanced version\n",
+    "\n",
+    "This step is not strictly necessary, but it is useful if you want to run the preprocessing step separately before model inference\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Create a list of files to be preprocessed:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds_path = Path(\"../samples/fundus\")\n",
+    "files = list((ds_path / \"original\").glob(\"*\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Images with .dcm extension will be read as dicom and the pixel_array will be read as RGB. All other images will be read using PIL's Image.open"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "0it [00:00, ?it/s][Parallel(n_jobs=4)]: Using backend LokyBackend with 4 concurrent workers.\n",
+      "6it [00:00, 1511.28it/s]"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "[Parallel(n_jobs=4)]: Done   2 out of   6 | elapsed:    1.2s remaining:    2.3s\n",
+      "[Parallel(n_jobs=4)]: Done   3 out of   6 | elapsed:    1.2s remaining:    1.2s\n",
+      "[Parallel(n_jobs=4)]: Done   4 out of   6 | elapsed:    1.2s remaining:    0.6s\n",
+      "[Parallel(n_jobs=4)]: Done   6 out of   6 | elapsed:    1.6s finished\n"
+     ]
+    }
+   ],
+   "source": [
+    "bounds = parallel_preprocess(\n",
+    "    files,                    # List of image files\n",
+    "    rgb_path=ds_path / \"rgb\", # Output path for RGB images\n",
+    "    ce_path=ds_path / \"ce\",   # Output path for Contrast Enhanced images\n",
+    "    n_jobs=4,                 # number of preprocessing workers\n",
+    ")\n",
+    "df_bounds = pd.DataFrame(bounds).set_index(\"id\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The preprocessor will produce RGB and contrast-enhanced preprocessed images cropped to a square and return a dataframe with the image bounds that can be used to reconstruct the original image. Output files will be named the same as input images, but with .png extension. Be careful with providing multiple inputs with the same filename without extension as this will result in over-written images. Any exceptions during pre-processing will not stop execution but will print error. Images that failed pre-processing for any reason will be marked with `success=False` in the df_bounds dataframe."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df_bounds.to_csv(ds_path / \"meta.csv\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "rtnls",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}