Skip to content

LightCraft: An open-source non-destructive photo editor written by scratch in pure Rust

18.3 KB
Raw Blame
//! Synthetic HEIF files for tests (feature `testdata`): lossless, so every decoded sample is known.
//!
//! Each coded picture is one 32 × 32 coding tree unit stored as PCM samples (H.265 7.3.8.7):
//! the bitstream carries the YCbCr values verbatim, so the decoder's HEVC stage reproduces them
//! exactly and a test checks everything after it (grid composition, colour, transforms,
//! metadata) against values it chose. The few CABAC bins around the PCM data are written with a
//! minimal arithmetic encoder (9.3.4.4). Larger images are grids of such pictures, which is how
//! iPhones store photos too (with 512 × 512 tiles).
//!
//! Not a general HEIF or HEVC writer: 4:2:0 or monochrome, 8 or 10 bits, a CTU per picture.

/// Side of every coded picture.
pub const TILE: u32 = 32;

/// YCbCr samples at a luma position (chroma is taken at even positions, 4:2:0).
pub type Sampler<'a> = &'a dyn Fn(u32, u32) -> [u16; 3];

/// A property of the primary image.
#[derive(Debug, Clone, PartialEq)]
pub enum Prop {
    /// `colr` of type `prof`.
    Icc(Vec<u8>),
    /// `colr` of type `nclx`: primaries, transfer, matrix, full range.
    Nclx(u16, u16, u16, bool),
    /// `irot`: quarter turns counter-clockwise.
    Irot(u8),
    /// `imir` with this axis.
    Imir(u8),
    /// `clap`: width, height, horizontal and vertical offset (whole pixels).
    Clap(u32, u32, i32, i32),
}

/// What [`build`] writes.
pub struct Spec<'a> {
    /// Displayed (grid output) size, before transforms.
    pub width: u32,
    pub height: u32,
    pub bit_depth: u8,
    pub sample: Sampler<'a>,
    /// Properties of the primary image, in association order.
    pub props: Vec<Prop>,
    /// EXIF as a TIFF structure (written with HEIF's 4-byte offset header).
    pub exif: Option<Vec<u8>>,
    /// An alpha auxiliary image (monochrome, full range).
    pub alpha: Option<&'a dyn Fn(u32, u32) -> u16>,
    /// A thumbnail item of half the size with these samples (in its own coordinates).
    pub thumbnail: Option<Sampler<'a>>,
    /// Auxiliary images of these types the decoder must ignore (HDR gain map, depth…).
    pub ignored_aux: Vec<&'static str>,
}

impl<'a> Spec<'a> {
    pub fn new(width: u32, height: u32, sample: Sampler<'a>) -> Spec<'a> {
        Spec { width, height, bit_depth: 8, sample, props: Vec::new(), exif: None, alpha: None, thumbnail: None, ignored_aux: Vec::new() }
    }
}

#[derive(Default)]
struct Bits {
    bytes: Vec<u8>,
    n: usize,
}

impl Bits {
    fn put(&mut self, v: u32, len: u32) {
        for i in (0..len).rev() {
            if self.n.is_multiple_of(8) {
                self.bytes.push(0);
            }
            if (v >> i) & 1 == 1
                && let Some(b) = self.bytes.last_mut()
            {
                *b |= 0x80 >> (self.n % 8);
            }
            self.n += 1;
        }
    }

    fn ue(&mut self, v: u32) {
        let x = u64::from(v) + 1;
        let len = 64 - x.leading_zeros();
        self.put(0, len - 1);
        self.put((x & 0xffff_ffff) as u32, len);
    }

    fn align_zero(&mut self) {
        while !self.n.is_multiple_of(8) {
            self.put(0, 1);
        }
    }

    fn trailing(&mut self) {
        self.put(1, 1);
        self.align_zero();
    }
}

/// The CABAC arithmetic encoder of H.265 9.3.4.4, for the bins these pictures need.
struct Cabac {
    low: u32,
    range: u32,
    first: bool,
    outstanding: u32,
}

impl Cabac {
    fn new() -> Cabac {
        Cabac { low: 0, range: 510, first: true, outstanding: 0 }
    }

    fn put_bit(&mut self, out: &mut Bits, b: u32) {
        if self.first {
            self.first = false;
        } else {
            out.put(b, 1);
        }
        while self.outstanding > 0 {
            out.put(1 - b, 1);
            self.outstanding -= 1;
        }
    }

