v0.18.90

What's Changed

• Fix HistogramStandardization example by @vedal in #1022
• docs: add vedal as a contributor for doc by @allcontributors in #1041
• Add workflow to validate pull request title by @fepegar in #1042
• docs: add alabamagan as a contributor for bug by @allcontributors in #1043
• docs: add justusschock as a contributor for ideas, and review by @allcontributors in #1044
• Add support to unload images by @fepegar in #983
• Remove mypy config file by @fepegar in #1045

New Contributors

• @vedal made their first contribution in #1022

Full Changelog: v0.18.89...v0.18.90

TorchIO: a Python library for efficient loading, preprocessing, augmentation and patch-based sampling of medical images in deep learning

v0.18.0

Bump version: 0.17.57 → 0.18.0

Medical image preprocessing and augmentation tools for deep learning.

TorchIO is a Python package containing a set of tools to efficiently read, preprocess, sample, augment, and write 3D medical images in deep learning applications written in PyTorch, including intensity and spatial transforms for data augmentation and preprocessing. Transforms include typical computer vision operations such as random affine transformations and also domain-specific ones such as simulation of intensity artifacts due to MRI magnetic field inhomogeneity or k-space motion artifacts.

Tools for medical image processing in deep learning and PyTorch

v0.14.2

Bump version: 0.14.1 → 0.14.2

TorchIO: Tools for loading, augmenting and writing 3D medical images on PyTorch

If you use TorchIO for your research, please cite the paper:

TorchIO: a Python library for efficient loading, preprocessing, augmentation and patch-based sampling of medical images in deep learning.

TorchIO: Tools for loading, augmenting and writing 3D medical images with PyTorch

TorchIO is a Python package containing a set of tools to efficiently read, sample and write 3D medical images in deep learning applications written in PyTorch, including intensity and spatial transforms for data augmentation and preprocessing. Transforms include typical computer vision operations such as random affine transformations and also domain-specific ones such as simulation of intensity artifacts due to MRI magnetic field inhomogeneity or k-space motion artifacts.

TorchIO: tools for loading, augmenting and writing 3D medical images with PyTorch

TorchIO is a Python package containing a set of tools to efficiently read, sample and write 3D medical images in deep learning applications written in PyTorch, including intensity and spatial transforms for data augmentation and preprocessing. Transforms include typical computer vision operations such as random affine transformations and also domain-specific ones such as simulation of intensity artifacts due to MRI magnetic field inhomogeneity or k-space motion artifacts.

TorchIO: tools for loading, augmenting and writing 3D medical images on PyTorch

TorchIO is a Python package containing a set of tools to efficiently read, sample and write 3D medical images in deep learning applications written in PyTorch, including intensity and spatial transforms for data augmentation and preprocessing. Transforms include typical computer vision operations such as random affine transformations and also domain-specific ones such as simulation of intensity artifacts due to MRI magnetic field inhomogeneity or k-space motion artifacts.

TorchIO: Tools for loading, augmenting and writing 3D medical images on PyTorch

TorchIO

torchio is a Python package containing a set of tools to efficiently
read, sample and write 3D medical images in deep learning applications
written in PyTorch,
including intensity and spatial transforms
for data augmentation and preprocessing. Transforms include typical computer vision operations
such as random affine transformations and also domain specific ones such as
simulation of intensity artifacts due to
MRI magnetic field inhomogeneity
or k-space motion artifacts.

This package has been greatly inspired by NiftyNet.

Credits

If you like this repository, please click on Star!

If you used this package for your research, please cite this repository using
the information available on its
Zenodo entry or use this BibTeX:

@software{perez_garcia_fernando_2020_3598622,
  author       = {Pérez-García, Fernando},
  title        = {{fepegar/torchio: TorchIO: Tools for loading,
                   augmenting and writing 3D medical images on
                   PyTorch}},
  month        = jan,
  year         = 2020,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.3598622},
  url          = {https://doi.org/10.5281/zenodo.3598622}
}

Index

• Installation

