TorchIO

https://docs.torchio.org
Admin
TorchIO is an open-source Python library for efficient loading, preprocessing, augmentation, and...
Tokens:87,000
Snippets:727
Trust Score:5.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install TorchIO with uv

Source: https://docs.torchio.org/getting-started

Install the core TorchIO package using the uv package manager.

```bash
uv add torchio
```

--------------------------------

### Install TorchIO with extras using uv

Source: https://docs.torchio.org/getting-started

Install TorchIO with optional 'plot' and 'csv' extras using the uv package manager.

```bash
uv add torchio --extra plot --extra csv
```

--------------------------------

### Install TorchIO with pip

Source: https://docs.torchio.org/getting-started

Install the core TorchIO package using pip.

```bash
pip install torchio
```

--------------------------------

### Install TorchIO with extras using pip

Source: https://docs.torchio.org/getting-started

Install TorchIO with optional 'plot' and 'csv' extras using pip.

```bash
pip install "torchio[plot,csv]"
```

--------------------------------

### Install 3D Slicer Preview with Homebrew

Source: https://docs.torchio.org/interfaces/slicer

Use this command to install the preview version of 3D Slicer on macOS using Homebrew.

```bash
brew tap homebrew/cask-versions && brew cask install slicer-preview

```

--------------------------------

### `as_sitk(**kwargs)`

Source: https://docs.torchio.org/data/image

Get the image as an instance of SimpleITK.Image.

```APIDOC
## `as_sitk(**kwargs)`

### Description
Get the image as an instance of [sitk.Image][].

### Method
`as_sitk(**kwargs)`
```

--------------------------------

### Example Usage: Resampling an Image

Source: https://docs.torchio.org/transforms/preprocessing/Resample

A practical example demonstrating how to use the Resample transform to downsample an image and add it back to a subject.

```APIDOC
## Example Usage: Resampling an Image

### Description
This example demonstrates a common use case: resampling an image to a different spacing and incorporating it into a subject.

### Code
```python
import torchio as tio

# Load a subject and remove the segmentation image if it exists
subject = tio.datasets.FPG()
if 'seg' in subject:
    subject.remove_image('seg')

# Initialize Resample transform to target 8mm isotropic spacing
resample_transform = tio.Resample(8)

# Apply the transform to the 't1' image in the subject
t1_resampled = resample_transform(subject.t1)

# Add the resampled image back to the subject with a new key
subject.add_image(t1_resampled, 'Downsampled')

# Optionally, plot the subject to visualize the changes
# subject.plot()
```
```

--------------------------------

### as_sitk(**kwargs)

Source: https://docs.torchio.org/data/image

Get the image as an instance of [sitk.Image][].

```APIDOC
## `as_sitk(**kwargs)`

### Description
Get the image as an instance of [sitk.Image][].
```

--------------------------------

### Instantiate LabelMap from SimpleITK Image

Source: https://docs.torchio.org/data/image

Create a TorchIO LabelMap from a SimpleITK image. Ensure SimpleITK is installed and imported.

```python
>>> import torchio as tio
>>> import SimpleITK as sitk
>>> sitk_image = sitk.Image(20, 30, 40, sitk.sitkUInt16)
>>> tio.LabelMap.from_sitk(sitk_image)
LabelMap(shape: (1, 20, 30, 40); spacing: (1.00, 1.00, 1.00); orientation: LPS+; memory: 93.8 KiB; dtype: torch.IntTensor)
```

```python
>>> sitk_image = sitk.Image((224, 224), sitk.sitkVectorFloat32, 3)
>>> tio.ScalarImage.from_sitk(sitk_image)
ScalarImage(shape: (3, 224, 224, 1); spacing: (1.00, 1.00, 1.00); orientation: LPS+; memory: 588.0 KiB; dtype: torch.FloatTensor)
```

--------------------------------

### Install TorchIO with conda

Source: https://docs.torchio.org/getting-started

Install the core TorchIO package using conda from the conda-forge channel.

```bash
conda install -c conda-forge torchio
```

--------------------------------

### Basic TorchIO Hello World Example

Source: https://docs.torchio.org/getting-started

Demonstrates creating subjects with different image types (NIfTI, DICOM, tensors), applying preprocessing and augmentation transforms, and loading batches using SubjectsDataset and SubjectsLoader. Use this to understand the fundamental data loading and transformation pipeline.

```python
import torch
import torchio as tio

# Each instance of tio.Subject is passed arbitrary keyword arguments.
# Typically, these arguments will be instances of tio.Image
subject_a = tio.Subject(
    t1=tio.ScalarImage('subject_a.nii.gz'),
    label=tio.LabelMap('subject_a.nii'),
    diagnosis='positive',
    age=36,
)

# Image files can be in any format supported by SimpleITK or NiBabel, including DICOM
subject_b = tio.Subject(
    t1=tio.ScalarImage('subject_b_dicom_folder/'),
    label=tio.LabelMap('subject_b_seg.nrrd'),
    diagnosis='negative',
    age=24,
)

# Images may also be created using PyTorch tensors or NumPy arrays
tensor_4d = torch.rand(4, 100, 100, 100)
subject_c = tio.Subject(
    t1=tio.ScalarImage(tensor=tensor_4d),
    label=tio.LabelMap(tensor=(tensor_4d > 0.5)),
    diagnosis='negative',
    age=19,
)

subjects_list = [
    subject_a,
    subject_b,
    subject_c,
]

# Let's use one preprocessing transform and one augmentation transform
# This transform will be applied only to scalar images:
rescale = tio.RescaleIntensity(out_min_max=(0, 1))

# As RandomAffine is faster then RandomElasticDeformation, we choose to
# apply RandomAffine 80% of the times and RandomElasticDeformation the rest
# Also, there is a 25% chance that none of them will be applied
spatial = tio.OneOf({
        tio.RandomAffine(): 0.8,
        tio.RandomElasticDeformation(): 0.2,
    },
    p=0.75,
)

# Transforms can be composed as in torchvision.transforms
transforms = [rescale, spatial]
transform = tio.Compose(transforms)

# SubjectsDataset is a subclass of torch.data.utils.Dataset
subjects_dataset = tio.SubjectsDataset(subjects_list, transform=transform)

# Images are processed in parallel thanks to a SubjectsLoader
# (which inherits from torch.utils.data.DataLoader)
training_loader = tio.SubjectsLoader(
    subjects_dataset,
    batch_size=4,
    num_workers=4,
    shuffle=True,
)

# Training epoch
for subjects_batch in training_loader:
    inputs = subjects_batch['t1'][tio.DATA]
    target = subjects_batch['label'][tio.DATA]

```

