dymokomi/luce-heic
Source of release 0.5.2
0.5.2 / src / heic / items.lucb
#==============================================================================================
#
# heic/items - Image items: the primary image's layout, coded and grid items, and alpha
#
# A coded item (hvc1) is one HEVC picture cropped by its conformance window. A grid item
# lists tiles (dimg) that are decoded one by one and copied into the output canvas,
# clipped at its right and bottom. An alpha plane comes from an auxiliary item (auxl)
# whose auxC names the HEVC or CICP alpha type.
#
#==============================================================================================
## One geometric transform, applied to the decoded image in association order.
struct Transform:
var kind: u32
## irot: the anticlockwise quarter turns; imir: 0 flips top to bottom, 1 left to
## right, as libheif and macOS read the axis field.
var value: u32
## clap: the crop rectangle.
var left: usize
var top: usize
var width: usize
var height: usize
## What the container says about the primary image.
struct Layout:
var primary: usize
## One more than the alpha item's index; 0 when there is no alpha.
var alpha: usize
## The decoded size (ispe), and the size after the transforms.
var coded_width: usize
var coded_height: usize
var width: usize
var height: usize
var bits: u32
var monochrome: bool
var icc: const u8[]
## nclx matrix_coefficients and full_range_flag; -1 when there is no nclx.
var matrix: i32
var full_range: i32
var transforms: Transform[4]
var transform_count: usize
## Refuses essential properties this decoder does not implement.
func check_properties(heif: const Heif*, item: const Item*) -> !:
for i in 0..<item.property_count:
let index = (usize)(item.properties[i] & 32767)
if index == 0 or index > heif.properties.length:
if index != 0:
error(corrupt, "HEIF property index is out of range")
continue
if (item.properties[i] & 32768) != 0:
var known = false
for kind in known_properties:
known = known or heif.properties[index - 1].kind == kind
if not known:
error(unsupported, "HEIF image has an essential property this decoder does not support")
## The image size an item's ispe states.
func item_size(heif: const Heif*, item: const Item*) -> (usize, usize)!:
let ispe = heif.property(item, box_ispe) else error(corrupt, "HEIF image item has no ispe")
var r = try ispe.reader(heif.data, 4)
let width = (usize)(try r.uint(4))
let height = (usize)(try r.uint(4))
if width == 0 or height == 0 or width > 1000000 or height > 1000000:
error(corrupt, "HEIF image size is out of range")
return (width, height)
## The hvcC of a coded item, or of a grid's first tile.
func item_config(heif: const Heif*, item: const Item*) -> Config!:
var coded = item
if item.kind == item_grid:
if item.tile_count == 0:
error(corrupt, "HEIF grid has no tiles")
coded = &heif.items[try heif.find(heif.tiles[item.first_tile])]
if coded.kind != item_hvc1:
error(unsupported, "HEIF image is not HEVC coded")
let hvcc = heif.property(coded, box_hvcc) else error(corrupt, "HEIF image item has no hvcC")
return try Config.open(heif.data[hvcc.body..<hvcc.end])
## Describes the primary image: sizes, bit depth, color, transforms and alpha.
func describe(heif: const Heif*) -> Layout!:
var layout = Layout(matrix = -1, full_range = -1)
layout.primary = try heif.find(heif.primary)
let item = &heif.items[layout.primary]
if item.kind != item_hvc1 and item.kind != item_grid:
error(unsupported, "HEIF primary image is not an HEVC or grid image (AVIF, overlays and others are not supported)")
try check_properties(heif, item)
let (width, height) = try item_size(heif, item)
layout.coded_width = width
layout.coded_height = height
let config = try item_config(heif, item)
layout.bits = config.bits
layout.monochrome = config.chroma == 0
if config.chroma > 1:
error(unsupported, "HEIC 4:2:2 and 4:4:4 chroma are not supported")
var w = width
var h = height
for i in 0..<item.property_count:
let index = (usize)(item.properties[i] & 32767)
if index == 0:
continue
let p = heif.properties[index - 1]
if p.kind == box_colr:
try colr_property(heif, p, &layout)
elif p.kind == box_clap or p.kind == box_irot or p.kind == box_imir:
if layout.transform_count == 4:
error(unsupported, "HEIF image has too many transforms")
var t = Transform(kind = p.kind)
var r = try p.reader(heif.data)
if p.kind == box_irot:
t.value = (u32)(try r.byte()) & 3
if (t.value & 1) == 1:
let swap = w
w = h
h = swap
elif p.kind == box_imir:
t.value = (u32)(try r.byte()) & 1
else:
try clean_aperture(&r, w, h, &t)
w = t.width
h = t.height
layout.transforms[layout.transform_count] = t
layout.transform_count += 1
layout.width = w
layout.height = h
if item.kind == item_grid and layout.matrix < 0 and layout.icc.length == 0:
# A grid without colr takes its first tile's, as macOS does.
try read_colr(heif, &heif.items[try heif.find(heif.tiles[item.first_tile])], &layout)
for i in 0..<heif.items.length:
let candidate = &heif.items[i]
if candidate.auxiliary_of == heif.primary and (candidate.kind == item_hvc1 or candidate.kind == item_grid):
if let aux = heif.property(candidate, box_auxc):
var r = try aux.reader(heif.data, 4)
let name = try r.cstring()
if name == "urn:mpeg:hevc:2015:auxid:1" or name == "urn:mpeg:mpegB:cicp:systems:auxiliary:alpha":
try check_properties(heif, candidate)
layout.alpha = i + 1
return layout
## Reads a colr property: nclx into the matrix and range, an ICC profile into `icc`.
func colr_property(heif: const Heif*, p: Box, layout: Layout*) -> !:
var r = try p.reader(heif.data)
let kind = (u32)(try r.uint(4))
if kind == colr_nclx and layout.matrix < 0:
_ = try r.uint(4)
layout.matrix = (i32)(try r.uint(2))
layout.full_range = (i32)(try r.byte() >> 7)
elif (kind == colr_prof or kind == colr_ricc) and layout.icc.length == 0:
layout.icc = r.data[4..]
## Reads every colr property of `item`.
func read_colr(heif: const Heif*, item: const Item*, layout: Layout*) -> !:
for i in 0..<item.property_count:
let index = (usize)(item.properties[i] & 32767)
if index > 0 and index <= heif.properties.length and heif.properties[index - 1].kind == box_colr:
try colr_property(heif, heif.properties[index - 1], layout)
## The clap crop of a `width` by `height` image, rounded down as ISO/IEC 23008-12 does.
func clean_aperture(r: Reader*, width: usize, height: usize, t: Transform*) -> !:
var values: f64[8]
for i in 0..<(usize)8:
let raw = try r.uint(4)
values[i] = (f64)(i32)(u32)raw if i >= 4 and (i & 1) == 0 else (f64)raw
if values[1] == 0.0 or values[3] == 0.0 or values[5] == 0.0 or values[7] == 0.0:
error(corrupt, "HEIF clean aperture has a zero denominator")
let clean_w = values[0] / values[1]
let clean_h = values[2] / values[3]
let centre_x = values[4] / values[5] + ((f64)width - 1.0) / 2.0
let centre_y = values[6] / values[7] + ((f64)height - 1.0) / 2.0
let left = math.floor(centre_x - (clean_w - 1.0) / 2.0)
let right = math.floor(centre_x + (clean_w - 1.0) / 2.0)
let top = math.floor(centre_y - (clean_h - 1.0) / 2.0)
let bottom = math.floor(centre_y + (clean_h - 1.0) / 2.0)
if not (left >= 0.0 and top >= 0.0 and right >= left and bottom >= top and right < (f64)width and bottom < (f64)height):
error(corrupt, "HEIF clean aperture lies outside the image")
t.left = (usize)left
t.top = (usize)top
t.width = (usize)(right - left) + 1
t.height = (usize)(bottom - top) + 1
## Decodes the primary image, and its alpha plane, into `planes`.
func render(heif: const Heif*, layout: const Layout*, planes: Planes*, max_bytes: usize, max_pixels: usize, threads: usize) -> !:
try render_item(heif, layout.primary, planes, max_bytes, max_pixels, threads)
if planes.width != layout.coded_width or planes.height != layout.coded_height:
error(corrupt, "HEIF image size differs from its coded pictures")
if (planes.chroma == 0) != layout.monochrome or planes.bits != layout.bits:
error(corrupt, "HEVC stream format differs from its hvcC configuration")
if layout.alpha != 0:
var alpha = Planes()
defer alpha.close()
try render_item(heif, layout.alpha - 1, &alpha, max_bytes, max_pixels, threads)
if alpha.width != planes.width or alpha.height != planes.height:
error(corrupt, "HEIF alpha image size differs from the image")
planes.alpha = alpha.luma
planes.alpha_bits = alpha.bits
var moved: u16[]
alpha.luma = moved
# The color description: nclx, else the stream's VUI (range absent means limited, as
# HEVC infers), else BT.709 for an unspecified matrix, as macOS ImageIO decodes.
planes.matrix = (u32)layout.matrix if layout.matrix >= 0 else planes.matrix
if planes.matrix == 2:
planes.matrix = 1
planes.full_range = layout.full_range == 1 if layout.full_range >= 0 else planes.full_range
## Decodes item `index` (coded or grid) into `planes`.
func render_item(heif: const Heif*, index: usize, planes: Planes*, max_bytes: usize, max_pixels: usize, threads: usize) -> !:
let item = &heif.items[index]
if item.kind == item_hvc1:
var pic = Picture()
defer pic.close()
try decode_coded(heif, item, &pic, max_bytes, max_pixels)
try start_planes(planes, &pic, pic.width - pic.crop_left - pic.crop_right, pic.height - pic.crop_top - pic.crop_bottom, max_bytes)
copy_picture(&pic, planes, 0, 0)
return
if item.kind != item_grid:
error(unsupported, "HEIF image item is not HEVC coded")
var descriptor = Buffer(maximum = 64)
defer descriptor.close()
try heif.item_data(item, &descriptor)
var r = Reader(data = descriptor.view(), little = false)
if try r.byte() != 0:
error(unsupported, "unsupported HEIF grid version")
let wide = ((try r.byte()) & 1) != 0
let rows = (usize)(try r.byte()) + 1
let columns = (usize)(try r.byte()) + 1
let width = (usize)(try r.uint(4 if wide else 2))
let height = (usize)(try r.uint(4 if wide else 2))
if rows * columns != item.tile_count or width == 0 or height == 0:
error(corrupt, "HEIF grid does not match its tiles")
if width * height > max_pixels:
error(limit, "HEIF grid exceeds the pixel limit")
# The first tile fixes the tile size and format; the rest decode in parallel.
var grid = Grid(heif = heif, item = item, planes = planes, columns = columns, max_bytes = max_bytes, max_pixels = max_pixels)
var pic = Picture()
defer pic.close()
try decode_coded(heif, try grid.tile(0), &pic, max_bytes, max_pixels)
grid.tile_w = pic.width - pic.crop_left - pic.crop_right
grid.tile_h = pic.height - pic.crop_top - pic.crop_bottom
if grid.tile_w * columns < width or grid.tile_h * rows < height:
error(corrupt, "HEIF grid tiles do not cover the image")
try start_planes(planes, &pic, width, height, max_bytes)
planes.tile_width = grid.tile_w
planes.tile_height = grid.tile_h
copy_picture(&pic, planes, 0, 0)
try run_tasks(item.tile_count - 1, threads, decode_tile, (void*)&grid)
## A grid being decoded: where its tiles go.
struct Grid:
var heif: const Heif*
var item: const Item*
var planes: Planes*
var columns: usize
var tile_w: usize
var tile_h: usize
var max_bytes: usize
var max_pixels: usize
## The coded item of tile `t`.
func tile(t: usize) -> const Item*!:
let tile = &self.heif.items[try self.heif.find(self.heif.tiles[self.item.first_tile + t])]
if tile.kind != item_hvc1:
error(unsupported, "HEIF grid tile is not HEVC coded")
return tile
## Decodes grid tile `task + 1` and copies it into place.
func decode_tile(raw: void*, task: usize) -> !:
let grid = (Grid*)raw
let t = task + 1
var pic = Picture()
defer pic.close()
try decode_coded(grid.heif, try grid.tile(t), &pic, grid.max_bytes, grid.max_pixels)
if pic.width - pic.crop_left - pic.crop_right != grid.tile_w or pic.height - pic.crop_top - pic.crop_bottom != grid.tile_h or pic.bits != grid.planes.bits or pic.chroma != grid.planes.chroma or pic.bits_c != pic.bits:
error(corrupt, "HEIF grid tiles differ in size or format")
copy_picture(&pic, grid.planes, (t % grid.columns) * grid.tile_w, (t // grid.columns) * grid.tile_h)
## Decodes one coded (hvc1) item into `pic`.
func decode_coded(heif: const Heif*, item: const Item*, pic: Picture*, max_bytes: usize, max_pixels: usize) -> !:
let hvcc = heif.property(item, box_hvcc) else error(corrupt, "HEIF image item has no hvcC")
var data = Buffer(maximum = max_bytes)
defer data.close()
try heif.item_data(item, &data)
try decode_picture(heif.data[hvcc.body..<hvcc.end], data.view(), pic, max_bytes, max_pixels)
## Allocates `planes` at `width` by `height` in the format of `pic`.
func start_planes(planes: Planes*, pic: const Picture*, width: usize, height: usize, max_bytes: usize) -> !:
planes.width = width
planes.height = height
planes.chroma = pic.chroma
planes.bits = pic.bits
planes.matrix = (u32)pic.matrix if pic.matrix >= 0 else 2
planes.full_range = pic.full_range == 1
if pic.bits_c != pic.bits:
error(unsupported, "HEVC luma and chroma bit depths differ")
let chroma = ((width + 1) >> 1) * ((height + 1) >> 1) if pic.chroma != 0 else 0
if (width * height + 2 * chroma) * 2 > max_bytes:
error(limit, "HEIF image exceeds the byte limit")
with memory.heap:
planes.luma = try new u16[width * height]
if pic.chroma != 0:
planes.cb = try new u16[chroma]
planes.cr = try new u16[chroma]
## Copies the cropped picture into `planes` at (x, y), clipped to the planes.
func copy_picture(pic: const Picture*, planes: Planes*, x: usize, y: usize):
let w = pic.width - pic.crop_left - pic.crop_right
let h = pic.height - pic.crop_top - pic.crop_bottom
let columns = w if x + w <= planes.width else planes.width - x
let rows = h if y + h <= planes.height else planes.height - y
for row in 0..<rows:
let source = (pic.crop_top + row) * pic.width + pic.crop_left
memory.copy(planes.luma[(y + row) * planes.width + x..], pic.luma[source..], columns)
if pic.chroma == 0:
return
let cw = (planes.width + 1) >> 1
let ccolumns = (columns + 1) >> 1
for row in 0..<(rows + 1) >> 1:
let source = ((pic.crop_top >> 1) + row) * pic.cwidth + (pic.crop_left >> 1)
let target = ((y >> 1) + row) * cw + (x >> 1)
memory.copy(planes.cb[target..], pic.cb[source..], ccolumns)
memory.copy(planes.cr[target..], pic.cr[source..], ccolumns)