CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-simpleitk

SimpleITK is a simplified interface to the Insight Toolkit (ITK) for image registration and segmentation

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

io.mddocs/reference/core/

Image I/O

SimpleITK provides comprehensive image input/output capabilities supporting medical imaging formats (DICOM, NIfTI, NRRD, MetaIO) and common image formats (PNG, JPEG, TIFF, BMP). Both procedural functions and object-oriented reader/writer classes are available for single files and image series.

Capabilities

Procedural I/O Functions

Simplified interface for common reading and writing tasks.

def ReadImage(fileName: str | list[str], outputPixelType: int = sitkUnknown, imageIO: str = ""):
    """
    Read image from file or series of files.

    This procedural interface handles both single files and image series.
    For a list of filenames, reads them as a 3D volume.

    Args:
        fileName: Single filename or list of filenames for series
        outputPixelType: Convert to this pixel type (default: same as file)
        imageIO: ImageIO name to use (default: auto-detect from extension)

    Returns:
        Image object

    Examples:
        # Single file
        image = sitk.ReadImage('ct_scan.nii.gz')

        # Series of files
        series_files = ['slice001.dcm', 'slice002.dcm', 'slice003.dcm']
        volume = sitk.ReadImage(series_files)

        # Force pixel type conversion
        image = sitk.ReadImage('input.png', sitk.sitkFloat32)

        # Specify ImageIO explicitly
        image = sitk.ReadImage('data.img', imageIO='NiftiImageIO')
    """

def WriteImage(image, fileName: str | list[str], useCompression: bool = False,
               compressionLevel: int = -1, imageIO: str = "", compressor: str = ""):
    """
    Write image to file or series of files.

    For a list of filenames, writes 3D image as series of 2D slices.

    Args:
        image: Image to write
        fileName: Single filename or list of filenames for series
        useCompression: Enable compression (format-dependent)
        compressionLevel: Compression level hint (-1 for default, 0-9 typically)
        imageIO: ImageIO name to use (default: auto-detect)
        compressor: Compressor algorithm hint (e.g., 'JPEG', 'LZW')

    Examples:
        # Single file
        sitk.WriteImage(image, 'output.nii.gz')

        # With compression
        sitk.WriteImage(image, 'output.mha', useCompression=True, compressionLevel=5)

        # Write 3D as series
        series_names = [f'slice{i:03d}.png' for i in range(image.GetDepth())]
        sitk.WriteImage(image, series_names)
    """

Usage examples:

import SimpleITK as sitk

# Read various formats
ct_image = sitk.ReadImage('scan.nii.gz')  # NIfTI compressed
mri_image = sitk.ReadImage('brain.mha')   # MetaImage
png_image = sitk.ReadImage('photo.png')   # PNG

# Write with compression
sitk.WriteImage(ct_image, 'output.nii.gz', useCompression=True)

# Convert formats
image = sitk.ReadImage('input.dcm')
sitk.WriteImage(image, 'output.nrrd')

ImageFileReader Class

Object-oriented interface for reading single image files with metadata access.

class ImageFileReader:
    """
    Reader for single image files.

    Provides access to image metadata without requiring full pixel data load.
    """

    def __init__(self):
        """Create image file reader."""

    def SetFileName(self, fileName: str) -> None:
        """
        Set input filename.

        Args:
            fileName: Path to image file
        """

    def GetFileName(self) -> str:
        """
        Get input filename.

        Returns:
            Filename string
        """

    def SetImageIO(self, imageIO: str) -> None:
        """
        Specify ImageIO to use.

        Args:
            imageIO: ImageIO name (e.g., 'GDCMImageIO', 'NiftiImageIO')
        """

    def GetImageIO(self) -> str:
        """Get ImageIO name."""

    def SetOutputPixelType(self, pixelType: int) -> None:
        """
        Set output pixel type for conversion.

        Args:
            pixelType: Desired pixel type (e.g., sitkFloat32)
        """

    def Execute(self):
        """
        Read and return image.

        Returns:
            Image object
        """

    def ReadImageInformation(self) -> None:
        """
        Read only image metadata (not pixel data).

        Must call before accessing metadata methods.
        """

    def GetMetaData(self, key: str) -> str:
        """
        Get metadata value for key.

        Call ReadImageInformation() first.

        Args:
            key: Metadata key

        Returns:
            Metadata value as string
        """

    def HasMetaDataKey(self, key: str) -> bool:
        """
        Check if metadata key exists.

        Args:
            key: Metadata key

        Returns:
            True if key exists
        """

    def GetMetaDataKeys(self) -> tuple[str, ...]:
        """
        Get all metadata keys.

        Returns:
            Tuple of metadata key strings
        """

    def GetSize(self) -> tuple[int, ...]:
        """
        Get image size (after ReadImageInformation).

        Returns:
            Image dimensions
        """

    def GetOrigin(self) -> tuple[float, ...]:
        """Get image origin (after ReadImageInformation)."""

    def GetSpacing(self) -> tuple[float, ...]:
        """Get image spacing (after ReadImageInformation)."""

    def GetDirection(self) -> tuple[float, ...]:
        """Get image direction (after ReadImageInformation)."""

    def GetNumberOfComponents(self) -> int:
        """Get components per pixel (after ReadImageInformation)."""

    def GetPixelID(self) -> int:
        """Get pixel type ID (after ReadImageInformation)."""