--------------------------------

### RandomLabelsToImage Usage Example

Source: https://docs.torchio.org/transforms/augmentation/RandomLabelsToImage

This example demonstrates how to use the RandomLabelsToImage transform as part of a Compose sequence. It loads a dataset, applies resampling and random blurring, and then uses RandomLabelsToImage to create a synthetic image before applying the blur.

```python
import torch
import torchio as tio
torch.manual_seed(42)
colin = tio.datasets.Colin27(2008)
label_map = colin.cls
colin.remove_image('t1')
colin.remove_image('t2')
colin.remove_image('pd')
downsample = tio.Resample(1)
blurring_transform = tio.RandomBlur(std=0.6)
create_synthetic_image = tio.RandomLabelsToImage(
    image_key='synthetic',
    ignore_background=True,
)
transform = tio.Compose((
    downsample,
    create_synthetic_image,
    blurring_transform,
))
colin_synth = transform(colin)
colin_synth.plot()
```

--------------------------------

### PyTorch Pooling Example

Source: https://docs.torchio.org/transforms/preprocessing/EnsureShapeMultiple

Demonstrates how PyTorch pooling rounds down output sizes, potentially losing original shape information.

```python
>>> import torch
>>> x = torch.rand(3, 10, 20, 31)
>>> x_down = torch.nn.functional.max_pool3d(x, 2)
>>> x_down.shape
torch.Size([3, 5, 10, 15])
```

```python
>>> x_down_up = torch.nn.functional.interpolate(x_down, scale_factor=2)
>>> x_down_up.shape
torch.Size([3, 10, 20, 30])
>>> x.shape
torch.Size([3, 10, 20, 31])
```

--------------------------------

### Initialize and use LabelSampler

Source: https://docs.torchio.org/patches/training

Initialize a LabelSampler with patch size, label name, and label probabilities. Iterate through the sampler to get patches and print their shapes.

```python
>>> import torchio as tio
>>> subject = tio.datasets.Colin27()
>>> subject
Colin27(Keys: ('t1', 'head', 'brain'); images: 3)
>>> probabilities = {0: 0.5, 1: 0.5}
>>> sampler = tio.data.LabelSampler(
...     patch_size=64,
...     label_name='brain',
...     label_probabilities=probabilities,
... )
>>> generator = sampler(subject)
>>> for patch in generator:
...     print(patch.shape)

```

--------------------------------

### Setup and Transformations for Volume Slicing

Source: https://docs.torchio.org/examples/plot_3d_to_2d

Imports necessary libraries and defines a dataset with transformations including cropping, padding, random flipping, and random affine transformations. This prepares the data for 2D slice extraction.

```python
import matplotlib.pyplot as plt
import torch

import torchio as tio

torch.manual_seed(0)
max_queue_length = 16
patches_per_volume = 2

subject = tio.datasets.Colin27()
subject.remove_image('head')

subjects = 50 * [subject]
max_side = max(subject.shape)
transform = tio.Compose(
    (
        tio.CropOrPad(max_side),
        tio.RandomFlip(),
        tio.RandomAffine(degrees=360),
    )
)
dataset = tio.SubjectsDataset(subjects, transform=transform)
patch_size = (max_side, max_side, 1)  # 2D slices


def plot_batch(sampler):
    queue = tio.Queue(dataset, max_queue_length, patches_per_volume, sampler)
    loader = tio.SubjectsLoader(queue, batch_size=16)
    batch = tio.utils.get_first_item(loader)

    _, axes = plt.subplots(4, 4, figsize=(12, 10))
    for ax, im in zip(axes.flatten(), batch['t1']['data'], strict=True):
        ax.imshow(im.squeeze(), cmap='gray')
    plt.suptitle(sampler.__class__.__name__)
    plt.tight_layout()
```

--------------------------------

### SequentialLabels Example

Source: https://docs.torchio.org/transforms/preprocessing/SequentialLabels

Demonstrates how SequentialLabels re-indexes labels, including cases with and without a background label. The background label 0 is always preserved in the output.

```python
>>> import torch
>>> import torchio as tio
>>> def get_image(*labels):
...     tensor = torch.as_tensor(labels).reshape(1, 1, 1, -1)
...     image = tio.LabelMap(tensor=tensor)
...     return image
...
>>> img_with_bg = get_image(0, 5, 10)
>>> transform = tio.SequentialLabels()
>>> transform(img_with_bg).data
tensor([[[[0, 1, 2]]]])
>>> img_without_bg = get_image(7, 11, 99)
>>> transform(img_without_bg).data
tensor([[[[0, 1, 2]]]])
```

