torch-trandsforms 0.3.1

A pytorch-first transform library for ND data, such as multi-channel 3D volumes

torch traNDsforms

A pytorch-first transform library for ND data, such as multi-channel 3D volumes

torch traNDsforms is in early alpha and may have bugs and a significant lack of usefulness :)

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

In early alpha, install torch traNDsforms like this:

pip install git+ssh://[e-mail]/alexandrainst/torch-trandsforms.git/

Soon enough, you will be able to run the following:

pip install torch_trandsforms

or

poetry add torch-trandsforms

or

conda install torch_trandsforms

Usage

Creating the RandomRotate90 class, as an example of customizing your own transform:

import torch
from torch_trandsforms.base import BaseTransform

class RandomRotate90(BaseTransform):  # note the use of BaseTransform as base class here
    """
    Rotates the input 90 degrees around a randomly determined axis
    NOTE: This is the not actual implementation of RandomRotate90
    """
    def __init__(self, nd=3, p=0.5):
        super().__init__(p = p, nd = nd)
        self.options = self._get_options(nd)

    def _get_options(self, nd):
        """
        Create potential rotations based on the nd argument
        This can be lower than the number of dimensions of the actual input
            in case you do not want a leading dimension to be rotated
        """
        options = []

        for i in range(nd):
            for j in range(nd):
                if not i == j:
                    options.append((-i-1, -j-1))

        return options
    
    def get_parameters(self, **inputs):
        """
        overrides the base get_parameters to choose a random
            rotation option for each input
        """
        rotation = random.choice(self.options)
        return {'rot':rotation}
    
    def apply(self, input, **params):
        """
        apply MUST be overwritten 
        It is applied to each input sequentially, and thus must have
            parameters that are exactly equal for each instance,
            meaning most likely NO randomization here
        """
        rot = params['rot']
        return torch.rot90(input, dims=rot)

And we can now use our class to demonstrate the library functionality:

torch.manual_seed(451)  # all randomization uses torch.random in the actual implementation

tensor = torch.arange(16).view(2,2,2,2)  # create a 4D tensor
another_tensor = torch.arange(16).view(2,2,2,2)  # create an exactly equal tensor for demonstration

print(tensor)
print(another_tensor)

random_rotator = RandomRotate90(nd=2, p=1.)  # we only want the last two dimensions to be rotateable but it should rotate every time (p=1)

transformed = random_rotator(data=tensor, foo=another_tensor)  # "data" is arbitrary, it is the key that will be returned, demonstrated by "foo"

print(transformed['data'])
print(transformed['foo'])

Speed

Please see TIMING.md for timings. See test_speed.py for methodology.

Support

Please use 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:

• Implement basic functionality (normalize, dtype changing, change device)
• Implement value-level noise functionality (uniform, salt and pepper, gaussian)
• Implement structural transforms (cropping, flipping)
• Implement placeholder transforms for not-yet-ND-capable transforms (arbitrary rotation, scaling)
• More examples, including better visuals
• 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:

• Geometric operations using PyTorch Geometric
• Point clouds, meshes using PyTorch 3D
• Data loading, sampling, and structures
• torchscript compatibility

Contributing

See Contributing

Authors

The project is maintained by developers at the Alexandra Institute

• Oliver G. Hjermitslev (ohjerm) [e-mail]

...to be expanded...

License

See the MIT License

📃 Citation

@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}}
}