# How a HEIC file is structured

> A technical reference for anyone parsing these files: the box structure, the item model, and the parts that trip up naive implementations.

Source: https://jpg-heic.com/heic-file-format-specification | Section: Reference | Updated: 2026-08-31

## Where the format comes from

HEIF is defined in **ISO/IEC 23008-12**, part 12 of the MPEG-H family. It is built on the
 **ISO Base Media File Format** (ISO/IEC 14496-12), the same foundation as MP4, which is why HEIC
 files are structured as a tree of boxes rather than a header followed by pixel data.

That inheritance is the source of both its power and its awkwardness. The container was designed for
 time-based media, and still images were fitted into that model as a special case where the timeline
 has a single point.

## Top-level box structure

| Box | Name | Purpose |
|---|---|---|
| ftyp | File Type | Brand identifiers — heic, mif1, msf1 |
| meta | Metadata | Container for everything describing the items |
| hdlr | Handler | Declares the content type, pict for images |
| pitm | Primary Item | Which item ID is the main image |
| iinf | Item Info | Lists every item with its ID and type |
| iloc | Item Location | Byte offsets and lengths for each item |
| iprp | Item Properties | Dimensions, rotation, colour profile, decoder config |
| iref | Item Reference | Relationships — thumbnails, depth maps, derivations |
| mdat | Media Data | The actual compressed bitstreams |

## The item model

Every image in a HEIC is an **item** with a numeric ID. A single file might contain item 1 as the
 primary image, item 2 as its thumbnail, item 3 as a depth map, and item 4 as an alpha channel. The
 `iref` box records how they relate; the `pitm` box says which one to display.

Items are not always stored images. **Derived items** describe transformations applied to other
 items — a grid item assembles tiles into one large image, and an identity item applies rotation or
 cropping without re-encoding. A parser that ignores derived items will get the wrong picture, or none,
 from a file that other software handles fine.

## Properties worth knowing

 - `ispe` — image spatial extent, the stored pixel dimensions.

 - `hvcC` — HEVC decoder configuration, holding the VPS, SPS and PPS parameter sets.

 - `irot` — rotation in 90° increments, applied at display time.

 - `imir` — mirroring, horizontal or vertical.

 - `clap` — clean aperture, a crop applied at display time.

 - `colr` — colour information, either an ICC profile or NCLX coefficients.

 - `pixi` — bits per channel, which is how 10-bit files are identified.

 - `auxC` — auxiliary type, marking depth maps and alpha channels.

The order of operations matters and is specified: `clap` first, then `irot`,
 then `imir`. Getting that sequence wrong produces images that are correct in dimension but
 wrong in orientation — a common bug in first-pass implementations.

## Where naive parsers go wrong

 - **Assuming one image per file**
 Always read `pitm`. Taking the first item in `iinf` frequently returns the
 thumbnail instead of the photo.

 - **Ignoring derived items**
 Grid-derived images are common in high-resolution captures. The primary item may be a recipe
 rather than a bitstream.

 - **Skipping transformative properties**
 Rotation and cropping live in properties, not in the pixel data. Ignoring them yields sideways or
 oversized images.

 - **Assuming 8-bit**
 Check `pixi`. Ten-bit files are increasingly common and overflow buffers sized for
 8-bit data.

 - **Assuming construction method 0**
 `iloc` supports item-relative and offset-based construction methods, and real files
 use them.

 **Do not write your own parser.** [libheif](https://jpg-heic.com/heic-file-format-specification) is the
 reference open-source implementation, is well maintained, and handles the edge cases above along
 with many others. Every browser-based HEIC tool worth using, including this one, wraps it rather
 than reimplementing it.

## Frequently asked questions

**What standard defines the HEIC format?**

ISO/IEC 23008-12, part 12 of MPEG-H, which specifies the HEIF container. It builds on the ISO Base Media File Format, ISO/IEC 14496-12, the same foundation as MP4.

**How are multiple images stored in one HEIC file?**

Each image is an item with a numeric ID, listed in the iinf box and located through iloc. The pitm box identifies the primary image, and iref records relationships such as thumbnails and depth maps.

**Why do some HEIC files decode to the wrong orientation?**

Rotation is stored as an irot property applied at display time rather than baked into the pixels. Parsers that ignore item properties produce correctly sized but incorrectly oriented images.

**What is a derived image item?**

An item that describes a transformation of other items rather than containing its own bitstream — a grid assembling tiles, or an identity item applying rotation or cropping without re-encoding.