Usage example:

import SimpleITK as sitk

# Read with metadata access
reader = sitk.ImageFileReader()
reader.SetFileName('dicom_image.dcm')

# Read metadata without loading pixels
reader.ReadImageInformation()
print(f"Image size: {reader.GetSize()}")
print(f"Spacing: {reader.GetSpacing()}")

# Access DICOM tags
if reader.HasMetaDataKey('0010|0010'):  # Patient name
    patient_name = reader.GetMetaData('0010|0010')
    print(f"Patient: {patient_name}")

# Read pixel data
image = reader.Execute()

ImageSeriesReader Class

Reader for series of image files (typically DICOM).

class ImageSeriesReader:
    """
    Reader for image series (multiple files as 3D volume).

    Commonly used for DICOM series where each file is a 2D slice.
    """

    def __init__(self):
        """Create image series reader."""

    def SetFileNames(self, fileNames: list[str]) -> None:
        """
        Set list of filenames to read.

        Args:
            fileNames: Ordered list of image filenames
        """

    def GetFileNames(self) -> tuple[str, ...]:
        """
        Get list of filenames.

        Returns:
            Tuple of filenames
        """

    def SetImageIO(self, imageIO: str) -> None:
        """
        Specify ImageIO to use.

        Args:
            imageIO: ImageIO name
        """

    def SetOutputPixelType(self, pixelType: int) -> None:
        """Set output pixel type for conversion."""

    def Execute(self):
        """
        Read series and return 3D image.

        Returns:
            3D Image object
        """

    def GetMetaData(self, slice: int, key: str) -> str:
        """
        Get metadata from specific slice.

        Args:
            slice: Slice index
            key: Metadata key

        Returns:
            Metadata value
        """

    def HasMetaDataKey(self, slice: int, key: str) -> bool:
        """
        Check if slice has metadata key.

        Args:
            slice: Slice index
            key: Metadata key

        Returns:
            True if key exists for slice
        """

    def GetMetaDataKeys(self, slice: int) -> tuple[str, ...]:
        """
        Get metadata keys for slice.

        Args:
            slice: Slice index

        Returns:
            Tuple of metadata keys
        """

Usage example:

import SimpleITK as sitk

# Read DICOM series
reader = sitk.ImageSeriesReader()
dicom_names = sitk.ImageSeriesReader.GetGDCMSeriesFileNames('dicom_directory/')
reader.SetFileNames(dicom_names)

volume = reader.Execute()

# Access per-slice metadata
if reader.HasMetaDataKey(0, '0008|0060'):  # Modality
    modality = reader.GetMetaData(0, '0008|0060')
    print(f"Modality: {modality}")

ImageFileWriter Class

Writer for single image files.

class ImageFileWriter:
    """Writer for single image files."""

    def __init__(self):
        """Create image file writer."""

    def SetFileName(self, fileName: str) -> None:
        """
        Set output filename.

        Args:
            fileName: Output file path
        """

    def GetFileName(self) -> str:
        """Get output filename."""

    def SetImageIO(self, imageIO: str) -> None:
        """
        Specify ImageIO to use.

        Args:
            imageIO: ImageIO name
        """

    def SetUseCompression(self, useCompression: bool) -> None:
        """
        Enable/disable compression.

        Args:
            useCompression: True to enable compression
        """

    def GetUseCompression(self) -> bool:
        """Get compression setting."""

    def SetCompressionLevel(self, level: int) -> None:
        """
        Set compression level.

        Args:
            level: Compression level (-1 for default, typically 0-9)
        """

    def GetCompressionLevel(self) -> int:
        """Get compression level."""

    def SetCompressor(self, compressor: str) -> None:
        """
        Set compression algorithm.

        Args:
            compressor: Compressor name (e.g., 'JPEG', 'LZW', 'ZLib')
        """

    def Execute(self, image) -> None:
        """
        Write image to file.

        Args:
            image: Image to write
        """

