tessl/pypi-torchio

Tools for medical image processing with PyTorch

Overview

Eval results

Files

Augmentation Transforms

Name: tessl/pypi-torchio
Author: tessl

Extensive augmentation transforms including spatial augmentations (affine, elastic deformation, flipping) and intensity augmentations with medical imaging-specific artifacts (motion, ghosting, bias field, spike artifacts). These transforms increase dataset diversity and improve model robustness.

Capabilities

Spatial Augmentation

Spatial augmentation transforms that modify the geometric properties of medical images while maintaining anatomical realism and medical validity.

Flipping Transforms

Random and deterministic flipping along specified axes, commonly used for data augmentation in medical imaging.

class Flip(SpatialTransform):
    """
    Deterministic image flipping along specified axes.
    
    Parameters:
    - axes: Axes to flip (int, tuple, or sequence)
    """
    def __init__(self, axes: Union[int, tuple[int, ...]]): ...

class RandomFlip(SpatialTransform):
    """
    Random image flipping with specified probability.
    
    Parameters:
    - axes: Axes that can be flipped (default: (0,) for left-right)
    - flip_probability: Probability of flipping each axis
    """
    def __init__(
        self,
        axes: TypeTuple = (0,),
        flip_probability: float = 0.5
    ): ...

Affine Transforms

Affine transformations including rotation, translation, scaling, and shearing, essential for geometric data augmentation.

class Affine(SpatialTransform):
    """
    Deterministic affine transformation.
    
    Parameters:
    - scales: Scaling factors per axis
    - degrees: Rotation angles in degrees per axis
    - translation: Translation in voxels per axis
    - isotropic: Whether to use isotropic scaling
    - center: Center of rotation ('image' or 'origin')
    - default_pad_value: Padding value for out-of-bounds regions
    """
    def __init__(
        self,
        scales: TypeRangeFloat = None,
        degrees: TypeRangeFloat = None,
        translation: TypeRangeFloat = None,
        isotropic: bool = False,
        center: str = 'image',
        default_pad_value: float = 0,
        **kwargs
    ): ...

class RandomAffine(SpatialTransform):
    """
    Random affine transformation.
    
    Parameters:
    - scales: Range of scaling factors (tuple of min, max)
    - degrees: Range of rotation degrees per axis
    - translation: Range of translation in voxels
    - isotropic: Whether to use isotropic scaling
    - center: Center of rotation
    - default_pad_value: Padding value for out-of-bounds regions
    """
    def __init__(
        self,
        scales: TypeRangeFloat = None,
        degrees: TypeRangeFloat = None,
        translation: TypeRangeFloat = None,
        isotropic: bool = False,
        center: str = 'image',
        default_pad_value: float = 0,
        **kwargs
    ): ...

Elastic Deformation

Non-linear elastic deformations that simulate realistic tissue deformations and anatomical variations.

class ElasticDeformation(SpatialTransform):
    """
    Deterministic elastic deformation.
    
    Parameters:
    - num_control_points: Number of control points for B-spline grid
    - max_displacement: Maximum displacement in voxels
    - locked_borders: Whether to lock image borders
    """
    def __init__(
        self,
        num_control_points: TypeTuple = 7,
        max_displacement: TypeRangeFloat = 7.5,
        locked_borders: int = 2
    ): ...

class RandomElasticDeformation(SpatialTransform):
    """
    Random elastic deformation.
    
    Parameters:
    - num_control_points: Number of control points for deformation grid
    - max_displacement: Maximum displacement range
    - locked_borders: Number of border voxels to keep fixed
    """
    def __init__(
        self,
        num_control_points: TypeTuple = 7,
        max_displacement: TypeRangeFloat = 7.5,
        locked_borders: int = 2
    ): ...

Combined Transforms

class AffineElasticDeformation(SpatialTransform):
    """
    Combined affine and elastic deformation.
    
    Applies affine transformation followed by elastic deformation
    for realistic anatomical variations.
    """
    def __init__(
        self,
        scales: TypeRangeFloat = None,
        degrees: TypeRangeFloat = None,
        translation: TypeRangeFloat = None,
        num_control_points: TypeTuple = 7,
        max_displacement: TypeRangeFloat = 7.5,
        **kwargs
    ): ...

class RandomAffineElasticDeformation(SpatialTransform):
    """Random combined affine and elastic deformation."""
    def __init__(
        self,
        scales: TypeRangeFloat = None,
        degrees: TypeRangeFloat = None,
        translation: TypeRangeFloat = None,
        num_control_points: TypeTuple = 7,
        max_displacement: TypeRangeFloat = 7.5,
        **kwargs
    ): ...

