Skip to main content

batchgenerators by MIC@DKFZ

Copyright German Cancer Research Center (DKFZ) and contributors. Please make sure that your usage of this code is in compliance with its license.

batchgenerators is a python package for data augmentation. It is developed jointly between the Division of Medical Image Computing at the German Cancer Research Center (DKFZ) and the Applied Computer Vision Lab of the Helmholtz Imaging Platform.

It is not (yet) perfect, but we feel it is good enough to be shared with the community. If you encounter bug, feel free to contact us or open a github issue.

If you use it please cite the following work:

Isensee Fabian, Jäger Paul, Wasserthal Jakob, Zimmerer David, Petersen Jens, Kohl Simon, 
Schock Justus, Klein Andre, Roß Tobias, Wirkert Sebastian, Neher Peter, Dinkelacker Stefan, 
Köhler Gregor, Maier-Hein Klaus (2020). batchgenerators - a python framework for data 
augmentation. doi:10.5281/zenodo.3632567

batchgenerators also contains the following application-specific augmentations:

  • Anatomy-informed Data Augmentation
    Proposed at MICCAI 2023 for simulation of soft-tissue deformations. Implementation details can be found here.
  • Misalignment Data Augmentation
    Proposed in Nature Scientific Reports 2023 for enhancing model's adaptability to diverse misalignments
    between multi-modal (multi-channel) images and thereby ensuring robust performance. Implementation details can be found here.

If you use these augmentations please cite them too.

Build Status

Supported Augmentations

We supports a variety of augmentations, all of which are compatible with 2D and 3D input data! (This is something that was missing in most other frameworks).

  • Spatial Augmentations
    • mirroring
    • channel translation (to simulate registration errors)
    • elastic deformations
    • rotations
    • scaling
    • resampling
    • multi-channel misalignments
  • Color Augmentations
    • brightness (additive, multiplivative)
    • contrast
    • gamma (like gamma correction in photo editing)
  • Noise Augmentations
    • Gaussian Noise
    • Rician Noise
    • ...will be expanded in future commits
  • Cropping
    • random crop
    • center crop
    • padding
  • Anatomy-informed Augmentation

Note: Stack transforms by using batchgenerators.transforms.abstract_transforms.Compose. Finish it up by plugging the composed transform into our multithreader: batchgenerators.dataloading.multi_threaded_augmenter.MultiThreadedAugmenter

How to use it

The working principle is simple: Derive from DataLoaderBase class, reimplement generate_train_batch member function and use it to stack your augmentations! For simple example see batchgenerators/examples/example_ipynb.ipynb

A heavily commented example for using SlimDataLoaderBase and MultithreadedAugmentor is available at: batchgenerators/examples/multithreaded_with_batches.ipynb. It gives an idea of the interplay between the SlimDataLoaderBase and the MultiThreadedAugmentor. The example uses the MultiThreadedAugmentor for loading and augmentation on mutiple processes, while covering the entire dataset only once per epoch (basically sampling without replacement).

We also now have an extensive example for BraTS2017/2018 with both 2D and 3D DataLoader and augmentations: batchgenerators/examples/brats2017/

There are also CIFAR10/100 datasets and DataLoader available at batchgenerators/datasets/cifar.py

Data Structure

The data structure that is used internally (and with which you have to comply when implementing generate_train_batch) is kept simple as well: It is just a regular python dictionary! We did this to allow maximum flexibility in the kind of data that is passed along through the pipeline. The dictionary must have a 'data' key:value pair. It optionally can handle a 'seg' key:vlaue pair to hold a segmentation. If a 'seg' key:value pair is present all spatial transformations will also be applied to the segmentation! A part from 'data' and 'seg' you are free to do whatever you want (your image classification/regression target for example). All key:value pairs other than 'data' and 'seg' will be passed through the pipeline unmodified.

'data' value must have shape (b, c, x, y) for 2D or shape (b, c, x, y, z) for 3D! 'seg' value must have shape (b, c, x, y) for 2D or shape (b, c, x, y, z) for 3D! Color channel may be used here to allow for several segmentation maps. If you have only one segmentation, make sure to have shape (b, 1, x, y (, z))

How to install locally

Install batchgenerators

pip install --upgrade batchgenerators

Import as follows

from batchgenerators.transforms.color_transforms import ContrastAugmentationTransform

Windows Support is very experimental!

