Iris Codec Python API

Copyright © 2025 Iris Developers; MIT Software License

The Iris Codec Community module is a part of the Iris Digital Pathology project. This module allows for:

• Reading and writing of Iris whole slide image (WSI) digital slide files (.iris)
• Decoding Iris Codec-type compressed tile image data.

This module was designed to allow for extremely fast slide access using a simple API. We want to simplify access to these files for you.

Iris Codec for Python is available via the Anaconda and PyPi package managers. We prefer the Anaconda enviornment as it includes dynamic libraries. In a true package manager sense, if you choose to develop C/C++ applications with Python bindings Anaconda will allow you to dynamically link the C++ Iris-Codec in addition to Python modules.

Installation

Conda-Forge (Recommended)

We prefer the Anaconda environment as it includes optimized dynamic libraries and better dependency management for scientific computing environments, particularly for OpenSlide integration on Linux and macOS.

Quick Installation:

conda install -c conda-forge iris-codec

Or with mamba (faster):

mamba install iris-codec

Environment Setup:

# Configure conda-forge channel permanently
conda config --add channels conda-forge
conda config --set channel_priority strict

# Then install
conda install iris-codec

PyPI

Basic Installation:

pip install iris-codec

With Encoder Support:

# For slide encoding capabilities (requires OpenSlide)
pip install iris-codec openslide-bin

[!NOTE] Windows Limitation: The Conda-Forge encoder does not support OpenSlide on Windows as OpenSlide lacks official Windows support in Conda-Forge. We're developing native vendor format support to eliminate this dependency.

Key Features

• High-Performance Slide Reading: Optimized C++ backend with Python bindings
• Multiple Format Support: Read Iris files and encode from 40+ vendor formats
• Memory Efficient: Tiles loaded on-demand with automatic memory management
• Research-Friendly: NumPy array output, PIL/Pillow integration
• Metadata Rich: Full access to slide properties, annotations, and associated images
• Encoding Pipeline: Convert vendor formats (SVS, NDPI, VSI, MRXS) to optimized Iris format
• Privacy Controls: Metadata stripping and anonymization for research workflows

Quick Start

Basic Slide Reading

from Iris import Codec

# Open and validate slide
slide_path = 'path/to/slide.iris'
result = Codec.validate_slide_path(slide_path)
if not result.success():
    raise Exception(f'Validation failed: {result.message}')

slide = Codec.open_slide(slide_path)
if not slide:
    raise Exception('Failed to open slide')

# Get slide information
result, info = slide.get_info()
if not result.success():
    raise Exception(f'Failed to read slide info: {result.message}')

print(f"Slide: {info.extent.width}x{info.extent.height}px")
print(f"Layers: {len(info.extent.layers)}")
print(f"Encoding: {info.encoding}")

Slide Encoding

from Iris import Encoder, Codec

# Convert vendor format to Iris
result = Encoder.encode_slide_file(
    source='input.dcm',
    outdir='./output/',
    desired_encoding=Codec.Encoding.TILE_ENCODING_JPEG,
    derivation=Encoder.EncoderDerivation.layer_2x,
    concurrency=8
)

if not result.success():
    raise Exception(f'Encoding failed: {result.message}')
print('Encoding completed successfully!')

API Reference

Core Reading Functions

Import the Iris Codec module and basic validation:

from Iris import Codec

# File validation (recommended before opening)
slide_path = 'path/to/slide_file.iris'
result = Codec.validate_slide_path(slide_path)
if not result.success():
    raise Exception(f'Invalid slide file: {result.message}')
print(f"Slide '{slide_path}' passed validation")

Opening Slides

Deep validation performs comprehensive checks of the internal offset chain and IFE standard compliance:

# Open slide file
slide = Codec.open_slide(slide_path)
if not slide: 
    raise Exception('Failed to open slide file')

Slide Information and Metadata

Get comprehensive slide information including dimensions, layers, and metadata:

# Get slide abstraction
result, info = slide.get_info()
if not result.success():
    raise Exception(f'Failed to read slide information: {result.message}')

# Basic slide properties
extent = info.extent
print(f"Slide: {extent.width}x{extent.height}px")
print(f"Encoding: {info.encoding}")
print(f"Format: {info.format}")