class RandomAnisotropy(SpatialTransform):
    """
    Random anisotropic scaling to simulate resolution variations.
    
    Parameters:
    - axes: Axes along which to apply anisotropic scaling
    - downsampling: Range of downsampling factors
    """
    def __init__(
        self,
        axes: tuple[int, ...] = (0, 1, 2),
        downsampling: TypeRangeFloat = (1.5, 5)
    ): ...

Usage example:

import torchio as tio

# Spatial augmentation pipeline
spatial_augmentation = tio.Compose([
    tio.RandomFlip(axes=(0,), flip_probability=0.5),
    tio.RandomAffine(
        scales=(0.9, 1.1),
        degrees=(-10, 10),
        translation=(-5, 5)
    ),
    tio.RandomElasticDeformation(
        num_control_points=7,
        max_displacement=7.5
    ),
])

subject = tio.Subject(
    t1=tio.ScalarImage('t1.nii.gz'),
    seg=tio.LabelMap('segmentation.nii.gz')
)

augmented = spatial_augmentation(subject)

Intensity Augmentation

Intensity augmentations that modify pixel/voxel intensities to simulate acquisition variations, artifacts, and improve model robustness to intensity variations.

Noise Augmentation

class Noise(IntensityTransform):
    """
    Deterministic noise addition.
    
    Parameters:
    - std: Standard deviation of Gaussian noise
    """
    def __init__(self, std: float): ...

class RandomNoise(IntensityTransform):
    """
    Random Gaussian noise addition.
    
    Parameters:
    - std: Range of standard deviation values (float or tuple)
    """
    def __init__(self, std: TypeRangeFloat = (0, 0.25)): ...

Blurring

class Blur(IntensityTransform):
    """
    Deterministic Gaussian blurring.
    
    Parameters:
    - std: Standard deviation for Gaussian kernel
    """
    def __init__(self, std: TypeRangeFloat): ...

class RandomBlur(IntensityTransform):
    """
    Random Gaussian blurring.
    
    Parameters:
    - std: Range of standard deviation values
    """
    def __init__(self, std: TypeRangeFloat = (0, 2)): ...

Gamma Correction

class Gamma(IntensityTransform):
    """
    Deterministic gamma correction.
    
    Parameters:
    - log_gamma: Log of gamma value for correction
    """
    def __init__(self, log_gamma: float): ...

class RandomGamma(IntensityTransform):
    """
    Random gamma correction.
    
    Parameters:
    - log_gamma: Range of log gamma values
    """
    def __init__(self, log_gamma: TypeRangeFloat = (-0.3, 0.3)): ...

Medical Imaging Specific Artifacts

TorchIO provides specialized augmentations that simulate realistic medical imaging artifacts commonly encountered in MRI and other modalities.

class Motion(IntensityTransform):
    """
    Deterministic motion artifacts simulation.
    
    Simulates patient motion during MRI acquisition.
    
    Parameters:
    - degrees: Rotation angles for motion simulation
    - translation: Translation distances for motion
    - num_transforms: Number of motion transforms to apply
    """
    def __init__(
        self,
        degrees: TypeRangeFloat = 10,
        translation: TypeRangeFloat = 10,
        num_transforms: int = 2
    ): ...

class RandomMotion(IntensityTransform):
    """
    Random motion artifacts simulation.
    
    Parameters:
    - degrees: Range of rotation angles
    - translation: Range of translation distances
    - num_transforms: Range of number of transforms
    """
    def __init__(
        self,
        degrees: TypeRangeFloat = 10,
        translation: TypeRangeFloat = 10,
        num_transforms: TypeRangeFloat = 2
    ): ...

class BiasField(IntensityTransform):
    """
    Deterministic bias field simulation.
    
    Simulates MRI bias field inhomogeneity.
    
    Parameters:
    - coefficients: Polynomial coefficients for bias field
    """
    def __init__(self, coefficients: TypeRangeFloat): ...

class RandomBiasField(IntensityTransform):
    """
    Random bias field simulation.
    
    Parameters:
    - coefficients: Range of polynomial coefficients
    """
    def __init__(self, coefficients: TypeRangeFloat = 0.5): ...

class Ghosting(IntensityTransform):
    """
    Deterministic ghosting artifacts simulation.
    
    Simulates MRI ghosting artifacts from periodic motion.
    
    Parameters:
    - num_ghosts: Number of ghost repetitions
    - axes: Axes along which ghosting occurs
    - intensity: Intensity of ghost artifacts
    """
    def __init__(
        self,
        num_ghosts: int,
        axes: tuple[int, ...],
        intensity: float
    ): ...