• Features

  • Data handling
    • ImagesDataset
    • Samplers
    • Queue
  • Transforms
    • Augmentation
      • Intensity
        • MRI k-space motion artifacts
        • MRI magnetic field inhomogeneity
        • Gaussian noise
      • Spatial
        • B-spline dense deformation
        • Flip
        • Affine transform
    • Preprocessing
      • Histogram standardization
      • Z-normalization
      • Rescale
      • Resample
      • Pad
      • Crop

• Example

• Related projects

• See also

Installation

This package is on the
Python Package Index (PyPI).
To install it, just run in a terminal the following command:

$ pip install torchio

Features

Data handling

ImagesDataset

ImagesDataset is a reader of medical images that directly inherits from
torch.utils.Dataset.
It can be used with a
torch.utils.DataLoader
for efficient reading and data augmentation.

It receives a list of subjects, where each subject is composed of a list of
torchio.Image instances.
The paths suffix must be .nii, .nii.gz or .nrrd.

import torchio

subject_a = [
    Image('t1', '~/Dropbox/MRI/t1.nrrd', torchio.INTENSITY),
    Image('label', '~/Dropbox/MRI/t1_seg.nii.gz', torchio.LABEL),
]
subject_b = [
    Image('t1', '/tmp/colin27_t1_tal_lin.nii.gz', torchio.INTENSITY),
    Image('t2', '/tmp/colin27_t2_tal_lin.nii', torchio.INTENSITY),
    Image('label', '/tmp/colin27_seg1.nii.gz', torchio.LABEL),
]
subjects_list = [subject_a, subject_b]
subjects_dataset = torchio.ImagesDataset(subjects_list)
subject_sample = subjects_dataset[0]

Samplers

torchio includes grid, uniform and label patch samplers. There is also an
aggregator used for dense predictions.
For more information about patch-based training, see
NiftyNet docs.

import torch
import torchio

CHANNELS_DIMENSION = 1
patch_overlap = 4
grid_sampler = torchio.inference.GridSampler(
    input_array,  # some NumPy array
    patch_size=128,
    patch_overlap=patch_overlap,
)
patch_loader = torch.utils.data.DataLoader(grid_sampler, batch_size=4)
aggregator = torchio.inference.GridAggregator(
    input_array,
    patch_overlap=patch_overlap,
)

with torch.no_grad():
    for patches_batch in patch_loader:
        input_tensor = patches_batch['image']
        locations = patches_batch['location']
        logits = model(input_tensor)  # some torch.nn.Module
        labels = logits.argmax(dim=CHANNELS_DIMENSION, keepdim=True)
        outputs = labels
        aggregator.add_batch(outputs, locations)

output_array = aggregator.output_array

Queue

A patches Queue (or buffer) can be used for randomized patch-based sampling
during training.
This interactive animation
can be used to understand how the queue works.

import torch
import torchio

patches_queue = torchio.Queue(
    subjects_dataset=subjects_dataset,  # instance of torchio.ImagesDataset
    queue_length=300,
    samples_per_volume=10,
    patch_size=96,
    sampler_class=torchio.sampler.ImageSampler,
    num_workers=4,
    shuffle_subjects=True,
    shuffle_patches=True,
)
patches_loader = DataLoader(patches_queue, batch_size=4)

num_epochs = 20
for epoch_index in range(num_epochs):
    for patches_batch in patches_loader:
        logits = model(patches_batch)  # model is some torch.nn.Module

Transforms

The transforms package should remind users of
torchvision.transforms.
They take as input the samples generated by an ImagesDataset.

A transform can be quickly applied to an image file using the command-line
tool torchio-transform:

$ torchio-transform input.nii.gz RandomMotion output.nii.gz --kwargs "proportion_to_augment=1 num_transforms=4"

Augmentation

Intensity

MRI k-space motion artifacts

Magnetic resonance images suffer from motion artifacts when the subject moves
during image acquisition. This transform follows
Shaw et al., 2019 to
simulate motion artifacts for data augmentation.

MRI magnetic field inhomogeneity

