# torch traNDsforms
<div align="center">
[](https://github.com/alexandrainst/torch-trandsforms/actions/workflows/build.yml?query=branch%3Amain)
[](https://pypi.org/project/torch-trandsforms/)
[](https://github.com/alexandrainst/torch-trandsforms/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Aapp%2Fdependabot)
[](https://github.com/psf/black)
[](https://github.com/PyCQA/bandit)
[](https://github.com/alexandrainst/torch-trandsforms/blob/main/.pre-commit-config.yaml)
[](https://github.com/alexandrainst/torch-trandsforms/releases)
[](https://github.com/alexandrainst/torch-trandsforms/blob/main/LICENSE)
A pytorch-first transform library for ND data, such as multi-channel 3D volumes
</div>
## Features
torch traNDsforms is an easy to use transform library for N-dimensional PyTorch data
- Differentiable, accelerated ND transformations with most tensors
- One transform pipeline for all your data using `KeyedTransforms`
- Customizable and lightweight
- No superfluous dependencies
- Collaborative
## Installation
```bash
pip install torch_trandsforms
```
or
```bash
poetry add torch-trandsforms
```
or potentially
```bash
conda install torch_trandsforms
```
## Usage
Creating a single transform that rotates both input data and ground truth data. The data is considered 3D with a leading channel dimension.
```python
import torch
from torch_trandsforms import RandomRotate
# create data and target
input_tensor = torch.rand((3,16,16,16), device="cuda", dtype=torch.float32)
target_tensor = torch.rand((1,16,16,16), device="cuda", dtype=torch.float32)
# create our random rotator, which rotates dim -3 from -90 to 90, dim -2 from -90 to 90, and dim -1 from -180 to 180
# this operates only on inputs with the keynames "input" or "target" and in the trailing 3 dimensions
rotator = RandomRotate((90,90,180), nd=3, keys=["input", "target"], align_corners=True)
# transform the data and target
transformed = rotator(input=input_tensor, target=target_tensor)
# the data is recovered using the same keys as in the input
data = transformed["input"]
target = transformed["target"]
```
Create a Compose object to run a sequence of transforms one after another:
```python
import torch
from torch_trandsforms import Compose, RandomResize, RandomRotate, RandomCrop, RandomApply, UniformNoise, GaussianNoise, SaltAndPepperNoise
# create data and target
input_tensor = torch.rand((3,16,16,16), device="cuda", dtype=torch.float32)
target_tensor = torch.rand((16,16,16), device="cuda").round()
# create our transform pipeline using some shape/size augmentation on both input and target, as well as some noise on the input
transform = Compose([
RandomResize(0.3, p=0.75, keys="*"), # keys="*" is the same as keys=["foo", "bar"] here
RandomRotate([180,180,180], sample_mode="nearest", p=0.9, nd=3, keys=["foo", "bar"]),
RandomCrop(16, padding=0, p=1.0, keys="*"), # nd is 3 by default - but nd=1,2,3 all work here, just on the trailing dimensions
RandomApply([
UniformNoise(p=1.0, low=-0.2, hi=0.2, keys=["foo"]), # for most noise transforms, we only want the data to be augmented
GaussianNoise(mean=torch.tensor(0.0, device="cuda"), std=0.05, p=1.0, keys=["foo"]),
SaltAndPepperNoise(0.2, low=0.0, hi=1.0, a=torch.tensor(0.5, device="cuda"), p=1.0, copy_input=True, keys=["foo"])
], min=1, max=1) # apply exactly 1 of the above three transforms each time
])
# transform the data and target
transformed = transform(foo=input_tensor, bar=target_tensor)
# the data is recovered using the same keys as in the input
data = transformed["foo"]
target = transformed["bar"]
```
For more examples of use, see [EXAMPLES.md](https://github.com/alexandrainst/torch-trandsforms/blob/main/examples/EXAMPLES.md)
## Speed
Please see [TIMING.md](https://github.com/alexandrainst/torch-trandsforms/blob/main/TIMING.md) for timings. See [test_speed.py](https://github.com/alexandrainst/torch-trandsforms/blob/main/test_speed.py) for methodology.
## Support
Please use [Issues](https://github.com/alexandrainst/torch-trandsforms/issues) for any issues, feature requests, or general feedback.
## Roadmap
For now, traNDsforms is in early alpha. That will continue for a while, while basic functionality is implemented.
The roadmap is determined by the collaborative efforts of every user that provides feedback, reports bugs, or produces pull requests. Thank you!
For now, the roadmap looks something like this:
- [x] Implement basic functionality (normalize, dtype changing, change device)
- [x] Implement value-level noise functionality (uniform, salt and pepper, gaussian)
- [x] Implement structural transforms (cropping, flipping)
- [x] Implement placeholder transforms for not-yet-ND-capable transforms (arbitrary rotation, scaling)
- [x] More examples, including better visuals
- [x] Development structure: Lock main && publish
- [ ] Move basic functionality to _functional and _utils
Later additions (and reasons for postponing):
- [ ] Arbitrary rotations (missing ND affine_grid and grid_sample)
- [ ] Gaussian Blur (missing implementation of ND convolution)
- [ ] Affine transformations (missing efficient ND computation)
Potential additions:
- [ ] ND Bounding Boxes
- [ ] Geometric operations using PyTorch Geometric
- [ ] Point clouds, meshes using PyTorch 3D
- [ ] Data loading, sampling, and structures
- [ ] torchscript compatibility
## Contributing
See [Contributing](https://github.com/alexandrainst/torch-trandsforms/blob/main/CONTRIBUTING.md)
## Authors
The project is maintained by developers at the [Alexandra Institute](https://alexandra.dk/)
- Oliver G. Hjermitslev (ohjerm) <oliver.gyldenberg@alexandra.dk>
...to be expanded...
## License
See the [MIT License](https://github.com/alexandrainst/torch-trandsforms/blob/main/LICENSE)
## 📃 Citation
```bibtex
@misc{torch-trandsforms,
author = {Alexandra Institute},
title = {A pytorch-first transform library for ND data, such as multi-channel 3D volumes},
year = {2023},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/alexandrainst/torch-trandsforms}}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/alexandrainst/torch-trandsforms",
"name": "torch-trandsforms",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "pytorch, transforms, torchvision, data",
"author": "Oliver Hjermitslev",
"author_email": "oliver.gyldenberg@alexandra.dk",
"download_url": "https://files.pythonhosted.org/packages/31/e8/31f71857e12371e80f3f961931c533cba39b1f0f38f1b2a2b07138d5b080/torch_trandsforms-0.3.6.tar.gz",
"platform": null,
"description": "# torch traNDsforms\n\n<div align=\"center\">\n\n[](https://github.com/alexandrainst/torch-trandsforms/actions/workflows/build.yml?query=branch%3Amain)\n[](https://pypi.org/project/torch-trandsforms/)\n[](https://github.com/alexandrainst/torch-trandsforms/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Aapp%2Fdependabot)\n\n[](https://github.com/psf/black)\n[](https://github.com/PyCQA/bandit)\n[](https://github.com/alexandrainst/torch-trandsforms/blob/main/.pre-commit-config.yaml)\n[](https://github.com/alexandrainst/torch-trandsforms/releases)\n[](https://github.com/alexandrainst/torch-trandsforms/blob/main/LICENSE)\n\n\nA pytorch-first transform library for ND data, such as multi-channel 3D volumes\n\n</div>\n\n## Features\n\ntorch traNDsforms is an easy to use transform library for N-dimensional PyTorch data\n\n - Differentiable, accelerated ND transformations with most tensors\n - One transform pipeline for all your data using `KeyedTransforms`\n - Customizable and lightweight\n - No superfluous dependencies\n - Collaborative\n\n## Installation\n\n```bash\npip install torch_trandsforms\n```\n\nor\n\n```bash\npoetry add torch-trandsforms\n```\n\nor potentially\n\n```bash\nconda install torch_trandsforms\n```\n\n## Usage\n\nCreating a single transform that rotates both input data and ground truth data. The data is considered 3D with a leading channel dimension.\n\n\n\n```python\nimport torch\nfrom torch_trandsforms import RandomRotate\n\n# create data and target\ninput_tensor = torch.rand((3,16,16,16), device=\"cuda\", dtype=torch.float32)\ntarget_tensor = torch.rand((1,16,16,16), device=\"cuda\", dtype=torch.float32)\n\n# create our random rotator, which rotates dim -3 from -90 to 90, dim -2 from -90 to 90, and dim -1 from -180 to 180\n# this operates only on inputs with the keynames \"input\" or \"target\" and in the trailing 3 dimensions\nrotator = RandomRotate((90,90,180), nd=3, keys=[\"input\", \"target\"], align_corners=True)\n\n# transform the data and target\ntransformed = rotator(input=input_tensor, target=target_tensor)\n\n# the data is recovered using the same keys as in the input\ndata = transformed[\"input\"]\ntarget = transformed[\"target\"]\n```\n\nCreate a Compose object to run a sequence of transforms one after another:\n\n\n\n```python\nimport torch\nfrom torch_trandsforms import Compose, RandomResize, RandomRotate, RandomCrop, RandomApply, UniformNoise, GaussianNoise, SaltAndPepperNoise\n\n# create data and target\ninput_tensor = torch.rand((3,16,16,16), device=\"cuda\", dtype=torch.float32)\ntarget_tensor = torch.rand((16,16,16), device=\"cuda\").round()\n\n# create our transform pipeline using some shape/size augmentation on both input and target, as well as some noise on the input\ntransform = Compose([\n RandomResize(0.3, p=0.75, keys=\"*\"), # keys=\"*\" is the same as keys=[\"foo\", \"bar\"] here\n RandomRotate([180,180,180], sample_mode=\"nearest\", p=0.9, nd=3, keys=[\"foo\", \"bar\"]),\n RandomCrop(16, padding=0, p=1.0, keys=\"*\"), # nd is 3 by default - but nd=1,2,3 all work here, just on the trailing dimensions\n RandomApply([\n UniformNoise(p=1.0, low=-0.2, hi=0.2, keys=[\"foo\"]), # for most noise transforms, we only want the data to be augmented\n GaussianNoise(mean=torch.tensor(0.0, device=\"cuda\"), std=0.05, p=1.0, keys=[\"foo\"]),\n SaltAndPepperNoise(0.2, low=0.0, hi=1.0, a=torch.tensor(0.5, device=\"cuda\"), p=1.0, copy_input=True, keys=[\"foo\"])\n ], min=1, max=1) # apply exactly 1 of the above three transforms each time\n])\n\n# transform the data and target\ntransformed = transform(foo=input_tensor, bar=target_tensor)\n\n# the data is recovered using the same keys as in the input\ndata = transformed[\"foo\"]\ntarget = transformed[\"bar\"]\n```\n\nFor more examples of use, see [EXAMPLES.md](https://github.com/alexandrainst/torch-trandsforms/blob/main/examples/EXAMPLES.md)\n\n## Speed\n\nPlease see [TIMING.md](https://github.com/alexandrainst/torch-trandsforms/blob/main/TIMING.md) for timings. See [test_speed.py](https://github.com/alexandrainst/torch-trandsforms/blob/main/test_speed.py) for methodology.\n\n## Support\n\nPlease use [Issues](https://github.com/alexandrainst/torch-trandsforms/issues) for any issues, feature requests, or general feedback.\n\n## Roadmap\n\nFor now, traNDsforms is in early alpha. That will continue for a while, while basic functionality is implemented.\n\nThe roadmap is determined by the collaborative efforts of every user that provides feedback, reports bugs, or produces pull requests. Thank you!\n\nFor now, the roadmap looks something like this:\n - [x] Implement basic functionality (normalize, dtype changing, change device)\n - [x] Implement value-level noise functionality (uniform, salt and pepper, gaussian)\n - [x] Implement structural transforms (cropping, flipping)\n - [x] Implement placeholder transforms for not-yet-ND-capable transforms (arbitrary rotation, scaling)\n - [x] More examples, including better visuals\n - [x] Development structure: Lock main && publish\n - [ ] Move basic functionality to _functional and _utils\n\nLater additions (and reasons for postponing):\n - [ ] Arbitrary rotations (missing ND affine_grid and grid_sample)\n - [ ] Gaussian Blur (missing implementation of ND convolution)\n - [ ] Affine transformations (missing efficient ND computation)\n\nPotential additions:\n - [ ] ND Bounding Boxes\n - [ ] Geometric operations using PyTorch Geometric\n - [ ] Point clouds, meshes using PyTorch 3D\n - [ ] Data loading, sampling, and structures\n - [ ] torchscript compatibility\n\n## Contributing\n\nSee [Contributing](https://github.com/alexandrainst/torch-trandsforms/blob/main/CONTRIBUTING.md)\n\n## Authors\n\nThe project is maintained by developers at the [Alexandra Institute](https://alexandra.dk/)\n\n - Oliver G. Hjermitslev (ohjerm) <oliver.gyldenberg@alexandra.dk>\n\n...to be expanded...\n\n## License\n\nSee the [MIT License](https://github.com/alexandrainst/torch-trandsforms/blob/main/LICENSE)\n\n## \ud83d\udcc3 Citation\n\n```bibtex\n@misc{torch-trandsforms,\n author = {Alexandra Institute},\n title = {A pytorch-first transform library for ND data, such as multi-channel 3D volumes},\n year = {2023},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {\\url{https://github.com/alexandrainst/torch-trandsforms}}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A pytorch-first transform library for ND data, such as multi-channel 3D volumes",
"version": "0.3.6",
"project_urls": {
"Homepage": "https://github.com/alexandrainst/torch-trandsforms",
"Repository": "https://github.com/alexandrainst/torch-trandsforms"
},
"split_keywords": [
"pytorch",
" transforms",
" torchvision",
" data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2bf24f8e3cf8b8b9a6a48d9585a6400073ae1ac58fa658920bca376d73e06f23",
"md5": "f4bba46733da2502f3b39da27ec18dab",
"sha256": "e64b9e7feb82b0d54878a91cd781af43e2a7c81f701c857b44297085f3f48863"
},
"downloads": -1,
"filename": "torch_trandsforms-0.3.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4bba46733da2502f3b39da27ec18dab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 25306,
"upload_time": "2024-04-23T09:28:20",
"upload_time_iso_8601": "2024-04-23T09:28:20.801134Z",
"url": "https://files.pythonhosted.org/packages/2b/f2/4f8e3cf8b8b9a6a48d9585a6400073ae1ac58fa658920bca376d73e06f23/torch_trandsforms-0.3.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "31e831f71857e12371e80f3f961931c533cba39b1f0f38f1b2a2b07138d5b080",
"md5": "df20662d2c43740a0cf47dc653108b31",
"sha256": "a876e102860b64dbc3d04c82b28234fd8c61c1d03e4218775fa90c0eff2bbbc9"
},
"downloads": -1,
"filename": "torch_trandsforms-0.3.6.tar.gz",
"has_sig": false,
"md5_digest": "df20662d2c43740a0cf47dc653108b31",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 24667,
"upload_time": "2024-04-23T09:28:23",
"upload_time_iso_8601": "2024-04-23T09:28:23.395459Z",
"url": "https://files.pythonhosted.org/packages/31/e8/31f71857e12371e80f3f961931c533cba39b1f0f38f1b2a2b07138d5b080/torch_trandsforms-0.3.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 09:28:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexandrainst",
"github_project": "torch-trandsforms",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "torch-trandsforms"
}
JSON