class RandomGhosting(IntensityTransform):
    """
    Random ghosting artifacts simulation.
    
    Parameters:
    - num_ghosts: Range of number of ghosts
    - axes: Axes along which ghosting can occur
    - intensity: Range of ghost intensities
    """
    def __init__(
        self,
        num_ghosts: tuple[int, int] = (4, 10),
        axes: tuple[int, ...] = (0, 1, 2),
        intensity: TypeRangeFloat = (0.5, 1)
    ): ...

class Spike(IntensityTransform):
    """
    Deterministic spike artifacts simulation.
    
    Simulates k-space spike artifacts in MRI.
    
    Parameters:
    - num_spikes: Number of spikes to add
    - intensity: Intensity of spikes
    """
    def __init__(
        self,
        num_spikes: int,
        intensity: float
    ): ...

class RandomSpike(IntensityTransform):
    """
    Random spike artifacts simulation.
    
    Parameters:
    - num_spikes: Range of number of spikes
    - intensity: Range of spike intensities
    """
    def __init__(
        self,
        num_spikes: tuple[int, int] = (1, 3),
        intensity: TypeRangeFloat = (1, 3)
    ): ...

Swap and Label Manipulation

class Swap(IntensityTransform):
    """
    Deterministic axis swapping.
    
    Parameters:
    - patch_size: Size of patches to swap
    - num_iterations: Number of swap iterations
    """
    def __init__(
        self,
        patch_size: int = 15,
        num_iterations: int = 100
    ): ...

class RandomSwap(IntensityTransform):
    """
    Random axis swapping for data augmentation.
    
    Parameters:
    - patch_size: Range of patch sizes for swapping
    - num_iterations: Range of number of iterations
    """
    def __init__(
        self,
        patch_size: TypeRangeFloat = 15,
        num_iterations: TypeRangeFloat = 100
    ): ...

class LabelsToImage(IntensityTransform):
    """
    Convert label map to intensity image.
    
    Parameters:
    - label_key: Name of label image in subject
    - used_labels: Labels to convert (None for all)
    """
    def __init__(
        self,
        label_key: str,
        used_labels: list[int] = None
    ): ...

class RandomLabelsToImage(IntensityTransform):
    """
    Randomly convert labels to intensity image.
    
    Parameters:
    - label_key: Name of label image in subject
    - used_labels: Labels that can be converted
    """
    def __init__(
        self,
        label_key: str,
        used_labels: list[int] = None
    ): ...

Usage example:

# Medical imaging specific augmentation
medical_augmentation = tio.Compose([
    tio.RandomNoise(std=(0, 0.1)),
    tio.RandomBlur(std=(0, 1)),
    tio.RandomGamma(log_gamma=(-0.3, 0.3)),
    tio.RandomMotion(degrees=2, translation=2),
    tio.RandomBiasField(coefficients=0.5),
    tio.RandomGhosting(num_ghosts=(2, 6), intensity=(0.5, 1)),
    tio.RandomSpike(num_spikes=(1, 3), intensity=(1, 3)),
])

subject = tio.Subject(
    t1=tio.ScalarImage('t1.nii.gz'),
    t2=tio.ScalarImage('t2.nii.gz')
)

# Apply medical imaging artifacts
augmented = medical_augmentation(subject)

Complete Augmentation Pipeline

Example of a comprehensive augmentation pipeline combining spatial and intensity transforms:

# Complete augmentation pipeline
augmentation_pipeline = tio.Compose([
    # Spatial augmentation
    tio.RandomFlip(axes=(0,)),
    tio.RandomAffine(
        scales=(0.9, 1.1),
        degrees=(-5, 5),
        translation=(-5, 5),
        isotropic=False
    ),
    tio.RandomElasticDeformation(
        num_control_points=(4, 8),
        max_displacement=(1, 7.5)
    ),
    
    # Intensity augmentation
    tio.RandomNoise(std=(0, 0.05)),
    tio.RandomBlur(std=(0, 0.5)),
    tio.RandomGamma(log_gamma=(-0.2, 0.2)),
    
    # Medical imaging artifacts
    tio.RandomMotion(
        degrees=(0, 2),
        translation=(0, 2),
        num_transforms=(1, 3)
    ),
    tio.RandomBiasField(coefficients=(0, 0.3)),
    tio.RandomGhosting(intensity=(0.5, 0.8)),
])

# Apply to subject
augmented_subject = augmentation_pipeline(subject)

Install with Tessl CLI