Iris File Extension (IFE)

• Iris File Extension (IFE) is a modern, vendor-neutral binary container that optimizes real-time transfer and viewing of digital pathology whole slide images.
• IFE employs a structured offset-chain architecture with validation tags for O(1) tile lookup and robust corruption recovery.
• IFE integrates with web streaming and analysis tools while complementing DICOM archival standards for flexible, performance-oriented workflows.

The Iris File Extension (IFE) is a modern, vendor-agnostic, vendor-neutral, open-source binary container format for digital pathology whole slide images (WSI), designed specifically for performance-oriented viewing and transfer rather than long-term archival custody. In the 2025 specification paper, IFE is defined as a performance-oriented, ephemeral transport format that sits between long-term archives—typically DICOM in PACS or imaging archives—and high-performance whole slide viewers or analysis systems; the later server and client integration paper extends that model to native web streaming, OpenSeaDragon interoperability, and RESTful serving from a single slide container (Landvater et al., 21 Apr 2025, Landvater et al., 8 Aug 2025).

1. Ecosystem Role and Conceptual Position

IFE was introduced to address an unmet need for efficient real-time transfer and display in digital pathology. The specification situates it within a workflow in which the authoritative slide is stored as a single high-resolution DICOM image, then converted to Iris format when rapid viewing is needed, for example in primary diagnosis. In that workflow, Iris files may be served from a slide server or cached locally on a workstation and can be deleted when no longer needed because they can be regenerated quickly from DICOM (Landvater et al., 21 Apr 2025).

This positioning is defined in contrast to several existing format families. DICOM is described as authoritative, interoperable, and metadata-rich, but structured for radiology and not optimized for live WSI navigation, especially because DICOM WSI stores tiles as separate multi-frame objects with duplicated metadata and non-native pyramidal indexing. TIFF and vendor formats are often pyramidal and random-access, but the papers emphasize proprietary variants, complex tag ecosystems, and endianness issues, as well as a lack of tailoring to modern multi-threaded and GPU-accelerated pipelines. Deep Zoom Image (DZI) and directory-per-tile layouts are recognized as practical intermediate formats for some viewers, especially OpenSeaDragon-based systems, but they are characterized as heavily dependent on the filesystem and therefore fragile and difficult to manage at enterprise scale (Landvater et al., 21 Apr 2025).

IFE’s niche is therefore explicitly defined as a single binary container—one file per slide—containing tiles, pyramid levels, metadata, and annotations, while remaining compatible with DICOM as a metadata source and archival standard but not a replacement for DICOM. The server paper adds a related operational claim: IFE is intended as a primary WSI storage format that can be streamed efficiently to modern web viewers without conversion into millions of small tile files. This suggests two deployment interpretations: an ephemeral cache in DICOM-centric environments, and an operational primary object in viewer-facing stacks. The papers are nevertheless consistent on one point: IFE does not aim to supplant DICOM as the long-term archive or regulatory standard (Landvater et al., 21 Apr 2025, Landvater et al., 8 Aug 2025).

2. Binary Container Structure and Tile Indexing

An Iris file is organized as a sequence of data-blocks at 64-bit byte offsets. These data-blocks are linked by offsets forming an offset-chain. The specification defines two block families. Header blocks contain fixed fields, such as the file header, tile-table header, and clinical-metadata header. Array blocks follow the same model but terminate in a variable-length array whose entry size is stored explicitly to guarantee forward compatibility. All multi-byte values are little-endian, and floating-point values follow IEEE-754, which the paper notes makes files portable and trivially readable by languages such as JavaScript for files below 4 GB because of 32-bit limitations (Landvater et al., 21 Apr 2025).

The high-level structure is divided into four logical layers of blocks. The file header appears at the start of the file and contains a validation tag plus byte offsets to the tile-table header and clinical-metadata header. The tile-table header contains rendering essentials, including image codec type, pixel format, tile dimensions, and pointers to the layer-extents array and tile-offsets array. The clinical-metadata header is required, although most of its contents are optional; it points to attributes, associated images, ICC color profile, and annotations. The payload blocks contain raw byte arrays for compressed tile data, compressed associated images, ICC profile bytes, and annotation graphics (Landvater et al., 21 Apr 2025).

IFE is optimized for multi-pyramidal rendering. Multiple pyramid levels are encoded in a single container, and the layer-extents plus tile-offset structures provide a direct mapping from a tile coordinate to a file location. For each pyramid layer, the layer-extents array stores the number of tiles in the $x$ and $y$ directions and the layer’s scale relative to the base or reference layer. From that, the decoder constructs a global tile index $g$ that flattens the three-dimensional address $(L, x, y)$ into a single integer:

$$g = \bigg(\sum_{l' < L} N_{l'}\bigg) + (y \cdot W_L + x)$$