--------------------------------

### Initialize and use WeightedSampler

Source: https://docs.torchio.org/patches/training

Initialize a WeightedSampler with a patch size and probability map name. Iterate through the sampler to get patches, printing the location of each patch.

```python
>>> import torchio as tio
>>> subject = tio.Subject(
...     t1=tio.ScalarImage('t1_mri.nii.gz'),
...     sampling_map=tio.Image('sampling.nii.gz', type=tio.SAMPLING_MAP),
... )
>>> patch_size = 64
>>> sampler = tio.data.WeightedSampler(patch_size, 'sampling_map')
>>> for patch in sampler(subject):
...     print(patch[tio.LOCATION])

```

--------------------------------

### Clamp transform with subject and plotting

Source: https://docs.torchio.org/transforms/preprocessing/Clamp

This example demonstrates applying the Clamp transform to a subject's image and then visualizing the result. It shows how to integrate the transform into a typical TorchIO workflow.

```python
import torchio as tio
subject = tio.datasets.Slicer('CTChest')
ct = subject.CT_chest
HOUNSFIELD_AIR, HOUNSFIELD_BONE = -1000, 1000
clamp = tio.Clamp(out_min=HOUNSFIELD_AIR, out_max=HOUNSFIELD_BONE)
ct_clamped = clamp(ct)
subject.add_image(ct_clamped, 'Clamped')
subject.plot()
```

--------------------------------

### CopyAffine Usage Example

Source: https://docs.torchio.org/transforms/preprocessing/CopyAffine

Demonstrates how to use the CopyAffine transform to fix spatial metadata inconsistencies and enable resampling.

```APIDOC
## Example Usage

This example shows how to use `CopyAffine` to resolve issues caused by slight differences in affine matrices between images, allowing for successful resampling.

### Scenario
Two images, `t1` and `t2`, are created with very similar but not identical affine matrices due to simulated precision loss.

### Problem
Attempting to resample the subject directly results in an error because the images are considered to be in different spatial spaces.

### Solution
Apply the `CopyAffine` transform, specifying `t1` as the source for the affine matrix. This synchronizes the spatial metadata.

### Result
After applying `CopyAffine`, the `resample` operation succeeds, indicating that the images are now in consistent spatial spaces.

```python
>>> import torch
>>> import torchio as tio
>>> import numpy as np
>>> np.random.seed(0)
>>> affine = np.diag((*(np.random.rand(3) + 0.5), 1))
>>> t1 = tio.ScalarImage(tensor=torch.rand(1, 100, 100, 100), affine=affine)
>>> # Simulate loss of precision
>>> bad_affine = affine.astype(np.float16)
>>> t2 = tio.ScalarImage(tensor=torch.rand(1, 100, 100, 100), affine=bad_affine)
>>> subject = tio.Subject(t1=t1, t2=t2)
>>> resample = tio.Resample(0.5)
>>> try:
...     resample(subject).shape
... except RuntimeError as e:
...     print(f"Error during resampling: {e}")
Error during resampling: More than one shape found in subject images:
{'t1': (1, 210, 244, 221), 't2': (1, 210, 243, 221)}
>>> transform = tio.CopyAffine('t1')
>>> fixed = transform(subject)
>>> resample(fixed).shape
(1, 210, 244, 221)
```
```

--------------------------------

### RandomGamma Transform Example

Source: https://docs.torchio.org/transforms/augmentation/RandomGamma

Instantiate and apply the RandomGamma transform to a subject. The `log_gamma` parameter controls the range of the gamma exponent.

```python
import torchio as tio
subject = tio.datasets.FPG()
transform = tio.RandomGamma(log_gamma=(-0.3, 0.3))  # gamma between 0.74 and 1.34
transformed = transform(subject)
```

--------------------------------

### MonaiAdapter Usage Examples

Source: https://docs.torchio.org/transforms/others/MonaiAdapter

Demonstrates how to use MonaiAdapter with different types of MONAI transforms, including array transforms, dictionary transforms, and within a Compose pipeline.

```APIDOC
## Examples

```python
>>> import torch
>>> import torchio as tio
>>> from monai.transforms import NormalizeIntensity
>>> from monai.transforms import NormalizeIntensityd
>>> from monai.transforms import RandSpatialCropd
>>> subject = tio.Subject(
...     t1=tio.ScalarImage(tensor=torch.randn(1, 64, 64, 64)),
...     seg=tio.LabelMap(tensor=torch.ones(1, 64, 64, 64)),
... )
>>> # Array transform — applied to each image
>>> adapter = tio.MonaiAdapter(NormalizeIntensity())
>>> transformed = adapter(subject)
>>> # Dictionary transform — applied to specified keys
>>> adapter = tio.MonaiAdapter(NormalizeIntensityd(keys=["t1"]))
>>> transformed = adapter(subject)
>>> # Spatial dict transform (affine is updated)
>>> adapter = tio.MonaiAdapter(
...     RandSpatialCropd(keys=["t1", "seg"], roi_size=[32, 32, 32]),
... )
>>> transformed = adapter(subject)
>>> # Inside a Compose pipeline
>>> pipeline = tio.Compose([
...     tio.ToCanonical(),
...     tio.MonaiAdapter(NormalizeIntensity()),
...     tio.RandomFlip(),
... ])
>>> transformed = pipeline(subject)
```
```

