tessl/pypi-itk

Insight Toolkit for N-dimensional image processing, segmentation, and registration in medical and scientific applications

—

Pending

Overview

Eval results

Files

NumPy Integration

Name: tessl/pypi-itk
Author: tessl

Seamless conversion between ITK images and NumPy arrays, supporting both deep copies and memory-shared views for efficient data exchange with the Python scientific computing ecosystem.

Capabilities

Image to Array Conversion

Convert ITK images to NumPy arrays with control over memory sharing and axis ordering.

def array_from_image(image_or_filter, keep_axes=False, update=True, ttype=None):
    """
    Get a NumPy array from an ITK image (deep copy).
    
    Parameters:
    - image_or_filter: itk.Image or ProcessObject - Image or filter producing an image
    - keep_axes: bool - If False (default), returns C-order indexing (k,j,i). If True, preserves ITK ordering (i,j,k)
    - update: bool - Update the pipeline before conversion
    - ttype: type, optional - Specify image type explicitly
    
    Returns:
    numpy.ndarray - Deep copy of image data
    
    Note:
    By default, axis order is reversed for NumPy compatibility. A 3D ITK image with
    dimensions (i,j,k) becomes a NumPy array with shape (k,j,i) unless keep_axes=True.
    
    Aliases: GetArrayFromImage
    """

def array_view_from_image(image_or_filter, keep_axes=False, update=True, ttype=None):
    """
    Get a NumPy array view (shared memory) from an ITK image.
    
    Parameters:
    - image_or_filter: itk.Image or ProcessObject - Image or filter producing an image
    - keep_axes: bool - If False (default), returns C-order indexing (k,j,i). If True, preserves ITK ordering (i,j,k)
    - update: bool - Update the pipeline before conversion
    - ttype: type, optional - Specify image type explicitly
    
    Returns:
    numpy.ndarray - View sharing memory with ITK image (no copy)
    
    Warning:
    The returned array shares memory with the ITK image. Modifications to the array
    will modify the image. The image must remain alive while the array is in use.
    
    Aliases: GetArrayViewFromImage
    """

Array to Image Conversion

Create ITK images from NumPy arrays with optional memory sharing.

def image_from_array(arr, is_vector=False, ttype=None):
    """
    Create an ITK image from a NumPy array (deep copy).
    
    Parameters:
    - arr: numpy.ndarray or array-like - NumPy array or compatible array
    - is_vector: bool - If True, last dimension is treated as vector components
    - ttype: type, optional - Specify output ITK image type
    
    Returns:
    itk.Image or itk.VectorImage
    
    Note:
    - Array dimensions are reversed to match ITK convention
    - NumPy array with shape (k,j,i) becomes ITK image with size (i,j,k)
    - If is_vector=True, shape (k,j,i,c) creates VectorImage with c components per pixel
    
    Aliases: GetImageFromArray
    """

def image_view_from_array(arr, is_vector=False, ttype=None, need_contiguous=True):
    """
    Create an ITK image view (shared memory) from a NumPy array.
    
    Parameters:
    - arr: numpy.ndarray - NumPy array (must be contiguous if need_contiguous=True)
    - is_vector: bool - If True, last dimension is treated as vector components
    - ttype: type, optional - Specify output ITK image type
    - need_contiguous: bool - Require contiguous array (default True)
    
    Returns:
    itk.Image or itk.VectorImage - View sharing memory with NumPy array
    
    Warning:
    The returned image shares memory with the NumPy array. Modifications to the image
    will modify the array. The array must remain alive while the image is in use.
    
    Aliases: GetImageViewFromArray
    """

VectorContainer Conversion

Convert ITK VectorContainer objects to/from NumPy arrays.

def array_from_vector_container(container, ttype=None):
    """
    Get NumPy array from VectorContainer (deep copy).
    
    Parameters:
    - container: itk.VectorContainer - VectorContainer to convert
    - ttype: type, optional - Specify container type explicitly
    
    Returns:
    numpy.ndarray
    """

def array_view_from_vector_container(container, ttype=None):
    """
    Get NumPy array view from VectorContainer (shared memory).
    
    Parameters:
    - container: itk.VectorContainer - VectorContainer to convert
    - ttype: type, optional - Specify container type explicitly
    
    Returns:
    numpy.ndarray - View sharing memory with container
    """

def vector_container_from_array(arr, ttype=None):
    """
    Create VectorContainer from NumPy array.
    
    Parameters:
    - arr: numpy.ndarray - Array to convert
    - ttype: type, optional - Specify output container type
    
    Returns:
    itk.VectorContainer
    """