    fn renorm(&mut self, out: &mut Bits) {
        while self.range < 256 {
            if self.low < 256 {
                self.put_bit(out, 0);
            } else if self.low >= 512 {
                self.low -= 512;
                self.put_bit(out, 1);
            } else {
                self.low -= 256;
                self.outstanding += 1;
            }
            self.range <<= 1;
            self.low <<= 1;
        }
    }

    /// `part_mode` = PART_2Nx2N: the most probable symbol of a fresh context (initValue 184 at
    /// QP 26 gives pStateIdx 0, valMps 1), so the LPS range is `rangeTabLps[0][3]` = 240.
    fn part_mode_2nx2n(&mut self, out: &mut Bits) {
        let lps = [128, 176, 208, 240][((self.range >> 6) & 3) as usize];
        self.range -= lps;
        self.renorm(out);
    }

    /// A terminating bin equal to 1 (`pcm_flag`, `end_of_slice_segment_flag`), with the flush.
    fn terminate_one(&mut self, out: &mut Bits) {
        self.range -= 2;
        self.low += self.range;
        self.range = 2;
        self.renorm(out);
        self.put_bit(out, (self.low >> 9) & 1);
        out.put(((self.low >> 7) & 3) | 1, 2);
    }
}

fn nal(kind: u8, rbsp: &[u8]) -> Vec<u8> {
    let mut out = vec![kind << 1, 1];
    let mut zeros = 0;
    for &b in rbsp {
        if zeros >= 2 && b <= 3 {
            out.push(3);
            zeros = 0;
        }
        zeros = if b == 0 { zeros + 1 } else { 0 };
        out.push(b);
    }
    out
}

fn profile_idc(bit_depth: u8, mono: bool) -> u32 {
    match (bit_depth, mono) {
        (_, true) => 4, // range extensions
        (8, false) => 1,
        _ => 2,
    }
}

fn ptl(w: &mut Bits, idc: u32) {
    w.put(0, 2);
    w.put(0, 1);
    w.put(idc, 5);
    w.put(1 << (31 - idc), 32); // compatible with itself
    w.put(0b1001, 4); // progressive, frame only
    w.put(0, 22);
    w.put(0, 21);
    w.put(0, 1);
    w.put(93, 8); // level 3.1
}

fn parameter_sets(bit_depth: u8, mono: bool) -> [Vec<u8>; 3] {
    let idc = profile_idc(bit_depth, mono);
    let bd = u32::from(bit_depth);
    let mut v = Bits::default();
    v.put(0, 4);
    v.put(3, 2);
    v.put(0, 6);
    v.put(0, 3);
    v.put(1, 1);
    v.put(0xffff, 16);
    ptl(&mut v, idc);
    v.put(0, 1); // vps_sub_layer_ordering_info_present_flag
    v.ue(0);
    v.ue(0);
    v.ue(0);
    v.put(0, 6); // vps_max_layer_id
    v.ue(0); // vps_num_layer_sets_minus1
    v.put(0, 1); // vps_timing_info_present_flag
    v.put(0, 1); // vps_extension_flag
    v.trailing();

    let mut s = Bits::default();
    s.put(0, 4);
    s.put(0, 3);
    s.put(1, 1);
    ptl(&mut s, idc);
    s.ue(0);
    s.ue(if mono { 0 } else { 1 });
    s.ue(TILE);
    s.ue(TILE);
    s.put(0, 1); // conformance_window_flag
    s.ue(bd - 8);
    s.ue(bd - 8);
    s.ue(4);
    s.put(1, 1);
    s.ue(0);
    s.ue(0);
    s.ue(0);
    s.ue(2); // log2_min_luma_coding_block_size_minus3: 32
    s.ue(0); // log2_diff_max_min_luma_coding_block_size: CTB 32
    s.ue(0); // log2_min_luma_transform_block_size_minus2: 4
    s.ue(3); // log2_diff_max_min_luma_transform_block_size: 32
    s.ue(0);
    s.ue(0);
    s.put(0, 1); // scaling_list_enabled_flag
    s.put(0, 1); // amp_enabled_flag
    s.put(0, 1); // sample_adaptive_offset_enabled_flag
    s.put(1, 1); // pcm_enabled_flag
    s.put(bd - 1, 4); // pcm_sample_bit_depth_luma_minus1
    s.put(bd - 1, 4); // pcm_sample_bit_depth_chroma_minus1
    s.ue(2); // log2_min_pcm_luma_coding_block_size_minus3: 32
    s.ue(0); // log2_diff_max_min_pcm_luma_coding_block_size
    s.put(1, 1); // pcm_loop_filter_disabled_flag
    s.ue(0); // num_short_term_ref_pic_sets
    s.put(0, 1); // long_term_ref_pics_present_flag
    s.put(0, 1); // sps_temporal_mvp_enabled_flag
    s.put(0, 1); // strong_intra_smoothing_enabled_flag
    s.put(0, 1); // vui_parameters_present_flag
    s.put(0, 1); // sps_extension_present_flag
    s.trailing();

    let mut p = Bits::default();
    p.ue(0);
    p.ue(0);
    p.put(0, 6); // dependent slices, output flag, 3 extra header bits, sign hiding
    p.put(0, 1); // cabac_init_present_flag
    p.ue(0);
    p.ue(0);
    p.ue(0); // init_qp_minus26 (se(0) is the same bits)
    p.put(0, 3); // constrained intra, transform skip, cu_qp_delta
    p.ue(0);
    p.ue(0);
    p.put(0, 1);
    p.put(0, 2);
    p.put(0, 1); // transquant_bypass_enabled_flag
    p.put(0, 1); // tiles_enabled_flag
    p.put(0, 1); // entropy_coding_sync_enabled_flag
    p.put(0, 1); // pps_loop_filter_across_slices_enabled_flag
    p.put(1, 1); // deblocking_filter_control_present_flag
    p.put(0, 1); // deblocking_filter_override_enabled_flag
    p.put(1, 1); // pps_deblocking_filter_disabled_flag
    p.put(0, 1);
    p.put(0, 1);
    p.ue(0);
    p.put(0, 1);
    p.put(0, 1);
    p.trailing();
    [nal(32, &v.bytes), nal(33, &s.bytes), nal(34, &p.bytes)]
}

/// One coded 32 × 32 picture: the `hvcC` payload and the item data (length-prefixed NAL).
struct Coded {
    hvcc: Vec<u8>,
    data: Vec<u8>,
}

fn picture(bit_depth: u8, mono: bool, sample: &dyn Fn(u32, u32) -> [u16; 3]) -> Coded {
    let bd = u32::from(bit_depth);
    let mut w = Bits::default();
    w.put(1, 1); // first_slice_segment_in_pic_flag
    w.put(0, 1); // no_output_of_prior_pics_flag
    w.ue(0);
    w.ue(2); // I slice
    w.ue(0); // slice_qp_delta, se(0)
    w.trailing(); // byte_alignment()
    let mut c = Cabac::new();
    c.part_mode_2nx2n(&mut w);
    c.terminate_one(&mut w); // pcm_flag
    w.align_zero(); // pcm_alignment_zero_bit
    for y in 0..TILE {
        for x in 0..TILE {
            w.put(u32::from(sample(x, y)[0]), bd);
        }
    }
    if !mono {
        for k in 1..3 {
            for y in 0..TILE / 2 {
                for x in 0..TILE / 2 {
                    w.put(u32::from(sample(2 * x, 2 * y)[k]), bd);
                }
            }
        }
    }
    let mut c = Cabac::new();
    c.terminate_one(&mut w); // end_of_slice_segment_flag (its flush ends in the stop bit)
    w.align_zero();
    let slice = nal(19, &w.bytes);

    let sets = parameter_sets(bit_depth, mono);
    let mut h = vec![1u8, profile_idc(bit_depth, mono) as u8];
    h.extend_from_slice(&(1u32 << (31 - profile_idc(bit_depth, mono))).to_be_bytes());
    h.extend_from_slice(&[
        0x90,
        0,
        0,
        0,
        0,
        0,
        93,
        0xf0,
        0,
        0xfc,
        0xfc | u8::from(!mono),
        0xf8 | (bit_depth - 8),
        0xf8 | (bit_depth - 8),
        0,
        0,
        0x0f,
        3,
    ]);
    for (kind, set) in [32u8, 33, 34].into_iter().zip(&sets) {
        h.push(0x80 | kind);
        h.extend_from_slice(&1u16.to_be_bytes());
        h.extend_from_slice(&(set.len() as u16).to_be_bytes());
        h.extend_from_slice(set);
    }
    let mut data = (slice.len() as u32).to_be_bytes().to_vec();
    data.extend_from_slice(&slice);
    Coded { hvcc: h, data }
}

fn bx(kind: &[u8; 4], payload: &[u8]) -> Vec<u8> {
    let mut v = ((payload.len() + 8) as u32).to_be_bytes().to_vec();
    v.extend_from_slice(kind);
    v.extend_from_slice(payload);
    v
}

fn full_box(kind: &[u8; 4], version: u8, payload: &[u8]) -> Vec<u8> {
    let mut p = vec![version, 0, 0, 0];
    p.extend_from_slice(payload);
    bx(kind, &p)
}

struct Item {
    id: u16,
    kind: &'static [u8; 4],
    data: Vec<u8>,
    /// Indices (1-based) into the property list, with the essential flag.
    props: Vec<(u8, bool)>,
    /// Not an image of its own (a grid tile).
    hidden: bool,
}

#[derive(Default)]
struct File {
    items: Vec<Item>,
    props: Vec<Vec<u8>>,
    refs: Vec<(&'static [u8; 4], u16, Vec<u16>)>,
}

impl File {
    fn prop(&mut self, b: Vec<u8>) -> u8 {
        self.props.push(b);
        self.props.len() as u8
    }