--------------------------------

### Apply CropOrPad to a Tensor Image

Source: https://docs.torchio.org/transforms/preprocessing/CropOrPad

This example demonstrates applying the `CropOrPad` transform to a `ScalarImage` tensor and then creating a `Subject` containing both the original and transformed images.

```python
import torchio as tio
t1 = tio.datasets.Colin27().t1
crop_pad = tio.CropOrPad((512, 512, 32))
t1_pad_crop = crop_pad(t1)
subject = tio.Subject(t1=t1, crop_pad=t1_pad_crop)
# subject.plot()
```

--------------------------------

### Initialize RandomAnisotropy Transform

Source: https://docs.torchio.org/transforms/augmentation/RandomAnisotropy

Instantiate the RandomAnisotropy transform with custom parameters for axes and downsampling factors. This example shows how to set a single axis and a fixed downsampling factor, and then how to specify a range for the downsampling factor across multiple axes.

```python
>>> import torchio as tio
>>> transform = tio.RandomAnisotropy(axes=1, downsampling=2)
```

```python
>>> transform = tio.RandomAnisotropy(
...     axes=(0, 1, 2),
...     downsampling=(2, 5),
... )   # Multiply spacing of one of the 3 axes by a factor randomly chosen in [2, 5]
```

--------------------------------

### Initialize Colin27 Dataset (2008 Version)

Source: https://docs.torchio.org/datasets

Instantiate the Colin27 dataset for the 2008 version. Note that this version has a higher resolution, resulting in larger image sizes and potentially longer processing times.

```python
>>> colin_2008 = tio.datasets.Colin27(version=2008)
>>> colin_2008
Colin27(Keys: ('t1', 't2', 'pd', 'cls'); images: 4)
>>> colin_2008.load()
>>> colin_2008.t1
ScalarImage(shape: (1, 362, 434, 362); spacing: (0.50, 0.50, 0.50); orientation: RAS+; memory: 217.0 MiB; type: intensity)
```

--------------------------------

### `from_sitk(sitk_image)` (classmethod)

Source: https://docs.torchio.org/data/image

Instantiate a new TorchIO image from a SimpleITK.Image.

```APIDOC
## `from_sitk(sitk_image)` `classmethod`

### Description
Instantiate a new TorchIO image from a [sitk.Image][].

### Method
`from_sitk(sitk_image)`

### Parameters
#### Path Parameters
- **sitk_image** (sitk.Image) - Required - The SimpleITK image to convert.

### Request Example
```python
>>> import torchio as tio
>>> import SimpleITK as sitk
>>> sitk_image = sitk.Image(20, 30, 40, sitk.sitkUInt16)
>>> tio.LabelMap.from_sitk(sitk_image)
LabelMap(shape: (1, 20, 30, 40); spacing: (1.00, 1.00, 1.00); orientation: LPS+; memory: 93.8 KiB; dtype: torch.IntTensor)
>>> sitk_image = sitk.Image((224, 224), sitk.sitkVectorFloat32, 3)
>>> tio.ScalarImage.from_sitk(sitk_image)
ScalarImage(shape: (3, 224, 224, 1); spacing: (1.00, 1.00, 1.00); orientation: LPS+; memory: 588.0 KiB; dtype: torch.FloatTensor)
```
```

--------------------------------

### ScalarImage Instantiation and Basic Usage

Source: https://docs.torchio.org/data/image

Demonstrates how to create a ScalarImage instance from a file path or a PyTorch tensor, and access its data and affine matrix.

```APIDOC
## ScalarImage

Bases: `Image`

Image whose pixel values represent scalars.

Examples:
```
>>> import torch
>>> import torchio as tio
>>> # Loading from a file
>>> t1_image = tio.ScalarImage('t1.nii.gz')
>>> dmri = tio.ScalarImage(tensor=torch.rand(32, 128, 128, 88))
>>> image = tio.ScalarImage('safe_image.nrrd', check_nans=False)
>>> data, affine = image.data, image.affine
>>> affine.shape
(4, 4)
>>> image.data is image[tio.DATA]
True
>>> image.data is image.tensor
True
>>> type(image.data)
torch.Tensor
```
```

--------------------------------

### Initialize Colin27 Dataset (1998 Version)

Source: https://docs.torchio.org/datasets

Instantiate the Colin27 dataset for the 1998 version. This dataset provides a template with specific image dimensions and memory usage.

```python
>>> import torchio as tio
>>> colin_1998 = tio.datasets.Colin27(version=1998)
>>> colin_1998
Colin27(Keys: ('t1', 'head', 'brain'); images: 3)
>>> colin_1998.load()
>>> colin_1998.t1
ScalarImage(shape: (1, 181, 217, 181); spacing: (1.00, 1.00, 1.00); orientation: RAS+; memory: 27.1 MiB; type: intensity)
```

--------------------------------

### Initialize IXI Dataset with Transforms

Source: https://docs.torchio.org/datasets

Load the IXI dataset, applying specified transformations such as converting to canonical orientation and resampling. Set download=True to download the dataset if it's not present. Note that this dataset is several GB in size.

```python
>>> import torchio as tio
>>> transforms = [
...     tio.ToCanonical(),  # to RAS
...     tio.Resample((1, 1, 1)),  # to 1 mm iso
... ]
>>> ixi_dataset = tio.datasets.IXI(
...     'path/to/ixi_root/',
...     modalities=('T1', 'T2'),
...     transform=tio.Compose(transforms),
...     download=True,
... )
```

--------------------------------