where $N_{l'}$ is the number of tiles in layer $l'$, $W_L$ is the number of tiles in $x$ at layer $L$, and $y$0 is the tile coordinate within that layer. Layers are ordered from lowest scale near the start of the file toward highest scale near the end for purposes of this indexing model, and tiles within a layer are ordered row-major from top-left to bottom-right. The tile-offsets array then stores, for each global index entry, the byte offset and compressed byte size of the corresponding tile, with sparse tiles represented by a special sparse-tile value. The decoder’s access path is correspondingly short: compute the global index, read the tile-offsets entry, seek to the stored offset, read the stored size, and decompress with the specified codec. The specification characterizes this as $y$1 lookup and as the core of Iris’s high-performance access pattern (Landvater et al., 21 Apr 2025).

The web-integration paper presents the same raster-order principle in the RESTful/OpenSeaDragon setting, where tiles within a given layer use a two-dimensional index $y$2:

$y$3

That form is exposed in the tile-serving URL model and implemented internally by the IrisTileSource for OpenSeaDragon (Landvater et al., 8 Aug 2025).

3. Validation Semantics, Structural Integrity, and Recovery

A distinctive aspect of IFE is its validation model. Every data-block begins with a 64-bit validation tag that encodes the block’s own byte offset. If a block begins at offset $y$4, then the first 8 bytes of that block also encode the integer $y$5, so a deserializer satisfies the invariant

$y$6

in the sense that the first field read from offset $y$7 must equal $y$8. If it does not, the structure is invalid. Immediately after that validation tag, the block stores a type-specific recovery tag that identifies the kind of block, such as tile-table header, attributes array, or another defined block type (Landvater et al., 21 Apr 2025).

This yields what the specification repeatedly describes as deep but cheap validation. A validator can follow the offset-chain starting from the file header, confirming at each step that the validation tag matches the expected byte offset and that the block type is appropriate, before any image data are decoded. The papers present this as computationally trivial and central to file safety and resilience. Partial corruption can be recognized without necessarily making the remainder of the file unusable, since validation is structural and block-local (Landvater et al., 21 Apr 2025).

The same mechanism supports corruption recovery. A recovery tool may scan the byte stream for positions $y$9 whose 8-byte value $g$0 satisfies $g$1, treating them as candidate block starts. The subsequent recovery tag identifies the block type. The specification states that this enables partial reconstruction of valid blocks and images even when some metadata segments are damaged, and the server paper reiterates the existence of deep validation routines and corruption recovery logic in the codec. This is especially relevant for large WSI objects vulnerable to partial disk or network corruption over time (Landvater et al., 21 Apr 2025, Landvater et al., 8 Aug 2025).

4. Compression, Metadata, Color Management, and Annotation Semantics

IFE is described as codec-agnostic but codec-aware. The container specifies how compressed tiles are stored and indexed, while the tile-table header records the codec used for tile image data and the pixel format, including channels, bit depth, and alpha-channel presence. Current officially supported codecs are JPEG and AVIF. The reference codec uses TurboJPEG for JPEG, and AVIF is explicitly justified in the specification as a future-proofing choice and as compatible with GPU acceleration. The specification also reserves constants for future codecs, including the proprietary Iris Codec compression algorithm, which is in development and not part of the current edition, as well as possible future support for JPEG 2000, JPEG XL, or HEVC/H.265 if the community requests it. Because tiles are encoded independently, codecs can be replaced or added without changing the higher-level file organization (Landvater et al., 21 Apr 2025).

Tile dimensions are recorded in the tile-table header. The specification notes that the reference encoder uses tiles fixed at 256×256 pixels, while the server paper states that IFE allows flexible tile sizes and layer magnifications. This combination indicates that the container records the parameters it uses rather than imposing a single universal pyramidal scheme at the serving layer (Landvater et al., 21 Apr 2025, Landvater et al., 8 Aug 2025).

Metadata are intentionally separated from the performance-critical rendering path. The clinical-metadata header is mandatory, but the structures it references are largely optional. The attributes array supports two representations. In the DICOM-compatible representation, attributes follow the DICOM PS3.3 tag/value model, supporting straightforward round-tripping between DICOM and Iris. In the ASCII/UTF-8 key-value representation, keys are encoded as ASCII and values as UTF-8 strings. The authors also describe an Iris Interoperability Standard (I2S) under development, intended to extend the metadata dictionary beyond DICOM PS3.3 for daily-use and vendor-specific viewer metadata while maintaining DICOM compatibility for core clinical fields. The papers explicitly state that an encoder may include no attributes at all or may include a rich metadata set (Landvater et al., 21 Apr 2025).

Color management is handled through a dedicated ICC profile block pointed to by the clinical-metadata header. Associated images are stored in their own array, where each entry includes a role label such as “thumbnail,” “slide_label,” or “macro,” plus codec or type, dimensions, and a pointer to the compressed byte stream. This allows packaging overview, label, and related images into the same slide object (Landvater et al., 21 Apr 2025).

IFE also includes first-class annotations. These are stored in a dedicated data-block array and positioned in a layer-agnostic coordinate system called slide space, defined in floating-point tile units at the coarsest layer, layer 0. For each axis,

$g$2

and an annotation is defined by a slide-space offset and size: $g$3, $g$4. The paper’s example places an annotation at about $g$5 tiles in $g$6 and $g$7 tile in width, independently of the underlying pixel grid. The annotation also has raster dimensions in pixels and may have a vector source such as text or SVG from which the raster is derived. The specification presents this separation as enabling resolution-independent semantic positioning together with resolution-appropriate rendering. Annotation records may include a unique annotation identifier, parent-child relationships, and annotation groups, which the paper identifies as especially important for machine-learning and classification workflows. Supported forms include text annotations, vector-derived graphics, and raster overlays (Landvater et al., 21 Apr 2025).

5. Software Stack, Serving Architecture, and Integration Patterns

The reference software ecosystem is divided into several layers. The low-level Iris-File-Extension library implements direct serialization and deserialization of IFE blocks and strict validation of byte streams against the specification. It contains no image codecs and no file I/O calls, leaving byte-stream provision to the caller, and it allows zero-copy deserialization where possible. It is released as C++ source under the MIT license with Python and JavaScript WebAssembly bindings. The higher-level Iris Codec Community Module is a drop-in encoder/decoder for IFE with an object-oriented API returning fully decompressed tiles; it handles IFE structure, metadata, and image codecs, supports JPEG and AVIF, integrates with Iris Core for GPU-accelerated decoding where available, and can losslessly copy compatible compressed tile streams when the source is already tiled at 256×256. If linked with OpenSlide, that particular build becomes GPLv2 because OpenSlide is GPLv2. The source is MIT-licensed, with Python bindings distributed as iris-codec on Conda-Forge and Iris-Codec on PyPI, plus JavaScript via WebAssembly compiled with Emscripten (Landvater et al., 21 Apr 2025).

The server-side integration paper adds the Iris RESTful Server, implemented in C++ using Boost Beast for HTTP and Boost Asio for asynchronous networking. The architecture is explicitly split into a networking stack and a file system stack, joined by lockless FIFO queues. Networking threads clear buffers and handle TCP, TLS/SSL, and HTTP parsing and writing; file system threads parse and validate REST requests, open and validate IFE files, memory-map slides into virtual memory, and read tile bytes or metadata. Once a slide is opened and validated, the server creates a memory-mapped, reference-counted slide handle shared across TCP sessions, allowing fast random access with predictable read patterns and reuse of the OS page cache (Landvater et al., 8 Aug 2025).

Two API surfaces are exposed. The native Iris RESTful API provides slide metadata at GET <URL>/slides/<slide-name>/metadata and tile retrieval at GET <URL>/slides/<slide-name>/layers/<layer>/tiles/<tile>. The same server also exposes selected DICOMweb WADO-RS endpoints: metadata at the study and instance levels and tile retrieval at frames/<tile>. In this mapping, one IFE slide is exposed as a DICOM series, each IFE layer is treated as an instance, and each tile within a layer is exposed as a frame. This gives existing DICOMweb-oriented systems a compatibility surface without changing the underlying IFE representation (Landvater et al., 8 Aug 2025).

Browser integration is provided through IrisTileSource, a TileSource subclass merged into the next OpenSeaDragon release. Rather than consuming a .dzi descriptor and a static directory tree of image tiles, IrisTileSource requests slide metadata from the server, configures the OpenSeaDragon pyramid automatically, computes raster-order tile indices internally using $g$8, and requests each tile using the Iris RESTful tile endpoint. The paper states that replacing DZI with IFE in an existing OpenSeaDragon viewer typically requires changing about four lines of configuration. That design is described as a drop-in replacement for DZI in OpenSeaDragon-based pathology viewers (Landvater et al., 8 Aug 2025).

Adoption patterns span several environments. The specification lists slide-server and IMS deployments in which DICOM or proprietary WSI is converted to Iris on ingest or first request, stored on high-speed NAS or local SSD, and optionally purged when slides become cold. Desktop or in-lab viewers can cache IFE locally for high-speed browsing. Web viewers may use JavaScript/WASM bindings together with HTTP range requests or future network protocols, while analysis pipelines can iterate tiles in bulk, read only selected layers or regions, and use annotation groups as labels for supervised learning. The reference implementations are tested on Linux, macOS, iOS, and Windows across x86-64, AMD64, arm64, aarch64, arm64v8, and arm7 where specified (Landvater et al., 21 Apr 2025).

The web server is also presented as a security-focused microservice. The paper emphasizes strict URL parsing, restricted static file serving, TLS support, optional self-signed 2048-bit RSA certificates for load-balancer-to-container encryption, and CORS configuration via wildcard or specific viewer-origin policy. A notable operational safeguard is that .iris slide files cannot be downloaded even when static HTTP serving is enabled, which the paper presents as preventing raw slide exfiltration (Landvater et al., 8 Aug 2025).

6. Performance Characteristics, Misconceptions, and Future Directions

The specification paper reports local and remote tile-access measurements using a 2020 13" MacBook Pro M1, 8 GB RAM, macOS 15.4, with batches of 10,000 tiles drawn from the highest-resolution layer. Three implementations were compared: DICOMweb (Slim viewer) over a gigabit network, WsiDicom using local DICOM, and Iris Codec using local Iris files.

Implementation	Tile access rate	Approx. time per tile
DICOMweb (Slim)	~5 tiles/s	~200 ms/tile
WsiDicom (local DICOM)	3400–4800 tiles/s	~0.25 ms/tile
Iris Codec (IFE)	6400–8100 tiles/s	~0.14 ms/tile

The same paper states that these time-per-tile values align with previous Iris Core rendering work reporting 0.10–0.16 ms/tile and full field-of-view rendering times $g$9 of 10–35 ms, which are faster than a 60 Hz display refresh cycle. It also explicitly cautions that the DICOMweb comparison includes network latency and therefore is not a pure format comparison, even though it reflects real-world remoted-viewing behavior (Landvater et al., 21 Apr 2025).

The server paper evaluates end-to-end HTTP tile serving with Locust under ramped load, comparing a private Iris deployment, a public Iris example domain, Path-Presenter serving DZI over static HTTP, and the NCI Imaging Data Commons Slim viewer serving DICOMweb WADO-RS.

System	Throughput	Response times (50% / 75% / 95%)
Iris Private Instance	3883 avg, 5061 max requests/s	21 ms / 33 ms / 63 ms
Iris RESTful Example	1241 avg, 1944 max requests/s	59 ms / 71 ms / 120 ms
Path-Presenter (DZI)	987 avg, 1560 max requests/s	79 ms / 93 ms / 160 ms
Slim (DICOMweb)	114 avg, 146 max requests/s	650 ms / 1.2 s / 2.3 s

The paper attributes the server-side performance to memory mapping of IFE slide files, reference-counted slide handles reused across sessions, separation of networking and filesystem stacks, lockless FIFOs, optimized C++ implementation with Boost Beast and Asio, and IFE’s computationally trivial validation and low-instruction-count reads. It also states that IFE encoding from DICOM or proprietary formats is highly parallelized because of layer-agnostic tile ordering, and that a full pyramid with 2× or 4× downsampling can be generated from a single high-resolution source in ~1–2 minutes with current Iris Codec implementations, faster when OpenSlide decoding is not required (Landvater et al., 8 Aug 2025).

Several misconceptions are addressed directly by the papers. First, IFE is not presented as a DICOM replacement; it is an ephemeral transport format or operational streaming format that complements DICOM archival practice. Second, static HTTP is not said to be impossible for IFE, because byte-range requests together with WebAssembly decoding are feasible, but the server paper argues that such a client-side approach is more complex and less efficient than a server that understands IFE natively. Third, the contrast with DZI is not simply about viewer compatibility: the papers emphasize filesystem explosion, preprocessing time, possible metadata loss, synchronization burden, and audit or lifecycle complexity in directory-per-tile workflows (Landvater et al., 21 Apr 2025, Landvater et al., 8 Aug 2025).

The future-work agenda is extensive. A dedicated Iris File Extension Networking Protocol is under development but not yet standardized. The proprietary Iris Codec compression algorithm remains in development and outside the current specification. Planned work includes GPU-based AV1 encoder support through Vulkan KHR Video Decode AV1 and Apple VideoToolbox, possible additional codec support such as JPEG2000, JPEG XL, and HEVC/H.265, more detailed publications on encoding speed and controlled-corruption recovery behavior, fuller definition of the I2S metadata standard, continued tuning of encoding and decoding paths, expanded DICOMweb and IMS/PACS integration, enhanced recovery tools, and scanner APIs for live stream encoding directly into both archival DICOM and IFE. The papers further state that future standards bodies might draw on IFE ideas such as the tile-table for later DICOM image object definitions, but that remains future work rather than current standardization (Landvater et al., 21 Apr 2025, Landvater et al., 8 Aug 2025).