Data

Tools

Indexes

Applications

Experiments

Open Source Science

Fundus Image Toolbox

Fundus Image Toolbox: A Python package for fundus image processing - Published in JOSS (2025)

https://github.com/berenslab/fundus_image_toolbox

Science Score: 95.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ✓
    DOI references
    Found 14 DOI reference(s) in README and JOSS metadata
  • ✓
    Academic publication links
    Links to: arxiv.org, joss.theoj.org, zenodo.org
  • ✓
    Committers with academic emails
    1 of 3 committers (33.3%) from academic institutions
  • ○
    Institutional organization owner
  • ✓
    JOSS paper metadata
    Published in Journal of Open Source Software

Scientific Fields

Mathematics Computer Science - 88% confidence
Artificial Intelligence and Machine Learning Computer Science - 62% confidence
Last synced: 4 months ago · JSON representation

Repository

A Python package for fundus image processing.

Basic Info
  • Host: GitHub
  • Owner: berenslab
  • License: mit
  • Language: Jupyter Notebook
  • Default Branch: main
  • Homepage:
  • Size: 43.3 MB
Statistics
  • Stars: 15
  • Watchers: 4
  • Forks: 2
  • Open Issues: 0
  • Releases: 3
Created over 1 year ago · Last pushed 7 months ago
Metadata Files
Readme License

Readme.md

Fundus Image Toolbox

DOI Logo

