Metadata-Version: 2.1
Name: cornucopia
Version: 0.3.0
Summary: An abundance of augmentation layers
Home-page: UNKNOWN
Author: Yael Balbastre
Author-email: yael.balbastre@gmail.com
License: MIT
Project-URL: Source Code, https://github.com/balbasty/cornucopia
Platform: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: torch >=1.8
Requires-Dist: numpy
Requires-Dist: nibabel
Requires-Dist: torch-interpol >=0.2.4
Requires-Dist: torch-distmap

<picture align="center">
  <source media="(prefers-color-scheme: dark)" srcset="docs/icons/cornucopia_lightorange.svg">
  <source media="(prefers-color-scheme: light)"  srcset="docs/icons/cornucopia_orange.svg">
  <img alt="Cornucopia logo" src="https://github.com/balbasty/cornucopia/raw/main/docs/icons/cornucopia_orange.svg">
</picture>

The `cornucopia` package provides a generic framework for preprocessing,
augmentation, and domain randomization; along with an abundance of specific layers,
mostly targeted at (medical) imaging. `cornucopia` is written using a PyTorch
backend, and therefore runs **on the CPU or GPU**.

Cornucopia is *intended* to be used on the GPU for on-line augmentation.
A quick [benchmark](examples/benchmark.ipynb) of affine and elastic augmentation
shows that while cornucopia is slower than [TorchIO](https://github.com/fepegar/torchio)
on the CPU (~ 3s vs 1s), it is greatly accelerated on the GPU (~ 50ms).

Since gradients are not expected to backpropagate through its layers, it can
theoretically be used within any dataloader pipeline,
independent of the downstream learning framework (pytorch, tensorflow, jax, ...).

## Installation

### Dependencies

- `pytorch >= 1.8`
- `numpy`
- `nibabel`
- `torch-interpol`
- `torch-distmap`

### Conda

```sh
conda install cornucopia -c balbasty -c pytorch -c conda-forge
```

### Pip (release)

```sh
pip install cornucopia
```

### Pip (dev)

```sh
pip install cornucopia@git+https://github.com/balbasty/cornucopia
```

## Documentation

Read the [documentation](https://cornucopia.readthedocs.io) and in particular:
- [installation](https://cornucopia.readthedocs.io/en/latest/install/)
- [get started](https://cornucopia.readthedocs.io/en/latest/start/)
- [examples](https://cornucopia.readthedocs.io/en/latest/examples/overview/)
- [API](https://cornucopia.readthedocs.io/en/latest/api/overview/)

## Other augmentation packages

There are other great, and much more mature, augmentation packages 
out-there (although few run on the GPU). Here's a non-exhaustive list:
- [MONAI](https://github.com/Project-MONAI/MONAI)
- [TorchIO](https://github.com/fepegar/torchio)
- [Albumentations](https://github.com/albumentations-team/albumentations) (2D only)
- [Volumentations](https://github.com/ZFTurbo/volumentations) (3D extension of Albumentations)

## Contributions

If you find this project useful and wish to contribute, please reach out!