VNL Vector Conversion

Convert VNL (Vector Numerics Library) vectors to/from NumPy arrays.

def array_from_vnl_vector(vnl_vector, ttype=None):
    """
    Get NumPy array from vnl_vector (deep copy).
    
    Parameters:
    - vnl_vector: vnl_vector - VNL vector to convert
    - ttype: type, optional - Specify vector type explicitly
    
    Returns:
    numpy.ndarray
    
    Aliases: GetArrayFromVnlVector
    """

def array_view_from_vnl_vector(vnl_vector, ttype=None):
    """
    Get NumPy array view from vnl_vector (shared memory).
    
    Parameters:
    - vnl_vector: vnl_vector - VNL vector to convert
    - ttype: type, optional - Specify vector type explicitly
    
    Returns:
    numpy.ndarray - View sharing memory with vnl_vector
    """

def vnl_vector_from_array(arr, ttype=None):
    """
    Create vnl_vector from NumPy array.
    
    Parameters:
    - arr: numpy.ndarray - 1D array to convert
    - ttype: type, optional - Specify output vnl_vector type
    
    Returns:
    vnl_vector
    
    Aliases: GetVnlVectorFromArray
    """

VNL Matrix Conversion

Convert VNL matrices to/from NumPy arrays.

def array_from_vnl_matrix(vnl_matrix, ttype=None):
    """
    Get NumPy array from vnl_matrix (deep copy).
    
    Parameters:
    - vnl_matrix: vnl_matrix - VNL matrix to convert
    - ttype: type, optional - Specify matrix type explicitly
    
    Returns:
    numpy.ndarray
    
    Aliases: GetArrayFromVnlMatrix
    """

def array_view_from_vnl_matrix(vnl_matrix, ttype=None):
    """
    Get NumPy array view from vnl_matrix (shared memory).
    
    Parameters:
    - vnl_matrix: vnl_matrix - VNL matrix to convert
    - ttype: type, optional - Specify matrix type explicitly
    
    Returns:
    numpy.ndarray - View sharing memory with vnl_matrix
    """

def vnl_matrix_from_array(arr, ttype=None):
    """
    Create vnl_matrix from NumPy array.
    
    Parameters:
    - arr: numpy.ndarray - 2D array to convert
    - ttype: type, optional - Specify output vnl_matrix type
    
    Returns:
    vnl_matrix
    
    Aliases: GetVnlMatrixFromArray
    """

ITK Matrix Conversion

Convert ITK Matrix objects to/from NumPy arrays.

def array_from_matrix(itk_matrix):
    """
    Get NumPy array from itk.Matrix (deep copy).
    
    Parameters:
    - itk_matrix: itk.Matrix - ITK matrix to convert
    
    Returns:
    numpy.ndarray
    
    Aliases: GetArrayFromMatrix
    """

def matrix_from_array(arr):
    """
    Create itk.Matrix from NumPy array.
    
    Parameters:
    - arr: numpy.ndarray - 2D array to convert
    
    Returns:
    itk.Matrix
    
    Aliases: GetMatrixFromArray
    """

xarray Integration

Convert between ITK images and xarray DataArrays for scientific data analysis with labeled dimensions.

def xarray_from_image(l_image, view=False):
    """
    Convert an ITK image to an xarray DataArray with labeled dimensions.

    Parameters:
    - l_image: itk.Image or ProcessObject - Image or filter producing an image
    - view: bool - If True, creates a view (shared memory); if False, creates a copy

    Returns:
    xarray.DataArray - DataArray with:
        - Labeled dimensions (e.g., 'x', 'y', 'z')
        - Coordinate arrays based on image spacing and origin
        - Image metadata stored as attributes

    Note:
    Requires xarray package: pip install xarray
    """

def image_from_xarray(data_array):
    """
    Create an ITK image from an xarray DataArray.

    Parameters:
    - data_array: xarray.DataArray - DataArray with spatial dimensions

    Returns:
    itk.Image - ITK image with spacing and origin from DataArray coordinates

    Note:
    The DataArray's coordinate information is used to set image spacing and origin.
    """

VTK Integration

Convert between ITK images and VTK images for visualization with VTK-based tools.

def vtk_image_from_image(l_image):
    """
    Convert an ITK image to a VTK image.

    Parameters:
    - l_image: itk.Image or ProcessObject - Image or filter producing an image

    Returns:
    vtk.vtkImageData - VTK image with same data, spacing, origin, and extent

    Note:
    Requires VTK package: pip install vtk
    Data is copied (not shared) between ITK and VTK formats.
    """