    fn add(&mut self, kind: &'static [u8; 4], data: Vec<u8>, props: Vec<(u8, bool)>) -> u16 {
        let id = self.items.len() as u16 + 1;
        self.items.push(Item { id, kind, data, props, hidden: false });
        id
    }

    /// A coded image of `w` × `h` (a grid when larger than a tile); returns its item id.
    fn image(&mut self, w: u32, h: u32, bit_depth: u8, mono: bool, sample: &dyn Fn(u32, u32) -> [u16; 3]) -> u16 {
        let (cols, rows) = (w.div_ceil(TILE), h.div_ceil(TILE));
        let ispe = |w: u32, h: u32| {
            let mut p = w.to_be_bytes().to_vec();
            p.extend_from_slice(&h.to_be_bytes());
            full_box(b"ispe", 0, &p)
        };
        let mut hvcc_prop = None;
        let tile_ispe = self.prop(ispe(TILE, TILE));
        let mut tiles = Vec::new();
        for r in 0..rows {
            for c in 0..cols {
                let coded = picture(bit_depth, mono, &|x, y| sample((c * TILE + x).min(w - 1), (r * TILE + y).min(h - 1)));
                let hv = *hvcc_prop.get_or_insert_with(|| self.prop(bx(b"hvcC", &coded.hvcc)));
                tiles.push(self.add(b"hvc1", coded.data, vec![(hv, true), (tile_ispe, false)]));
            }
        }
        if let ([only], true) = (tiles.as_slice(), w == TILE && h == TILE) {
            return *only;
        }
        for it in self.items.iter_mut().filter(|i| tiles.contains(&i.id)) {
            it.hidden = true;
        }
        let mut g = vec![0u8, 0, (rows - 1) as u8, (cols - 1) as u8];
        g.extend_from_slice(&(w as u16).to_be_bytes());
        g.extend_from_slice(&(h as u16).to_be_bytes());
        let grid_ispe = self.prop(ispe(w, h));
        let id = self.add(b"grid", g, vec![(grid_ispe, false)]);
        self.refs.push((b"dimg", id, tiles));
        id
    }