### Get Subject Spatial Shape

Source: https://docs.torchio.org/datasets

Access the `spatial_shape` property of a dataset subject to get its spatial dimensions (height, width, depth). This checks for spatial shape consistency across all images in the subject.

```python
import torchio as tio
colin = tio.datasets.Colin27() # Example dataset
colin.spatial_shape
```

--------------------------------

### RemoveLabels Transform Example

Source: https://docs.torchio.org/transforms/preprocessing/RemoveLabels

Demonstrates how to use the RemoveLabels transform to remove specific labels from a label map and add the result as a new image to a subject. This example shows how to define the labels to remove and apply the transform.

```python
import torchio as tio
colin = tio.datasets.Colin27(2008)
label_map = colin.cls
colin.remove_image('t2')
colin.remove_image('pd')
names_to_remove = (
    'Fat',
    'Muscles',
    'Skin and Muscles',
    'Skull',
    'Fat 2',
    'Dura',
    'Marrow'
)
labels = [colin.NAME_TO_LABEL[name] for name in names_to_remove]
skull_stripping = tio.RemoveLabels(labels)
only_brain = skull_stripping(label_map)
colin.add_image(only_brain, 'brain')
colors = {
    0: (0, 0, 0),
    1: (127, 255, 212),
    2: (96, 204, 96),
    3: (240, 230, 140),
    4: (176, 48, 96),
    5: (48, 176, 96),
    6: (220, 247, 164),
    7: (103, 255, 255),
    9: (205, 62, 78),
    10: (238, 186, 243),
    11: (119, 159, 176),
    12: (220, 216, 20),
}
colin.plot(cmap_dict={'cls': colors, 'brain': colors})
```

--------------------------------

### as_pil(transpose=True)

Source: https://docs.torchio.org/data/image

Get the image as an instance of [PIL.Image][].

```APIDOC
## `as_pil(transpose=True)`

### Description
Get the image as an instance of [PIL.Image][].

### Parameters
#### Query Parameters
- **transpose** (bool) - Optional - Whether to transpose the image dimensions for PIL compatibility. Default: `True`.

### Notes
Values will be clamped to 0-255 and cast to uint8.
To use this method, Pillow needs to be installed: `pip install Pillow`.
```

--------------------------------

### from_sitk(sitk_image)

Source: https://docs.torchio.org/data/image

Instantiate a new TorchIO image from a [sitk.Image][].

```APIDOC
## `from_sitk(sitk_image)` `classmethod`

### Description
Instantiate a new TorchIO image from a [sitk.Image][].

### Parameters
#### Request Body
- **sitk_image** (sitk.Image) - Required - A SimpleITK image object.

### Examples
```python
>>> import torchio as tio
>>> import SimpleITK as sitk
>>> sitk_image = sitk.Image(20, 30, 40, sitk.sitkUInt16)
>>> tio.LabelMap.from_sitk(sitk_image)
LabelMap(shape: (1, 20, 30, 40); spacing: (1.00, 1.00, 1.00); orientation: LPS+; memory: 93.8 KiB; dtype: torch.IntTensor)
>>> sitk_image = sitk.Image((224, 224), sitk.sitkVectorFloat32, 3)
>>> tio.ScalarImage.from_sitk(sitk_image)
ScalarImage(shape: (3, 224, 224, 1); spacing: (1.00, 1.00, 1.00); orientation: LPS+; memory: 588.0 KiB; dtype: torch.FloatTensor)
```
```

--------------------------------

### ZonePlate.get_inverse_transform

Source: https://docs.torchio.org/datasets

Gets a reversed list of the inverses of the applied transforms.

```APIDOC
## ZonePlate.get_inverse_transform(warn=True, ignore_intensity=False, image_interpolation=None)

### Description
Get a reversed list of the inverses of the applied transforms.

### Parameters
#### Query Parameters
- **warn** (bool) - Optional - Issue a warning if some transforms are not invertible. Default: `True`
- **ignore_intensity** (bool) - Optional - If `True`, all instances of `IntensityTransform` will be ignored. Default: `False`
- **image_interpolation** (str | None) - Optional - Modify interpolation for scalar images inside transforms that perform resampling. Default: `None`
```

--------------------------------

### numpy()

Source: https://docs.torchio.org/data/image

Get a NumPy array containing the image data.

```APIDOC
## `numpy()`

### Description
Get a NumPy array containing the image data.
```

--------------------------------

### `numpy()`

Source: https://docs.torchio.org/data/image

Get a NumPy array containing the image data.

```APIDOC
## `numpy()`

### Description
Get a NumPy array containing the image data.

### Method
`numpy()`
```

--------------------------------

### Remap Labels Example

Source: https://docs.torchio.org/transforms/preprocessing/RemapLabels

This example demonstrates how to use the RemapLabels transform to group various anatomical labels into broader categories like background, gray matter, white matter, and CSF. It then applies this remapping to a subject's segmentation and adds the remapped image back to the subject.

```python
import torchio as tio

subject = tio.datasets.FPG()
subject.remove_image('t1')

background_labels = (0, 1, 2, 3, 4)
csf_labels = (5, 12, 16, 47, 52, 53)
white_matter_labels = (
    45, 46,
    66, 67,
    81, 82,
    83, 84,
    85, 86,
    87,
    89, 90,
    91, 92,
    93, 94,
)

not_gray_matter_labels = (
    background_labels
    + csf_labels
    + white_matter_labels
)

gray_matter_labels = [
    label for label in subject.GIF_COLORS
    if label not in not_gray_matter_labels
]

labels_groups = (
    background_labels,
    gray_matter_labels,
    white_matter_labels,
    csf_labels,
)
remapping = {}
for target, labels in enumerate(labels_groups):
    for label in labels:
        remapping[label] = target

parcellation_to_tissues = tio.RemapLabels(remapping)
tissues = parcellation_to_tissues(subject).seg
subject.add_image(tissues, 'remapped')
subject.plot()

```