Fundus quality prediction A quality prediction model for fundus images (gradeable vs. ungradeable) based on an ensemble of 10 models (ResNets and EfficientNets) trained on DeepDRiD and DrimDB data. Can be just used for prediction or retrained.
Read more.
Example image
Fundus fovea and optic disc localization A model to predict the center coordinates of the fovea and the optic disc in fundus images based on a multi-task EfficientNet trained on ADAM, REFUGE and IDRID datasets. Can be just used for prediction or retrained.
Read more.
Example image
Example predictions from the external dataset "DeepDRiD".
Fundus registration Align a fundus photograph to another fundus photograph from the same eye using SuperRetina (Liu et al., 2022). Image registration also goes by the terms image alignment and image matching.
Read more.
Example image
Fundus vessel segmentation Segment the blood vessels in a fundus image using an ensemble of FR-U-Nets trained on the FIVES dataset (Köhler et al., 2024).
Read more.
Example image
Fundus circle crop Fastly crop fundus images to a circle and center it (Fu et al., 2019).
Read more.
Example image
Fundus utilities A collection of additional utilities that can come in handy when working with fundus images.
Read more.
- ImageTorchUtils: Image manipulation based on Pytorch tensors. - Balancing: A script to balance a torch dataset by both oversampling the minority class and undersampling the majority class from [imbalanced-dataset-sampler](https://github.com/ufoym/imbalanced-dataset-sampler/). - Fundus transforms: A collection of torchvision data augmentation transforms to apply to fundus images adapted from [pytorch-classification](https://github.com/YijinHuang/pytorch-classification/blob/master/data/transforms.py). - Get pixel mean std: A script to calculate the mean and standard deviation of the pixel values of a dataset by channel. - Get efficientnet resnet: Getter for torchvision models with efficientnet and resnet architectures initialized with ImageNet weights. - Lr scheduler: Get a pytorch learning rate scheduler (plus a warmup scheduler) for a given optimizer: OneCycleLR, CosineAnnealingLR, CosineAnnealingWarmRestarts. - Multilevel 3-way split: Split a pandas dataframe into train, validation and test splits with the options to split by group (i.e. keep groups together) and stratify by label. Wrapper for [multi_level_split](https://github.com/lmkoch/multi-level-split/). - Seed everything: Set seed for reproducibility in python, numpy and torch.

Usage

The following code summarises the usage of the toolbox. See the usage_all.ipynb for a tutorial notebook and examples directory for more detailed usage examples information on the respective packages. ```python

Get sample images. All methods work on path(s) to image(s) or on image(s) as numpy arrays, tensors or PIL images.

fundus1, fundus2 = "path/to/fundus1.jpg", "path/to/fundus2.jpg" ```

python import fundus_image_toolbox as fit fundus1_cropped = fit.crop(fundus1, size=(512,512)) # > np.ndarray (512, 512, 3) uint8

python import fundus_image_toolbox as fit model, _ = fit.load_fovea_od_model(device="cuda:0") coordinates = model.predict([fundus1, fundus2]) # > List[np.ndarray[fovea_x,fovea_y,od_x,od_y], ...] fit.plot_coordinates([fundus1, fundus2], coordinates)

python import fundus_image_toolbox as fit ensemble = fit.load_quality_ensemble(device="cuda:0") confs, labels = fit.ensemble_predict_quality(ensemble, [fundus1, fundus2], threshold=0.5) # > np.ndarray[conf1, conf2], np.ndarray[label1, label2] for img, conf, label in zip([fundus1, fundus2], confs, labels): fit.plot_quality(img, conf, label, threshold=0.5)

```python import fundusimagetoolbox as fit

config = fit.getregistrationconfig()

if wanted, change the config dictionary

model, matcher = fit.loadregistrationmodel(config)

movingimagealigned = fit.register( fundus1, fundus2, show=True, showmapping=False, config=config, model=model, matcher=matcher ) # > np.ndarray (hin, w_in, 3) uint8 ```

python import fundus_image_toolbox as fit ensemble = fit.load_segmentation_ensemble(device=device) vessel_masks = fit.ensemble_predict_segmentation(ensemble, [fundus1, fundus2], threshold=0.5, size=(512, 512)) # > np.ndarray[np.ndarray[h_in, w_in], ...] float64 fit.plot_masks([fundus1, fundus2], vessel_masks)

Installation

Install the toolbox

You can install the latest tagged version of the toolbox by running:

bash pip install fundus_image_toolbox

or the development version by running:

bash pip install git+https://github.com/berenslab/fundus_image_toolbox

Create a virtual environment

Alternatively, you can create a new conda environment and install the toolbox there: bash conda create --name fundus_image_toolbox python=3.9.19 pip conda activate fundus_image_toolbox And then pip install fundus_image_toolbox or pip install . within the new environment.
Or create a new virtual environment including the toolbox with uv:
bash uv venv source .venv/bin/activate

Contribute

You are very welcome to contribute to the toolbox. Please raise an issue or create a pull request to do so. Please feel free to contact us if you have any questions or need help via julius.gervelmeyer [at] uni-tuebingen.de.

Cite

If you use this toolbox in your research, please consider citing it:

Gervelmeyer et al., (2025). Fundus Image Toolbox: A Python package for fundus image processing. Journal of Open Source Software, 10(108), 7101, https://doi.org/10.21105/joss.07101

Bibtex ```bibtex @article{Gervelmeyer2025-fit, title = "Fundus Image Toolbox: A Python package for fundus image processing", author = "Gervelmeyer, Julius and M{\"u}ller, Sarah and Huang, Ziwei and Berens, Philipp", journal = "Journal of Open Source Software", publisher = "The Open Journal", volume = 10, number = 108, pages = "7101", month = apr, year = 2025, doi = "https://doi.org/10.21105/joss.07101", } ```


If you use external parts of the toolbox that this toolbox provides an interface for, please consider citing the respective papers: - Fundus registration: Liu et al., 2022 - Fundus vessel segmentation: Köhler et al., 2024 - Fundus circle crop: Fu et al., 2019 <!-- - Müller et al., 2023 --> <!-- - -->

License

The toolbox is licensed under the MIT License. See the license file for more information. <!-- As external packages are used, please check the respective licenses. That includes fundusvesselsegmentation.-->

Owner

  • Name: Berens Lab @ University of Tübingen
  • Login: berenslab
  • Kind: organization
  • Email: philipp.berens@uni-tuebingen.de
  • Location: Tübingen, Germany

Department of Data Science at the Hertie Institute for AI in Brain Health, University of Tübingen

JOSS Publication

Fundus Image Toolbox: A Python package for fundus image processing
Published
April 03, 2025
DOI
Volume 10, Issue 108, Page 7101
Authors
Julius Gervelmeyer ORCID
Hertie Institute for AI in Brain Health, University of Tübingen, Tübingen, Germany
Sarah Müller ORCID
Hertie Institute for AI in Brain Health, University of Tübingen, Tübingen, Germany
Ziwei Huang ORCID
Hertie Institute for AI in Brain Health, University of Tübingen, Tübingen, Germany
Philipp Berens ORCID
Hertie Institute for AI in Brain Health, University of Tübingen, Tübingen, Germany
Editor
Øystein Sørensen ORCID
Tags
fundus image retina registration optic disc fovea vessel segmentation quality prediction circle crop
View PDF Review Thread Software Archive

GitHub Events

Total
  • Create event: 8
  • Release event: 4
  • Issues event: 4
  • Watch event: 10
  • Delete event: 5
  • Issue comment event: 3
  • Push event: 64
  • Pull request event: 29
Last Year
  • Create event: 8
  • Release event: 4
  • Issues event: 4
  • Watch event: 10
  • Delete event: 5
  • Issue comment event: 3
  • Push event: 64
  • Pull request event: 29

Committers

Last synced: 5 months ago

All Time
  • Total Commits: 88
  • Total Committers: 3
  • Avg Commits per committer: 29.333
  • Development Distribution Score (DDS): 0.114
Past Year
  • Commits: 60
  • Committers: 3
  • Avg Commits per committer: 20.0
  • Development Distribution Score (DDS): 0.167
Top Committers
Name Email Commits
juliusge j****r@s****e 78
juliusge 3****e 8
Ziwei Huang h****i@o****m 2
Committer Domains (Top 20 + Academic)
student.uni-tuebingen.de: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time
  • Total issues: 2
  • Total pull requests: 29
  • Average time to close issues: 6 days
  • Average time to close pull requests: 2 days
  • Total issue authors: 2
  • Total pull request authors: 2
  • Average comments per issue: 1.5
  • Average comments per pull request: 0.0
  • Merged pull requests: 29
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 2
  • Pull requests: 25
  • Average time to close issues: 6 days
  • Average time to close pull requests: 2 days
  • Issue authors: 2
  • Pull request authors: 2
  • Average comments per issue: 1.5
  • Average comments per pull request: 0.0
  • Merged pull requests: 25
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • Eason-Qin (1)
  • msayhan (1)
Pull Request Authors
  • juliusge (28)
  • huangziwei (1)
Top Labels
Issue Labels
Pull Request Labels

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 207 last-month
  • Total dependent packages: 0
  • Total dependent repositories: 0
  • Total versions: 5
  • Total maintainers: 1
pypi.org: fundus-image-toolbox

A toolbox for fundus image analysis

  • Versions: 5
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 207 Last month
Rankings
Dependent packages count: 9.9%
Average: 33.0%
Dependent repos count: 56.0%
Maintainers (1)
berenslab
Last synced: 4 months ago

Dependencies

pyproject.toml pypi
.github/workflows/python-publish.yml actions
  • actions/checkout v4 composite
  • actions/download-artifact v4 composite
  • actions/setup-python v5 composite
  • actions/upload-artifact v4 composite
  • pypa/gh-action-pypi-publish release/v1 composite
fundus_image_toolbox/registration/SuperRetina/requirements.txt pypi
  • Pillow ==9.2.0
  • PyYAML ==6.0
  • imgaug ==0.4.0
  • matplotlib ==3.5.1
  • numpy ==1.22.3
  • opencv_python ==4.6.0.66
  • scikit_learn ==1.1.1
  • scipy ==1.8.0
  • torch ==1.8.1
  • torchvision ==0.9.1
  • tqdm ==4.64.0
uv.lock pypi
  • 194 dependencies