0
# ITK - The Insight Toolkit
1
2
A comprehensive open-source toolkit for N-dimensional scientific image processing, segmentation, and registration. ITK provides hundreds of algorithms and data structures for medical image analysis, computer vision, and scientific computing applications, with extensive Python bindings, cross-platform compatibility, and high-performance implementations optimized for research and clinical workflows.
3
4
## Package Information
5
6
- **Package Name**: itk
7
- **Package Type**: PyPI
8
- **Language**: C++ with Python bindings
9
- **Installation**: `pip install itk`
10
11
## Core Imports
12
13
```python
14
import itk
15
```
16
17
For specific components:
18
19
```python
20
# Core data structures
21
from itk import Image, Point, Vector, Matrix
22
23
# I/O operations
24
from itk import imread, imwrite, ImageFileReader, ImageFileWriter
25
26
# Filtering operations (functional interface)
27
from itk import median_image_filter, gaussian_blur_image_filter
28
from itk import binary_threshold_image_filter, otsu_threshold_image_filter
29
30
# Registration and transforms
31
from itk import AffineTransform, registration_method_v4
32
from itk import mutual_information_image_to_image_metric_v4
33
34
# Segmentation
35
from itk import watershed_image_filter, connected_threshold_image_filter
36
37
# Mesh processing
38
from itk import Mesh, QuadEdgeMesh, PointSet
39
40
# NumPy integration
41
from itk import array_from_image, image_from_array
42
```
43
44
## Basic Usage
45
46
```python
47
import itk
48
import numpy as np
49
50
# Read and write images (most common operations)
51
image = itk.imread('input.png')
52
itk.imwrite(image, 'output.png')
53
54
# Convert between ITK and NumPy (seamless integration)
55
array = itk.array_from_image(image)
56
new_image = itk.image_from_array(array)
57
58
# Image filtering (modern functional interface)
59
# Smooth an image with median filter
60
smoothed = itk.median_image_filter(image, radius=2)
61
62
# Threshold an image
63
binary = itk.binary_threshold_image_filter(
64
image, lower_threshold=100, upper_threshold=255
65
)
66
67
# Advanced filtering with automatic parameter deduction
68
blurred = itk.gaussian_blur_image_filter(image, variance=2.0)
69
70
# Registration example
71
fixed_image = itk.imread('fixed.png')
72
moving_image = itk.imread('moving.png')
73
74
# Simple registration using functional interface
75
result = itk.registration_method_v4(
76
fixed_image=fixed_image,
77
moving_image=moving_image,
78
metric='mutual_information',
79
transform='affine'
80
)
81
82
# Segmentation example
83
segments = itk.watershed_image_filter(image, threshold=0.01, level=0.3)
84
85
# Traditional object-oriented interface (still available)
86
image_type = itk.Image[itk.F, 3]
87
image = image_type.New()
88
size = itk.Size[3]([100, 100, 50])
89
region = itk.ImageRegion[3]()
90
region.SetSize(size)
91
image.SetRegions(region)
92
image.Allocate()
93
```
94
95
## Architecture
96
97
ITK follows a modular, template-heavy C++ design exposed through comprehensive Python bindings:
98
99
- **Modular Design**: ITK is organized into specialized modules (Core, Filtering, IO, Registration, Segmentation, Numerics)
100
- **Template System**: Extensive templates for pixel types and dimensions, with automatic instantiation for Python
101
- **Dual Interface**: Modern functional snake_case API (`itk.median_image_filter()`) alongside traditional object-oriented interface
102
- **Pipeline Architecture**: Filters and data objects form efficient processing pipelines with lazy evaluation
103
- **Smart Pointers**: Reference-counted smart pointers provide automatic memory management
104
- **Multi-dimensional Support**: Native N-dimensional data structures and algorithms (1D to 6D+)
105
- **Cross-platform**: Runs on Windows, macOS, Linux with extensive CI/CD testing
106
107
ITK's architecture enables both high-performance C++ execution and Pythonic ease of use, making it suitable for research prototyping and production medical imaging applications.
108
109
## Capabilities
110
111
### Core Data Structures
112
113
Fundamental N-dimensional containers for images, geometric primitives, matrices, and arrays that form the backbone of all ITK operations.
114
115
```python { .api }
116
# Image containers
117
class Image[PixelType, Dimension]:
118
def SetPixel(self, index: Index[Dimension], pixel: PixelType) -> None: ...
119
def GetPixel(self, index: Index[Dimension]) -> PixelType: ...
120
def GetRegion(self) -> ImageRegion[Dimension]: ...
121
def SetSpacing(self, spacing: SpacingType) -> None: ...
122
def GetSpacing(self) -> SpacingType: ...
123
124
# Geometric primitives
125
class Point[CoordType, Dimension]:
126
def GetElement(self, i: int) -> CoordType: ...
127
def SetElement(self, i: int, value: CoordType) -> None: ...
128
def EuclideanDistanceTo(self, other: Point[CoordType, Dimension]) -> CoordType: ...
129
130
class Vector[CoordType, Dimension]:
131
def GetNorm(self) -> CoordType: ...
132
def Normalize(self) -> Vector[CoordType, Dimension]: ...
133
def GetElement(self, i: int) -> CoordType: ...
134
135
# Matrix operations
136
class Matrix[T, NRows, NColumns]:
137
def GetElement(self, row: int, col: int) -> T: ...
138
def SetElement(self, row: int, col: int, value: T) -> None: ...
139
def GetInverse(self) -> Matrix[T, NRows, NColumns]: ...
140
```
141
142
[Core Data Structures](./data-structures.md)
143
144
### Geometric Transforms
145
146
Comprehensive framework for spatial transformations including rigid, affine, and non-linear deformations used in image registration and resampling.
147
148
```python { .api }
149
class Transform[ScalarType, InputDimension, OutputDimension]:
150
def TransformPoint(self, point: Point[ScalarType, InputDimension]) -> Point[ScalarType, OutputDimension]: ...
151
def TransformVector(self, vector: Vector[ScalarType, InputDimension]) -> Vector[ScalarType, OutputDimension]: ...
152
def GetParameters(self) -> ParametersType: ...
153
def SetParameters(self, parameters: ParametersType) -> None: ...
154
155
class AffineTransform[T, NDimensions]:
156
def GetMatrix(self) -> Matrix[T, NDimensions, NDimensions]: ...
157
def SetMatrix(self, matrix: Matrix[T, NDimensions, NDimensions]) -> None: ...
158
def GetOffset(self) -> Vector[T, NDimensions]: ...
159
def SetOffset(self, offset: Vector[T, NDimensions]) -> None: ...
160
```
161
162
[Geometric Transforms](./transforms.md)
163
164
### Mesh Processing
165
166
3D mesh data structures including traditional and half-edge representations for surface modeling and analysis.
167
168
```python { .api }
169
class Mesh[PixelType, Dimension, MeshTraits]:
170
def SetPoint(self, id: PointIdentifier, point: Point[CoordType, Dimension]) -> None: ...
171
def GetPoint(self, id: PointIdentifier) -> Point[CoordType, Dimension]: ...
172
def SetCell(self, id: CellIdentifier, cell: CellAutoPointer) -> None: ...
173
def GetCell(self, id: CellIdentifier) -> CellType: ...
174
def GetNumberOfPoints(self) -> PointsContainer.ElementIdentifier: ...
175
176
class QuadEdgeMesh[PixelType, Dimension, Traits]:
177
def AddFace(self, points: list[PointIdentifier]) -> QEType: ...
178
def DeleteFace(self, face: QEType) -> None: ...
179
def FindEdge(self, point1: PointIdentifier, point2: PointIdentifier) -> QEType: ...
180
```
181
182
[Mesh Processing](./mesh.md)
183
184
### Image Functions
185
186
Interpolation, analysis, and processing functions that operate on image data including various interpolation schemes and neighborhood operations.
187
188
```python { .api }
189
class InterpolateImageFunction[InputImageType, CoordRep]:
190
def Evaluate(self, point: Point[CoordRep, ImageDimension]) -> OutputType: ...
191
def EvaluateAtIndex(self, index: Index[ImageDimension]) -> OutputType: ...
192
def EvaluateAtContinuousIndex(self, index: ContinuousIndex[CoordRep, ImageDimension]) -> OutputType: ...
193
194
class LinearInterpolateImageFunction[InputImageType, CoordRep]:
195
def SetInputImage(self, image: InputImageType) -> None: ...
196
197
class BSplineInterpolateImageFunction[InputImageType, CoordRep, CoefficientType]:
198
def SetSplineOrder(self, order: int) -> None: ...
199
def GetSplineOrder(self) -> int: ...
200
```
201
202
[Image Functions](./image-functions.md)
203
204
### Image Adaptors
205
206
View adaptors that provide different pixel interpretations and mathematical transformations of existing images without copying data.
207
208
```python { .api }
209
class ImageAdaptor[TImage, TAccessor]:
210
def SetPixelAccessor(self, accessor: TAccessor) -> None: ...
211
def GetPixelAccessor(self) -> TAccessor: ...
212
213
class RGBToLuminanceImageAdaptor[TImage]:
214
def SetImage(self, image: TImage) -> None: ...
215
216
class NthElementImageAdaptor[TImage, TOutputPixelType]:
217
def SelectNthElement(self, nth: int) -> None: ...
218
```
219
220
[Image Adaptors](./image-adaptors.md)
221
222
### Finite Difference Framework
223
224
PDE-based image processing framework for level set methods, segmentation, and deformable models.
225
226
```python { .api }
227
class FiniteDifferenceImageFilter[TInputImage, TOutputImage]:
228
def SetNumberOfIterations(self, iterations: int) -> None: ...
229
def SetTimeStep(self, time_step: float) -> None: ...
230
def GetElapsedIterations(self) -> int: ...
231
232
class LevelSetFunction[TImageType]:
233
def ComputeSpeedImage(self) -> None: ...
234
def ComputeAdvectionImage(self) -> None: ...
235
def SetAdvectionWeight(self, weight: ScalarValueType) -> None: ...
236
```
237
238
[Finite Difference Framework](./finite-difference.md)
239
240
### GPU Computing
241
242
GPU-accelerated computing support using OpenCL for high-performance image processing operations.
243
244
```python { .api }
245
class GPUImage[TPixel, VImageDimension]:
246
def GetGPUDataManager(self) -> GPUDataManager: ...
247
def UpdateGPUBuffer(self) -> None: ...
248
def UpdateCPUBuffer(self) -> None: ...
249
250
class GPUImageDataManager[ImageType]:
251
def SetCPUBufferPointer(self, ptr: PixelType) -> None: ...
252
def SetGPUDirtyFlag(self, isDirty: bool) -> None: ...
253
```
254
255
[GPU Computing](./gpu-computing.md)
256
257
### Spatial Objects
258
259
Geometric object representations for modeling anatomical structures and regions of interest.
260
261
```python { .api }
262
class SpatialObject[TDimension]:
263
def IsInside(self, point: Point[ScalarType, TDimension]) -> bool: ...
264
def ComputeLocalBoundingBox(self) -> BoundingBoxType: ...
265
def SetObjectToParentTransform(self, transform: TransformType) -> None: ...
266
267
class EllipseSpatialObject[TDimension]:
268
def SetRadius(self, radius: ArrayType) -> None: ...
269
def GetRadius(self) -> ArrayType: ...
270
```
271
272
[Spatial Objects](./spatial-objects.md)
273
274
### NumPy Integration
275
276
Seamless integration utilities for converting between ITK images and NumPy arrays, enabling interoperability with the Python scientific computing ecosystem.
277
278
```python { .api }
279
def array_from_image(image: Image) -> numpy.ndarray: ...
280
def image_from_array(array: numpy.ndarray, is_vector: bool = False) -> Image: ...
281
def array_view_from_image(image: Image) -> numpy.ndarray: ...
282
def image_view_from_array(array: numpy.ndarray, is_vector: bool = False) -> Image: ...
283
284
# Type instantiation helpers
285
def template(template_class): ...
286
def auto_pipeline(*args, **kwargs): ...
287
def size(sequence) -> Size: ...
288
def index(sequence) -> Index: ...
289
```
290
291
[NumPy Integration](./numpy-integration.md)
292
293
### Image Filtering
294
295
Extensive collection of image processing algorithms including smoothing, enhancement, morphological operations, and feature detection with both traditional and modern functional interfaces.
296
297
```python { .api }
298
# Modern functional interface (preferred)
299
def median_image_filter(input_image, radius: int | Sequence[int]) -> Image: ...
300
def gaussian_blur_image_filter(input_image, variance: float | Sequence[float]) -> Image: ...
301
def binary_threshold_image_filter(input_image, lower_threshold, upper_threshold, inside_value=255, outside_value=0) -> Image: ...
302
def otsu_threshold_image_filter(input_image, inside_value=255, outside_value=0) -> Image: ...
303
def watershed_image_filter(input_image, threshold: float, level: float) -> Image: ...
304
def gradient_magnitude_image_filter(input_image) -> Image: ...
305
def binary_dilate_image_filter(input_image, kernel_radius: int | Sequence[int]) -> Image: ...
306
def binary_erode_image_filter(input_image, kernel_radius: int | Sequence[int]) -> Image: ...
307
308
# Traditional object-oriented interface
309
class MedianImageFilter[InputImageType, OutputImageType]:
310
def SetRadius(self, radius: int | Sequence[int]) -> None: ...
311
def GetRadius(self) -> Sequence[int]: ...
312
```
313
314
[Image Filtering](./filtering.md)
315
316
### Registration Framework
317
318
Comprehensive image registration system supporting multiple transform types, similarity metrics, and optimization methods for medical image alignment.
319
320
```python { .api }
321
# Modern registration interface
322
def registration_method_v4(fixed_image, moving_image, metric: str = 'mutual_information',
323
transform: str = 'affine', optimizer: str = 'gradient_descent') -> dict: ...
324
325
# Registration components
326
class ImageRegistrationMethodv4[TFixedImage, TMovingImage]:
327
def SetFixedImage(self, image: TFixedImage) -> None: ...
328
def SetMovingImage(self, image: TMovingImage) -> None: ...
329
def SetMetric(self, metric: MetricType) -> None: ...
330
def SetOptimizer(self, optimizer: OptimizerType) -> None: ...
331
def SetTransform(self, transform: TransformType) -> None: ...
332
333
class MutualInformationImageToImageMetricv4[TFixedImage, TMovingImage]:
334
def SetNumberOfHistogramBins(self, bins: int) -> None: ...
335
def GetValue(self) -> float: ...
336
337
class GradientDescentOptimizerv4:
338
def SetLearningRate(self, rate: float) -> None: ...
339
def SetNumberOfIterations(self, iterations: int) -> None: ...
340
```
341
342
[Registration Framework](./registration.md)
343
344
### Segmentation Algorithms
345
346
Advanced segmentation methods including level sets, region growing, clustering, and watershed algorithms for extracting anatomical structures.
347
348
```python { .api }
349
# Functional segmentation interface
350
def connected_threshold_image_filter(input_image, seed_points: Sequence, lower: float, upper: float) -> Image: ...
351
def confidence_connected_image_filter(input_image, seed_points: Sequence, multiplier: float = 2.5) -> Image: ...
352
def watershed_image_filter(input_image, threshold: float, level: float) -> Image: ...
353
def geodesic_active_contour_level_set_image_filter(input_image, feature_image, seeds) -> Image: ...
354
355
# Level set segmentation
356
class GeodesicActiveContourLevelSetImageFilter[TInputImage, TFeatureImage, TOutputImage]:
357
def SetFeatureImage(self, image: TFeatureImage) -> None: ...
358
def SetAdvectionScaling(self, scaling: float) -> None: ...
359
def SetCurvatureScaling(self, scaling: float) -> None: ...
360
def SetPropagationScaling(self, scaling: float) -> None: ...
361
362
# Region growing
363
class ConnectedThresholdImageFilter[TInputImage, TOutputImage]:
364
def SetSeed(self, seed: Index) -> None: ...
365
def AddSeed(self, seed: Index) -> None: ...
366
def SetLower(self, threshold: PixelType) -> None: ...
367
def SetUpper(self, threshold: PixelType) -> None: ...
368
```
369
370
[Segmentation](./segmentation.md)
371
372
### Comprehensive I/O Support
373
374
Extensive file format support for medical imaging, computer vision, and scientific data with automatic format detection and metadata preservation.
375
376
```python { .api }
377
# High-level I/O functions
378
def imread(filename: str, pixel_type=None, fallback_only: bool = False) -> Image: ...
379
def imwrite(image: Image, filename: str, compression: bool = False, use_streaming: bool = False) -> None: ...
380
def meshread(filename: str) -> Mesh: ...
381
def meshwrite(mesh: Mesh, filename: str) -> None: ...
382
def transformread(filename: str) -> Transform: ...
383
def transformwrite(transform: Transform, filename: str) -> None: ...
384
385
# Format-specific readers/writers
386
class ImageFileReader[TOutputImage]:
387
def SetFileName(self, filename: str) -> None: ...
388
def GetFileName(self) -> str: ...
389
def Update(self) -> None: ...
390
def GetOutput(self) -> TOutputImage: ...
391
392
class ImageFileWriter[TInputImage]:
393
def SetFileName(self, filename: str) -> None: ...
394
def SetInput(self, image: TInputImage) -> None: ...
395
def SetUseCompression(self, compression: bool) -> None: ...
396
def Write(self) -> None: ...
397
398
# DICOM support
399
class GDCMImageIO:
400
def SetLoadSequences(self, load: bool) -> None: ...
401
def SetLoadPrivateTags(self, load: bool) -> None: ...
402
def GetPatientName(self) -> str: ...
403
def GetStudyDescription(self) -> str: ...
404
```
405
406
[I/O Operations](./io.md)
407
408
## Types
409
410
```python { .api }
411
# Common type abbreviations
412
F = float # 32-bit float
413
D = float # 64-bit double
414
UC = int # unsigned char
415
US = int # unsigned short
416
UI = int # unsigned int
417
UL = int # unsigned long
418
SC = int # signed char
419
SS = int # signed short
420
SI = int # signed int
421
SL = int # signed long
422
423
# Template instantiation types
424
class Index[Dimension]: ...
425
class Size[Dimension]: ...
426
class ImageRegion[Dimension]: ...
427
class SpacingType: ...
428
class OriginType: ...
429
class DirectionType: ...
430
class ParametersType: ...
431
class PointIdentifier: ...
432
class CellIdentifier: ...
433
```