--------------------------------

### Load RSNA-MICCAI Dataset

Source: https://docs.torchio.org/datasets

Download the dataset using kaggle CLI and instantiate the RSNA-MICCAI dataset for training or testing. The dataset must be downloaded before instantiation.

```python
import torchio as tio
from subprocess import call
call('kaggle competitions download -c rsna-miccai-brain-tumor-radiogenomic-classification'.split())
root_dir = 'rsna-miccai-brain-tumor-radiogenomic-classification'
train_set = tio.datasets.RSNAMICCAI(root_dir, train=True)
test_set = tio.datasets.RSNAMICCAI(root_dir, train=False)
len(train_set), len(test_set)
```

--------------------------------

### get_center(lps=False)

Source: https://docs.torchio.org/data/image

Get image center in RAS+ or LPS+ coordinates.

```APIDOC
## `get_center(lps=False)`

### Description
Get image center in RAS+ or LPS+ coordinates.

### Parameters
#### Query Parameters
- **lps** (bool) - Optional - If `True`, the coordinates will be in LPS+ orientation, i.e. the first dimension grows towards the left, etc. Otherwise, the coordinates will be in RAS+ orientation. Default: `False`.
```

--------------------------------

### Initialize and Use Queue for Training

Source: https://docs.torchio.org/patches/training

Instantiate a Queue with a SubjectsDataset, sampler, and configuration for training. Use a SubjectsLoader to create batches from the queue, ensuring num_workers is 0 for the loader.

```python
>>> import torch
>>> import torchio as tio
>>> patch_size = 96
>>> queue_length = 300
>>> samples_per_volume = 10
>>> sampler = tio.data.UniformSampler(patch_size)
>>> subject = tio.datasets.Colin27()
>>> subjects_dataset = tio.SubjectsDataset(10 * [subject])
>>> patches_queue = tio.Queue(
...     subjects_dataset,
...     queue_length,
...     samples_per_volume,
...     sampler,
...     num_workers=4,
... )
>>> patches_loader = tio.SubjectsLoader(
...     patches_queue,
...     batch_size=16,
...     num_workers=0,  # this must be 0
... )
```

--------------------------------

### get_bounds()

Source: https://docs.torchio.org/data/image

Get minimum and maximum world coordinates occupied by the image.

```APIDOC
## `get_bounds()`

### Description
Get minimum and maximum world coordinates occupied by the image.
```

--------------------------------

### `get_center(lps=False)`

Source: https://docs.torchio.org/data/image

Get image center in RAS+ or LPS+ coordinates.

```APIDOC
## `get_center(lps=False)`

### Description
Get image center in RAS+ or LPS+ coordinates.

### Method
`get_center(lps=False)`

### Parameters
#### Query Parameters
- **lps** (bool) - Optional - If `True`, the coordinates will be in LPS+ orientation, i.e. the first dimension grows towards the left, etc. Otherwise, the coordinates will be in RAS+ orientation. Defaults to False.
```

--------------------------------

### Distributed Training with Queue and SubjectsLoader

Source: https://docs.torchio.org/patches/training

This snippet demonstrates setting up a distributed training loop using TorchIO's Queue and SubjectsLoader. It includes initialization of distributed samplers and loaders, and the main training loop structure. Ensure `num_workers` for SubjectsLoader is 0 when using a Queue.

```python
>>> # Usage with distributed training
>>> import torch.distributed as dist
>>> from torch.utils.data.distributed import DistributedSampler
>>> # Assume a process running on distributed node 3
>>> rank = 3
>>> patch_sampler = tio.data.UniformSampler(patch_size)
>>> subject = tio.datasets.Colin27()
>>> subjects_dataset = tio.SubjectsDataset(10 * [subject])
>>> subject_sampler = dist.DistributedSampler(
...     subjects_dataset,
...     rank=local_rank,
...     shuffle=True,
...     drop_last=True,
... )
>>> # Each process is assigned (len(subjects_dataset) // num_processes) subjects
>>> patches_queue = tio.Queue(
...     subjects_dataset,
...     queue_length,
...     samples_per_volume,
...     patch_sampler,
...     num_workers=4,
...     subject_sampler=subject_sampler,
... )
>>> patches_loader = tio.SubjectsLoader(
...     patches_queue,
...     batch_size=16,
...     num_workers=0,  # this must be 0
... )
>>> num_epochs = 2
>>> model = torch.nn.Identity()
>>> for epoch_index in range(num_epochs):
...     subject_sampler.set_epoch(epoch_index)
...     for patches_batch in patches_loader:
...         inputs = patches_batch['t1'][tio.DATA]
...         targets = patches_batch['brain'][tio.DATA]
...         logits = model(inputs)
```

--------------------------------

### show

Source: https://docs.torchio.org/data/image

Opens the image using external viewing software. If no viewer path is specified, it attempts to use environment variables or default viewers like ITK-SNAP.

```APIDOC
## show(viewer_path=None)

### Description
Open the image using external software.

### Parameters
#### Path Parameters
- **viewer_path** (TypePath | None) - Optional - Path to the application used to view the image. If `None`, the value of the environment variable `SITK_SHOW_COMMAND` will be used. If this variable is also not set, TorchIO will try to guess the location of ITK-SNAP and 3D Slicer. Default: None

### Raises
- **RuntimeError** - If the viewer is not found.
```