    fn write(self, primary: u16) -> Vec<u8> {
        let ftyp = bx(b"ftyp", b"heic\0\0\0\0mif1heic");
        let mut hdlr = vec![0u8; 4];
        hdlr.extend_from_slice(b"pict");
        hdlr.extend_from_slice(&[0; 13]);
        let hdlr = full_box(b"hdlr", 0, &hdlr);
        let pitm = full_box(b"pitm", 0, &primary.to_be_bytes());
        let mut iinf = (self.items.len() as u16).to_be_bytes().to_vec();
        for it in &self.items {
            let mut e = vec![2, 0, 0, u8::from(it.hidden)]; // version 2, flags
            e.extend_from_slice(&it.id.to_be_bytes());
            e.extend_from_slice(&[0, 0]);
            e.extend_from_slice(it.kind);
            e.push(0);
            iinf.extend_from_slice(&bx(b"infe", &e));
        }
        let iinf = full_box(b"iinf", 0, &iinf);
        let mut iref = Vec::new();
        for (kind, from, to) in &self.refs {
            let mut r = from.to_be_bytes().to_vec();
            r.extend_from_slice(&(to.len() as u16).to_be_bytes());
            for t in to {
                r.extend_from_slice(&t.to_be_bytes());
            }
            iref.extend_from_slice(&bx(kind, &r));
        }
        let iref = full_box(b"iref", 0, &iref);
        let ipco = bx(b"ipco", &self.props.concat());
        let mut ipma = (self.items.iter().filter(|i| !i.props.is_empty()).count() as u32).to_be_bytes().to_vec();
        for it in self.items.iter().filter(|i| !i.props.is_empty()) {
            ipma.extend_from_slice(&it.id.to_be_bytes());
            ipma.push(it.props.len() as u8);
            ipma.extend(it.props.iter().map(|&(i, essential)| i | if essential { 0x80 } else { 0 }));
        }
        let iprp = bx(b"iprp", &[ipco, full_box(b"ipma", 0, &ipma)].concat());
        let iloc = |base: u32| {
            let mut l = vec![0x44, 0x00];
            l.extend_from_slice(&(self.items.len() as u16).to_be_bytes());
            let mut offset = base;
            for it in &self.items {
                l.extend_from_slice(&it.id.to_be_bytes());
                l.extend_from_slice(&[0, 0, 0, 0, 0, 1]); // construction method 0, data ref 0, one extent
                l.extend_from_slice(&offset.to_be_bytes());
                l.extend_from_slice(&(it.data.len() as u32).to_be_bytes());
                offset += it.data.len() as u32;
            }
            full_box(b"iloc", 1, &l)
        };
        let meta = |base| full_box(b"meta", 0, &[hdlr.clone(), pitm.clone(), iloc(base), iinf.clone(), iref.clone(), iprp.clone()].concat());
        let start = (ftyp.len() + meta(0).len() + 8) as u32;
        let mdat = bx(b"mdat", &self.items.iter().flat_map(|i| i.data.iter().copied()).collect::<Vec<u8>>());
        [ftyp, meta(start), mdat].concat()
    }
}

/// Writes the HEIF file `spec` describes.
pub fn build(spec: &Spec<'_>) -> Vec<u8> {
    let mut f = File::default();
    let primary = f.image(spec.width, spec.height, spec.bit_depth, false, spec.sample);
    let mut assoc = Vec::new();
    for p in &spec.props {
        let b = match p {
            Prop::Icc(icc) => bx(b"colr", &[b"prof".as_slice(), icc].concat()),
            Prop::Nclx(pr, tc, mc, full) => {
                let mut c = b"nclx".to_vec();
                for v in [pr, tc, mc] {
                    c.extend_from_slice(&v.to_be_bytes());
                }
                c.push(if *full { 0x80 } else { 0 });
                bx(b"colr", &c)
            }
            Prop::Irot(a) => bx(b"irot", &[a & 3]),
            Prop::Imir(a) => bx(b"imir", &[a & 1]),
            Prop::Clap(w, h, ho, vo) => {
                let mut c = Vec::new();
                for v in [*w as i32, 1, *h as i32, 1, *ho, 1, *vo, 1] {
                    c.extend_from_slice(&v.to_be_bytes());
                }
                bx(b"clap", &c)
            }
        };
        assoc.push((f.prop(b), true, matches!(p, Prop::Clap(..))));
    }
    if let Some(it) = f.items.iter_mut().find(|i| i.id == primary) {
        it.props.extend(assoc.iter().map(|&(i, e, _)| (i, e)));
    }
    if let Some(exif) = &spec.exif {
        let id = f.add(b"Exif", [&[0u8, 0, 0, 0][..], exif].concat(), Vec::new());
        f.refs.push((b"cdsc", id, vec![primary]));
    }
    let bd = spec.bit_depth;
    let aux = |f: &mut File, urn: &str, sample: &dyn Fn(u32, u32) -> [u16; 3]| {
        let id = f.image(spec.width, spec.height, bd, true, sample);
        let auxc = f.prop(full_box(b"auxC", 0, &[urn.as_bytes(), &[0]].concat()));
        if let Some(it) = f.items.iter_mut().find(|i| i.id == id) {
            it.props.push((auxc, true));
        }
        f.refs.push((b"auxl", id, vec![primary]));
    };
    if let Some(alpha) = spec.alpha {
        aux(&mut f, "urn:mpeg:hevc:2015:auxid:1", &|x, y| [alpha(x, y), 0, 0]);
    }
    for urn in &spec.ignored_aux {
        aux(&mut f, urn, &|x, y| [((x + y) % 256) as u16, 0, 0]);
    }
    if let Some(sample) = spec.thumbnail {
        // Half the size, with the primary image's colour and orientation (not its crop).
        let id = f.image(spec.width / 2, spec.height / 2, spec.bit_depth, false, sample);
        if let Some(it) = f.items.iter_mut().find(|i| i.id == id) {
            it.props.extend(assoc.iter().filter(|a| !a.2).map(|&(i, e, _)| (i, e)));
        }
        f.refs.push((b"thmb", id, vec![primary]));
    }
    f.write(primary)
}