0
# Core Data Structures
1

2
Essential data structures for handling medical images in TorchIO, providing the foundation for medical image processing workflows. These classes handle image loading, metadata management, and provide the base for all TorchIO operations.
3

4
## Capabilities
5

6
### Subject Container
7

8
A dictionary-like container that stores multiple medical images and metadata for a single patient or case. The Subject class is the primary data structure in TorchIO, organizing related images (T1, T2, segmentations, etc.) and their associated information.
9

10
```python { .api }
11
class Subject(dict):
12
    """
13
    Dictionary-like container for storing medical images and metadata.
14
    
15
    Parameters:
16
    - *args: If provided, a dictionary of items
17
    - **kwargs: Items that will be added to the subject sample
18
    """
19
    def __init__(self, *args, **kwargs: dict[str, Any]): ...
20
    
21
    def get_images(self, intensity_only: bool = True) -> list[Image]:
22
        """
23
        Get list of images in the subject.
24
        
25
        Parameters:
26
        - intensity_only: If True, only return intensity images (not label maps)
27
        
28
        Returns:
29
        List of Image objects
30
        """
31
    
32
    def check_consistent_spatial_shape(self):
33
        """Check all images have the same spatial shape"""
34
    
35
    def check_consistent_orientation(self):
36
        """Check all images have the same orientation"""
37
    
38
    def check_consistent_space(self):
39
        """Check all images are in the same physical space"""
40
    
41
    @property
42
    def shape(self) -> tuple[int, int, int, int]:
43
        """Return shape of first image in subject (channels, depth, height, width)"""
44
    
45
    @property
46
    def spatial_shape(self) -> tuple[int, int, int]:
47
        """Return spatial shape (depth, height, width)"""
48
    
49
    @property
50
    def spacing(self) -> tuple[float, float, float]:
51
        """Return voxel spacing in mm"""
52
    
53
    def apply_transform(self, transform: 'Transform') -> 'Subject':
54
        """Apply a transform to the subject"""
55
    
56
    def plot(self, **kwargs):
57
        """Plot all images in the subject"""
58
    
59
    def load(self):
60
        """Load all images in the subject into memory"""
61
```
62

63
Usage example:
64

65
```python
66
import torchio as tio
67

68
# Create a subject with multiple images and metadata
69
subject = tio.Subject(
70
    t1=tio.ScalarImage('path/to/t1.nii.gz'),
71
    t2=tio.ScalarImage('path/to/t2.nii.gz'),
72
    flair=tio.ScalarImage('path/to/flair.nii.gz'),
73
    seg=tio.LabelMap('path/to/segmentation.nii.gz'),
74
    age=67,
75
    sex='M',
76
    diagnosis='healthy'
77
)
78

79
# Access images and metadata
80
t1_image = subject['t1']
81
age = subject['age']
82

83
# Get all intensity images
84
intensity_images = subject.get_images(intensity_only=True)
85

86
# Check spatial consistency
87
subject.check_consistent_spatial_shape()
88
```
89

90
### Base Image Class
91

92
Abstract base class for all medical images in TorchIO, providing common functionality for image loading, data access, and spatial information management.
93

94
```python { .api }
95
class Image:
96
    """
97
    Base class for medical images.
98
    
99
    Parameters:
100
    - path: Path to the image file
101
    - type: Type of image ('intensity' or 'label')
102
    - **kwargs: Additional keyword arguments
103
    """
104
    def __init__(self, path: TypePath, type: str = None, **kwargs): ...
105
    
106
    @property
107
    def data(self) -> torch.Tensor:
108
        """Image data as PyTorch tensor with shape (C, D, H, W)"""
109
    
110
    @property
111
    def affine(self) -> np.ndarray:
112
        """4x4 affine transformation matrix from voxel to world coordinates"""
113
    
114
    @property
115
    def shape(self) -> tuple[int, int, int, int]:
116
        """Image shape (channels, depth, height, width)"""
117
    
118
    @property
119
    def spatial_shape(self) -> tuple[int, int, int]:
120
        """Spatial shape (depth, height, width)"""
121
    
122
    @property
123
    def spacing(self) -> tuple[float, float, float]:
124
        """Voxel spacing in mm (depth, height, width)"""
125
    
126
    @property
127
    def origin(self) -> tuple[float, float, float]:
128
        """Image origin in world coordinates"""
129
    
130
    @property
131
    def orientation(self) -> tuple[str, str, str]:
132
        """Image orientation (e.g., ('L', 'A', 'S'))"""
133
    
134
    def get_center(self, lps: bool = False) -> tuple[float, float, float]:
135
        """Get center coordinates of the image"""
136
    
137
    def save(self, path: TypePath):
138
        """Save image to file"""
139
    
140
    def plot(self, **kwargs):
141
        """Plot image using matplotlib"""
142
    
143
    def show(self, **kwargs):
144
        """Show image using external viewer"""
145
    
146
    def as_pil(self) -> 'PIL.Image':
147
        """Convert to PIL Image (for 2D images)"""
148
    
149
    def as_sitk(self) -> 'sitk.Image':
150
        """Convert to SimpleITK Image"""
151
    
152
    def to_gif(self, output_path: TypePath, **kwargs):
153
        """Save image as animated GIF"""
154
    
155
    def __getitem__(self, item) -> 'Image':
156
        """Support indexing and slicing"""
157
```
158

