HEIC: derived images and metadata

A derived image item has no coded data of its own. Its item data is a short description, usually kept in idat, and its inputs are the items its dimg reference lists, in order. Phones store large photos this way: an iPhone photo’s primary item is a grid of 512 × 512 HEVC tiles, each tile a hidden hvc1 item. Item types and references are on Boxes and items.

grid: image grid

Offset	Size	Type	Name	Description
0	1	u8	version	0.
1	1	u8	flags	Bit 0 set: the output size fields are 32-bit; clear: 16-bit.
2	1	u8	rows_minus_one	Rows of tiles − 1.
3	1	u8	columns_minus_one	Columns of tiles − 1.
4	2 or 4	uint	output_width	Width of the assembled image.
6 or 8	2 or 4	uint	output_height	Height of the assembled image.

The dimg reference lists rows × columns input images in row-major order, all the same size. They are placed edge to edge from the top left, and the result is cut to output_width × output_height, so the last column and row may hang over the edge. Transformations such as irot on the grid item apply to the assembled image; the tiles themselves are not rotated.

A 4032 × 3024 photo in 512 × 512 tiles needs 8 columns and 6 rows: 00 00 05 07 0F C0 0B D0 (version 0, 16-bit sizes, rows − 1 = 5, columns − 1 = 7, width 4032, height 3024).

iovl: image overlay

Offset	Size	Type	Name	Description
0	1	u8	version	0.
1	1	u8	flags	Bit 0 set: sizes and offsets are 32-bit; clear: 16-bit.
2	8	u16 × 4	canvas_fill_value	Red, green, blue and alpha of the background, each scaled to 0 to 65535.
10	2 or 4	uint	output_width	Canvas width.
…	2 or 4	uint	output_height	Canvas height.
…	2 or 4 each	int	horizontal_offset, vertical_offset	One signed pair per input image, in `dimg` order: where its top-left corner goes.

Inputs are drawn in order, later ones over earlier ones, and anything outside the canvas is cut off.

iden: identity

An iden item has no data and exactly one input. It is that image with the iden item’s own properties applied, such as a crop or rotation, so one coded image can be offered in several forms.

Thumbnails, alpha and depth

Thumbnail: an image item with a thmb reference to the image it shows in small.
Alpha: a monochrome image item with an auxl reference to its master and an auxC alpha type. If the master has a prem reference to it, the colour is premultiplied.
Depth: as alpha, with a depth auxC type; the aux_subtype bytes say how values map to distance.
Auxiliary images are usually hidden, and are the same size as their master or scaled to it.

Exif and XMP items

Metadata items point at the image they describe with a cdsc reference.

Offset	Size	Type	Name	Description
0	4	u32	exif_tiff_header_offset	Bytes from the end of this field to the TIFF header of the Exif data. Often 6, skipping the text `Exif\0\0`.
4	to end	bytes	Exif data	A TIFF-structured Exif block, starting `II` or `MM` at the offset above.

XMP is a mime item whose content_type is application/rdf+xml; its data is the XMP packet. Readers turn the image with irot and imir; an Exif orientation tag in the metadata is informative and is not applied again.

Showing the primary image

Read pitm, then the item’s type in iinf.
For a coded item, gather its bytes from iloc, prepend the parameter sets from its decoder configuration (hvcC) and decode.
For a grid, decode each dimg input and place it; for iovl, draw the inputs on the canvas; for iden, take the input.
Apply the item’s clap, irot and imir in the order ipma lists them.
Convert to RGB with the colr codes or profile, and combine with the alpha item if there is one.