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.
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 iniinffrequently 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
ilocsupports item-relative and offset-based construction methods, and real files use them.
Do not write your own parser. libheif 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.
Common 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.