0
# Core Data Structures
1

2
Fundamental N-dimensional containers for images, geometric primitives, matrices, and arrays that form the backbone of all ITK operations. These data structures provide the essential building blocks for scientific image processing, with comprehensive support for multi-dimensional data and efficient memory management.
3

4
## Capabilities
5

6
### Image Containers
7

8
Multi-dimensional image containers with spatial metadata, supporting various pixel types and providing efficient access to image data.
9

10
```python { .api }
11
class Image[PixelType, Dimension]:
12
    """
13
    Primary N-dimensional image container with spatial metadata.
14
    
15
    Template Parameters:
16
    - PixelType: Type of pixel data (e.g., itk.F, itk.UC, itk.Vector[itk.F, 3])
17
    - Dimension: Spatial dimensionality (typically 2 or 3)
18
    """
19
    def New() -> Image[PixelType, Dimension]: ...
20
    def SetPixel(self, index: Index[Dimension], pixel: PixelType) -> None: ...
21
    def GetPixel(self, index: Index[Dimension]) -> PixelType: ...
22
    def SetRegions(self, region: ImageRegion[Dimension]) -> None: ...
23
    def GetRegion(self) -> ImageRegion[Dimension]: ...
24
    def GetLargestPossibleRegion(self) -> ImageRegion[Dimension]: ...
25
    def GetBufferedRegion(self) -> ImageRegion[Dimension]: ...
26
    def GetRequestedRegion(self) -> ImageRegion[Dimension]: ...
27
    def Allocate(self, initialize: bool = False) -> None: ...
28
    def FillBuffer(self, value: PixelType) -> None: ...
29
    def SetSpacing(self, spacing: SpacingType) -> None: ...
30
    def GetSpacing(self) -> SpacingType: ...
31
    def SetOrigin(self, origin: OriginType) -> None: ...
32
    def GetOrigin(self) -> OriginType: ...
33
    def SetDirection(self, direction: DirectionType) -> None: ...
34
    def GetDirection(self) -> DirectionType: ...
35
    def TransformPhysicalPointToIndex(self, point: Point[float, Dimension]) -> Index[Dimension]: ...
36
    def TransformIndexToPhysicalPoint(self, index: Index[Dimension]) -> Point[float, Dimension]: ...
37
    def TransformPhysicalPointToContinuousIndex(self, point: Point[float, Dimension]) -> ContinuousIndex[float, Dimension]: ...
38

39
class ImageBase[VImageDimension]:
40
    """Base class for all image types providing common spatial metadata functionality."""
41
    def GetImageDimension() -> int: ...
42
    def SetLargestPossibleRegion(self, region: ImageRegion[VImageDimension]) -> None: ...
43
    def GetLargestPossibleRegion(self) -> ImageRegion[VImageDimension]: ...
44
    def CopyInformation(self, data: ImageBase[VImageDimension]) -> None: ...
45
    def GetNumberOfComponentsPerPixel(self) -> int: ...
46

47
class ImageRegion[VImageDimension]:
48
    """Defines a rectangular region within an N-dimensional image."""
49
    def New() -> ImageRegion[VImageDimension]: ...
50
    def SetSize(self, size: Size[VImageDimension]) -> None: ...
51
    def GetSize(self) -> Size[VImageDimension]: ...
52
    def SetIndex(self, index: Index[VImageDimension]) -> None: ...
53
    def GetIndex(self) -> Index[VImageDimension]: ...
54
    def GetNumberOfPixels(self) -> int: ...
55
    def IsInside(self, index: Index[VImageDimension]) -> bool: ...
56
    def Crop(self, region: ImageRegion[VImageDimension]) -> bool: ...
57
    def PadByRadius(self, radius: Size[VImageDimension]) -> None: ...
58
    def ShrinkByRadius(self, radius: Size[VImageDimension]) -> bool: ...
59
```
60

61
### Geometric Primitives
62

63
Basic geometric types for representing positions, vectors, and spatial relationships in N-dimensional space.
64