MRI magnetic field inhomogeneity creates slow frequency intensity variations.
This transform is very similar to the one in
NiftyNet.

Gaussian noise

Adds noise sampled from a normal distribution with mean 0 and standard
deviation sampled from a uniform distribution in the range std_range.
It is often used after ZNormalization, as the output of
this transform has zero-mean.

Spatial

B-spline dense elastic deformation

Flip

Reverse the order of elements in an image along the given axes.

Affine transform

Preprocessing

Histogram standardization

Implementation of
New variants of a method of MRI scale standardization
adapted from NiftyNet.

Z-normalization

This transform first extracts the values with intensity greater than the mean,
which is an approximation of the foreground voxels.
Then the foreground mean is subtracted from the image and it is divided by the
foreground standard deviation.

Rescale

Rescale intensity values in an image to a certain range.

Resample

Resample images to a new voxel spacing using nibabel.

Pad

Pad images, like in torchvision.transforms.Pad.

Crop

Crop images passing 1, 3, or 6 integers, as in Pad.

Example

This example shows the imp...

TorchIO: Tools for loading, augmenting and writing 3D medical images on PyTorch

TorchIO

torchio is a Python package containing a set of tools to efficiently
read, sample and write 3D medical images in deep learning applications
written in PyTorch,
including intensity and spatial transforms
for data augmentation and preprocessing. Transforms include typical computer vision operations
such as random affine transformations and also domain specific ones such as
simulation of intensity artifacts due to
MRI magnetic field inhomogeneity
or k-space motion artifacts.

This package has been greatly inspired by NiftyNet.

Index

• Installation
• Features
  • Data handling
    • ImagesDataset
    • Samplers
    • Queue
  • Transforms
    • Intensity
      • MRI k-space motion artifacts
      • MRI magnetic field inhomogeneity
      • Gaussian noise
      • Normalization
        • Histogram standardization
        • Z-normalization
        • Rescale
    • Spatial
      • Flip
      • Affine transform
      • B-spline dense deformation
• Example

Installation

$ pip install torchio

Features

Data handling

ImagesDataset

ImagesDataset is a reader of medical images that directly inherits from
torch.utils.Dataset.
It can be used with a
torch.utils.DataLoader
for efficient reading and data augmentation.

The paths suffix must be .nii, .nii.gz or .nrrd.

import torchio

subject_a = {
    't1': dict(path='~/Dropbox/MRI/t1.nii.gz', type=torchio.INTENSITY),
    'label': dict(path='~/Dropbox/MRI/t1_seg.nii.gz', type=torchio.LABEL),
}
subject_b = {
    't1': dict(path='/tmp/colin27_t1_tal_lin.nii.gz', type=torchio.INTENSITY),
    'label': dict(path='/tmp/colin27_seg1.nii.gz', type=torchio.LABEL),
}
paths_list = [subject_a, subject_b]
subjects_dataset = torchio.ImagesDataset(paths_list)
subject_sample = subjects_dataset[0]

Samplers

torchio includes grid, uniform and label patch samplers. There is also an
aggregator used for dense predictions. The code for these is almost
copy-pasted from NiftyNet.

For more information about patch-based training, see
NiftyNet docs.

import torch
import torchio

CHANNELS_DIMENSION = 1
patch_overlap = 4
grid_sampler = torchio.inference.GridSampler(
    input_array,  # some NumPy array
    patch_size=128,
    patch_overlap=patch_overlap,
)
patch_loader = torch.utils.data.DataLoader(grid_sampler, batch_size=4)
aggregator = torchio.inference.GridAggregator(
    input_array,
    patch_overlap=patch_overlap,
)

with torch.no_grad():
    for patches_batch in patch_loader:
        input_tensor = patches_batch['image']
        locations = patches_batch['location']
        logits = model(input_tensor)  # some torch.nn.Module
        labels = logits.argmax(dim=CHANNELS_DIMENSION, keepdim=True)
        outputs = labels
        aggregator.add_batch(outputs, locations)

output_array = aggregator.output_array