Usage example:

import SimpleITK as sitk

# Configure writer
writer = sitk.ImageFileWriter()
writer.SetFileName('output.nii.gz')
writer.SetUseCompression(True)
writer.SetCompressionLevel(9)

# Write image
writer.Execute(image)

ImageSeriesWriter Class

Writer for image series (3D to multiple 2D files).

class ImageSeriesWriter:
    """Writer for image series (3D volume as multiple 2D slices)."""

    def __init__(self):
        """Create image series writer."""

    def SetFileNames(self, fileNames: list[str]) -> None:
        """
        Set output filenames for each slice.

        Number of filenames must match image depth.

        Args:
            fileNames: List of output filenames
        """

    def GetFileNames(self) -> tuple[str, ...]:
        """Get output filenames."""

    def SetImageIO(self, imageIO: str) -> None:
        """Set ImageIO to use."""

    def SetUseCompression(self, useCompression: bool) -> None:
        """Enable/disable compression."""

    def Execute(self, image) -> None:
        """
        Write 3D image as series of 2D files.

        Args:
            image: 3D Image to write
        """

Usage example:

import SimpleITK as sitk

# Write 3D volume as PNG series
volume = sitk.ReadImage('volume.nii.gz')
depth = volume.GetDepth()

writer = sitk.ImageSeriesWriter()
writer.SetFileNames([f'slice_{i:04d}.png' for i in range(depth)])
writer.Execute(volume)

DICOM Series Utilities

Helper functions for working with DICOM directories.

class ImageSeriesReader:
    """DICOM series utilities (static methods)."""

    @staticmethod
    def GetGDCMSeriesFileNames(directory: str, seriesID: str = "", useSeriesDetails: bool = False,
                                recursive: bool = False, loadSequences: bool = False) -> tuple[str, ...]:
        """
        Get filenames for DICOM series in directory.

        Args:
            directory: Directory containing DICOM files
            seriesID: Specific series UID to read (empty for first series)
            useSeriesDetails: Use additional DICOM tags for series grouping
            recursive: Search subdirectories
            loadSequences: Load sequence information

        Returns:
            Ordered tuple of DICOM filenames for series
        """

    @staticmethod
    def GetGDCMSeriesIDs(directory: str, useSeriesDetails: bool = False,
                         recursive: bool = False, loadSequences: bool = False) -> tuple[str, ...]:
        """
        Get all series IDs in directory.

        Args:
            directory: Directory containing DICOM files
            useSeriesDetails: Use additional DICOM tags for series grouping
            recursive: Search subdirectories
            loadSequences: Load sequence information

        Returns:
            Tuple of series UID strings
        """

Usage example:

import SimpleITK as sitk

# Find all series in directory
series_ids = sitk.ImageSeriesReader.GetGDCMSeriesIDs('dicom_dir/')
print(f"Found {len(series_ids)} series")

# Read first series
if series_ids:
    series_files = sitk.ImageSeriesReader.GetGDCMSeriesFileNames('dicom_dir/', series_ids[0])
    reader = sitk.ImageSeriesReader()
    reader.SetFileNames(series_files)
    image = reader.Execute()

# Read specific series with details
series_files = sitk.ImageSeriesReader.GetGDCMSeriesFileNames(
    'dicom_dir/',
    series_ids[0],
    useSeriesDetails=True,
    recursive=True
)

ImageIO Registry

Query available image I/O formats.

def GetRegisteredImageIOs() -> tuple[str, ...]:
    """
    Get list of registered ImageIO types.

    Returns:
        Tuple of ImageIO names (e.g., 'GDCMImageIO', 'PNGImageIO', 'NiftiImageIO')

    Example:
        ios = sitk.GetRegisteredImageIOs()
        print(f"Available ImageIOs: {ios}")
    """

