dymokomi/luce-heic
Source of release 0.5.1
0.5.1 / src / heic / module.lucb
#==============================================================================================
#
# heic - A HEIC/HEIF still-image decoder
#
# DESCRIPTION:
# Reads the primary image of a HEIF file whose pictures are HEVC coded, as iPhones and
# macOS write them: the ISO BMFF container, grid images made of tiles, an auxiliary
# alpha image, the clean aperture, rotation and mirroring, and the nclx or ICC color
# description. The HEVC decoder is intra only (I slices of the Main, Main 10 and Main
# Still Picture profiles, 4:2:0 and 4:0:0 up to 12 bits) with tiles, wavefront rows,
# scaling lists, PCM, transform skip, lossless blocks, deblocking and SAO. Everything is
# Luce Base: no platform codec is used. Fragments, in ORDER:
#
# module.lucb the public API: is_heic, probe, decode, decode_planes
# container.lucb ISO BMFF boxes, items, properties, references and item data
# bitstream.lucb NAL framing, emulation prevention and Exp-Golomb bit reading
# params.lucb VPS/SPS/PPS parsing and scaling lists
# slice.lucb slice segment headers
# cabac.lucb the arithmetic decoder and its context initialisation
# picture.lucb the picture, its per-block maps and tile scan tables
# syntax.lucb coding tree units, coding units, transform trees and SAO syntax
# residual.lucb residual coding: last position, significance maps and levels
# transform.lucb dequantisation, scaling lists and the inverse DCT/DST
# intra.lucb reference samples, their filtering and the 35 intra modes
# filters.lucb the deblocking filter
# sao.lucb sample adaptive offset
# stream.lucb decoding one item's HEVC stream into a picture
# items.lucb coded and grid items, alpha, and the image layout
# color.lucb YCbCr to RGB, chroma upsampling, rotation and mirroring
# parallel.lucb running grid tiles and output bands on worker threads
# tests.lucb unit, corpus and malformed-input tests
#
#==============================================================================================
import memory
from luce_std import math
import thread
from luce_raster.binary import Reader, Buffer, slice
from luce_raster.model import Raster, SampleType
from luce_raster.errors import corrupt, unsupported, invalid, limit
## The decoded primary image before color conversion: planes at the image grid's size
## (tiles assembled, conformance window applied), not yet cropped by the clean aperture,
## rotated or mirrored. Samples are integers of `bits` bits.
pub struct Planes:
pub var width: usize
pub var height: usize
## 0 for monochrome (luma only), 1 for 4:2:0 chroma.
pub var chroma: u32
pub var bits: u32
pub var luma: u16[]
## The chroma planes, `(width + 1) // 2` by `(height + 1) // 2`, empty when monochrome.
pub var cb: u16[]
pub var cr: u16[]
## The auxiliary alpha image's luma, the same size as `luma`, or empty.
pub var alpha: u16[]
pub var alpha_bits: u32
## The YCbCr to RGB matrix (ISO/IEC 23091-2 MatrixCoefficients: 1 BT.709, 5 and 6
## BT.601, 9 BT.2020, 0 GBR) and range, from the nclx box, else the stream's VUI,
## else BT.709 limited range as HEVC and macOS assume. iPhones write nclx or VUI.
pub var matrix: u32
pub var full_range: bool
## The tile size of a grid image, 0 for a single coded picture.
pub var tile_width: usize
pub var tile_height: usize
pub func close():
with memory.heap:
if self.luma.length > 0:
free(self.luma)
if self.cb.length > 0:
free(self.cb)
if self.cr.length > 0:
free(self.cr)
if self.alpha.length > 0:
free(self.alpha)
self = Planes()
## True when `data` starts with an ISO BMFF `ftyp` box whose major or compatible brands
## name HEVC-coded HEIF (heic, heix, heim, heis, hevc, hevx) or plain HEIF (mif1, msf1).
pub func is_heic(data: const u8[]) -> bool:
if data.length < 16 or data[4] != 'f' or data[5] != 't' or data[6] != 'y' or data[7] != 'p':
return false
let size = ((usize)data[0] << 24) | ((usize)data[1] << 16) | ((usize)data[2] << 8) | (usize)data[3]
let end = size if size >= 16 and size <= data.length else 16
var position: usize = 8
while position + 4 <= end:
if is_brand(read32(data, position)):
return true
position += 8 if position == 8 else 4
return false
## Reads the container and sets the size, channels ("R", "G", "B" and "A", or "Y" and "A"
## for monochrome), sample type (uint8, or uint16 above 8 bits) and `file_format` "HEIC".
## An ICC profile becomes the "icc_profile" attribute.
pub func probe(image: Raster*) -> !:
var heif: Heif
defer heif.close()
try parse_heif(image.encoded, &heif)
let layout = try describe(&heif)
image.width = layout.width
image.height = layout.height
image.bits = (usize)layout.bits
let count: usize = (1 if layout.monochrome else 3) + (1 if layout.alpha != 0 else 0)
try image.standard(count, .uint8 if layout.bits == 8 else .uint16)
if layout.icc.length > 0:
try image.attribute("icc_profile", "icc", layout.icc)
_ = try image.validate()
image.file_format = "HEIC"
## Decodes the primary image into `image.pixels`, which the caller allocated after `probe`.
## Values are the image's integer units: 0-255, or 0-65535 above 8 bits. Grid tiles and
## the color conversion run on up to `threads` threads.
pub func decode(image: Raster*, threads: usize = 1) -> !:
var heif: Heif
defer heif.close()
try parse_heif(image.encoded, &heif)
let layout = try describe(&heif)
let count: usize = (1 if layout.monochrome else 3) + (1 if layout.alpha != 0 else 0)
if layout.width != image.width or layout.height != image.height or count != image.channels.length or image.pixels.length != layout.width * layout.height * count:
error(invalid, "HEIC raster does not match its probe or its pixels are not allocated")
var planes: Planes
defer planes.close()
try render(&heif, &layout, &planes, image.max_bytes, image.max_pixels, threads)
try convert(&planes, &layout, image.pixels, threads)
## Decodes the primary image of the HEIF file in `data` into `planes`, with its alpha plane
## when the file has one, for callers that do their own color conversion. Grid tiles
## decode on up to `threads` threads.
pub func decode_planes(data: const u8[], planes: Planes*, max_bytes: usize = 1073741824, max_pixels: usize = 268435456, threads: usize = 1) -> !:
var heif: Heif
defer heif.close()
try parse_heif(data, &heif)
let layout = try describe(&heif)
planes.close()
try render(&heif, &layout, planes, max_bytes, max_pixels, threads)