Understanding the iloc Box in AVIF Format

This article provides a technical overview of the Item Location Box (iloc) within the AV1 Image File Format (AVIF). It explains what the iloc box is, how it functions as a spatial directory for file payloads, its structural parameters within the underlying ISO Base Media File Format, and why it is critical for decoding image data, transparency channels, and auxiliary metadata.

What Is the 'iloc' Box?

The AVIF format is built upon the ISO Base Media File Format (ISOBMFF) and the High Efficiency Image File Format (HEIF) container standard. In this architecture, raw compressed image data is separated from metadata and structural descriptions.

The iloc (Item Location) box is a fundamental structural atom that acts as an address book or lookup table. While descriptive boxes (such as iinf for Item Information) assign identifiers and types to distinct items in an image file, the iloc box provides the exact physical coordinates—offsets and lengths—where the raw payload for each item resides within the file.

Primary Functions of the 'iloc' Box

1. Mapping Item IDs to Byte Offsets
   Every distinct element of an AVIF file—including the primary AV1 bitstream, auxiliary alpha (transparency) channels, depth maps, thumbnails, and Exif/XMP metadata blocks—is assigned a numerical item_ID. The iloc box explicitly maps each item_ID to its storage location, typically pointing to byte ranges inside the mdat (Media Data) box.

2. Managing Data Extents
   The iloc box defines whether an item’s data is stored contiguously or broken into multiple segments called "extents." For each item, the box specifies an extent_count. If an item is split across non-contiguous chunks in the file, the iloc box lists the offset and length for each individual extent so the parser can reconstruct the continuous byte stream.

3. Defining Offset Precision and Construction Methods
   The header of the iloc box defines the size (in bytes) of offset and length fields (typically 4 or 8 bytes) to optimize file overhead for both small images and files larger than 4 gigabytes. It also indicates the construction_method, informing the reader whether offsets are calculated relative to the start of the file or relative to other structural elements, such as the idat (Item Data) box.

Structure of an 'iloc' Entry

For each registered item, an iloc entry contains the following core parameters:

• Item_ID: A unique 16-bit or 32-bit identifier matching the item defined in the iinf box.
• Data_reference_index: An index pointing to the data reference box (dref), indicating whether the payload is inside the current file or stored externally.
• Base_offset: A baseline byte offset applied to all extents belonging to this item.
• Extent_offset: The location of a specific data segment relative to the base offset or file origin.
• Extent_length: The total size in bytes of the specific data segment.

Why the 'iloc' Box Is Crucial for AVIF

Without the iloc box, a decoder would have no mechanism to extract the compressed AV1 video frames that constitute the image. It allows AVIF decoders to quickly parse the lightweight structural metadata at the beginning of the file and selectively read only the necessary byte ranges via targeted read operations (such as HTTP Range Requests). This design enables rapid header inspection, selective decoding of metadata, and efficient rendering in web browsers.