Properties are boxes in ipco, tied to items by ipma (see
Boxes and items). Descriptive properties
say what an image is; transformative ones (clap, irot,
imir) change how it is shown and are applied in their listed order after
decoding. Offsets below are from the end of the box header, and after version and
flags for a full box. All numbers are big-endian.
ispe: image size
Full box, version 0. Required for every image item.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
| 0 | 4 | u32 | image_width | Width of the decoded image in pixels, before any transformation. |
| 4 | 4 | u32 | image_height | Height in pixels. |
pixi: pixel information
Full box, version 0.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
| 0 | 1 | u8 | num_channels | Channels in the decoded image: 1 for monochrome, 3 for colour. |
| 1 | 1 each | u8 | bits_per_channel | Bit depth of each channel. |
colr: colour information
A plain box. An item may have one nclx and one ICC colr.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
| 0 | 4 | 4CC | colour_type | nclx for code points, rICC for a restricted ICC profile, prof for any ICC profile. |
| 4 | 2 | u16 | colour_primaries | nclx only; codes below. |
| 6 | 2 | u16 | transfer_characteristics | nclx only. |
| 8 | 2 | u16 | matrix_coefficients | nclx only. |
| 10 | 1 bit + 7 | bit | full_range_flag | nclx only: 1 for full-range samples, 0 for video range. The other 7 bits are reserved. |
| 4 | to end | bytes | ICC profile | rICC and prof: the whole profile. |
The codes are those of ITU-T H.273 (and ISO/IEC 23091-2), the same as in HEVC and AV1 video. 2 means unspecified in all three; unlisted values are reserved.
| Code | colour_primaries |
|---|---|
| 1 | BT.709 and sRGB |
| 2 | Unspecified |
| 4 | BT.470 System M |
| 5 | BT.470 System B, G (and BT.601 625-line) |
| 6 | BT.601 525-line (SMPTE 170M) |
| 7 | SMPTE 240M |
| 8 | Generic film (illuminant C) |
| 9 | BT.2020 and BT.2100 |
| 10 | SMPTE ST 428-1 (CIE XYZ) |
| 11 | SMPTE RP 431-2 (DCI-P3) |
| 12 | SMPTE EG 432-1 (Display P3) |
| 22 | EBU Tech. 3213-E |
| Code | transfer_characteristics |
|---|---|
| 1 | BT.709 |
| 2 | Unspecified |
| 4 | Gamma 2.2 (BT.470 System M) |
| 5 | Gamma 2.8 (BT.470 System B, G) |
| 6 | BT.601 |
| 7 | SMPTE 240M |
| 8 | Linear |
| 9 | Logarithmic, 100:1 range |
| 10 | Logarithmic, 100 × √10 : 1 range |
| 11 | IEC 61966-2-4 (xvYCC) |
| 12 | BT.1361 extended colour gamut |
| 13 | IEC 61966-2-1 (sRGB) |
| 14 | BT.2020, 10-bit |
| 15 | BT.2020, 12-bit |
| 16 | SMPTE ST 2084 (PQ, BT.2100) |
| 17 | SMPTE ST 428-1 |
| 18 | ARIB STD-B67 (HLG, BT.2100) |
| Code | matrix_coefficients |
|---|---|
| 0 | Identity: the samples are G, B, R (or X, Y, Z) |
| 1 | BT.709 |
| 2 | Unspecified |
| 4 | US FCC 73.682 |
| 5 | BT.470 System B, G (BT.601 625-line) |
| 6 | BT.601 525-line (SMPTE 170M) |
| 7 | SMPTE 240M |
| 8 | YCgCo |
| 9 | BT.2020 non-constant luminance |
| 10 | BT.2020 constant luminance |
| 11 | SMPTE ST 2085 (Y′D′zD′x) |
| 12 | Chromaticity-derived non-constant luminance |
| 13 | Chromaticity-derived constant luminance |
| 14 | ICtCp (BT.2100) |
An sRGB photo is usually 1, 13, 6 (or 1), full range. Code 3 is reserved in all three lists.
hvcC: HEVC decoder configuration
A plain box holding the HEVCDecoderConfigurationRecord of ISO/IEC 14496-15. Every
hvc1 item needs one; it carries the parameter sets.
| Offset | Bits | Name | Description |
|---|---|---|---|
| 0 | 8 | configurationVersion | 1. |
| 1 | 2 | general_profile_space | 0. |
| 1 | 1 | general_tier_flag | 0 Main tier, 1 High tier. |
| 1 | 5 | general_profile_idc | 1 Main, 2 Main 10, 3 Main Still Picture, 4 range extensions, 9 screen content (H.265 Annex A). |
| 2 | 32 | general_profile_compatibility_flags | Bit j set when the stream also conforms to profile j. |
| 6 | 48 | general_constraint_indicator_flags | As in the HEVC profile_tier_level syntax. |
| 12 | 8 | general_level_idc | 30 × the level number, e.g. 93 for level 3.1. |
| 13 | 4 + 12 | reserved, min_spatial_segmentation_idc | Reserved bits are 1. |
| 15 | 6 + 2 | reserved, parallelismType | 0 unknown, 1 slices, 2 tiles, 3 wavefront. |
| 16 | 6 + 2 | reserved, chromaFormat | 0 monochrome, 1 4:2:0, 2 4:2:2, 3 4:4:4. |
| 17 | 5 + 3 | reserved, bitDepthLumaMinus8 | Luma bit depth − 8. |
| 18 | 5 + 3 | reserved, bitDepthChromaMinus8 | Chroma bit depth − 8. |
| 19 | 16 | avgFrameRate | 0 for still images. |
| 21 | 2 | constantFrameRate | 0 for still images. |
| 21 | 3 | numTemporalLayers | |
| 21 | 1 | temporalIdNested | |
| 21 | 2 | lengthSizeMinusOne | Each NAL unit in the item data is preceded by its length in this + 1 bytes, usually 4. |
| 22 | 8 | numOfArrays | Then this many arrays: |
| +0 | 1 + 1 + 6 | array_completeness, reserved, NAL_unit_type | Type 32 VPS, 33 SPS, 34 PPS, 39 prefix SEI, 40 suffix SEI. |
| +1 | 16 | numNalus | Then each NAL unit as a u16 length and its bytes. |
To decode an hvc1 item, feed the VPS, SPS and PPS from here, then the
item’s NAL units, to an HEVC decoder.
irot, imir and clap: transformations
| Box | Size | Name | Description |
|---|---|---|---|
| irot | 6 bits + 2 bits | reserved, angle | Rotate anticlockwise by angle × 90°. |
| imir | 7 bits + 1 bit | reserved, axis | 0: mirror about a vertical axis (left and right swap). 1: mirror about a horizontal axis (top and bottom swap). |
| clap | u32, u32 | cleanApertureWidthN, D | Width of the crop, as a fraction. |
| u32, u32 | cleanApertureHeightN, D | Height of the crop. | |
| i32, u32 | horizOffN, D | Horizontal position of the crop’s centre minus (width − 1) ÷ 2. | |
| i32, u32 | vertOffN, D | Vertical position of the centre minus (height − 1) ÷ 2. |
The imir reading is libheif’s (bit set means a horizontal axis); this site has not read the HEIF text itself. Earlier HEIF drafts named the field differently, and some old files may disagree.
auxC: auxiliary image type
Full box, version 0, on an item that has an auxl reference to its
master image.
| Size | Type | Name | Description |
|---|---|---|---|
| varies | string | aux_type | Zero-terminated URN naming the kind of image. |
| to end | bytes | aux_subtype | Codec-specific detail; for HEVC, SEI messages such as depth representation information. |
| aux_type | Meaning |
|---|---|
urn:mpeg:hevc:2015:auxid:1 | Alpha plane (HEVC). |
urn:mpeg:hevc:2015:auxid:2 | Depth map (HEVC). |
urn:mpeg:mpegB:cicp:systems:auxiliary:alpha | Alpha plane, codec-independent (used by AVIF). |
urn:mpeg:mpegB:cicp:systems:auxiliary:depth | Depth map, codec-independent. |
urn:com:apple:photo:2020:aux:hdrgainmap | Apple’s HDR gain map, written by iPhones; not part of the standard. |
Other properties
| Box | Fields | Meaning |
|---|---|---|
| pasp | hSpacing u32, vSpacing u32 | Pixel aspect ratio, hSpacing : vSpacing. |
| lsel | layer_id u16 | Which layer of a layered image to show. |
| clli | max_content_light_level u16, max_pic_average_light_level u16 | HDR content light levels in cd/m². |
| mdcv | 3 × (x u16, y u16), white x u16, white y u16, max u32, min u32 | Mastering display: primaries and white point in steps of 0.00002, luminance in steps of 0.0001 cd/m², in the order of the HEVC mastering display SEI. |
| iscl | full box; target width numerator, denominator, target height numerator, denominator, each u16 | Scaling of the image. |
| udes | full box; lang, name, description, tags, four zero-terminated strings | A user description of the item. |
| rloc | full box; horizontal_offset u32, vertical_offset u32 | Position of this image within a larger reference image. |
libheif also knows newer properties from later amendments and related standards,
among them amve (ambient viewing environment), cmin and
cmex (camera intrinsics and extrinsics), and the uncompressed-image boxes
of ISO/IEC 23001-17. Their full definitions are not covered here.