65
```python { .api }
66
class Point[TCoordinate, VPointDimension]:
67
    """Geometric point in N-dimensional space."""
68
    def New() -> Point[TCoordinate, VPointDimension]: ...
69
    def GetElement(self, i: int) -> TCoordinate: ...
70
    def SetElement(self, i: int, value: TCoordinate) -> None: ...
71
    def Fill(self, value: TCoordinate) -> None: ...
72
    def GetVectorFromOrigin(self) -> Vector[TCoordinate, VPointDimension]: ...
73
    def GetVnlVector(self) -> vnl_vector[TCoordinate]: ...
74
    def EuclideanDistanceTo(self, other: Point[TCoordinate, VPointDimension]) -> TCoordinate: ...
75
    def SquaredEuclideanDistanceTo(self, other: Point[TCoordinate, VPointDimension]) -> TCoordinate: ...
76
    def SetToMidPoint(self, A: Point[TCoordinate, VPointDimension], B: Point[TCoordinate, VPointDimension]) -> None: ...
77
    def SetToBarycentricCombination(self, A: Point[TCoordinate, VPointDimension], B: Point[TCoordinate, VPointDimension], alpha: float) -> None: ...
78

79
class Vector[T, VVectorDimension]:
80
    """Geometric vector with mathematical operations."""
81
    def New() -> Vector[T, VVectorDimension]: ...
82
    def GetElement(self, i: int) -> T: ...
83
    def SetElement(self, i: int, value: T) -> None: ...
84
    def Fill(self, value: T) -> None: ...
85
    def GetNorm(self) -> float: ...
86
    def GetSquaredNorm(self) -> T: ...
87
    def Normalize(self) -> T: ...
88
    def SetNormalize(self) -> None: ...
89
    def CrossProduct(self, other: Vector[T, VVectorDimension]) -> Vector[T, VVectorDimension]: ...
90
    def GetVnlVector(self) -> vnl_vector[T]: ...
91

92
class CovariantVector[T, VVectorDimension]:
93
    """Covariant vector for representing gradients and normal vectors."""
94
    def New() -> CovariantVector[T, VVectorDimension]: ...
95
    def GetElement(self, i: int) -> T: ...
96
    def SetElement(self, i: int, value: T) -> None: ...
97
    def GetNorm(self) -> float: ...
98
    def Normalize(self) -> T: ...
99

100
class ContinuousIndex[TCoordinate, VIndexDimension]:
101
    """Continuous index coordinates for sub-pixel positioning."""
102
    def New() -> ContinuousIndex[TCoordinate, VIndexDimension]: ...
103
    def GetElement(self, i: int) -> TCoordinate: ...
104
    def SetElement(self, i: int, value: TCoordinate) -> None: ...
105

106
class Index[VIndexDimension]:
107
    """Multi-dimensional array index."""
108
    def New() -> Index[VIndexDimension]: ...
109
    def GetElement(self, i: int) -> int: ...
110
    def SetElement(self, i: int, value: int) -> None: ...
111
    def Fill(self, value: int) -> None: ...
112
    def CalculateOffset(self, size: Size[VIndexDimension]) -> int: ...
113

114
class Size[VSizeDimension]:
115
    """Multi-dimensional array size."""
116
    def New() -> Size[VSizeDimension]: ...
117
    def GetElement(self, i: int) -> int: ...
118
    def SetElement(self, i: int, value: int) -> None: ...
119
    def Fill(self, value: int) -> None: ...
120
    def CalculateProductOfElements(self) -> int: ...
121

122
class Offset[VOffsetDimension]:
123
    """Integer offset vector for relative positioning."""
124
    def New() -> Offset[VOffsetDimension]: ...
125
    def GetElement(self, i: int) -> int: ...
126
    def SetElement(self, i: int, value: int) -> None: ...
127
    def Fill(self, value: int) -> None: ...
128
```
129

130
### Matrix and Array Types
131

132
Mathematical containers for linear algebra operations and data storage.
133

134
```python { .api }
135
class Matrix[T, NRows, NColumns]:
136
    """Fixed-size matrix with linear algebra operations."""
137
    def New() -> Matrix[T, NRows, NColumns]: ...
138
    def GetElement(self, row: int, col: int) -> T: ...
139
    def SetElement(self, row: int, col: int, value: T) -> None: ...
140
    def Fill(self, value: T) -> None: ...
141
    def SetIdentity(self) -> None: ...
142
    def GetTranspose(self) -> Matrix[T, NColumns, NRows]: ...
143
    def GetInverse(self) -> Matrix[T, NRows, NColumns]: ...
144
    def GetVnlMatrix(self) -> vnl_matrix[T]: ...
145
    def InPlaceTranspose(self) -> None: ...
146
    def GetTrace(self) -> T: ...
147
    def Invert(self) -> bool: ...
148

149
class VariableLengthVector[TValue]:
150
    """Dynamic-length vector container."""
151
    def New() -> VariableLengthVector[TValue]: ...
152
    def SetSize(self, size: int) -> None: ...
153
    def GetSize(self) -> int: ...
154
    def GetElement(self, i: int) -> TValue: ...
155
    def SetElement(self, i: int, value: TValue) -> None: ...
156
    def Fill(self, value: TValue) -> None: ...
157
    def GetNorm(self) -> float: ...
158
    def Normalize(self) -> None: ...
159

160
class Array[TValue]:
161
    """Dynamic array container."""
162
    def New() -> Array[TValue]: ...
163
    def SetSize(self, size: int) -> None: ...
164
    def GetSize(self) -> int: ...
165
    def GetElement(self, i: int) -> TValue: ...
166
    def SetElement(self, i: int, value: TValue) -> None: ...
167
    def Fill(self, value: TValue) -> None: ...
168

169
class FixedArray[TValue, VLength]:
170
    """Fixed-size array container."""
171
    def New() -> FixedArray[TValue, VLength]: ...
172
    def GetElement(self, i: int) -> TValue: ...
173
    def SetElement(self, i: int, value: TValue) -> None: ...
174
    def Fill(self, value: TValue) -> None: ...
175
    def GetSize(self) -> int: ...
176

177
class SymmetricSecondRankTensor[TComponent, NDimension]:
178
    """Symmetric tensor representation for diffusion and structure tensors."""
179
    def New() -> SymmetricSecondRankTensor[TComponent, NDimension]: ...
180
    def GetElement(self, i: int, j: int) -> TComponent: ...
181
    def SetElement(self, i: int, j: int, value: TComponent) -> None: ...
182
    def GetTrace(self) -> TComponent: ...
183
    def ComputeEigenValues(self) -> FixedArray[TComponent, NDimension]: ...
184
    def ComputeEigenAnalysis(self) -> tuple: ...
185
```
186