--------------------------------

### EnsureShapeMultiple Cropping Example

Source: https://docs.torchio.org/transforms/preprocessing/EnsureShapeMultiple

Crops an image to ensure its dimensions are multiples of 8.

```python
>>> import torchio as tio
>>> image = tio.datasets.Colin27().t1
>>> image.shape
(1, 181, 217, 181)
>>> transform = tio.EnsureShapeMultiple(8, method='crop')
>>> transformed = transform(image)
>>> transformed.shape
(1, 176, 216, 176)
```

--------------------------------

### EnsureShapeMultiple Padding Example

Source: https://docs.torchio.org/transforms/preprocessing/EnsureShapeMultiple

Pads an image to ensure its dimensions are multiples of 8.

```python
>>> import torchio as tio
>>> image = tio.datasets.Colin27().t1
>>> image.shape
(1, 181, 217, 181)
>>> transform = tio.EnsureShapeMultiple(8, method='pad')
>>> transformed = transform(image)
>>> transformed.shape
(1, 184, 224, 184)
```

--------------------------------

### Create a Subject with Images and Metadata

Source: https://docs.torchio.org/data/subject

Instantiate a Subject by passing image objects and metadata as keyword arguments or from a dictionary. Ensure image paths are valid.

```python
>>> import torchio as tio
>>> # One way:
>>> subject = tio.Subject(
...     one_image=tio.ScalarImage('path_to_image.nii.gz'),
...     a_segmentation=tio.LabelMap('path_to_seg.nii.gz'),
...     age=45,
...     name='John Doe',
...     hospital='Hospital Juan Negrín',
... )
>>> # If you want to create the mapping before, or have spaces in the keys:
>>> subject_dict = {
...     'one image': tio.ScalarImage('path_to_image.nii.gz'),
...     'a segmentation': tio.LabelMap('path_to_seg.nii.gz'),
...     'age': 45,
...     'name': 'John Doe',
...     'hospital': 'Hospital Juan Negrín',
... }
>>> subject = tio.Subject(subject_dict)
```

--------------------------------

### Get a Specific Image from Subject

Source: https://docs.torchio.org/data/subject

Retrieve a single image from the subject by its assigned name.

```python
>>> subject.get_image('one_image')
```

--------------------------------

### `as_pil(transpose=True)`

Source: https://docs.torchio.org/data/image

Get the image as an instance of PIL.Image. Values will be clamped to 0-255 and cast to uint8.

```APIDOC
## `as_pil(transpose=True)`

### Description
Get the image as an instance of [PIL.Image][].
Note
Values will be clamped to 0-255 and cast to uint8.
Note
To use this method, Pillow needs to be installed: `pip install Pillow`.

### Method
`as_pil(transpose=True)`

### Parameters
#### Query Parameters
- **transpose** (bool) - Optional - Whether to transpose the image. Defaults to True.

```

--------------------------------

### Initialize and Apply RandomAffine Transform

Source: https://docs.torchio.org/transforms/augmentation/RandomAffine

Demonstrates how to initialize a RandomAffine transform with specified scales and degrees, and then apply it to a TorchIO image. This is useful for data augmentation by introducing spatial variations.

```python
import torchio as tio
image = tio.datasets.Colin27().t1
transform = tio.RandomAffine(
    scales=(0.9, 1.2),
    degrees=15,
)
transformed = transform(image)
```

--------------------------------

### EnsureShapeMultiple Cropping 2D Example

Source: https://docs.torchio.org/transforms/preprocessing/EnsureShapeMultiple

Crops a 2D image slice to ensure its dimensions are multiples of 8.

```python
>>> import torchio as tio
>>> image = tio.datasets.Colin27().t1
>>> image_2d = image.data[..., :1]
>>> image_2d.shape
torch.Size([1, 181, 217, 1])
>>> transform = tio.EnsureShapeMultiple(8, method='crop')
>>> transformed = transform(image_2d)
>>> transformed.shape
torch.Size([1, 176, 216, 1])
```

--------------------------------

### Initialize HistogramStandardization with Landmark File Path

Source: https://docs.torchio.org/transforms/preprocessing/HistogramStandardization

Initialize the HistogramStandardization transform using a path to a PyTorch file containing saved landmarks. The file should contain a dictionary with image names as keys and landmark paths as values.

```python
>>> import torch
>>> import torchio as tio
>>> landmarks = {
...     't1': 't1_landmarks.npy',
...     't2': 't2_landmarks.npy',
... }
>>> torch.save(landmarks, 'path_to_landmarks.pth')
>>> transform = tio.HistogramStandardization('path_to_landmarks.pth')
```

--------------------------------

### Get Subject Shape

Source: https://docs.torchio.org/data/subject

Access the shape of the first image in the subject. This checks for shape consistency across all images.

```python
>>> import torchio as tio
>>> colin = tio.datasets.Colin27()
>>> colin.shape
(1, 181, 217, 181)
```

--------------------------------

### `to_video(output_path, frame_rate=15, seconds=None, direction='I', verbosity='error')`

Source: https://docs.torchio.org/data/image

Create a video showing all image slices along a specified direction.