Batchgenerators makes heavy use of python multiprocessing and python multiprocessing on windows is different from linux. To prevent the workers from freezing in windows, you have to guard your code with if __name__ == '__main__' and use multiprocessing's freeze_support. The executed script may then look like this:

# some imports and functions here

def main():
    # do some stuff

if __name__ == '__main__':
    from multiprocessing import freeze_support
    freeze_support()
    main()

This is not required on Linux.

Release Notes

(only highlights, not an exhaustive list)

  • 0.23.2:

    • Misalignment data augmentation added
  • 0.23.1:

    • Anatomy-informed data augmentation added
  • 0.23:

    • fixed the import mess. __init__.py files are now empty. This is a breaking change for some users! Please adapt your imports :-)
    • local_transforms are now a thing, check them out!
    • resize_segmentation now uses 'edge' mode and no longer takes a cval argument. Resizing segmentations with constant border values (previous default) can cause problems and should not be done.
  • 0.20.0:

    • fixed an issue with MultiThreadedAugmenter not terminating properly after KeyboardInterrupt; Fixed an error with the number and order of samples being returned when pin_memory=True; Improved performance by always hiding process-process communication bottleneck through threading
  • 0.19.5:

    • fixed OMP_NUM_THREADS issue by using threadpoolctl package; dropped python 2 support (threadpoolctl is not available for python 2)
  • 0.19:

    • There is now a complete example for BraTS2017/8 available for both 2D and 3D. Use this if you would like to get some insights on how I (Fabian) do my experiments
    • Windows is now supported! Thanks @justusschock for your support!
    • new, simple parametrization of elastic deformation. Use SpatialTransform_2!
    • CIFAR10/100 DataLoader are now available for your convenience
    • a bug in MultiThreadedAugmenter that could interfere with reproducibility is now fixed
  • 0.18:

    • all augmentations (there are some exceptions though) are implemented on a per-sample basis. This should make it easier to use the augmentations outside of the Transforms of batchgenerators
    • applicable Transforms now have a keyword p_per_sample with which the user can specify a probability with which this transform is applied to a sample. Before, this was handled by RndTransform and applied to the whole batch (so either all samples were augmented or none). Now this decision is made on a per-sample basis and increases variability by a lot.
    • following the previous point, RndTransform is now deprecated
    • AlternativeMultiThreadedAugmenter is now deprecated as well (no need to have this anymore)
    • pytorch users can now transform numpy arrays to pytorch tensors within batchgenerators (NumpyToTensor). For some reason, inter-process communication is faster with tensors (~factor 4), so this is recommended!
    • if numpy arrays were converted to pytorch tensors, MultithreadedAugmenter now allows to pin the memory as well (pin_memory=True). This will happen in a background thread (inspired by pytorch DataLoader). pinned memory can be copied to the GPU much faster. My (Fabian) classification experiment with Resnet50 got a speed boost of 12% from just that.

batchgenerators is developed by the Division of Medical Image Computing of the German Cancer Research Center (DKFZ) and the Applied Computer Vision Lab (ACVL) of the Helmholtz Imaging Platform.

Metadata

Release files for batchgenerators 0.25.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for batchgenerators 0.25.6
File Size Uploaded Provenance Actions
batchgenerators-0.25.6.tar.gz 107.7 kB With provenance Details for batchgenerators-0.25.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for batchgenerators 0.25.6
File Interpreter ABI Platform Actions
batchgenerators-0.25.6-py3-none-any.whl Python 3 none any Details for batchgenerators-0.25.6-py3-none-any.whl

Total release size: 216.0 kB

Release files / batchgenerators-0.25.6.tar.gz

Download URL batchgenerators-0.25.6.tar.gz
Size 107.7 kB
Tags Source
SHA-256 checksum
How to use checksums
6aabe8c3179410200b9a202d1a7c1699bd8a0633378af7656d4c452c2f1a1c35
BLAKE2b-256 checksum
How to use checksums
83fce60005b021140eabe7088a05f48628338ce57ea29be14a921eac2296fb70
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / batchgenerators-0.25.6-py3-none-any.whl

Download URL batchgenerators-0.25.6-py3-none-any.whl
Size 108.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e36d0f039cece500424318718c47dd5cffb69495a3630c28cb142fe3593f594a
BLAKE2b-256 checksum
How to use checksums
ad90f8bc50ee1dc32d5efeedf842913b6fd7eb0c397e50c24476a8bb3832d3b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for batchgenerators 0.25.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for batchgenerators-0.25.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page