187
### Pixel Types
188

189
Specialized pixel types for different data representations including colors and multi-component data.
190

191
```python { .api }
192
class RGBPixel[ComponentType]:
193
    """RGB color pixel representation."""
194
    def New() -> RGBPixel[ComponentType]: ...
195
    def GetRed(self) -> ComponentType: ...
196
    def SetRed(self, red: ComponentType) -> None: ...
197
    def GetGreen(self) -> ComponentType: ...
198
    def SetGreen(self, green: ComponentType) -> None: ...
199
    def GetBlue(self) -> ComponentType: ...
200
    def SetBlue(self, blue: ComponentType) -> None: ...
201
    def GetLuminance(self) -> ComponentType: ...
202

203
class RGBAPixel[ComponentType]:
204
    """RGBA color pixel with alpha channel."""
205
    def New() -> RGBAPixel[ComponentType]: ...
206
    def GetRed(self) -> ComponentType: ...
207
    def SetRed(self, red: ComponentType) -> None: ...
208
    def GetGreen(self) -> ComponentType: ...
209
    def SetGreen(self, green: ComponentType) -> None: ...
210
    def GetBlue(self) -> ComponentType: ...
211
    def SetBlue(self, blue: ComponentType) -> None: ...
212
    def GetAlpha(self) -> ComponentType: ...
213
    def SetAlpha(self, alpha: ComponentType) -> None: ...
214

215
class HSVPixel[ComponentType]:
216
    """HSV color space pixel representation."""
217
    def New() -> HSVPixel[ComponentType]: ...
218
    def GetHue(self) -> ComponentType: ...
219
    def SetHue(self, hue: ComponentType) -> None: ...
220
    def GetSaturation(self) -> ComponentType: ...
221
    def SetSaturation(self, saturation: ComponentType) -> None: ...
222
    def GetValue(self) -> ComponentType: ...
223
    def SetValue(self, value: ComponentType) -> None: ...
224

225
class DiffusionTensor3D[TComponent]:
226
    """3D diffusion tensor for DTI applications."""
227
    def New() -> DiffusionTensor3D[TComponent]: ...
228
    def GetElement(self, i: int, j: int) -> TComponent: ...
229
    def SetElement(self, i: int, j: int, value: TComponent) -> None: ...
230
    def GetTrace(self) -> TComponent: ...
231
    def GetFractionalAnisotropy(self) -> TComponent: ...
232
    def GetRelativeAnisotropy(self) -> TComponent: ...
233
    def ComputeEigenAnalysis(self) -> tuple: ...
234
```
235

236
### Memory Management
237

238
Utilities for memory management and data import/export.
239

