0
# Medical Imaging
1

2
Specialized tools for working with DICOM (Digital Imaging and Communications in Medicine) files, the de-facto standard for medical imaging data. This module extends fastai's vision capabilities specifically for medical image processing workflows including CT scans, MRI, X-rays, and other medical imaging modalities.
3

4
## Capabilities
5

6
### DICOM File Operations
7

8
Loading and accessing DICOM files with proper metadata handling and format support.
9

10
```python { .api }
11
def get_dicom_files(path, recurse=True, folders=None):
12
    """
13
    Get DICOM files in path recursively, optionally filtering by folders.
14
    
15
    Parameters:
16
    - path: Directory path to search
17
    - recurse: Whether to search subdirectories (default: True)  
18
    - folders: List of specific folder names to search in (optional)
19
    
20
    Returns:
21
    List of DICOM file paths
22
    """
23

24
def dcmread(fn, force=False):
25
    """
26
    Open a DICOM file using pydicom.
27
    
28
    Parameters:
29
    - fn: Path to DICOM file
30
    - force: Force reading even if file appears corrupted
31
    
32
    Returns:
33
    DcmDataset object with enhanced functionality
34
    """
35
```
36

37
### DICOM Data Access
38

39
Accessing and converting DICOM pixel data with proper scaling and normalization.
40

41
```python { .api }
42
# Properties for DcmDataset objects
43
@property
44
def pixels(self):
45
    """Get pixel_array as a float32 tensor."""
46

47
@property  
48
def scaled_px(self):
49
    """Get pixels scaled by RescaleSlope and RescaleIntercept DICOM tags."""
50

51
@property
52
def shape(self):
53
    """Returns the shape of a DICOM image as (rows, columns)."""
54
```
55

56
### Medical Image Classes
57

58
Specialized tensor and PIL classes optimized for medical imaging display and processing.
59

60
```python { .api }
61
class TensorDicom(TensorImage):
62
    """Tensor representation of DICOM images with grayscale display defaults."""
63

64
class PILDicom(PILBase):
65
    """PIL-based DICOM image loader with custom creation methods."""
66

67
class TensorCTScan(TensorImageBW):
68
    """Specialized tensor for CT scan data with bone colormap."""
69

70
class PILCTScan(PILBase):
71
    """PIL-based CT scan image loader."""
72
```
73

74
### Medical Windowing
75

76
Medical windowing operations for contrast and brightness adjustment using standard anatomical windows.
77

78
```python { .api }
79
def windowed(self, w, l):
80
    """
81
    Scale pixel intensity using window width (w) and window level (l).
82
    
83
    Parameters:
84
    - w: Window width (contrast range)
85
    - l: Window level (brightness center)
86
    
87
    Returns:
88
    Windowed image tensor
89
    """
90

91
def pct_in_window(dcm, w, l):
92
    """
93
    Calculate percentage of pixels within specified window.
94
    
95
    Parameters:
96
    - dcm: DcmDataset object
97
    - w: Window width
98
    - l: Window level
99
    
100
    Returns:
101
    Float percentage (0.0 to 1.0)
102
    """
103

104
# Predefined medical windows
105
dicom_windows = SimpleNamespace(
106
    brain=(80,40),
107
    subdural=(254,100), 
108
    stroke=(8,32),
109
    brain_bone=(2800,600),
110
    brain_soft=(375,40),
111
    lungs=(1500,-600),
112
    mediastinum=(350,50),
113
    abdomen_soft=(400,50),
114
    liver=(150,30),
115
    spine_soft=(250,50),
116
    spine_bone=(1800,400)
117
)
118
```
119

120
### Histogram Scaling and Normalization
121

122
Advanced normalization techniques using frequency histogram equalization for optimal contrast.
123

124
```python { .api }
125
def freqhist_bins(self, n_bins=100):
126
    """
127
    Split pixel value range into groups with equal pixel counts.
128
    
129
    Parameters:
130
    - n_bins: Number of histogram bins (default: 100)
131
    
132
    Returns:
133
    Tensor of bin boundaries
134
    """
135

136
def hist_scaled(self, brks=None, min_px=None, max_px=None):
137
    """
138
    Scale tensor/DICOM using frequency histogram to values between 0 and 1.
139
    
140
    Parameters:
141
    - brks: Custom bin boundaries (optional, computed if None)
142
    - min_px: Minimum pixel value clipping (DcmDataset only)
143
    - max_px: Maximum pixel value clipping (DcmDataset only)
144
    
145
    Returns:
146
    Normalized tensor with values in [0,1]
147
    """
148
```
149

