0
# Utilities and Constants
1

2
Helper functions, type definitions, and constants for medical image processing, including file I/O utilities, type conversion functions, command-line tools, and medical imaging constants that support TorchIO's core functionality.
3

4
## Capabilities
5

6
### Type Conversion and Validation
7

8
Utility functions for converting and validating data types commonly used in medical image processing.
9

10
```python { .api }
11
def to_tuple(value: Any, length: int = 1) -> tuple[TypeNumber, ...]:
12
    """
13
    Convert variable to tuple of specified length.
14
    
15
    If value is iterable, length is ignored and tuple(value) is returned.
16
    If value is scalar, it's repeated length times.
17
    
18
    Parameters:
19
    - value: Value to convert to tuple
20
    - length: Target tuple length
21
    
22
    Returns:
23
    Tuple of specified length
24
    
25
    Examples:
26
    >>> to_tuple(1, length=3)
27
    (1, 1, 1)
28
    >>> to_tuple([1, 2], length=3)
29
    (1, 2)
30
    """
31

32
def check_sequence(sequence: Sequence, name: str) -> None:
33
    """
34
    Validate sequence parameters.
35
    
36
    Parameters:
37
    - sequence: Sequence to validate
38
    - name: Name for error messages
39
    
40
    Raises:
41
    ValueError: If sequence is invalid
42
    """
43

44
def is_iterable(object: Any) -> bool:
45
    """
46
    Check if object is iterable.
47
    
48
    Parameters:
49
    - object: Object to check
50
    
51
    Returns:
52
    True if object is iterable, False otherwise
53
    """
54

55
def parse_spatial_shape(shape) -> tuple[int, int, int]:
56
    """
57
    Parse spatial shape specification into 3D tuple.
58
    
59
    Parameters:
60
    - shape: Shape specification (int or sequence of ints)
61
    
62
    Returns:
63
    3D spatial shape tuple
64
    """
65

66
def guess_type(string: str) -> Any:
67
    """
68
    Guess variable type from string representation.
69
    
70
    Attempts to convert string to appropriate Python type
71
    (int, float, bool, None, or keeps as string).
72
    
73
    Parameters:
74
    - string: String to parse
75
    
76
    Returns:
77
    Parsed value with appropriate type
78
    """
79
```
80

81
### File and Path Operations
82

83
Functions for handling file paths, stems, and compression operations commonly needed in medical imaging workflows.
84

85
```python { .api }
86
def get_stem(path: TypePath) -> str:
87
    """
88
    Extract file stem from path (filename without extension).
89
    
90
    Handles complex medical imaging extensions like .nii.gz
91
    
92
    Parameters:
93
    - path: File path
94
    
95
    Returns:
96
    File stem without extensions
97
    
98
    Examples:
99
    >>> get_stem('image.nii.gz')
100
    'image'
101
    >>> get_stem('/path/to/scan.dcm')
102
    'scan'
103
    """
104

105
def normalize_path(path: TypePath) -> Path:
106
    """
107
    Normalize file path to Path object.
108
    
109
    Parameters:
110
    - path: Path as string or Path object
111
    
112
    Returns:
113
    Normalized Path object
114
    """
115

116
def get_torchio_cache_dir() -> Path:
117
    """
118
    Get TorchIO cache directory for temporary files.
119
    
120
    Returns platform-appropriate cache directory for TorchIO,
121
    creating it if it doesn't exist.
122
    
123
    Returns:
124
    Path to TorchIO cache directory
125
    """
126

127
def compress(
128
    input_path: TypePath,
129
    output_path: TypePath = None
130
) -> Path:
131
    """
132
    Compress file using gzip compression.
133
    
134
    Parameters:
135
    - input_path: Path to file to compress
136
    - output_path: Output path (optional, defaults to input_path + '.gz')
137
    
138
    Returns:
139
    Path to compressed file
140
    """
141
```
142

143
### Dataset and Data Operations
144

145
Utility functions for creating datasets, applying transforms to files, and managing data operations.
146

147
```python { .api }
148
def create_dummy_dataset(
149
    num_subjects: int,
150
    size_range: tuple[int, int] = (10, 20),
151
    directory: Path = None,
152
    random_seed: int = 42,
153
    **kwargs
154
) -> SubjectsDataset:
155
    """
156
    Create dummy dataset for testing and development.
157
    
158
    Generates synthetic medical imaging data with realistic
159
    structure for testing transforms and training loops.
160
    
161
    Parameters:
162
    - num_subjects: Number of subjects to create
163
    - size_range: Range of image sizes (min, max)
164
    - directory: Directory to save dummy images (None for temporary)
165
    - random_seed: Random seed for reproducibility
166
    
167
    Returns:
168
    SubjectsDataset with dummy subjects
169
    """
170

171
def apply_transform_to_file(
172
    transform: 'Transform',
173
    input_path: TypePath,
174
    output_path: TypePath,
175
    verbose: bool = False
176
) -> None:
177
    """
178
    Apply transform to image file and save result.
179
    
180
    Loads image from input_path, applies transform, and saves
181
    to output_path. Useful for batch processing of images.
182
    
183
    Parameters:
184
    - transform: Transform to apply
185
    - input_path: Path to input image
186
    - output_path: Path to save transformed image
187
    - verbose: Whether to print progress information
188
    """
189
```
190