```APIDOC
## `to_video(output_path, frame_rate=15, seconds=None, direction='I', verbosity='error')`

### Description
Create a video showing all image slices along a specified direction.
Note
Only `frame_rate` or `seconds` may (and must) be specified.

### Method
`to_video(output_path, frame_rate=15, seconds=None, direction='I', verbosity='error')`

### Parameters
#### Path Parameters
- **output_path** (TypePath) - Required - Path to the output video file.
#### Query Parameters
- **frame_rate** (float | None) - Optional - Number of frames per second (FPS). Defaults to 15.
- **seconds** (float | None) - Optional - Target duration of the full video.
- **direction** (str) - Optional - Defaults to 'I'.
- **verbosity** (str) - Optional - Defaults to 'error'.
```

--------------------------------

### as_pil

Source: https://docs.torchio.org/data/image

Converts the image to a PIL Image object. Values are clamped to 0-255 and cast to uint8. Pillow must be installed.

```APIDOC
## as_pil(transpose=True)

### Description
Get the image as an instance of [PIL.Image][].

### Parameters
#### Path Parameters
- **transpose** (bool) - Optional - Whether to transpose the image. Default: True

### Notes
Values will be clamped to 0-255 and cast to uint8.
To use this method, Pillow needs to be installed: `pip install Pillow`.
```

--------------------------------

### as_sitk

Source: https://docs.torchio.org/data/image

Converts the TorchIO image to a SimpleITK Image object.

```APIDOC
## as_sitk(**kwargs)

### Description
Get the image as an instance of [sitk.Image][].
```

--------------------------------

### Initialize RandomLabelsToImage with Default Parameters

Source: https://docs.torchio.org/transforms/augmentation/RandomLabelsToImage

Use this snippet to create a RandomLabelsToImage transform with default settings. It requires specifying the key for the label map.

```python
import torchio as tio

subject = tio.datasets.ICBM2009CNonlinearSymmetric()
# Using the default parameters
transform = tio.RandomLabelsToImage(label_key='tissues')
```

--------------------------------

### Get Subject Spacing

Source: https://docs.torchio.org/data/subject

Obtain the voxel spacing of the first image. The method ensures that all images in the subject share consistent spacing.

```python
>>> import torchio as tio
>>> colin = tio.datasets.Slicer()
>>> colin.spacing
(1.0, 1.0, 1.2999954223632812)
```

--------------------------------

### Get Subject Spatial Shape

Source: https://docs.torchio.org/data/subject

Retrieve the spatial dimensions (height, width, depth) of the first image. Consistency is verified across all images.

```python
>>> import torchio as tio
>>> colin = tio.datasets.Colin27()
>>> colin.spatial_shape
(181, 217, 181)
```

--------------------------------

### show(viewer_path=None)

Source: https://docs.torchio.org/data/image

Opens the image using an external viewer application. You can specify the path to the viewer, or let TorchIO use an environment variable or attempt to find a default viewer.

```APIDOC
## `show(viewer_path=None)`

Open the image using external software.

Parameters:
Name | Type | Description | Default
---|---|---|---
`viewer_path` | `TypePath | None` | Path to the application used to view the image. If `None`, the value of the environment variable `SITK_SHOW_COMMAND` will be used. If this variable is also not set, TorchIO will try to guess the location of ITK-SNAP and 3D Slicer. | `None`

Raises:
Type | Description
---|---
`RuntimeError` | If the viewer is not found.
```

--------------------------------

### load()

Source: https://docs.torchio.org/data/image

Load the image from disk.

```APIDOC
## `load()`

### Description
Load the image from disk.

### Returns
- **Tuple** - Tuple containing a 4D tensor of size (C,W,H,D) and a 2D 4x4 affine matrix to convert voxel indices to world coordinates.
```

--------------------------------

### Clamp Transform Initialization and Usage

Source: https://docs.torchio.org/transforms/preprocessing/Clamp

This snippet shows how to initialize the Clamp transform with minimum and maximum output values and apply it to an image.

```APIDOC
## Clamp

### Description
Clamp intensity values into a range [a,b]. For more information, see `torch.clamp()`.

### Parameters
#### Initialization Parameters
- **out_min** (`float | None`) - Optional - Minimum value a of the output image. If `None`, the minimum of the image is used. Default: `None`
- **out_max** (`float | None`) - Optional - Maximum value b of the output image. If `None`, the maximum of the image is used. Default: `None`

### Method
`__call__`

### Description
Transform data and return a result of the same type.

### Parameters
#### Path Parameters
- **data** (`TypeTransformInput`) - Required - Instance of `torchio.Subject`, 4D `torch.Tensor` or `numpy.ndarray` with dimensions (C,W,H,D), where C is the number of channels and W,H,D are the spatial dimensions. If the input is a tensor, the affine matrix will be set to identity. Other valid input types are a SimpleITK image, a `torchio.Image`, a NiBabel Nifti1 image or a `dict`. The output type is the same as the input type.

### Request Example
```python
import torchio as tio

ct = tio.datasets.Slicer('CTChest').CT_chest
HOUNSFIELD_AIR, HOUNSFIELD_BONE = -1000, 1000
clamp = tio.Clamp(out_min=HOUNSFIELD_AIR, out_max=HOUNSFIELD_BONE)
ct_clamped = clamp(ct)
```
```

--------------------------------

### Get Subject Spacing

Source: https://docs.torchio.org/datasets

Retrieves the spacing of the first image in a subject. This property ensures that the spacings are consistent across all images in the subject before returning the value.

```python
>>> import torchio as tio
>>> colin = tio.datasets.Slicer()
>>> colin.spacing
(1.0, 1.0, 1.2999954223632812)

```
Tokens:
Raw