Getting started
===============
Installation
------------
The Python package is hosted on the
`Python Package Index (PyPI) `_.
To install the latest PyTorch version before installing TorchIO, it is
recommended to use `light-the-torch `_::
$ pip install light-the-torch && ltt install torch
The latest published version of TorchIO can be installed using Pip Installs
Packages (``pip``)::
$ pip install torchio
To upgrade to the latest published version, use::
$ pip install --upgrade torchio
If you would like to install Matplotlib to use the plotting features, use::
$ pip install torchio[plot]
If you are on Windows and have
`trouble installing TorchIO `_,
try `installing PyTorch `_ with
`conda `_ before pip-installing
TorchIO.
Hello, World!
-------------
This example shows the basic usage of TorchIO, where an instance of
:class:`~torchio.SubjectsDataset` is passed to
a PyTorch :class:`~torch.SubjectsLoader` to generate training batches
of 3D images that are loaded, preprocessed and augmented on the fly,
in parallel::
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',
)
# 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',
)
# 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',
)
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]
Tutorials
---------
|Google-Colab-notebook|
The best way to quickly understand and try the library is the
`Jupyter Notebooks `_
hosted on Google Colab.
They include multiple examples and visualization of most of the classes,
including training of a `3D U-Net `_ for
brain segmentation on :math:`T_1`-weighted MRI with full volumes and
with subvolumes (aka patches or windows).
.. |Google-Colab-notebook| image:: https://colab.research.google.com/assets/colab-badge.svg
:target: https://github.com/fepegar/torchio/blob/main/tutorials/README.md
:alt: Google Colab notebook