Supported File Formats

Medical Imaging Formats

  • DICOM (.dcm, .ima) - Digital Imaging and Communications in Medicine
  • NIfTI (.nii, .nii.gz) - Neuroimaging Informatics Technology Initiative
  • NRRD (.nrrd, .nhdr) - Nearly Raw Raster Data
  • MetaImage (.mha, .mhd) - ITK MetaImage format
  • Analyze (.hdr, .img) - Mayo Analyze format
  • MINC (.mnc) - Medical Imaging NetCDF

General Image Formats

  • PNG (.png) - Portable Network Graphics
  • JPEG (.jpg, .jpeg) - Joint Photographic Experts Group
  • TIFF (.tif, .tiff) - Tagged Image File Format
  • BMP (.bmp) - Windows Bitmap
  • GIPL (.gipl) - Guys Image Processing Lab
  • VTK (.vtk) - Visualization Toolkit
  • HDF5 (.h5, .hdf5) - Hierarchical Data Format

Common Patterns

Reading DICOM Series

import SimpleITK as sitk
import os

dicom_dir = 'patient_study/'

# Method 1: Read first series automatically
series_ids = sitk.ImageSeriesReader.GetGDCMSeriesIDs(dicom_dir)
if series_ids:
    series_files = sitk.ImageSeriesReader.GetGDCMSeriesFileNames(dicom_dir, series_ids[0])
    image = sitk.ReadImage(series_files)

# Method 2: Read all files in directory (if only one series)
reader = sitk.ImageSeriesReader()
dicom_files = reader.GetGDCMSeriesFileNames(dicom_dir)
reader.SetFileNames(dicom_files)
image = reader.Execute()

Preserving Metadata When Writing

import SimpleITK as sitk

# Read with metadata
reader = sitk.ImageFileReader()
reader.SetFileName('input.dcm')
image = reader.Execute()

# Process image
processed = sitk.SmoothingRecursiveGaussian(image, sigma=[1.0, 1.0, 1.0])

# Write with metadata preserved
writer = sitk.ImageFileWriter()
writer.SetFileName('output.mha')
writer.Execute(processed)
# Spatial metadata (origin, spacing, direction) is preserved automatically

Converting Between Formats

import SimpleITK as sitk

# Read any format
image = sitk.ReadImage('input.dcm')  # DICOM

# Write to different format
sitk.WriteImage(image, 'output.nii.gz')  # NIfTI compressed
sitk.WriteImage(image, 'output.mha')     # MetaImage
sitk.WriteImage(image, 'output.nrrd')    # NRRD

# Convert 3D to PNG series
depth = image.GetDepth()
file_names = [f'slice_{i:04d}.png' for i in range(depth)]
sitk.WriteImage(image, file_names)

Checking File Format Before Reading

import SimpleITK as sitk

# Query available formats
available_ios = sitk.GetRegisteredImageIOs()
print("Supported formats:", available_ios)

# Read metadata without loading pixels
reader = sitk.ImageFileReader()
reader.SetFileName('large_image.nii.gz')
reader.ReadImageInformation()

print(f"Image dimensions: {reader.GetSize()}")
print(f"Pixel type: {reader.GetPixelID()}")
print(f"Will require loading: {reader.GetSize()[0] * reader.GetSize()[1] * reader.GetSize()[2]} pixels")

# Decide whether to load based on size
if reader.GetSize()[0] * reader.GetSize()[1] * reader.GetSize()[2] < 100000000:
    image = reader.Execute()

Writing with Optimal Compression

import SimpleITK as sitk

# High compression for archival
sitk.WriteImage(image, 'archive.nii.gz', useCompression=True, compressionLevel=9)

# Balanced compression for working files
sitk.WriteImage(image, 'working.nrrd', useCompression=True, compressionLevel=5)

# No compression for speed
sitk.WriteImage(image, 'fast.mha', useCompression=False)

# Specific compressor
writer = sitk.ImageFileWriter()
writer.SetFileName('output.tif')
writer.SetCompressor('LZW')
writer.Execute(image)

Install with Tessl CLI

npx tessl i tessl/pypi-simpleitk@2.5.1

docs

reference

core

image.md

io.md

numpy-integration.md

transforms.md

utilities.md

architecture.md

constants-enums.md

error-handling.md

performance.md

type-system.md

index.md

tile.json