Queue

A patches Queue (or buffer) can be used for randomized patch-based sampling
during training.
This interactive animation
can be used to understand how the queue works.

import torch
import torchio

patches_queue = torchio.Queue(
    subjects_dataset=subjects_dataset,
    queue_length=300,
    samples_per_volume=10,
    patch_size=96,
    sampler_class=torchio.sampler.ImageSampler,
    num_workers=4,
    shuffle_subjects=True,
    shuffle_patches=True,
)
patches_loader = DataLoader(patches_queue, batch_size=4)

num_epochs = 20
for epoch_index in range(num_epochs):
    for patches_batch in patches_loader:
        logits = model(patches_batch)  # model is some torch.nn.Module

Transforms

The transforms package should remind users of
torchvision.transforms.
They take as input the samples generated by an
ImagesDataset.

Intensity

MRI k-space motion artifacts

Magnetic resonance images suffer from motion artifacts when the subject moves
during image acquisition. This transform follows
Shaw et al., 2019 to
simulate motion artifacts for data augmentation.

MRI magnetic field inhomogeneity

MRI magnetic field inhomogeneity creates slow frequency intensity variations.
This transform is very similar to the one in
NiftyNet.

Gaussian noise

Adds noise sampled from a normal distribution with mean 0 and standard
deviation sampled from a uniform distribution in the range std_range.
It is often used after ZNormalization, as the output of
this transform has zero-mean.

Normalization

Histogram standardization

Implementation of
New variants of a method of MRI scale standardization
adapted from NiftyNet.

Z-normalization

This transform first extracts the values with intensity greater than the mean,
which is an approximation of the foreground voxels.
Then the foreground mean is subtracted from the image and it is divided by the
foreground standard deviation.

Rescale

Spatial

Flip

Reverse the order of elements in an image along the given axes.

Affine transform

B-spline dense elastic deformation

Example

This example shows the improvement in performance when multiple workers are
used to load and preprocess the volumes using multiple workers.

import time
import multiprocessing as mp

from tqdm import trange

import torch.nn as nn
from torch.utils.data import DataLoader
from torchvision.transforms import Compose

from torchio import ImagesDataset, Queue
from torchio.sampler import ImageSampler
from torchio.utils import create_dummy_dataset
from torchio.transforms import (
    ZNormalization,
    RandomNoise,
    RandomFlip,
    RandomAffine,
)


# Define training and patches sampling parameters
num_epochs = 4
patch_size = 128
queue_length = 400
samples_per_volume = 10
batch_size = 4

class Network(nn.Module):
    def __init__(self):
        super().__init__()
        self.conv = nn.Conv3d(
            in_channels=1,
            out_channels=3,
            kernel_size=3,
        )
    def forward(self, x):
        return self.conv(x)

model = Network()

# Create a dummy dataset in the temporary directory, for this example
subjects_list = create_dummy_dataset(
    num_images=100,
    size_range=(193, 229),
    force=False,
)

# Each element of subjects_list is a dictionary:
# subject_images = [
#     torchio.Image('one_image', path_to_one_image, torchio.INTENSITY),
#     torchio.Image('another_image', path_to_another_image, torchio.INTENSITY),
#     torchio.Image('a_label', path_to_a_label, torchio.LABEL),
# ]

# Define transforms for data normalization and augmentation
transforms = (
    ZNormalization(),
    RandomNoise(std_range=(0, 0.25)),
    RandomAffine(scales=(0.9, 1.1), degrees=10),
    RandomFlip(axes=(0,)),
)
transform = Compose(transforms)
subjects_dataset = ImagesDataset(subjects_list, transform)


# Run a benchmark for different numbers of workers
workers = range(mp.cpu_count() + 1)
for num_workers in workers:
    print('Number of workers:', num_workers)

    # Define the dataset as a queue of patches
    queue_dataset = Queue(
        subjects_dataset,
        queue_length,
        samples_per_volume,
        patch_size,
        ImageSampler,
        num_workers=num_workers,
    )
    batch_lo...