150
### Multi-channel Processing
151

152
Convert single DICOM images to multi-channel representations using multiple medical windows.
153

154
```python { .api }
155
def to_nchan(self, wins, bins=None):
156
    """
157
    Convert to multi-channel image using multiple windows.
158
    
159
    Parameters:
160
    - wins: List of (width, level) window tuples
161
    - bins: Histogram bins for additional normalized channel (None includes it, 0 excludes it)
162
    
163
    Returns:
164
    Multi-channel TensorCTScan
165
    """
166

167
def to_3chan(self, win1, win2, bins=None):
168
    """
169
    Convert to 3-channel image using two windows plus optional normalized channel.
170
    
171
    Parameters:
172
    - win1: First window (width, level) tuple
173
    - win2: Second window (width, level) tuple
174
    - bins: Include normalized channel (default: True)
175
    
176
    Returns:
177
    3-channel TensorCTScan
178
    """
179
```
180

181
### Image Processing and Filtering
182

183
Specialized filtering operations optimized for medical images.
184

185
```python { .api }
186
def uniform_blur2d(x, s):
187
    """
188
    Apply uniform blurring using 2D convolution.
189
    
190
    Parameters:
191
    - x: Input tensor
192
    - s: Blur kernel size
193
    
194
    Returns:
195
    Blurred tensor
196
    """
197

198
def gauss_blur2d(x, s):
199
    """
200
    Apply Gaussian blur using kornia filters.
201
    
202
    Parameters:
203
    - x: Input tensor
204
    - s: Gaussian sigma value
205
    
206
    Returns:
207
    Gaussian blurred tensor
208
    """
209
```
210

211
### Mask Generation and Cropping
212

213
Automatic mask generation and anatomical region cropping for focused analysis.
214

215
```python { .api }
216
def mask_from_blur(self, window, sigma=0.3, thresh=0.05, remove_max=True):
217
    """
218
    Create binary mask from blurred windowed image.
219
    
220
    Parameters:
221
    - window: Windowing parameters (w, l) tuple
222
    - sigma: Gaussian blur sigma relative to image size
223
    - thresh: Threshold for mask creation
224
    - remove_max: Remove maximum intensity pixels
225
    
226
    Returns:
227
    Binary mask tensor
228
    """
229

230
def mask2bbox(mask):
231
    """
232
    Convert binary mask to bounding box coordinates.
233
    
234
    Parameters:
235
    - mask: Binary mask tensor
236
    
237
    Returns:
238
    Bounding box tensor [x1, y1, x2, y2]
239
    """
240

241
def crop_resize(x, crops, new_sz):
242
    """
243
    Crop and resize image using bounding box coordinates.
244
    
245
    Parameters:
246
    - x: Input tensor
247
    - crops: Bounding box coordinates
248
    - new_sz: Target size (int or tuple)
249
    
250
    Returns:
251
    Cropped and resized tensor
252
    """
253
```
254

255
### Export and File Operations
256

257
Export processed medical images to standard formats with proper scaling and compression.
258

259
```python { .api }
260
def save_jpg(self, path, wins, bins=None, quality=90):
261
    """
262
    Save tensor or DICOM as multi-channel JPEG.
263
    
264
    Parameters:
265
    - path: Output file path
266
    - wins: List of windowing parameters
267
    - bins: Include normalized channel
268
    - quality: JPEG quality (0-100)
269
    """
270

271
def save_tif16(self, path, bins=None, compress=True):
272
    """
273
    Save as 16-bit TIFF image.
274
    
275
    Parameters:
276
    - path: Output file path
277
    - bins: Histogram binning parameters
278
    - compress: Enable TIFF compression
279
    """
280

281
def to_uint16(self, bins=None):
282
    """
283
    Convert to 16-bit unsigned integer array.
284
    
285
    Parameters:
286
    - bins: Histogram binning parameters
287
    
288
    Returns:
289
    numpy uint16 array
290
    """
291
```
292

293
### Medical Segmentation Data Loading
294

295
Specialized data loaders for medical image segmentation tasks with DICOM support.
296

297
```python { .api }
298
class DicomSegmentationDataLoaders(DataLoaders):
299
    """Specialized data loaders for DICOM segmentation tasks."""
300
    
301
    @classmethod
302
    def from_label_func(cls, path, fnames, label_func, valid_pct=0.2, seed=None, 
303
                       codes=None, item_tfms=None, batch_tfms=None, **kwargs):
304
        """
305
        Create DICOM segmentation DataLoaders from label function.
306
        
307
        Parameters:
308
        - path: Base data path
309
        - fnames: List of DICOM filenames
310
        - label_func: Function to get segmentation mask from filename
311
        - valid_pct: Validation split percentage
312
        - seed: Random seed for splitting
313
        - codes: Segmentation class codes
314
        - item_tfms/batch_tfms: Data transformations
315
        
316
        Returns:
317
        DicomSegmentationDataLoaders instance
318
        """
319
```
320