159
### Scalar Image
160

161
Represents intensity or scalar medical images such as MRI, CT scans, PET scans, and other quantitative imaging modalities.
162

163
```python { .api }
164
class ScalarImage(Image):
165
    """
166
    Represents intensity/scalar medical images (e.g., MRI, CT scans).
167
    Inherits all functionality from Image class.
168
    
169
    Default type: 'intensity'
170
    """
171
    def __init__(self, path: TypePath, **kwargs): ...
172
```
173

174
Usage example:
175

176
```python
177
# Load different types of scalar images
178
t1_image = tio.ScalarImage('t1_weighted.nii.gz')
179
ct_image = tio.ScalarImage('ct_scan.nii.gz')
180
pet_image = tio.ScalarImage('pet_scan.nii.gz')
181

182
# Access image properties
183
print(f"T1 shape: {t1_image.shape}")
184
print(f"T1 spacing: {t1_image.spacing}")
185
print(f"T1 origin: {t1_image.origin}")
186

187
# Access image data
188
t1_data = t1_image.data  # torch.Tensor with shape (1, D, H, W)
189
```
190

191
### Label Map
192

193
Represents segmentation or label images where each voxel contains a discrete label value indicating tissue type, anatomical structure, or pathological region.
194

195
```python { .api }
196
class LabelMap(ScalarImage):
197
    """
198
    Represents segmentation/label images.
199
    Inherits from ScalarImage but optimized for discrete label values.
200
    
201
    Default type: 'label'
202
    """
203
    def __init__(self, path: TypePath, **kwargs): ...
204
    
205
    def get_unique_labels(self) -> list[int]:
206
        """Get list of unique label values in the image"""
207
    
208
    def get_label_statistics(self) -> dict:
209
        """Get statistics for each label (volume, centroid, etc.)"""
210
```
211

212
Usage example:
213

214
```python
215
# Load segmentation image
216
segmentation = tio.LabelMap('brain_segmentation.nii.gz')
217

218
# Get unique labels
219
labels = segmentation.get_unique_labels()
220
print(f"Segmentation contains labels: {labels}")
221

222
# Access label statistics
223
stats = segmentation.get_label_statistics()
224
```
225

226
### Dataset Management
227

228
PyTorch-compatible dataset class for managing collections of subjects with optional transforms.
229

230
```python { .api }
231
class SubjectsDataset(torch.utils.data.Dataset):
232
    """
233
    PyTorch Dataset for loading multiple subjects with transforms.
234
    
235
    Parameters:
236
    - subjects: Sequence of Subject instances
237
    - transform: Optional transform to apply to each subject
238
    - load_getitem: If True, load images when __getitem__ is called
239
    """
240
    def __init__(
241
        self,
242
        subjects: Sequence[Subject],
243
        transform: Transform = None,
244
        load_getitem: bool = True
245
    ): ...
246
    
247
    def __len__(self) -> int:
248
        """Return number of subjects"""
249
    
250
    def __getitem__(self, index: int) -> Subject:
251
        """Get subject at index, applying transform if specified"""
252
    
253
    def dry_iter(self):
254
        """Iterate through subjects without loading image data"""
255
    
256
    def set_transform(self, transform: Transform):
257
        """Set or update the transform"""
258
```
259

260
Usage example:
261

262
```python
263
# Create subjects
264
subjects = [
265
    tio.Subject(
266
        t1=tio.ScalarImage(f'subject_{i}_t1.nii.gz'),
267
        seg=tio.LabelMap(f'subject_{i}_seg.nii.gz'),
268
        age=ages[i]
269
    )
270
    for i in range(100)
271
]
272

273
# Create dataset with preprocessing transform
274
preprocessing = tio.Compose([
275
    tio.ToCanonical(),
276
    tio.Resample(1),  # 1mm isotropic
277
    tio.CropOrPad((128, 128, 64)),
278
    tio.ZNormalization(),
279
])
280

281
dataset = tio.SubjectsDataset(subjects, transform=preprocessing)
282

283
# Use with PyTorch DataLoader
284
loader = torch.utils.data.DataLoader(dataset, batch_size=4, shuffle=True)
285

286
for batch in loader:
287
    # Process batch of subjects
288
    pass
289
```