191
### Batch Processing Utilities
192

193
Functions for handling batched medical image data and extracting information from data loaders.
194

195
```python { .api }
196
def history_collate(batch: Sequence, collate_transforms: bool = True) -> dict:
197
    """
198
    Custom collate function that preserves transform history.
199
    
200
    Parameters:
201
    - batch: Sequence of Subject instances
202
    - collate_transforms: Whether to collate transform histories
203
    
204
    Returns:
205
    Collated batch dictionary with preserved metadata
206
    """
207

208
def get_first_item(data_loader: torch.utils.data.DataLoader):
209
    """
210
    Get first item from data loader for inspection.
211
    
212
    Useful for debugging data loading pipelines and
213
    inspecting batch structure.
214
    
215
    Parameters:
216
    - data_loader: DataLoader to get item from
217
    
218
    Returns:
219
    First item from data loader
220
    """
221

222
def get_batch_images_and_size(batch: dict) -> tuple[list[str], int]:
223
    """
224
    Extract image names and batch size from batch.
225
    
226
    Parameters:
227
    - batch: Batch dictionary from TorchIO data loader
228
    
229
    Returns:
230
    Tuple of (list of image names, batch size)
231
    """
232

233
def get_subjects_from_batch(batch: dict) -> list:
234
    """
235
    Extract individual subjects from batched data.
236
    
237
    Reconstructs Subject instances from collated batch data.
238
    
239
    Parameters:
240
    - batch: Batched data dictionary
241
    
242
    Returns:
243
    List of Subject instances
244
    """
245

246
def add_images_from_batch(
247
    images_dict: dict,
248
    batch: dict,
249
    batch_idx: int
250
) -> None:
251
    """
252
    Add images from batch to images dictionary.
253
    
254
    Parameters:
255
    - images_dict: Dictionary to add images to
256
    - batch: Batch containing images
257
    - batch_idx: Index of current batch
258
    """
259
```
260

261
### System and Compatibility
262

263
Functions for system compatibility checks and introspection.
264

265
```python { .api }
266
def get_major_sitk_version() -> int:
267
    """
268
    Get major version of SimpleITK library.
269
    
270
    Returns:
271
    Major version number of installed SimpleITK
272
    """
273

274
def get_subclasses(target_class: type) -> list[type]:
275
    """
276
    Get all subclasses of a class recursively.
277
    
278
    Parameters:
279
    - target_class: Class to find subclasses of
280
    
281
    Returns:
282
    List of all subclasses (direct and indirect)
283
    """
284

285
def guess_external_viewer() -> Path | None:
286
    """
287
    Guess external image viewer application.
288
    
289
    Attempts to find suitable medical image viewer
290
    on the current system (ITK-SNAP, 3D Slicer, etc.).
291
    
292
    Returns:
293
    Path to viewer executable, or None if not found
294
    """
295
```
296

297
### Type Definitions
298

299
Comprehensive type definitions for medical image processing, providing type hints and validation for TorchIO operations.
300

301
```python { .api }
302
# Path and basic types
303
TypePath = Union[str, Path]
304
TypeNumber = Union[int, float]
305
TypeKeys = Optional[Sequence[str]]
306

307
# Data types
308
TypeData = Union[torch.Tensor, np.ndarray]
309
TypeDataAffine = tuple[torch.Tensor, np.ndarray]
310
TypeSlice = Union[int, slice]
311

312
# Geometric types
313
TypeDoubletInt = tuple[int, int]
314
TypeTripletInt = tuple[int, int, int]
315
TypeQuartetInt = tuple[int, int, int, int]
316
TypeSextetInt = tuple[int, int, int, int, int, int]
317

318
TypeDoubleFloat = tuple[float, float]
319
TypeTripletFloat = tuple[float, float, float]
320
TypeQuartetFloat = tuple[float, float, float, float]
321
TypeSextetFloat = tuple[float, float, float, float, float, float]
322

323
# Spatial types
324
TypeTuple = Union[int, TypeTripletInt]
325
TypeRangeInt = Union[int, TypeDoubletInt]
326
TypeSpatialShape = Union[int, TypeTripletInt]
327
TypeSpacing = Union[float, TypeTripletFloat]
328
TypeRangeFloat = Union[float, TypeDoubleFloat]
329

330
# Direction cosine matrices
331
TypeDirection2D = TypeQuartetFloat
332
TypeDirection3D = tuple[
333
    float, float, float,
334
    float, float, float,
335
    float, float, float,
336
]
337
TypeDirection = Union[TypeDirection2D, TypeDirection3D]
338

339
# Functional types
340
TypeCallable = Callable[[torch.Tensor], torch.Tensor]
341
```
342

343
### Constants
344

345
Essential constants used throughout TorchIO for consistent behavior and standardization.
346