def image_from_vtk_image(vtk_image):
    """
    Create an ITK image from a VTK image.

    Parameters:
    - vtk_image: vtk.vtkImageData - VTK image to convert

    Returns:
    itk.Image - ITK image with same data, spacing, origin, and size

    Note:
    Data is copied (not shared) from VTK to ITK format.
    """

Dictionary Serialization

Serialize and deserialize ITK data structures to/from dictionaries for JSON export, storage, or transmission.

def dict_from_image(image):
    """
    Serialize an ITK image to a dictionary.

    Parameters:
    - image: itk.Image - Image to serialize

    Returns:
    dict - Dictionary containing image data, spacing, origin, direction, and metadata

    Note:
    Useful for JSON serialization, web APIs, or storing image metadata.
    """

def image_from_dict(image_dict):
    """
    Deserialize an ITK image from a dictionary.

    Parameters:
    - image_dict: dict - Dictionary created by dict_from_image()

    Returns:
    itk.Image - Reconstructed ITK image
    """

def dict_from_mesh(mesh):
    """
    Serialize an ITK mesh to a dictionary.

    Parameters:
    - mesh: itk.Mesh - Mesh to serialize

    Returns:
    dict - Dictionary containing mesh points, cells, and metadata
    """

def mesh_from_dict(mesh_dict):
    """
    Deserialize an ITK mesh from a dictionary.

    Parameters:
    - mesh_dict: dict - Dictionary created by dict_from_mesh()

    Returns:
    itk.Mesh - Reconstructed ITK mesh
    """

def dict_from_pointset(pointset):
    """
    Serialize an ITK pointset to a dictionary.

    Parameters:
    - pointset: itk.PointSet - PointSet to serialize

    Returns:
    dict - Dictionary containing points and metadata
    """

def pointset_from_dict(pointset_dict):
    """
    Deserialize an ITK pointset from a dictionary.

    Parameters:
    - pointset_dict: dict - Dictionary created by dict_from_pointset()

    Returns:
    itk.PointSet - Reconstructed ITK pointset
    """

def dict_from_polyline(polyline):
    """
    Serialize an ITK polyline to a dictionary.

    Parameters:
    - polyline: itk.PolyLineParametricPath - Polyline to serialize

    Returns:
    dict - Dictionary containing polyline vertices and metadata
    """

def polyline_from_dict(polyline_dict):
    """
    Deserialize an ITK polyline from a dictionary.

    Parameters:
    - polyline_dict: dict - Dictionary created by dict_from_polyline()

    Returns:
    itk.PolyLineParametricPath - Reconstructed ITK polyline
    """

def dict_from_transform(transform):
    """
    Serialize an ITK transform to a dictionary.

    Parameters:
    - transform: itk.Transform - Transform to serialize

    Returns:
    dict - Dictionary containing transform parameters and metadata
    """

def transform_from_dict(transform_dict):
    """
    Deserialize an ITK transform from a dictionary.

    Parameters:
    - transform_dict: dict - Dictionary created by dict_from_transform()

    Returns:
    itk.Transform - Reconstructed ITK transform
    """

Usage Examples

Basic Image Conversion

import itk
import numpy as np

# ITK to NumPy (deep copy)
image = itk.imread('input.png', itk.F)
array = itk.array_from_image(image)
print(f"Array shape: {array.shape}, dtype: {array.dtype}")

# Process with NumPy
processed = array * 2.0 + 10.0

# NumPy to ITK (deep copy)
result_image = itk.image_from_array(processed)
itk.imwrite(result_image, 'output.png')

Using Array Views for Efficiency

import itk
import numpy as np

# Create ITK image
image = itk.imread('input.png', itk.F)

# Get view (no copy - shares memory)
array_view = itk.array_view_from_image(image)

# Modify array view (modifies image directly)
array_view[:, :] = array_view * 0.5

# Image is now modified
itk.imwrite(image, 'modified.png')

Axis Order Considerations

import itk
import numpy as np

# ITK image: size (256, 256, 128) means (width=256, height=256, depth=128)
image = itk.imread('volume.nii.gz')

# Default: axis order reversed for NumPy
array = itk.array_from_image(image)
print(f"Array shape: {array.shape}")  # (128, 256, 256) - depth first

# Keep ITK axis order
array_itk_order = itk.array_from_image(image, keep_axes=True)
print(f"ITK order shape: {array_itk_order.shape}")  # (256, 256, 128)

# When converting back, axis order is automatically handled
result_image = itk.image_from_array(array)
print(f"Image size: {itk.size(result_image)}")  # (256, 256, 128)

