torch-transform-image 0.0.2__py3-none-any.whl

torch_transform_image/__init__.py

@@ -0,0 +1,18 @@
+"""Real space transformations of 2D/3D images in PyTorch"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("torch-transform-image")
+except PackageNotFoundError:
+    __version__ = "uninstalled"
+__author__ = "Alister Burt"
+__email__ = "alisterburt@gmail.com"
+
+from torch_transform_image.transforms_2d import affine_transform_image_2d
+from torch_transform_image.transforms_3d import affine_transform_image_3d
+
+__all__ = [
+    'affine_transform_image_2d',
+    'affine_transform_image_3d',
+]

torch_transform_image/py.typed

@@ -0,0 +1,5 @@
+You may remove this file if you don't intend to add types to your package
+
+Details at:
+
+https://mypy.readthedocs.io/en/stable/installed_packages.html#creating-pep-561-compatible-packages

torch_transform_image/transforms_2d.py

@@ -0,0 +1,36 @@
+from typing import Literal
+
+import einops
+import torch
+from torch_affine_utils import homogenise_coordinates
+from torch_grid_utils import coordinate_grid
+from torch_image_interpolation import sample_image_2d
+
+
+def affine_transform_image_2d(
+        image: torch.Tensor,
+        matrices: torch.Tensor,
+        interpolation: Literal['nearest', 'bilinear', 'bicubic'],
+        yx_matrices: bool = False,
+) -> torch.Tensor:
+    # grab image dimensions
+    h, w = image.shape[-2:]
+
+    if not yx_matrices:
+        matrices[..., :2, :2] = (
+            torch.flip(matrices[..., :2, :2], dims=(-2, -1))
+        )
+        matrices[..., :2, 2] = torch.flip(matrices[..., :2, 2], dims=(-1,))
+
+    # generate grid of pixel coordinates
+    grid = coordinate_grid(image_shape=(h, w), device=image.device)
+
+    # apply matrix to coordinates
+    grid = homogenise_coordinates(grid)  # (h, w, yxw)
+    grid = einops.rearrange(grid, 'h w yxw -> h w yxw 1')
+    grid = matrices @ grid
+    grid = grid[..., :2, 0]  # dehomogenise coordinates: (..., h, w, yxw, 1) -> (..., h, w, yx)
+
+    # sample image at transformed positions
+    result = sample_image_2d(image, coordinates=grid, interpolation=interpolation)
+    return result

torch_transform_image/transforms_3d.py

@@ -0,0 +1,36 @@
+from typing import Literal
+
+import einops
+import torch
+from torch_affine_utils import homogenise_coordinates
+from torch_grid_utils import coordinate_grid
+from torch_image_interpolation import sample_image_3d
+
+
+def affine_transform_image_3d(
+        image: torch.Tensor,
+        matrices: torch.Tensor,
+        interpolation: Literal['nearest', 'trilinear'],
+        zyx_matrices: bool = False,
+) -> torch.Tensor:
+    # grab image dimensions
+    d, h, w = image.shape[-3:]
+
+    if not zyx_matrices:
+        matrices[..., :3, :3] = (
+            torch.flip(matrices[..., :3, :3], dims=(-2, -1))
+        )
+        matrices[..., :3, 3] = torch.flip(matrices[..., :3, 3], dims=(-1,))
+
+    # generate grid of pixel coordinates
+    grid = coordinate_grid(image_shape=(d, h, w), device=image.device)
+
+    # apply matrix to coordinates
+    grid = homogenise_coordinates(grid)  # (d, h, w, zyxw)
+    grid = einops.rearrange(grid, 'd h w zyxw -> d h w zyxw 1')
+    grid = matrices @ grid
+    grid = grid[..., :3, 0]  # dehomogenise coordinates: (..., d, h, w, zyxw, 1) -> (..., d, h, w, zyx)
+
+    # sample image at transformed positions
+    result = sample_image_3d(image, coordinates=grid, interpolation=interpolation)
+    return result

torch_transform_image-0.0.2.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: torch-transform-image
+Version: 0.0.2
+Summary: Real space transformations of 2D/3D images in PyTorch
+Project-URL: homepage, https://github.com/teamtomo/torch-transform-image
+Project-URL: repository, https://github.com/teamtomo/torch-transform-image
+Author-email: Alister Burt <alisterburt@gmail.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: torch
+Requires-Dist: torch-affine-utils
+Requires-Dist: torch-grid-utils
+Requires-Dist: torch-image-interpolation
+Provides-Extra: dev
+Requires-Dist: ipython; extra == 'dev'
+Requires-Dist: pdbpp; extra == 'dev'
+Requires-Dist: rich; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Description-Content-Type: text/markdown
+
+# torch-transform-image
+
+[![License](https://img.shields.io/pypi/l/torch-transform-image.svg?color=green)](https://github.com/teamtomo/torch-transform-image/raw/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/torch-transform-image.svg?color=green)](https://pypi.org/project/torch-transform-image)
+[![Python Version](https://img.shields.io/pypi/pyversions/torch-transform-image.svg?color=green)](https://python.org)
+[![CI](https://github.com/teamtomo/torch-transform-image/actions/workflows/ci.yml/badge.svg)](https://github.com/teamtomo/torch-transform-image/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/teamtomo/torch-transform-image/branch/main/graph/badge.svg)](https://codecov.io/gh/teamtomo/torch-transform-image)
+
+Real space transformations of 2D/3D images in PyTorch
+
+## Motivation
+
+This package provides a simple, consistent API for applying affine transformations to 2D/3D images in PyTorch. 
+It enables efficient, GPU-accelerated geometric transformations of images.
+
+## Installation
+
+```bash
+pip install torch-transform-image
+```
+
+## Features
+
+- Apply arbitrary affine transformations to 2D and 3D images
+- Support for various interpolation methods (nearest, bilinear, bicubic for 2D; nearest, trilinear for 3D)
+- Batched operations for efficient processing
+- Fully differentiable operations compatible with PyTorch's autograd
+
+## Coordinate System
+
+This package uses the same coordinate system as NumPy/PyTorch array indexing:
+- For 2D images: coordinates are ordered as `[y, x]` for dimensions `(height, width)`
+- For 3D images: coordinates are ordered as `[z, y, x]` for dimensions `(depth, height, width)`
+
+Transformation matrices left-multiply homogeneous pixel coordinates (`[y, x, 1]` for 2D and `[z, y, x, 1]` for 3D).
+
+### Generating Transformation Matrices
+
+The companion package [torch-affine-utils](https://github.com/teamtomo/torch-affine-utils) provides convenient functions 
+to generate transformation matrices that work with homogenous pixel coordinates (`yxw`/`zyxw`):
+
+```python
+from torch_affine_utils.transforms_2d import R, T, S  # Rotation, Translation, Scale for 2D
+from torch_affine_utils.transforms_3d import Rx, Ry, Rz, T, S  # Rotation, Translation, Scale for 3D
+```
+
+## Usage
+
+### 2D Transformations
+
+```python
+import torch
+from torch_transform_image import affine_transform_image_2d
+from torch_affine_utils.transforms_2d import R, T, S  # Rotation, Translation, Scale
+
+# Create a test image (28×28)
+image = torch.zeros((28, 28), dtype=torch.float32)
+image[14, 14] = 1  # Place a dot at the center
+
+# Create a transformation matrix to translate coordinates 4 pixels in y direction
+translation = T([4, 0])  # Uses [y, x] coordinate order matching dimensions (h, w)
+
+# Apply the transformation
+result = affine_transform_image_2d(
+    image=image,
+    matrices=translation, 
+    interpolation='bilinear',  # Options: 'nearest', 'bilinear', 'bicubic'
+    yx_matrices=True,  # The generated translations have [y, x] order
+)
+
+# Compose multiple transformations
+# First translate to origin, then rotate, then translate back
+T1 = T([-14, -14])  # Move center to origin
+R1 = R(45, yx=True)  # Rotate 45 degrees
+T2 = T([14, 14])  # Move back
+transform = T2 @ R1 @ T1  # Matrix composition (applied right-to-left)
+
+# Apply the composed transformation
+rotated = affine_transform_image_2d(
+    image=image,
+    matrices=transform,
+    interpolation='bicubic',
+    yx_matrices=True,
+)
+```
+
+### 3D Transformations
+
+```python
+import torch
+from torch_transform_image import affine_transform_image_3d
+from torch_affine_utils.transforms_3d import R, T, S  # Rotation, Translation, Scale
+
+# Create a test volume (64×64×64)
+volume = torch.zeros((64, 64, 64), dtype=torch.float32)
+volume[32, 32, 32] = 1  # Place a dot at the center
+
+# Create a transformation matrix (translate coordinates 5 voxels in z direction)
+translation = T([5, 0, 0])  # Uses [z, y, x] coordinate order matching dimensions (d, h, w)
+
+# Apply the transformation
+result = affine_transform_image_3d(
+    image=volume,
+    matrices=translation, 
+    interpolation='trilinear',  # Options: 'nearest', 'trilinear'
+    zyx_matrices=True,  # The generated translations have [z, y, x] order
+)
+```
+
+## How It Works
+
+Under the hood, the package:
+1. Creates a coordinate grid for the input image
+2. Applies the transformation matrix to these coordinates
+3. Samples the original image at the transformed coordinates using the specified interpolation method
+
+All operations are performed in PyTorch, making them fully differentiable and GPU-compatible.
+
+## License
+
+This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

torch_transform_image-0.0.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+torch_transform_image/__init__.py,sha256=CvPvmi8gnRML8YXeBgFn5PCLu3hoFuYDBJ60yADGbhM,534
+torch_transform_image/py.typed,sha256=esB4cHc6c07uVkGtqf8at7ttEnprwRxwk8obY8Qumq4,187
+torch_transform_image/transforms_2d.py,sha256=GBQB4MRpMQTy_RG3M9-7zI7T7U_fGGCEVh23Z_8B1eg,1211
+torch_transform_image/transforms_3d.py,sha256=qM20WNKGGDm_Yy1wCE0b2JfoDXV1Mk4G4YkRwbBi-W0,1227
+torch_transform_image-0.0.2.dist-info/METADATA,sha256=-5g55-h433MtUWl-_3dg3blzD2BPAweX6vpHRKsWQ-s,5968
+torch_transform_image-0.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+torch_transform_image-0.0.2.dist-info/licenses/LICENSE,sha256=Kbo_h3sPum8rDAhMerH9fl4hzFn-QUCekJf05zk2epY,1499
+torch_transform_image-0.0.2.dist-info/RECORD,,

torch_transform_image-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

torch_transform_image-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Alister Burt
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.