0
# Image Operations
1
2
Core image data structure and fundamental operations for creating, manipulating, and accessing image data. The Image class is the central data structure in SimpleITK, supporting 2D, 3D, and 4D images with various pixel types and comprehensive metadata handling.
3
4
## Capabilities
5
6
### Image Construction
7
8
Create images from scratch or from existing data with support for multiple pixel types and dimensions.
9
10
```python { .api }
11
class Image:
12
def __init__(self, width: int, height: int, pixelType: int):
13
"""Create 2D image with specified dimensions and pixel type"""
14
15
def __init__(self, width: int, height: int, depth: int, pixelType: int):
16
"""Create 3D image with specified dimensions and pixel type"""
17
18
def __init__(self, size: tuple, pixelType: int):
19
"""Create image with size tuple and pixel type"""
20
21
def __init__(self, size: tuple, pixelType: int, numberOfComponents: int):
22
"""Create vector image with multiple components per pixel"""
23
24
# Factory functions
25
def Image(width: int, height: int, pixelType: int) -> Image:
26
"""Create 2D image"""
27
28
def Image(width: int, height: int, depth: int, pixelType: int) -> Image:
29
"""Create 3D image"""
30
```
31
32
### Image Properties
33
34
Access and modify image metadata including dimensions, spacing, origin, and direction.
35
36
```python { .api }
37
class Image:
38
def GetSize(self) -> tuple:
39
"""Get image dimensions as tuple (width, height, [depth])"""
40
41
def GetWidth(self) -> int:
42
"""Get image width"""
43
44
def GetHeight(self) -> int:
45
"""Get image height"""
46
47
def GetDepth(self) -> int:
48
"""Get image depth (1 for 2D images)"""
49
50
def GetDimension(self) -> int:
51
"""Get number of spatial dimensions (2, 3, or 4)"""
52
53
def GetNumberOfPixels(self) -> int:
54
"""Get total number of pixels"""
55
56
def GetSpacing(self) -> tuple:
57
"""Get pixel spacing in physical units"""
58
59
def SetSpacing(self, spacing: tuple):
60
"""Set pixel spacing"""
61
62
def GetOrigin(self) -> tuple:
63
"""Get image origin in physical coordinates"""
64
65
def SetOrigin(self, origin: tuple):
66
"""Set image origin"""
67
68
def GetDirection(self) -> tuple:
69
"""Get direction matrix as flat tuple"""
70
71
def SetDirection(self, direction: tuple):
72
"""Set direction matrix from flat tuple"""
73
74
def GetPixelID(self) -> int:
75
"""Get pixel type identifier"""
76
77
def GetPixelIDValue(self) -> int:
78
"""Get pixel type value"""
79
80
def GetPixelIDTypeAsString(self) -> str:
81
"""Get pixel type as string"""
82
83
def GetNumberOfComponentsPerPixel(self) -> int:
84
"""Get number of components per pixel (1 for scalar, >1 for vector)"""
85
```
86
87
### Pixel Access
88
89
Direct pixel-level access for reading and writing individual pixel values.
90
91
```python { .api }
92
class Image:
93
def GetPixel(self, idx: tuple) -> float:
94
"""
95
Get pixel value at index.
96
97
Args:
98
idx: Pixel index as tuple (x, y, [z])
99
100
Returns:
101
Pixel value as float (scalar images) or tuple (vector images)
102
"""
103
104
def SetPixel(self, idx: tuple, value: float):
105
"""
106
Set pixel value at index.
107
108
Args:
109
idx: Pixel index as tuple (x, y, [z])
110
value: New pixel value
111
"""
112
113
def GetPixelAsInt8(self, idx: tuple) -> int: ...
114
def GetPixelAsUInt8(self, idx: tuple) -> int: ...
115
def GetPixelAsInt16(self, idx: tuple) -> int: ...
116
def GetPixelAsUInt16(self, idx: tuple) -> int: ...
117
def GetPixelAsInt32(self, idx: tuple) -> int: ...
118
def GetPixelAsUInt32(self, idx: tuple) -> int: ...
119
def GetPixelAsFloat(self, idx: tuple) -> float: ...
120
def GetPixelAsDouble(self, idx: tuple) -> float: ...
121
122
def SetPixelAsInt8(self, idx: tuple, value: int): ...
123
def SetPixelAsUInt8(self, idx: tuple, value: int): ...
124
def SetPixelAsInt16(self, idx: tuple, value: int): ...
125
def SetPixelAsUInt16(self, idx: tuple, value: int): ...
126
def SetPixelAsInt32(self, idx: tuple, value: int): ...
127
def SetPixelAsUInt32(self, idx: tuple, value: int): ...
128
def SetPixelAsFloat(self, idx: tuple, value: float): ...
129
def SetPixelAsDouble(self, idx: tuple, value: float): ...
130
```
131
132
### Buffer Access
133
134
Access to image data as contiguous memory buffers for efficient processing.
135
136
```python { .api }
137
class Image:
138
def GetBufferAsInt8(self) -> buffer:
139
"""Get image buffer as 8-bit signed integers"""
140
141
def GetBufferAsUInt8(self) -> buffer:
142
"""Get image buffer as 8-bit unsigned integers"""
143
144
def GetBufferAsInt16(self) -> buffer:
145
"""Get image buffer as 16-bit signed integers"""
146
147
def GetBufferAsUInt16(self) -> buffer:
148
"""Get image buffer as 16-bit unsigned integers"""
149
150
def GetBufferAsInt32(self) -> buffer:
151
"""Get image buffer as 32-bit signed integers"""
152
153
def GetBufferAsUInt32(self) -> buffer:
154
"""Get image buffer as 32-bit unsigned integers"""
155
156
def GetBufferAsInt64(self) -> buffer:
157
"""Get image buffer as 64-bit signed integers"""
158
159
def GetBufferAsUInt64(self) -> buffer:
160
"""Get image buffer as 64-bit unsigned integers"""
161
162
def GetBufferAsFloat(self) -> buffer:
163
"""Get image buffer as 32-bit floats"""
164
165
def GetBufferAsDouble(self) -> buffer:
166
"""Get image buffer as 64-bit floats"""
167
```
168
169
### Image Information
170
171
Copy metadata between images and access detailed image information.
172
173
```python { .api }
174
class Image:
175
def CopyInformation(self, sourceImage: Image):
176
"""
177
Copy spacing, origin, direction, and metadata from source image.
178
179
Args:
180
sourceImage: Image to copy information from
181
"""
182
183
def GetMetaData(self, key: str) -> str:
184
"""
185
Get metadata value for key.
186
187
Args:
188
key: Metadata key string
189
190
Returns:
191
Metadata value as string
192
"""
193
194
def SetMetaData(self, key: str, value: str):
195
"""
196
Set metadata key-value pair.
197
198
Args:
199
key: Metadata key string
200
value: Metadata value string
201
"""
202
203
def HasMetaDataKey(self, key: str) -> bool:
204
"""Check if metadata key exists"""
205
206
def GetMetaDataKeys(self) -> list:
207
"""Get list of all metadata keys"""
208
209
def EraseMetaData(self, key: str):
210
"""Remove metadata key"""
211
```
212
213
### NumPy Integration (Python-specific)
214
215
Efficient conversion between SimpleITK images and NumPy arrays with proper handling of metadata and memory layout.
216
217
```python { .api }
218
def GetArrayFromImage(image: Image) -> numpy.ndarray:
219
"""
220
Convert SimpleITK image to NumPy array.
221
222
Note: Array axes are in reverse order compared to SimpleITK
223
(z,y,x for 3D images vs x,y,z in SimpleITK)
224
225
Args:
226
image: SimpleITK Image
227
228
Returns:
229
NumPy array with image data
230
"""
231
232
def GetImageFromArray(array: numpy.ndarray, isVector: bool = False) -> Image:
233
"""
234
Convert NumPy array to SimpleITK image.
235
236
Args:
237
array: NumPy array with image data
238
isVector: True if array represents vector image
239
240
Returns:
241
SimpleITK Image
242
"""
243
244
def GetArrayViewFromImage(image: Image) -> numpy.ndarray:
245
"""
246
Get NumPy array view of image data (shares memory).
247
248
Args:
249
image: SimpleITK Image
250
251
Returns:
252
NumPy array view of image data
253
"""
254
255
def GetImageViewFromArray(array: numpy.ndarray, isVector: bool = False) -> Image:
256
"""
257
Create SimpleITK image view of NumPy array (shares memory).
258
259
Args:
260
array: NumPy array with image data
261
isVector: True if array represents vector image
262
263
Returns:
264
SimpleITK Image view
265
"""
266
```
267
268
### Usage Examples
269
270
#### Creating and Manipulating Images
271
272
```python
273
import SimpleITK as sitk
274
import numpy as np
275
276
# Create a 256x256 8-bit image
277
image = sitk.Image(256, 256, sitk.sitkUInt8)
278
279
# Set physical properties
280
image.SetSpacing([0.5, 0.5]) # 0.5mm pixel spacing
281
image.SetOrigin([0.0, 0.0]) # Origin at (0,0)
282
283
# Set some pixel values
284
image.SetPixel([128, 128], 255) # Set center pixel to white
285
286
# Get image properties
287
print(f"Size: {image.GetSize()}")
288
print(f"Spacing: {image.GetSpacing()}")
289
print(f"Pixel type: {image.GetPixelIDTypeAsString()}")
290
291
# Access pixel values
292
center_value = image.GetPixel([128, 128])
293
print(f"Center pixel value: {center_value}")
294
```
295
296
#### NumPy Integration
297
298
```python
299
import SimpleITK as sitk
300
import numpy as np
301
302
# Convert NumPy array to SimpleITK image
303
array = np.random.rand(100, 100).astype(np.float32)
304
image = sitk.GetImageFromArray(array)
305
306
# Set physical properties
307
image.SetSpacing([1.0, 1.0])
308
image.SetOrigin([0.0, 0.0])
309
310
# Process with SimpleITK
311
smoothed = sitk.SmoothingRecursiveGaussian(image, 2.0)
312
313
# Convert back to NumPy
314
result_array = sitk.GetArrayFromImage(smoothed)
315
316
print(f"Original array shape: {array.shape}")
317
print(f"Result array shape: {result_array.shape}")
318
```
319
320
#### Metadata Handling
321
322
```python
323
import SimpleITK as sitk
324
325
# Read image with metadata
326
image = sitk.ReadImage('medical_image.dcm')
327
328
# Access DICOM metadata
329
if image.HasMetaDataKey('0010|0010'): # Patient Name
330
patient_name = image.GetMetaData('0010|0010')
331
print(f"Patient: {patient_name}")
332
333
# Add custom metadata
334
image.SetMetaData('ProcessingDate', '2023-09-10')
335
image.SetMetaData('Algorithm', 'CustomProcessing')
336
337
# List all metadata keys
338
keys = image.GetMetaDataKeys()
339
print(f"Metadata keys: {len(keys)} entries")
340
```
341
342
## Core Framework Classes
343
344
### ProcessObject Base Class
345
346
Base class for all image processing filters and operations in SimpleITK.
347
348
```python { .api }
349
class ProcessObject:
350
def __init__(self):
351
"""Initialize process object"""
352
353
def Execute(self) -> Image:
354
"""Execute the filter/process and return result"""
355
356
def SetGlobalDefaultDebug(self, debugFlag: bool):
357
"""Set global debug flag for all process objects"""
358
359
def GetGlobalDefaultDebug(self) -> bool:
360
"""Get global debug flag"""
361
362
def SetGlobalDefaultNumberOfThreads(self, n: int):
363
"""Set global default number of threads for processing"""
364
365
def GetGlobalDefaultNumberOfThreads(self) -> int:
366
"""Get global default number of threads"""
367
368
def GetName(self) -> str:
369
"""Get name of the process object"""
370
371
def SetDebug(self, debugFlag: bool):
372
"""Enable/disable debug output for this object"""
373
374
def GetDebug(self) -> bool:
375
"""Get debug flag for this object"""
376
377
def SetNumberOfThreads(self, n: int):
378
"""Set number of threads for this object"""
379
380
def GetNumberOfThreads(self) -> int:
381
"""Get number of threads for this object"""
382
```
383
384
### ImageSource Classes
385
386
Source classes for generating synthetic images and test patterns.
387
388
```python { .api }
389
class ImageSource(ProcessObject):
390
def __init__(self):
391
"""Base class for image source objects"""
392
393
def SetSize(self, size: tuple):
394
"""Set output image size"""
395
396
def GetSize(self) -> tuple:
397
"""Get output image size"""
398
399
def SetSpacing(self, spacing: tuple):
400
"""Set output image spacing"""
401
402
def GetSpacing(self) -> tuple:
403
"""Get output image spacing"""
404
405
def SetOrigin(self, origin: tuple):
406
"""Set output image origin"""
407
408
def GetOrigin(self) -> tuple:
409
"""Get output image origin"""
410
411
def SetDirection(self, direction: tuple):
412
"""Set output image direction matrix"""
413
414
def GetDirection(self) -> tuple:
415
"""Get output image direction matrix"""
416
417
class GaussianSource(ImageSource):
418
def __init__(self):
419
"""Generate Gaussian blob images"""
420
421
def SetSigma(self, sigma: tuple):
422
"""Set Gaussian standard deviation for each dimension"""
423
424
def GetSigma(self) -> tuple:
425
"""Get Gaussian standard deviation"""
426
427
def SetMean(self, mean: tuple):
428
"""Set Gaussian mean (center) for each dimension"""
429
430
def GetMean(self) -> tuple:
431
"""Get Gaussian mean"""
432
433
def SetScale(self, scale: float):
434
"""Set amplitude scaling factor"""
435
436
def GetScale(self) -> float:
437
"""Get amplitude scaling factor"""
438
439
class GridSource(ImageSource):
440
def __init__(self):
441
"""Generate grid pattern images"""
442
443
def SetKernelOffset(self, offset: tuple):
444
"""Set grid offset"""
445
446
def SetKernelSpacing(self, spacing: tuple):
447
"""Set grid spacing"""
448
449
def SetSigma(self, sigma: tuple):
450
"""Set sigma for grid lines"""
451
452
class CheckerBoardSource(ImageSource):
453
def __init__(self):
454
"""Generate checkerboard pattern images"""
455
456
def SetCheckerValue(self, values: tuple):
457
"""Set values for checkerboard squares (value1, value2)"""
458
```
459
460
### Image Filter Base Classes
461
462
Base classes for different types of image filters.
463
464
```python { .api }
465
class ImageFilter(ProcessObject):
466
def __init__(self):
467
"""Base class for image-to-image filters"""
468
469
def SetInput(self, image: Image):
470
"""Set input image"""
471
472
def GetInput(self) -> Image:
473
"""Get input image"""
474
475
class UnaryFunctorImageFilter(ImageFilter):
476
def __init__(self):
477
"""Base class for unary function filters (single input image)"""
478
479
class BinaryFunctorImageFilter(ProcessObject):
480
def __init__(self):
481
"""Base class for binary function filters (two input images)"""
482
483
def SetInput1(self, image: Image):
484
"""Set first input image"""
485
486
def SetInput2(self, image: Image):
487
"""Set second input image"""
488
489
def GetInput1(self) -> Image:
490
"""Get first input image"""
491
492
def GetInput2(self) -> Image:
493
"""Get second input image"""
494
495
class TernaryFunctorImageFilter(ProcessObject):
496
def __init__(self):
497
"""Base class for ternary function filters (three input images)"""
498
499
def SetInput1(self, image: Image):
500
"""Set first input image"""
501
502
def SetInput2(self, image: Image):
503
"""Set second input image"""
504
505
def SetInput3(self, image: Image):
506
"""Set third input image"""
507
```