347
```python { .api }
348
# Image type constants
349
INTENSITY = 'intensity'          # For scalar/intensity images
350
LABEL = 'label'                  # For segmentation/label images
351
SAMPLING_MAP = 'sampling_map'    # For sampling probability maps
352

353
# Dictionary keys for subject data
354
PATH = 'path'                    # File path key
355
TYPE = 'type'                    # Image type key
356
STEM = 'stem'                    # File stem key
357
DATA = 'data'                    # Image data key
358
AFFINE = 'affine'               # Affine matrix key
359
TENSOR = 'tensor'               # Tensor data key
360

361
# Aggregator and queue keys
362
IMAGE = 'image'                  # Image key for aggregator
363
LOCATION = 'location'            # Location key for aggregator
364
HISTORY = 'history'              # Transform history key
365
NUM_SAMPLES = 'num_samples'      # Queue samples key
366

367
# Technical constants
368
CHANNELS_DIMENSION = 1           # PyTorch channel dimension index
369
MIN_FLOAT_32 = torch.finfo(torch.float32).eps  # Float32 epsilon
370

371
# Repository URLs
372
REPO_URL = 'https://github.com/TorchIO-project/torchio/'
373
DATA_REPO = 'https://github.com/TorchIO-project/torchio-data/raw/main/data/'
374
```
375

376
### Command Line Interface
377

378
TorchIO provides command-line tools for common medical image processing tasks.
379

380
```python { .api }
381
# CLI applications (available as shell commands after pip install)
382
# tiohd - Print image information
383
# tiotr - Apply transforms
384
# torchio-transform - Apply transforms (alias)
385
```
386

387
Command-line usage examples:
388

389
```bash
390
# Print image information
391
tiohd image.nii.gz
392

393
# Apply transform to image
394
tiotr input.nii.gz output.nii.gz --transform RandomFlip
395

396
# Apply multiple transforms
397
tiotr input.nii.gz output.nii.gz \
398
    --transform ToCanonical \
399
    --transform "Resample(1)" \
400
    --transform "RandomAffine(degrees=5)"
401
```
402

403
### Download and File Management
404

405
Utilities for downloading datasets and managing file integrity.
406

407
```python { .api }
408
def calculate_md5(fpath: TypePath, chunk_size: int = 1024 * 1024) -> str:
409
    """Calculate MD5 hash of file"""
410

411
def check_md5(fpath: TypePath, md5: str, **kwargs) -> bool:
412
    """Verify MD5 hash of file"""
413

414
def check_integrity(fpath: TypePath, md5: str = None) -> bool:
415
    """Check file exists and optionally verify MD5"""
416

417
def download_url(
418
    url: str,
419
    root: TypePath,
420
    filename: str = None,
421
    md5: str = None
422
) -> None:
423
    """Download file from URL with progress bar and integrity checking"""
424

425
def extract_archive(
426
    from_path: TypePath,
427
    to_path: TypePath = None,
428
    remove_finished: bool = False
429
) -> None:
430
    """Extract compressed archive (zip, tar, tar.gz, etc.)"""
431
```
432

433
### Usage Examples
434

435
#### Creating Test Data
436

437
```python
438
import torchio as tio
439
from pathlib import Path
440

441
# Create dummy dataset for testing
442
dummy_dataset = tio.utils.create_dummy_dataset(
443
    num_subjects=10,
444
    size_range=(32, 48),
445
    directory=Path('./test_data'),
446
    random_seed=42
447
)
448

449
print(f"Created {len(dummy_dataset)} dummy subjects")
450

451
# Use for testing transforms
452
test_transform = tio.Compose([
453
    tio.RandomFlip(),
454
    tio.RandomAffine(degrees=5),
455
    tio.RandomNoise(std=0.1),
456
])
457

458
dummy_dataset.set_transform(test_transform)
459
```
460

461
#### Batch Processing Files
462

463
```python
464
# Apply transform to multiple files
465
transform = tio.Compose([
466
    tio.ToCanonical(),
467
    tio.Resample(1),
468
    tio.ZNormalization(),
469
])
470

471
input_files = Path('./input').glob('*.nii.gz')
472
output_dir = Path('./processed')
473
output_dir.mkdir(exist_ok=True)
474

475
for input_file in input_files:
476
    output_file = output_dir / input_file.name
477
    tio.utils.apply_transform_to_file(
478
        transform=transform,
479
        input_path=input_file,
480
        output_path=output_file,
481
        verbose=True
482
    )
483
```
484

485
#### Working with Batches
486

487
```python
488
# Inspect data loader batches
489
dataset = tio.SubjectsDataset([...])  # Your subjects
490
loader = tio.SubjectsLoader(dataset, batch_size=4)
491

492
# Get first batch for inspection
493
first_batch = tio.utils.get_first_item(loader)
494

495
# Extract batch information
496
image_names, batch_size = tio.utils.get_batch_images_and_size(first_batch)
497
print(f"Batch contains {batch_size} subjects with images: {image_names}")
498

499
# Reconstruct individual subjects from batch
500
subjects = tio.utils.get_subjects_from_batch(first_batch)
501
print(f"Reconstructed {len(subjects)} subjects from batch")
502
```