# Layer information
print(f"Layers: {len(extent.layers)}")
for i, layer in enumerate(extent.layers):
    print(f"  Layer {i}: {layer.x_tiles}x{layer.y_tiles} tiles, {layer.scale}x scale, {layer.downsample}x downsample")

# Metadata access
metadata = info.metadata
print(f"Codec Version: {metadata.codec_version.major}.{metadata.codec_version.minor}.{metadata.codec_version.build}")
print(f"Microns Per Pixel: {metadata.microns_per_pixel}")
print(f"Magnification: {metadata.magnification}")

# Slide attributes
print("Slide attributes:")
for key in metadata.attributes:
    value = metadata.attributes[key]
    print(f"  {key}: {value}")

Reading Tile Data

Read individual tiles as NumPy arrays for analysis:

import numpy as np
from PIL import Image

# Read a specific tile
layer_index = 0  # Lowest resolution layer
tile_index = 0   # First tile

# Get tile as NumPy array (RGBA format)
tile_array = slide.read_slide_tile(layer_index, tile_index)
print(f"Tile shape: {tile_array.shape}")  # Should be (256, 256, 4)
print(f"Tile dtype: {tile_array.dtype}")  # Should be uint8

# Convert to PIL Image for display/processing
tile_image = Image.fromarray(tile_array)
tile_image.show()

# Access raw pixel data
red_channel = tile_array[:, :, 0]
alpha_channel = tile_array[:, :, 3]

Creating Composite Images

Generate overview images by stitching tiles together:

from PIL import Image

def create_layer_composite(slide, layer_index=0):
    """Create a composite image from all tiles in a layer"""
    
    # Get layer information
    result, info = slide.get_info()
    if not result.success():
        raise Exception(f'Failed to read slide info: {result.message}')
    
    layer = info.extent.layers[layer_index]
    scale = int(layer.scale)
    
    # Create composite image
    composite_width = info.extent.width // scale
    composite_height = info.extent.height // scale
    composite = Image.new('RGBA', (composite_width, composite_height))
    
    # Stitch tiles together
    tile_size = 256  # Iris tiles are always 256x256
    for y in range(layer.y_tiles):
        for x in range(layer.x_tiles):
            tile_index = y * layer.x_tiles + x
            tile_array = slide.read_slide_tile(layer_index, tile_index)
            tile_image = Image.fromarray(tile_array)
            
            # Paste tile into composite
            paste_x = x * tile_size
            paste_y = y * tile_size
            composite.paste(tile_image, (paste_x, paste_y))
    
    return composite

# Create and display low-resolution overview
overview = create_layer_composite(slide, layer_index=0)
overview.show()

[!CAUTION] Memory Warning: Despite Iris's fast read speeds, creating composite images of high-resolution layers requires substantial memory and processing time. PIL.Image creates full in-memory images rather than tiled representations. Limit composite creation to layer 0 or 1 for practical performance.

Associated Images and Thumbnails

Access embedded thumbnails and associated images:

from PIL import Image

# Get slide info first
result, info = slide.get_info()
if not result.success():
    raise Exception(f'Failed to read slide information: {result.message}')

# List available associated images
print("Available associated images:")
for image_name in info.metadata.associated_images:
    print(f"  - {image_name}")

# Read and display thumbnail if available
if 'thumbnail' in info.metadata.associated_images:
    thumbnail_array = slide.read_associated_image('thumbnail')
    thumbnail_image = Image.fromarray(thumbnail_array)
    thumbnail_image.show()
    print(f"Thumbnail size: {thumbnail_image.size}")

# Read other associated images
if 'label' in info.metadata.associated_images:
    label_array = slide.read_associated_image('label')
    label_image = Image.fromarray(label_array)
    label_image.show()

Advanced Reading Patterns

Efficient patterns for large-scale analysis:

Encoding API

The Python module includes comprehensive encoding capabilities for converting vendor WSI formats to optimized Iris files.

Basic Encoding

from Iris import Encoder, Codec

# Simple encoding with default settings
result = Encoder.encode_slide_file(
    source='path/to/input.dcm',  # SVS, NDPI, VSI, MRXS, DCM, etc.
    outdir='./output/'           # Output directory
)

if not result.success():
    raise Exception(f'Encoding failed: {result.message}')
print('Encoding completed successfully!')

Advanced Encoding Options

from Iris import Encoder, Codec, iris_core

