AVIF Primary Image Designation in Meta Box

In the AV1 Image File Format (AVIF), the primary image item is identified using the Primary Item Box (pitm) located directly within the file's root metadata container (meta box). This article explains how the pitm box functions, details its internal binary structure, and illustrates how decoders use it to link the primary image identifier to byte locations and decoder configuration properties.

The Role of the meta Container

AVIF is built on the ISO Base Media File Format (ISOBMFF) and inherits its structural design from the High Efficiency Image File Format (HEIF). In an AVIF file, image assets are not stored as linear media tracks; instead, they are cataloged as discrete "items" inside a container box of type meta.

A single AVIF file can contain multiple items, including thumbnails, alpha channels, depth maps, and gain maps. Because multiple images can coexist within the same container, an explicit pointer is required to signal which item represents the main image to display.

The Primary Item Box (pitm)

The pitm box is a required structure inside the meta box whenever an AVIF file contains displayable image items. Its sole purpose is to declare the item_ID of the primary visual item.

The box structure follows the ISOBMFF FullBox definition:

aligned(8) class PrimaryItemBox extends FullBox('pitm', version, 0) {
    if (version == 0) {
        unsigned int(16) item_ID;
    } else {
        unsigned int(32) item_ID;
    }
}

• Box Type (type): The four-character code 'pitm'.
• Version:
  • 0: Uses a 16-bit integer for the item_ID (standard for most AVIF implementations).
  • 1: Uses a 32-bit integer for the item_ID (used if the file references more than 65,535 items).
• Flags: A 24-bit field set to 0.
• item_ID: The numerical identifier that matches the primary AV1 image item.

How Decoders Resolve the Primary Image

Once a decoder identifies the item_ID in the pitm box, it traverses several sibling boxes inside the meta box to retrieve and decode the primary image:

1. Item Information Box (iinf): The parser checks the infe (Item Info Entry) matching the item_ID to verify its item type. For an AVIF primary image, the item_type is typically set to 'av01', confirming that the item is an AV1-encoded image.
2. Item Properties Box (iprp): The parser matches the item_ID through an Item Property Association box (ipma). This associates the primary item with essential decoding properties, such as the AV1 configuration box (av1C), image dimensions (ispe), color profiles (colr), and pixel aspect ratios (pasp).
3. Item Location Box (iloc): The parser uses the item_ID to find the exact byte offsets and lengths of the encoded AV1 bitstream inside the file (commonly stored within the Media Data Box, 'mdat').

By reading the pitm box first, an AVIF decoder avoids scanning all embedded items and immediately extracts, configures, and renders the designated primary visual asset.