321
### DICOM Metadata Processing
322

323
Extract and process DICOM metadata for analysis and quality control.
324

325
```python { .api }
326
def as_dict(self, px_summ=True, window=dicom_windows.brain):
327
    """
328
    Convert DICOM header to dictionary with optional pixel statistics.
329
    
330
    Parameters:
331
    - px_summ: Include pixel statistics (min, max, mean, std)
332
    - window: Window for percentage calculation
333
    
334
    Returns:
335
    Dictionary of DICOM tags and statistics
336
    """
337

338
@classmethod
339
def from_dicoms(cls, fns, n_workers=0, **kwargs):
340
    """
341
    Create pandas DataFrame from multiple DICOM files (attached to pd.DataFrame).
342
    
343
    Parameters:
344
    - fns: List of DICOM file paths
345
    - n_workers: Number of parallel workers
346
    - **kwargs: Additional arguments for as_dict
347
    
348
    Returns:
349
    DataFrame with DICOM metadata
350
    """
351
```
352

353
## Usage Examples
354

355
### Basic DICOM Processing
356

357
```python
358
from fastai.medical.imaging import *
359

360
# Load DICOM files
361
dicom_files = get_dicom_files('/path/to/dicoms')
362
dcm = dicom_files[0].dcmread()
363

364
# Display with medical windowing
365
dcm.show(scale=dicom_windows.brain)
366

367
# Create multi-channel representation
368
multi_chan = dcm.to_3chan(dicom_windows.brain, dicom_windows.subdural)
369
```
370

371
### Medical Image Classification
372

373
```python
374
from fastai.medical.imaging import *
375
from fastai.vision.all import *
376

377
# Setup medical image classification
378
items = get_dicom_files(path/"train")
379
df = pd.read_csv(path/"labels.csv")
380

381
dblock = DataBlock(
382
    blocks=(ImageBlock(cls=PILDicom), CategoryBlock),
383
    get_x=lambda x: path/x['file'],
384
    get_y=lambda x: x['label'],
385
    batch_tfms=[*aug_transforms(size=224), Normalize.from_stats(*imagenet_stats)]
386
)
387

388
dls = dblock.dataloaders(df.values)
389
learn = vision_learner(dls, resnet34, metrics=accuracy)
390
learn.fit_one_cycle(5)
391
```
392

393
### Medical Image Segmentation
394

395
```python
396
# DICOM segmentation pipeline
397
path = untar_data(URLs.TCGA_SMALL)
398
codes = np.loadtxt(path/'codes.txt', dtype=str)
399
fnames = get_dicom_files(path/'dicoms')
400

401
def get_mask(fn): 
402
    return path/'labels'/f'{fn.stem}.png'
403

404
dls = DicomSegmentationDataLoaders.from_label_func(
405
    path, fnames, get_mask, codes=codes, bs=4,
406
    item_tfms=[Resize(256)],
407
    batch_tfms=[*aug_transforms(size=224), Normalize.from_stats(*imagenet_stats)]
408
)
409

410
learn = unet_learner(dls, resnet34)
411
learn.fit_one_cycle(10)
412
```
413

414
### Advanced Medical Image Processing
415

416
```python
417
# Advanced processing workflow
418
dcm = dicom_file.dcmread()
419

420
# Generate mask and crop region of interest
421
mask = dcm.mask_from_blur(dicom_windows.brain, sigma=0.5)
422
bbox = mask2bbox(mask)
423
cropped = crop_resize(dcm.scaled_px[None], bbox[...,None], 256)[0]
424

425
# Export processed images
426
dcm.save_jpg('processed.jpg', [
427
    dicom_windows.brain, 
428
    dicom_windows.subdural, 
429
    dicom_windows.bone
430
])
431

432
# Batch metadata analysis
433
dicom_files = get_dicom_files(path)
434
df = pd.DataFrame.from_dicoms(dicom_files, n_workers=4)
435
```
436

437
## Types
438

439
```python { .api }
440
# External types (from pydicom)
441
DcmDataset  # PyDicom dataset object
442
DcmTag      # PyDicom tag object  
443
DcmMultiValue  # PyDicom multi-value object
444
```