Working with Vector Images

import itk
import numpy as np

# Create RGB image from NumPy
rgb_array = np.random.randint(0, 255, size=(100, 100, 3), dtype=np.uint8)

# Last dimension as vector components
rgb_image = itk.image_from_array(rgb_array, is_vector=True)
print(f"Pixels per element: {rgb_image.GetNumberOfComponentsPerPixel()}")  # 3

# Convert back
rgb_array_back = itk.array_from_image(rgb_image)
print(f"Array shape: {rgb_array_back.shape}")  # (100, 100, 3)

Integration with Image Processing Pipeline

import itk
import numpy as np

# Load image
image = itk.imread('input.png', itk.F)

# ITK processing
smoothed = itk.median_image_filter(image, radius=2)

# Convert to NumPy for custom processing
array = itk.array_from_image(smoothed)

# NumPy operations
array_processed = np.clip(array * 1.5, 0, 255)

# Back to ITK for more processing
processed_image = itk.image_from_array(array_processed)
edges = itk.canny_edge_detection_image_filter(processed_image)

# Save result
itk.imwrite(edges, 'edges.png')

Direct Filter Output Conversion

import itk
import numpy as np

# Apply filter and convert output directly
image = itk.imread('input.png', itk.F)
filter = itk.MedianImageFilter.New(image, radius=3)

# Convert filter output without explicit Update()
array = itk.array_from_image(filter)  # Automatically calls Update()

Memory-Efficient Processing

import itk
import numpy as np

# For large images, use views to avoid copies
image = itk.imread('large_image.nii.gz', itk.F)

# Get view instead of copy
array_view = itk.array_view_from_image(image)

# In-place NumPy operations
array_view *= 0.5
array_view += 10.0

# Changes are reflected in image
itk.imwrite(image, 'modified_large_image.nii.gz')

Creating Images from Generated Data

import itk
import numpy as np

# Generate synthetic data with NumPy
x = np.linspace(-5, 5, 256)
y = np.linspace(-5, 5, 256)
X, Y = np.meshgrid(x, y)
Z = np.sin(np.sqrt(X**2 + Y**2))

# Convert to ITK image
image = itk.image_from_array(Z.astype(np.float32))

# Set proper spacing and origin
image.SetSpacing([0.1, 0.1])
image.SetOrigin([-5.0, -5.0])

itk.imwrite(image, 'synthetic.png')

Type Conversion

import itk
import numpy as np

# Load as float for processing
image_float = itk.imread('input.png', itk.F)
array_float = itk.array_from_image(image_float)

# Process
processed = array_float * 255.0

# Convert to uint8 for saving
array_uint8 = processed.astype(np.uint8)
image_uint8 = itk.image_from_array(array_uint8)

itk.imwrite(image_uint8, 'output.png')

Matrix and Vector Conversions

import itk
import numpy as np

# Create affine transform
transform = itk.AffineTransform[itk.D, 3].New()

# Get matrix as NumPy array
matrix = transform.GetMatrix()
array = itk.array_from_matrix(matrix)
print(f"Matrix shape: {array.shape}")  # (3, 3)

# Modify and set back
array_modified = array @ np.array([[2, 0, 0], [0, 2, 0], [0, 0, 1]])
matrix_modified = itk.matrix_from_array(array_modified)
transform.SetMatrix(matrix_modified)

# Work with VNL vectors
vnl_vec = itk.vnl_vector[itk.D](3)
vnl_vec[0] = 1.0
vnl_vec[1] = 2.0
vnl_vec[2] = 3.0

# Convert to NumPy
vec_array = itk.array_from_vnl_vector(vnl_vec)
print(f"Vector: {vec_array}")  # [1. 2. 3.]

Best Practices

Memory Efficiency: Use array_view_from_image() and image_view_from_array() for large images when possible to avoid copying data.
Axis Order: Be aware that ITK uses (x, y, z) ordering while NumPy typically uses (z, y, x) for 3D data. Use keep_axes=True if you need ITK ordering.
Lifetime Management: When using views, ensure the source object (image or array) remains alive while the view is in use.
Type Matching: NumPy dtypes are automatically mapped to ITK pixel types (np.float32 → itk.F, np.uint8 → itk.UC, etc.).
Pipeline Integration: You can pass filters directly to conversion functions; they will automatically call Update().
Vector Images: Use is_vector=True when converting arrays with a channel dimension (e.g., RGB images).

Install with Tessl CLI

npx tessl i tessl/pypi-itk@5.4.1

tessl/pypi-itk