240
```python { .api }
241
class ImportImageFilter[TPixel, VImageDimension]:
242
    """Import external memory buffer as ITK image."""
243
    def New() -> ImportImageFilter[TPixel, VImageDimension]: ...
244
    def SetImportPointer(self, ptr: TPixel, num_pixels: int, let_filter_manage_memory: bool = False) -> None: ...
245
    def SetRegion(self, region: ImageRegion[VImageDimension]) -> None: ...
246
    def SetOrigin(self, origin: Point[float, VImageDimension]) -> None: ...
247
    def SetSpacing(self, spacing: SpacingType) -> None: ...
248
    def SetDirection(self, direction: DirectionType) -> None: ...
249
    def GetImportPointer(self) -> TPixel: ...
250

251
class ImageFileReader[TOutputImage]:
252
    """Read images from files."""
253
    def New() -> ImageFileReader[TOutputImage]: ...
254
    def SetFileName(self, filename: str) -> None: ...
255
    def GetFileName(self) -> str: ...
256
    def Update(self) -> None: ...
257
    def GetOutput(self) -> TOutputImage: ...
258
    def GetImageIO(self) -> ImageIOBase: ...
259
    def SetImageIO(self, io: ImageIOBase) -> None: ...
260

261
class ImageFileWriter[TInputImage]:
262
    """Write images to files."""
263
    def New() -> ImageFileWriter[TInputImage]: ...
264
    def SetFileName(self, filename: str) -> None: ...
265
    def SetInput(self, image: TInputImage) -> None: ...
266
    def Write(self) -> None: ...
267
    def Update(self) -> None: ...
268
    def GetImageIO(self) -> ImageIOBase: ...
269
    def SetImageIO(self, io: ImageIOBase) -> None: ...
270

271
class MetaDataDictionary:
272
    """Container for metadata key-value pairs."""
273
    def New() -> MetaDataDictionary: ...
274
    def HasKey(self, key: str) -> bool: ...
275
    def GetKeys(self) -> list[str]: ...
276
    def Clear(self) -> None: ...
277
```
278

279
## Usage Examples
280

281
### Creating and Manipulating Images
282

283
```python
284
import itk
285
import numpy as np
286

287
# Create a 3D float image
288
ImageType = itk.Image[itk.F, 3]
289
image = ImageType.New()
290

291
# Set up image region
292
size = itk.Size[3]([100, 100, 50])
293
index = itk.Index[3]([0, 0, 0])
294
region = itk.ImageRegion[3]()
295
region.SetSize(size)
296
region.SetIndex(index)
297

298
# Configure image properties
299
image.SetRegions(region)
300
image.SetSpacing([1.0, 1.0, 2.0])
301
image.SetOrigin([0.0, 0.0, 0.0])
302
image.Allocate()
303
image.FillBuffer(0.0)
304

305
# Set individual pixel values
306
for x in range(10):
307
    for y in range(10):
308
        for z in range(5):
309
            idx = itk.Index[3]([x, y, z])
310
            image.SetPixel(idx, float(x + y + z))
311

312
# Convert to NumPy array for processing
313
array = itk.array_from_image(image)
314
print(f"Image shape: {array.shape}")
315
print(f"Image dtype: {array.dtype}")
316

317
# Process with NumPy
318
processed_array = np.sqrt(array + 1.0)
319

320
# Convert back to ITK image
321
processed_image = itk.image_from_array(processed_array)
322
processed_image.CopyInformation(image)
323
```
324

325
### Working with Geometric Primitives
326

327
```python
328
import itk
329

330
# Create points and vectors
331
point1 = itk.Point[itk.D, 3]([1.0, 2.0, 3.0])
332
point2 = itk.Point[itk.D, 3]([4.0, 5.0, 6.0])
333

334
# Calculate distance
335
distance = point1.EuclideanDistanceTo(point2)
336
print(f"Distance: {distance}")
337

338
# Create and manipulate vectors
339
vector = itk.Vector[itk.D, 3]([1.0, 0.0, 0.0])
340
vector.Normalize()
341
norm = vector.GetNorm()
342
print(f"Normalized vector norm: {norm}")
343

344
# Work with matrices
345
matrix = itk.Matrix[itk.D, 3, 3]()
346
matrix.SetIdentity()
347
matrix.SetElement(0, 1, 0.5)
348
matrix.SetElement(1, 0, -0.5)
349

350
# Get matrix properties
351
trace = matrix.GetTrace()
352
determinant = matrix.GetVnlMatrix().determinant()
353
print(f"Matrix trace: {trace}")
354
```
355

356
### RGB and Color Pixels
357

358
```python
359
import itk
360

361
# Create RGB image
362
RGBImageType = itk.Image[itk.RGBPixel[itk.UC], 2]
363
rgb_image = RGBImageType.New()
364

365
# Set up region
366
size = itk.Size[2]([256, 256])
367
region = itk.ImageRegion[2]()
368
region.SetSize(size)
369
rgb_image.SetRegions(region)
370
rgb_image.Allocate()
371

372
# Create RGB pixel
373
rgb_pixel = itk.RGBPixel[itk.UC]()
374
rgb_pixel.SetRed(255)
375
rgb_pixel.SetGreen(128)
376
rgb_pixel.SetBlue(64)
377

378
# Fill image with color
379
rgb_image.FillBuffer(rgb_pixel)
380

381
# Extract luminance
382
luminance = rgb_pixel.GetLuminance()
383
print(f"Pixel luminance: {luminance}")
384
```