# Comprehensive encoding configuration
result = Encoder.encode_slide_file(
    source='input.dcm',                                    # DICOM with byte-stream preservation
    outdir='./encoded/',                                   # Output directory
    desired_encoding=Codec.Encoding.TILE_ENCODING_AVIF,   # Modern AVIF compression
    desired_byte_format=iris_core.Format.FORMAT_R8G8B8,   # RGB format
    derivation=Encoder.EncoderDerivation.layer_4x,        # 4x downsampling pyramid
    strip_metadata=True,                                   # Remove patient identifiers
    anonymize=True,                                        # Additional anonymization
    concurrency=8                                          # Use 8 threads
)

if not result.success():
    raise Exception(f'Advanced encoding failed: {result.message}')

Encoding Options Reference

Compression Formats:

• TILE_ENCODING_JPEG (default): High compatibility, excellent compression
• TILE_ENCODING_AVIF: Modern format, superior compression at higher quality

Pyramid Derivation:

• layer_2x: Generate 2x downsampled layers (recommended for most use cases)
• layer_4x: Generate 4x downsampled layers (good for very large slides)
• use_source: Use existing pyramid structure from source file

Byte Formats:

• FORMAT_R8G8B8: Standard RGB (3 bytes per pixel)
• FORMAT_R8G8B8A8: RGBA with alpha channel (4 bytes per pixel)
• FORMAT_B8G8R8: BGR format for specific applications
• FORMAT_B8G8R8A8: BGRA format

Privacy Options:

• strip_metadata=True: Remove patient identifiers and PHI

Progress Monitoring

The encoder automatically displays progress during encoding operations:

# The encode_slide_file function includes built-in progress display
result = Encoder.encode_slide_file(
    source='large_slide.dcm',
    outdir='./output/',
    concurrency=8
)

# Output shows real-time progress:
# [████████████████████████████████████████] 100.0% ETA: 00:00
# Iris Encoder completed successfully
# Slide written to ./output/large_slide.iris

Integration Examples

Channel-Separated Data with PyTorch

Iris provides read_slide_tile_channels which returns data in [4,256,256] format with separate channel arrays, useful for advanced image processing:

import numpy as np
import torch
from Iris import Codec

def create_channel_separated_dataset(slide_path, layer_index=0):
    """Demonstrate channel-separated tile reading with PyTorch tensors"""
    
    slide = Codec.open_slide(slide_path)
    if not slide:
        raise Exception(f'Failed to open slide: {slide_path}')
    
    result, info = slide.get_info()
    if not result.success():
        raise Exception('Failed to read slide info')
    
    layer = info.extent.layers[layer_index]
    print(f"Processing layer {layer_index}: {layer.x_tiles}x{layer.y_tiles} tiles")
    
    # Read first tile using channel-separated format
    tile_channels = slide.read_slide_tile_channels(layer_index, tile_index=0)
    print(f"Channel-separated shape: {tile_channels.shape}")  # Should be [4, 256, 256]
    
    # Convert to PyTorch tensor
    tensor = torch.from_numpy(tile_channels).float()
    
    # Access individual channels
    red_channel = tensor[0]      # Red channel [256, 256]
    green_channel = tensor[1]    # Green channel [256, 256] 
    blue_channel = tensor[2]     # Blue channel [256, 256]
    alpha_channel = tensor[3]    # Alpha channel [256, 256]
    
    print(f"Red channel shape: {red_channel.shape}")
    print(f"Alpha channel mean: {alpha_channel.mean():.2f}")
    
    # Example: Create a custom RGB combination
    # Emphasize red channel, reduce blue
    enhanced_rgb = torch.stack([
        red_channel * 1.2,      # Enhance red
        green_channel,          # Keep green
        blue_channel * 0.8      # Reduce blue
    ], dim=0)
    
    return enhanced_rgb, tensor

# Usage example
enhanced_rgb, original_tensor = create_channel_separated_dataset('slide.iris', layer_index=1)
print(f"Enhanced RGB shape: {enhanced_rgb.shape}")  # [3, 256, 256]
print(f"Original RGBA shape: {original_tensor.shape}")  # [4, 256, 256]

This channel-separated format is particularly useful for:

• Custom color space transformations
• Advanced image augmentations
• Channel-specific analysis (e.g., studying alpha transparency patterns)
• Memory-efficient processing when you only need specific channels

For additional support and examples, visit the Iris-Codec GitHub repository.