# Bio-Volumentations
`Bio-Volumentations` is an image augmentation and preprocessing package for 3D, 4D, and 5D biomedical images.
It offers a range of image transformations implemented efficiently for time-lapse multi-channel volumetric image data.
This includes both preprocessing transformations (such as intensity normalisation, padding, and type casting)
and augmentation transformations (such as affine transform, noise addition and removal, and contrast manipulation).
The `Bio-Volumentations` library is a suitable tool for data manipulation in machine learning applications.
It can be used with any major Python deep learning library, including PyTorch, PyTorch Lightning, TensorFlow, and Keras.
This library builds upon wide-spread libraries such as Albumentations (see the Contributions section below)
in terms of design and user interface. Therefore, it can easily be adopted by developers.
# Installation
Install the package from pip using:
```python
pip install bio-volumentations
```
## Requirements
NumPy https://numpy.org/ <br>
SciPy https://scipy.org/ <br>
Scikit-image https://scikit-image.org/ <br>
Matplotlib https://matplotlib.org/ <br>
SimpleITK https://simpleitk.org/ <br>
# Usage
### Importing
Import the library to your project using:
```python
import bio_volumentations as biovol
```
### How to Use Bio-Volumentations?
The Bio-Volumentations library processes 3D, 4D, and 5D images. Each image must be
represented as `numpy.ndarray`s and must conform to the following conventions:
- The order of dimensions is [C, Z, Y, X, T], where C is the channel dimension,
T is the time dimension, and Z, Y, and X are the spatial dimensions.
- The three spatial dimensions (Z, Y, X) are compulsory.
- The channel (C) dimension is optional. If it is not present, the library will automatically
create a dummy dimension in its place and output an image of shape (1, Z, Y, X).
- The time (T) dimension is optional and can only be present if the channel (C) dimension is
also present.
Thus, the input images can have these shapes:
- [Z, Y, X] (a single-channel volumetric image)
- [C, Z, Y, X] (a multi-channel volumetric image)
- [C, Z, Y, X, T] (a single-channel as well as multi-channel volumetric image sequence)
**It is strongly recommended to use `Compose` to create and use transformation pipelines.**
The `Compose` class automatically checks and adjusts image format, datatype, stacks
individual transforms to a pipeline, and outputs the image as a contiguous array.
Optionally, it can also convert the transformed image to a desired format.
More at the [documentation pages](https://www.google.com).
Below, there are several examples of how to use this library.
### Example: Transforming a Single Image
```python
import numpy as np
from bio_volumentations import Compose, RandomGamma, RandomRotate90, GaussianBlur
# Create the transformation using Compose from a list of transformations
aug = Compose([
RandomGamma(gamma_limit = (0.8, 1,2), p = 0.8),
RandomRotate90(axes = [1, 2, 3], p = 1),
GaussianBlur(sigma = 1.2, p = 0.8)
])
# Generate an image
img = np.random.rand(1, 128, 256, 256)
# Transform the image
# Notice that the image must be passed as a keyword argument to the transformation pipeline
# and extracted from the outputted dictionary.
data = {'image': img}
aug_data = aug(**data)
transformed_img = aug_data['image']
```
### Example: Transforming Image Tuples
Sometimes, it is necessary to consistently transform a tuple of corresponding images.
To that end, Bio-Volumentations define several target types:
- `image` for the image data;
- `mask` for integer-valued label images; and
- `float_mask` for real-valued label images.
The `mask` and `float_mask` target types are expected to have the same shape as the `image`
target except for the channel (C) dimension which must not be included.
For example, for images of shape (150, 300, 300), (1, 150, 300, 300), or
(4, 150, 300, 300), the corresponding `mask` must be of shape (150, 300, 300).
If one wants to use a multichannel `mask` or `float_mask`, one has to split it into
a set of single-channel `mask`s or `float_mask`s, respectively, and input them
as stand-alone targets (see below).
If a `Random...` transform receives multiple targets on its input in a single call,
the same random numbers are used to transform all of these targets.
However, some transformations might behave slightly differently for the individual
target types. For example, `RandomCrop` works in the same way for all target types, while
`RandomGaussianNoise` only affects the `image` target and leaves the `mask` and
`float_mask` targets unchanged. Please consult the documentation of respective transforms
for more details.
```python
import numpy as np
from bio_volumentations import Compose, RandomGamma, RandomRotate90, GaussianBlur
# Create the transformation using Compose from a list of transformations
aug = Compose([
RandomGamma(gamma_limit = (0.8, 1,2), p = 0.8),
RandomRotate90(axes = [1, 2, 3], p = 1),
GaussianBlur(sigma = 1.2, p = 0.8)
])
# Generate image and a corresponding labeled image
img = np.random.rand(1, 128, 256, 256)
lbl = np.random.randint(0, 1, size=(128, 256, 256), dtype=np.uint8)
# Transform the images
# Notice that the images must be passed as keyword arguments to the transformation pipeline
# and extracted from the outputted dictionary.
data = {'image': img, 'mask': lbl}
aug_data = aug(**data)
transformed_img, transformed_lbl = aug_data['image'], aug_data['mask']
```
### Example: Transforming Multiple Images of the Same Target Type
Although there are only three target types, one input arbitrary number of images to any
transformation. To achieve this, one has to define the value of the `targets` argument
when creating a `Compose` object.
`targets` must be a list with 3 items: a list with names of `image`-type targets,
a list with names of `mask`-type targets, and
a list with names of `float_mask`-type targets. The specified names will then be used
to input the images to the transformation call as well as during extracting the
transformed images from the outputted dictionary. Please see the code below
for a practical example.
```python
import numpy as np
from bio_volumentations import Compose, RandomGamma, RandomRotate90, GaussianBlur
# Create the transformation using Compose from a list of transformations and define targets
aug = Compose([
RandomGamma( gamma_limit = (0.8, 1,2), p = 0.8),
RandomRotate90(axes = [1, 2, 3], p = 1),
GaussianBlur(sigma = 1.2, p = 0.8)
],
targets= [ ['image' , 'image1'] , ['mask'], ['float_mask'] ])
# Generate the image data
img = np.random.rand(1, 128, 256, 256)
img1 = np.random.rand(1, 128, 256, 256)
lbl = np.random.randint(0, 1, size=(128, 256, 256), dtype=np.uint8)
# Transform the images
# Notice that the images must be passed as keyword arguments to the transformation pipeline
# and extracted from the outputted dictionary.
data = {'image': img, 'image1': img1, 'mask': lbl}
aug_data = aug(**data)
transformed_img = aug_data['image']
transformed_img1 = aug_data['image1']
transformed_lbl = aug_data['mask']
```
# Implemented Transforms
### A List of Implemented Transformations
Point transformations:
```python
GaussianNoise
PoissonNoise
GaussianBlur
RandomGaussianBlur
RandomGamma
RandomBrightnessContrast
HistogramEqualization
Normalize
NormalizeMeanStd
```
Geometrical transformations:
```python
AffineTransform
Resize
Scale
Flip
CenterCrop
Pad
RandomAffineTransform
RandomScale
RandomRotate90
RandomFlip
RandomCrop
```
Other:
```python
Float
Contiguous
```
# Contributions
Authors of the Bio-Volumentations library: Samuel Šuľan, Lucia Hradecká, Filip Lux.
- Lucia Hradecká: lucia.d.hradecka@gmail.com
- Filip Lux: lux.filip@gmail.com
The Bio-Volumentations library is based on the following image augmentation libraries:
- Albumentations: https://github.com/albumentations-team/albumentations
- 3D Conversion: https://github.com/ashawkey/volumentations
- Continued Development: https://github.com/ZFTurbo/volumentations
- Enhancements: https://github.com/qubvel/volumentations
- Further Enhancements: https://github.com/muellerdo/volumentations
We would thus like to thank their authors, namely:
- The Albumentations team: https://github.com/albumentations-team
- Pavel Iakubovskii: https://github.com/qubvel
- ZFTurbo: https://github.com/ZFTurbo
- ashawkey: https://github.com/ashawkey
- Dominik Müller: https://github.com/muellerdo
# Citation
TBA
Raw data
{
"_id": null,
"home_page": null,
"name": "bio-volumentations",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.1",
"maintainer_email": null,
"keywords": "image, augmentation, 3D, volumetric, biomedical, bioimage, preprocessing, transformation",
"author": "Lucia Hradeck\u00e1, Filip Lux, Samuel \u0160u\u013ean",
"author_email": "Lucia Hradeck\u00e1 <lucia.d.hradecka@gmail.com>, Filip Lux <lux.filip@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f7/2c/e5d30c465c2dcd63db2f96794bbeb131da6d119410a441fba2e0abe76357/bio_volumentations-1.1.2.tar.gz",
"platform": null,
"description": "# Bio-Volumentations\r\n\r\n`Bio-Volumentations` is an image augmentation and preprocessing package for 3D, 4D, and 5D biomedical images.\r\n\r\nIt offers a range of image transformations implemented efficiently for time-lapse multi-channel volumetric image data.\r\nThis includes both preprocessing transformations (such as intensity normalisation, padding, and type casting) \r\nand augmentation transformations (such as affine transform, noise addition and removal, and contrast manipulation).\r\n\r\nThe `Bio-Volumentations` library is a suitable tool for data manipulation in machine learning applications. \r\nIt can be used with any major Python deep learning library, including PyTorch, PyTorch Lightning, TensorFlow, and Keras.\r\n\r\nThis library builds upon wide-spread libraries such as Albumentations (see the Contributions section below) \r\nin terms of design and user interface. Therefore, it can easily be adopted by developers.\r\n\r\n# Installation\r\n\r\nInstall the package from pip using:\r\n```python\r\npip install bio-volumentations\r\n```\r\n## Requirements\r\n\r\nNumPy https://numpy.org/ <br> \r\nSciPy https://scipy.org/ <br>\r\nScikit-image https://scikit-image.org/ <br>\r\nMatplotlib https://matplotlib.org/ <br>\r\nSimpleITK https://simpleitk.org/ <br>\r\n\r\n\r\n# Usage\r\n\r\n### Importing\r\n\r\nImport the library to your project using:\r\n```python\r\nimport bio_volumentations as biovol\r\n```\r\n\r\n### How to Use Bio-Volumentations?\r\n\r\nThe Bio-Volumentations library processes 3D, 4D, and 5D images. Each image must be \r\nrepresented as `numpy.ndarray`s and must conform to the following conventions:\r\n\r\n- The order of dimensions is [C, Z, Y, X, T], where C is the channel dimension, \r\n T is the time dimension, and Z, Y, and X are the spatial dimensions.\r\n- The three spatial dimensions (Z, Y, X) are compulsory.\r\n- The channel (C) dimension is optional. If it is not present, the library will automatically\r\n create a dummy dimension in its place and output an image of shape (1, Z, Y, X).\r\n- The time (T) dimension is optional and can only be present if the channel (C) dimension is \r\n also present.\r\n\r\nThus, the input images can have these shapes:\r\n\r\n- [Z, Y, X] (a single-channel volumetric image)\r\n- [C, Z, Y, X] (a multi-channel volumetric image)\r\n- [C, Z, Y, X, T] (a single-channel as well as multi-channel volumetric image sequence)\r\n\r\n**It is strongly recommended to use `Compose` to create and use transformation pipelines.** \r\nThe `Compose` class automatically checks and adjusts image format, datatype, stacks\r\nindividual transforms to a pipeline, and outputs the image as a contiguous array. \r\nOptionally, it can also convert the transformed image to a desired format.\r\n\r\nMore at the [documentation pages](https://www.google.com).\r\n\r\nBelow, there are several examples of how to use this library.\r\n\r\n### Example: Transforming a Single Image\r\n\r\n```python\r\nimport numpy as np\r\nfrom bio_volumentations import Compose, RandomGamma, RandomRotate90, GaussianBlur\r\n\r\n# Create the transformation using Compose from a list of transformations\r\naug = Compose([\r\n RandomGamma(gamma_limit = (0.8, 1,2), p = 0.8),\r\n RandomRotate90(axes = [1, 2, 3], p = 1),\r\n GaussianBlur(sigma = 1.2, p = 0.8)\r\n ])\r\n\r\n# Generate an image \r\nimg = np.random.rand(1, 128, 256, 256)\r\n\r\n# Transform the image\r\n# Notice that the image must be passed as a keyword argument to the transformation pipeline\r\n# and extracted from the outputted dictionary.\r\ndata = {'image': img}\r\naug_data = aug(**data)\r\ntransformed_img = aug_data['image']\r\n```\r\n\r\n### Example: Transforming Image Tuples\r\n\r\nSometimes, it is necessary to consistently transform a tuple of corresponding images.\r\nTo that end, Bio-Volumentations define several target types:\r\n\r\n- `image` for the image data;\r\n- `mask` for integer-valued label images; and\r\n- `float_mask` for real-valued label images.\r\n\r\nThe `mask` and `float_mask` target types are expected to have the same shape as the `image`\r\ntarget except for the channel (C) dimension which must not be included. \r\nFor example, for images of shape (150, 300, 300), (1, 150, 300, 300), or\r\n(4, 150, 300, 300), the corresponding `mask` must be of shape (150, 300, 300).\r\nIf one wants to use a multichannel `mask` or `float_mask`, one has to split it into\r\na set of single-channel `mask`s or `float_mask`s, respectively, and input them\r\nas stand-alone targets (see below).\r\n\r\nIf a `Random...` transform receives multiple targets on its input in a single call,\r\nthe same random numbers are used to transform all of these targets.\r\n\r\nHowever, some transformations might behave slightly differently for the individual\r\ntarget types. For example, `RandomCrop` works in the same way for all target types, while\r\n`RandomGaussianNoise` only affects the `image` target and leaves the `mask` and\r\n`float_mask` targets unchanged. Please consult the documentation of respective transforms\r\nfor more details.\r\n\r\n```python\r\nimport numpy as np\r\nfrom bio_volumentations import Compose, RandomGamma, RandomRotate90, GaussianBlur\r\n\r\n# Create the transformation using Compose from a list of transformations\r\naug = Compose([\r\n RandomGamma(gamma_limit = (0.8, 1,2), p = 0.8),\r\n RandomRotate90(axes = [1, 2, 3], p = 1),\r\n GaussianBlur(sigma = 1.2, p = 0.8)\r\n ])\r\n\r\n# Generate image and a corresponding labeled image\r\nimg = np.random.rand(1, 128, 256, 256)\r\nlbl = np.random.randint(0, 1, size=(128, 256, 256), dtype=np.uint8)\r\n\r\n# Transform the images\r\n# Notice that the images must be passed as keyword arguments to the transformation pipeline\r\n# and extracted from the outputted dictionary.\r\ndata = {'image': img, 'mask': lbl}\r\naug_data = aug(**data)\r\ntransformed_img, transformed_lbl = aug_data['image'], aug_data['mask']\r\n```\r\n\r\n\r\n### Example: Transforming Multiple Images of the Same Target Type\r\n\r\nAlthough there are only three target types, one input arbitrary number of images to any\r\ntransformation. To achieve this, one has to define the value of the `targets` argument\r\nwhen creating a `Compose` object.\r\n\r\n`targets` must be a list with 3 items: a list with names of `image`-type targets, \r\na list with names of `mask`-type targets, and \r\na list with names of `float_mask`-type targets. The specified names will then be used \r\nto input the images to the transformation call as well as during extracting the\r\ntransformed images from the outputted dictionary. Please see the code below \r\nfor a practical example.\r\n\r\n```python\r\nimport numpy as np\r\nfrom bio_volumentations import Compose, RandomGamma, RandomRotate90, GaussianBlur\r\n\r\n# Create the transformation using Compose from a list of transformations and define targets\r\naug = Compose([\r\n RandomGamma( gamma_limit = (0.8, 1,2), p = 0.8),\r\n RandomRotate90(axes = [1, 2, 3], p = 1),\r\n GaussianBlur(sigma = 1.2, p = 0.8)\r\n ], \r\n targets= [ ['image' , 'image1'] , ['mask'], ['float_mask'] ])\r\n\r\n# Generate the image data\r\nimg = np.random.rand(1, 128, 256, 256)\r\nimg1 = np.random.rand(1, 128, 256, 256)\r\nlbl = np.random.randint(0, 1, size=(128, 256, 256), dtype=np.uint8)\r\n\r\n# Transform the images\r\n# Notice that the images must be passed as keyword arguments to the transformation pipeline\r\n# and extracted from the outputted dictionary.\r\ndata = {'image': img, 'image1': img1, 'mask': lbl}\r\naug_data = aug(**data)\r\ntransformed_img = aug_data['image']\r\ntransformed_img1 = aug_data['image1']\r\ntransformed_lbl = aug_data['mask']\r\n```\r\n\r\n# Implemented Transforms\r\n\r\n### A List of Implemented Transformations\r\n\r\nPoint transformations:\r\n```python\r\nGaussianNoise \r\nPoissonNoise\r\nGaussianBlur \r\nRandomGaussianBlur\r\nRandomGamma \r\nRandomBrightnessContrast \r\nHistogramEqualization \r\nNormalize\r\nNormalizeMeanStd\r\n```\r\n\r\nGeometrical transformations:\r\n```python\r\nAffineTransform\r\nResize \r\nScale\r\nFlip \r\nCenterCrop \r\nPad\r\nRandomAffineTransform\r\nRandomScale \r\nRandomRotate90\r\nRandomFlip \r\nRandomCrop\r\n```\r\n\r\nOther:\r\n```python\r\nFloat\r\nContiguous\r\n```\r\n\r\n\r\n# Contributions\r\n\r\nAuthors of the Bio-Volumentations library: Samuel \u0160u\u013ean, Lucia Hradeck\u00e1, Filip Lux.\r\n- Lucia Hradeck\u00e1: lucia.d.hradecka@gmail.com \r\n- Filip Lux: lux.filip@gmail.com \r\n\r\nThe Bio-Volumentations library is based on the following image augmentation libraries:\r\n- Albumentations: https://github.com/albumentations-team/albumentations \r\n- 3D Conversion: https://github.com/ashawkey/volumentations \r\n- Continued Development: https://github.com/ZFTurbo/volumentations \r\n- Enhancements: https://github.com/qubvel/volumentations \r\n- Further Enhancements: https://github.com/muellerdo/volumentations \r\n\r\nWe would thus like to thank their authors, namely:\r\n- The Albumentations team: https://github.com/albumentations-team \r\n- Pavel Iakubovskii: https://github.com/qubvel \r\n- ZFTurbo: https://github.com/ZFTurbo \r\n- ashawkey: https://github.com/ashawkey \r\n- Dominik M\u00fcller: https://github.com/muellerdo \r\n\r\n\r\n# Citation\r\n\r\nTBA\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Library for 3D-5D augmentations of volumetric multi-dimensional biomedical images",
"version": "1.1.2",
"project_urls": {
"Documentation": "https://biovolumentations.readthedocs.io/v1-1-2/",
"Homepage": "https://gitlab.fi.muni.cz/cbia/bio-volumentations/-/tree/v1-1-0?ref_type=heads",
"Repository": "https://gitlab.fi.muni.cz/cbia/bio-volumentations/-/tree/v1-1-0?ref_type=heads"
},
"split_keywords": [
"image",
" augmentation",
" 3d",
" volumetric",
" biomedical",
" bioimage",
" preprocessing",
" transformation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1577900353d624cc99d0bb48455bece5501e04452a5f172ca6d9fb31479f1bdc",
"md5": "4d8d71bffc3b79ff924fbfb51a7a148b",
"sha256": "83c0f000077600ed061221d1095f7ae72b4ce033ace6a1f2de4cd3a1b0a69ea6"
},
"downloads": -1,
"filename": "bio_volumentations-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d8d71bffc3b79ff924fbfb51a7a148b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.1",
"size": 40557,
"upload_time": "2024-04-15T11:34:44",
"upload_time_iso_8601": "2024-04-15T11:34:44.873977Z",
"url": "https://files.pythonhosted.org/packages/15/77/900353d624cc99d0bb48455bece5501e04452a5f172ca6d9fb31479f1bdc/bio_volumentations-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f72ce5d30c465c2dcd63db2f96794bbeb131da6d119410a441fba2e0abe76357",
"md5": "60ff214c6f43ff22670afeba185f6acc",
"sha256": "95eea1ce0473f8ebee3f2abf270920c6fcc70b0bcb9203f04595f3bb6d3655ef"
},
"downloads": -1,
"filename": "bio_volumentations-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "60ff214c6f43ff22670afeba185f6acc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.1",
"size": 28995,
"upload_time": "2024-04-15T11:34:46",
"upload_time_iso_8601": "2024-04-15T11:34:46.726385Z",
"url": "https://files.pythonhosted.org/packages/f7/2c/e5d30c465c2dcd63db2f96794bbeb131da6d119410a441fba2e0abe76357/bio_volumentations-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-15 11:34:46",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bio-volumentations"
}
JSON