<div align="center">
[](https://github.com/PhoenixDL/rising/actions/workflows/unittests.yml)
[](https://codecov.io/gh/PhoenixDL/rising)
[](https://join.slack.com/t/phoenixdl/shared_invite/enQtODgwODI0MTE1MjgzLTJkZDE4N2NhM2VmNzVhYTEyMzI3NzFmMDY0NjM3MzJlZWRmMTk5ZWM1YzY2YjY5ZGQ1NWI1YmJmOTdiYTdhYTE)
[](https://rising.readthedocs.io/en/latest/?badge=latest)
[](https://results.pre-commit.ci/latest/github/PhoenixDL/rising/master)[](https://zenodo.org/badge/latestdoi/222287924)
</div>
## What is `rising`?
Rising is a high-performance data loading and augmentation library for 2D *and* 3D data completely written in PyTorch.
Our goal is to provide a seamless integration into the PyTorch Ecosystem without sacrificing usability or features.
Multiple examples for different use cases can be found in our [tutorial docs](https://rising.readthedocs.io/en/latest/tutorials.html) e.g.
[2D Classification on MedNIST](https://github.com/PhoenixDL/rising/blob/master/notebooks/classification_2d_mednist.ipynb),
[3D Segmentation of Hippocampus (Medical Decathlon)](https://github.com/PhoenixDL/rising/blob/master/notebooks/lightning_segmentation.ipynb),
[Example Transformation Output](https://rising.readthedocs.io/en/latest/transformations.html),
[Integration of External Frameworks](https://rising.readthedocs.io/en/latest/external_augmentation.html)
## Why another framework?
| | rising | TorchIO | Batchgenerators | Kornia | DALI | Vanilla PyTorch | Albumentations |
| :--------: | :-----: | :----------: | :-------------: | :-----: | :--: | :-------------: | :------------: |
| Volumetric | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Gradients | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
| GPU | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ |
| Backend | PyTorch | PyTorch/SITK | NumPy | PyTorch | C++ | PyTorch | NumPy |
## Docs
[master](https://rising.readthedocs.io/en/latest/)
## Installation
Pypi Installation
```bash
pip install rising
```
Editable Installation for development
```bash
git clone git@github.com:PhoenixDL/rising.git
cd rising
pip install -e .
```
Running tests inside rising directory (top directory not the package directory)
```bash
python -m unittest
```
Check out our [contributing guide](https://rising.readthedocs.io/en/latest/contributing.html) for more information or additional help.
## What can I do with `rising`?
Rising currently consists out of two main modules:
### `rising.loading`
The `Dataloader` of rising will be your new best friend because it handles all your transformations and applies them efficiently to the data either on CPU or GPU.
On CPU you can easily switch between transformations which can only be performed per sample and transformations which can be applied per batch.
In contrast to the native PyTorch datasets you don't need to integrate your augmentation into your dataset.
Hence, the only purpose of the dataset is to provide an interface to access individual data samples.
Our `DataLoader` is a direct subclass of the PyTorch's dataloader and handles the batch assembly and applies the augmentations/transformations to the data.
### `rising.transforms`
This module implements many transformations which can be used during training for preprocessing and augmentation.
All of them are implemented directly in PyTorch such that gradients can be propagated through the transformations and (optionally) it can be applied on the GPU.
Finally, all transforms are implemented for 2D (natural images) and 3D (volumetric) data.
In the future, support for keypoints and other geometric primitives which can be assembled by connected points will be added.
## `rising` MNIST Example with CPU and GPU augmentation
`rising` uses the same `Dataset` structure as PyTorch and thus we can just reuse the MNIST dataset from torchvision.
```python3
import torchvision
from torchvision.transforms import ToTensor
# define dataset and use to tensor trafo to convert PIL image to tensor
dataset = torchvision.datasets.MNIST('./', train=True, download=True,
transform=ToTensor())
```
In the next step, the transformations/augmentations need to be defined.
The first transforms converts the Sequence from the torchvision dataset into a dict for the following `rising` transform which work on dicts.
At the end, the transforms are compose to one callable transform which can be passed to the `Dataloader`.
```python3
import rising.transforms as rtr
from rising.loading import DataLoader, default_transform_call
from rising.random import DiscreteParameter, UniformParameter
# define transformations
transforms = [
rtr.SeqToMap("data", "label"), # most rising transforms work on dicts
rtr.NormZeroMeanUnitStd(keys=["data"]),
rtr.Rot90((0, 1), keys=["data"], p=0.5),
rtr.Mirror(dims=DiscreteParameter([0, 1]), keys=["data"]),
rtr.Rotate(UniformParameter(0, 180), degree=True),
]
# by default rising assumes dicts but torchvision outputs tuples
# so we need to modify `transform_call` to support sequences and dicts
composed = rtr.Compose(transforms, transform_call=default_transform_call)
```
The `Dataloader` from `rising` automatically applies the specified transformations to the batches inside the multiprocessing context of the CPU.
```python3
dataloader = DataLoader(
dataset, batch_size=8, num_workers=8, batch_transforms=composed)
```
Alternatively, the augmentations can easily be applied on the GPU as well.
```python3
dataloader = DataLoader(
dataset, batch_size=8, num_workers=8, gpu_transforms=composed)
```
If either the GPU or CPU is the bottleneck of the pipeline, the `Dataloader` can be used to balance the augmentations load between them.
```python3
transforms_cpu = rtr.Compose(transforms[:2])
transforms_gpu = rtr.Compose(transforms[2:])
dataloader = DataLoader(
dataset, batch_size=8, num_workers=8,
batch_transforms=transforms_cpu,
gpu_transforms=transforms_gpu,
)
```
More details about how and where the augmentations are applied can be found below.
You can also check out our example Notebooks for [2D Classification](https://github.com/PhoenixDL/rising/blob/master/notebooks/classification_2d_mednist.ipynb), [3D Segmentation](https://github.com/PhoenixDL/rising/blob/master/notebooks/lightning_segmentation.ipynb)
and [Transformation Examples](https://rising.readthedocs.io/en/latest/transformations.html).
## Dataloading with `rising`
In general you do not need to be familiar with the whole augmentation process which runs in the background but if you are still curious about the
detailed pipeline this section will give a very short introduction into the backend of the `Dataloader`.
The flow charts below highlight the differences between a conventional augmentation pipeline and the pipeline used in `rising`.
CPU operations are visualized in blue while GPU operations are green.
The flow chart below visualizes the default augmentation pipeline of many other frameworks.
The transformations are applied to individual samples which are loaded and augmented inside of multiple background workers from the CPU.
This approach is already efficient and might only be slightly slower than batched execution of the transformations (if applied on the CPU).
GPU augmentations can be used to perform many operations in parallel and profit heavily from vectorization.
`rising` lets the user decide from case to case where augmentations should be applied during this pipeline.
This can heavily dependent on the specific tasks and the underlying hardware.
Running augmentations on the GPU is only efficient if they can be executed in a batched fashion to maximize the parallelization GPUs can provide.
As a consequence, `rising` implements all its transformations in a batched fashion and the `Dataloader` can execute them efficiently on the CPU and GPU.
Optionally, the `Dataloader` can still be used to apply transformations on a per sample fashion, e.g. when transforms from other frameworks should be integrated.
Because the `rising` augmentation pipeline is a superset of the currently used methods, external frameworks can be integrated into `rising`.
## Project Organization
`Issues`: If you find any bugs, want some additional features or maybe just have a question don't hesitate to open an issue :)
`General Project Future`: Most of the features and the milestone organisation can be found inside the `projects` tab.
Features which are planned for the next release/milestone are listed under `TODO Next Release` while features which are not scheduled yet are under `Todo`.
`Slack`: Join our Slack for the most up to date news or just to have a chat with us :)
Raw data
{
"_id": null,
"home_page": "https://github.com/PhoenixDL/rising",
"name": "rising",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "deep learning,augmentation,transforms,pytorch,medical",
"author": "Justus Schock, Michael Baumgartner",
"author_email": "justus.schock@rwth-aachen.de",
"download_url": "https://files.pythonhosted.org/packages/4a/70/fff2023edc9171b2b05f21adbddc217c5a7395e87118e85a7bb249dfc426/rising-0.3.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n![logo](docs/source/images/logo/rising_logo.png \"rising\")\n[](https://github.com/PhoenixDL/rising/actions/workflows/unittests.yml)\n\n\n[](https://codecov.io/gh/PhoenixDL/rising)\n\n[](https://join.slack.com/t/phoenixdl/shared_invite/enQtODgwODI0MTE1MjgzLTJkZDE4N2NhM2VmNzVhYTEyMzI3NzFmMDY0NjM3MzJlZWRmMTk5ZWM1YzY2YjY5ZGQ1NWI1YmJmOTdiYTdhYTE)\n[](https://rising.readthedocs.io/en/latest/?badge=latest)\n[](https://results.pre-commit.ci/latest/github/PhoenixDL/rising/master)[](https://zenodo.org/badge/latestdoi/222287924)\n\n</div>\n\n## What is `rising`?\n\nRising is a high-performance data loading and augmentation library for 2D *and* 3D data completely written in PyTorch.\nOur goal is to provide a seamless integration into the PyTorch Ecosystem without sacrificing usability or features.\nMultiple examples for different use cases can be found in our [tutorial docs](https://rising.readthedocs.io/en/latest/tutorials.html) e.g.\n[2D Classification on MedNIST](https://github.com/PhoenixDL/rising/blob/master/notebooks/classification_2d_mednist.ipynb),\n[3D Segmentation of Hippocampus (Medical Decathlon)](https://github.com/PhoenixDL/rising/blob/master/notebooks/lightning_segmentation.ipynb),\n[Example Transformation Output](https://rising.readthedocs.io/en/latest/transformations.html),\n[Integration of External Frameworks](https://rising.readthedocs.io/en/latest/external_augmentation.html)\n\n## Why another framework?\n\n| | rising | TorchIO | Batchgenerators | Kornia | DALI | Vanilla PyTorch | Albumentations |\n| :--------: | :-----: | :----------: | :-------------: | :-----: | :--: | :-------------: | :------------: |\n| Volumetric | \u2705 | \u2705 | \u2705 | \u274c | \u274c | \u274c | \u274c |\n| Gradients | \u2705 | \u274c | \u274c | \u2705 | \u274c | \u274c | \u274c |\n| GPU | \u2705 | \u274c | \u274c | \u2705 | \u2705 | \u274c | \u274c |\n| Backend | PyTorch | PyTorch/SITK | NumPy | PyTorch | C++ | PyTorch | NumPy |\n\n## Docs\n\n[master](https://rising.readthedocs.io/en/latest/)\n\n## Installation\n\nPypi Installation\n\n```bash\npip install rising\n```\n\nEditable Installation for development\n\n```bash\ngit clone git@github.com:PhoenixDL/rising.git\ncd rising\npip install -e .\n```\n\nRunning tests inside rising directory (top directory not the package directory)\n\n```bash\npython -m unittest\n```\n\nCheck out our [contributing guide](https://rising.readthedocs.io/en/latest/contributing.html) for more information or additional help.\n\n## What can I do with `rising`?\n\nRising currently consists out of two main modules:\n\n### `rising.loading`\n\nThe `Dataloader` of rising will be your new best friend because it handles all your transformations and applies them efficiently to the data either on CPU or GPU.\nOn CPU you can easily switch between transformations which can only be performed per sample and transformations which can be applied per batch.\nIn contrast to the native PyTorch datasets you don't need to integrate your augmentation into your dataset.\nHence, the only purpose of the dataset is to provide an interface to access individual data samples.\nOur `DataLoader` is a direct subclass of the PyTorch's dataloader and handles the batch assembly and applies the augmentations/transformations to the data.\n\n### `rising.transforms`\n\nThis module implements many transformations which can be used during training for preprocessing and augmentation.\nAll of them are implemented directly in PyTorch such that gradients can be propagated through the transformations and (optionally) it can be applied on the GPU.\nFinally, all transforms are implemented for 2D (natural images) and 3D (volumetric) data.\n\nIn the future, support for keypoints and other geometric primitives which can be assembled by connected points will be added.\n\n## `rising` MNIST Example with CPU and GPU augmentation\n\n`rising` uses the same `Dataset` structure as PyTorch and thus we can just reuse the MNIST dataset from torchvision.\n\n```python3\nimport torchvision\nfrom torchvision.transforms import ToTensor\n\n# define dataset and use to tensor trafo to convert PIL image to tensor\ndataset = torchvision.datasets.MNIST('./', train=True, download=True,\n transform=ToTensor())\n```\n\nIn the next step, the transformations/augmentations need to be defined.\nThe first transforms converts the Sequence from the torchvision dataset into a dict for the following `rising` transform which work on dicts.\nAt the end, the transforms are compose to one callable transform which can be passed to the `Dataloader`.\n\n```python3\nimport rising.transforms as rtr\nfrom rising.loading import DataLoader, default_transform_call\nfrom rising.random import DiscreteParameter, UniformParameter\n\n# define transformations\ntransforms = [\n rtr.SeqToMap(\"data\", \"label\"), # most rising transforms work on dicts\n rtr.NormZeroMeanUnitStd(keys=[\"data\"]),\n rtr.Rot90((0, 1), keys=[\"data\"], p=0.5),\n rtr.Mirror(dims=DiscreteParameter([0, 1]), keys=[\"data\"]),\n rtr.Rotate(UniformParameter(0, 180), degree=True),\n]\n\n# by default rising assumes dicts but torchvision outputs tuples\n# so we need to modify `transform_call` to support sequences and dicts\ncomposed = rtr.Compose(transforms, transform_call=default_transform_call)\n```\n\nThe `Dataloader` from `rising` automatically applies the specified transformations to the batches inside the multiprocessing context of the CPU.\n\n```python3\ndataloader = DataLoader(\n dataset, batch_size=8, num_workers=8, batch_transforms=composed)\n```\n\nAlternatively, the augmentations can easily be applied on the GPU as well.\n\n```python3\ndataloader = DataLoader(\n dataset, batch_size=8, num_workers=8, gpu_transforms=composed)\n```\n\nIf either the GPU or CPU is the bottleneck of the pipeline, the `Dataloader` can be used to balance the augmentations load between them.\n\n```python3\ntransforms_cpu = rtr.Compose(transforms[:2])\ntransforms_gpu = rtr.Compose(transforms[2:])\n\ndataloader = DataLoader(\n dataset, batch_size=8, num_workers=8,\n batch_transforms=transforms_cpu,\n gpu_transforms=transforms_gpu,\n)\n```\n\nMore details about how and where the augmentations are applied can be found below.\nYou can also check out our example Notebooks for [2D Classification](https://github.com/PhoenixDL/rising/blob/master/notebooks/classification_2d_mednist.ipynb), [3D Segmentation](https://github.com/PhoenixDL/rising/blob/master/notebooks/lightning_segmentation.ipynb)\nand [Transformation Examples](https://rising.readthedocs.io/en/latest/transformations.html).\n\n## Dataloading with `rising`\n\nIn general you do not need to be familiar with the whole augmentation process which runs in the background but if you are still curious about the\ndetailed pipeline this section will give a very short introduction into the backend of the `Dataloader`.\nThe flow charts below highlight the differences between a conventional augmentation pipeline and the pipeline used in `rising`.\nCPU operations are visualized in blue while GPU operations are green.\n\nThe flow chart below visualizes the default augmentation pipeline of many other frameworks.\nThe transformations are applied to individual samples which are loaded and augmented inside of multiple background workers from the CPU.\nThis approach is already efficient and might only be slightly slower than batched execution of the transformations (if applied on the CPU).\nGPU augmentations can be used to perform many operations in parallel and profit heavily from vectorization.\n![DefaultAugmentation](docs/source/images/dataloading/default.png \"default augmentation pipeline\")\n\n`rising` lets the user decide from case to case where augmentations should be applied during this pipeline.\nThis can heavily dependent on the specific tasks and the underlying hardware.\nRunning augmentations on the GPU is only efficient if they can be executed in a batched fashion to maximize the parallelization GPUs can provide.\nAs a consequence, `rising` implements all its transformations in a batched fashion and the `Dataloader` can execute them efficiently on the CPU and GPU.\nOptionally, the `Dataloader` can still be used to apply transformations on a per sample fashion, e.g. when transforms from other frameworks should be integrated.\n![RisingAugmentation](docs/source/images/dataloading/rising.png \"rising augmentation pipeline\")\n\nBecause the `rising` augmentation pipeline is a superset of the currently used methods, external frameworks can be integrated into `rising`.\n\n## Project Organization\n\n`Issues`: If you find any bugs, want some additional features or maybe just have a question don't hesitate to open an issue :)\n\n`General Project Future`: Most of the features and the milestone organisation can be found inside the `projects` tab.\nFeatures which are planned for the next release/milestone are listed under `TODO Next Release` while features which are not scheduled yet are under `Todo`.\n\n`Slack`: Join our Slack for the most up to date news or just to have a chat with us :)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "",
"version": "0.3.0",
"split_keywords": [
"deep learning",
"augmentation",
"transforms",
"pytorch",
"medical"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "a45cdd2a28cd81c0afd8a03f843d1ca5",
"sha256": "855ddfa0d7518598ed0a525d3724a4fff2a1f4d69fa52b6ea8f03bdfd664dcbd"
},
"downloads": -1,
"filename": "rising-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a45cdd2a28cd81c0afd8a03f843d1ca5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 94970,
"upload_time": "2022-12-29T16:48:23",
"upload_time_iso_8601": "2022-12-29T16:48:23.703915Z",
"url": "https://files.pythonhosted.org/packages/8a/26/b81d5a8979554a28066b8133dfc8c3e9424ba5f73c854b4ff246b53bf8aa/rising-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "6be2c302c2616f5ed462505f1696d735",
"sha256": "f1cc0ef47268c7bcb21499c9c82b43aacfe517286f8879e8b3211e3bed91911e"
},
"downloads": -1,
"filename": "rising-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "6be2c302c2616f5ed462505f1696d735",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 71701,
"upload_time": "2022-12-29T16:48:25",
"upload_time_iso_8601": "2022-12-29T16:48:25.142408Z",
"url": "https://files.pythonhosted.org/packages/4a/70/fff2023edc9171b2b05f21adbddc217c5a7395e87118e85a7bb249dfc426/rising-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-29 16:48:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "PhoenixDL",
"github_project": "rising",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rising"
}
JSON
