heic-rs 0.1.5

Pure-Rust HEIC/HEIF image decoder: no C, no unsafe, no_std-friendly, wasm-ready
Documentation
//! The small descriptive properties: `ispe`, `pixi`, `pasp`, `auxC`, and the
//! three transformative ones, `irot`, `imir` and `clap`.

use alloc::vec::Vec;

use crate::boxes::BoxHeader;
use crate::error::{Error, Result};

/// `ispe`: the coded size of an item, before any transform.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Ispe {
    /// Width in pixels.
    pub width: u32,
    /// Height in pixels.
    pub height: u32,
}

/// Parse `ispe`.
pub fn parse_ispe(b: &BoxHeader<'_>) -> Result<Ispe> {
    let (_v, _f, mut r) = b.full_box("ispe")?;
    let width = r.u32("ispe width")?;
    let height = r.u32("ispe height")?;
    if width == 0 || height == 0 {
        return Err(Error::Malformed("ispe declares a zero dimension"));
    }
    Ok(Ispe { width, height })
}

/// `pixi`: bits per channel.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Pixi {
    /// One entry per channel, in coding order.
    pub bits_per_channel: Vec<u8>,
}

/// Parse `pixi`.
pub fn parse_pixi(b: &BoxHeader<'_>) -> Result<Pixi> {
    let (_v, _f, mut r) = b.full_box("pixi")?;
    let n = r.u8("pixi channel count")?;
    if usize::from(n) > r.remaining() {
        return Err(Error::Malformed(
            "pixi declares more channels than it holds",
        ));
    }
    let mut bits_per_channel = Vec::with_capacity(usize::from(n));
    for _ in 0..n {
        bits_per_channel.push(r.u8("pixi channel depth")?);
    }
    Ok(Pixi { bits_per_channel })
}

/// `pasp`: the pixel aspect ratio. Reported, never applied.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Pasp {
    /// Horizontal spacing.
    pub h_spacing: u32,
    /// Vertical spacing.
    pub v_spacing: u32,
}

/// Parse `pasp`.
pub fn parse_pasp(b: &BoxHeader<'_>) -> Result<Pasp> {
    let mut r = b.reader();
    Ok(Pasp {
        h_spacing: r.u32("pasp hSpacing")?,
        v_spacing: r.u32("pasp vSpacing")?,
    })
}

/// `irot`: a counter-clockwise rotation in whole quarter turns.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Rotation {
    /// No rotation.
    #[default]
    None,
    /// 90 degrees counter-clockwise.
    Ccw90,
    /// 180 degrees.
    Ccw180,
    /// 270 degrees counter-clockwise, which is 90 clockwise.
    Ccw270,
}

impl Rotation {
    /// The rotation in degrees counter-clockwise.
    pub const fn degrees(self) -> u16 {
        match self {
            Rotation::None => 0,
            Rotation::Ccw90 => 90,
            Rotation::Ccw180 => 180,
            Rotation::Ccw270 => 270,
        }
    }

    /// True when applying this rotation exchanges width and height.
    pub const fn swaps_axes(self) -> bool {
        matches!(self, Rotation::Ccw90 | Rotation::Ccw270)
    }
}

/// Parse `irot`.
pub fn parse_irot(b: &BoxHeader<'_>) -> Result<Rotation> {
    let mut r = b.reader();
    Ok(match r.u8("irot angle")? & 0x03 {
        0 => Rotation::None,
        1 => Rotation::Ccw90,
        2 => Rotation::Ccw180,
        _ => Rotation::Ccw270,
    })
}

/// `imir`: a mirroring, named by the effect rather than by the axis.
///
/// The coded field names the *axis*: 0 is a vertical axis, which exchanges
/// left and right; 1 is a horizontal axis, which exchanges top and bottom.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Mirror {
    /// Coded axis 0: left and right are exchanged.
    LeftRight,
    /// Coded axis 1: top and bottom are exchanged.
    TopBottom,
}

/// Parse `imir`.
pub fn parse_imir(b: &BoxHeader<'_>) -> Result<Mirror> {
    let mut r = b.reader();
    Ok(if r.u8("imir axis")? & 0x01 == 0 {
        Mirror::LeftRight
    } else {
        Mirror::TopBottom
    })
}

/// `clap`: the clean aperture, as the four rationals the box actually stores.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Clap {
    /// Cropped width, numerator and denominator.
    pub width: (u32, u32),
    /// Cropped height, numerator and denominator.
    pub height: (u32, u32),
    /// Horizontal offset of the crop centre, numerator (signed) and denominator.
    pub horiz_off: (i32, u32),
    /// Vertical offset of the crop centre, numerator (signed) and denominator.
    pub vert_off: (i32, u32),
}

/// Parse `clap`.
pub fn parse_clap(b: &BoxHeader<'_>) -> Result<Clap> {
    let mut r = b.reader();
    let wn = r.u32("clap width numerator")?;
    let wd = r.u32("clap width denominator")?;
    let hn = r.u32("clap height numerator")?;
    let hd = r.u32("clap height denominator")?;
    let hon = r.u32("clap horizontal offset numerator")? as i32;
    let hod = r.u32("clap horizontal offset denominator")?;
    let von = r.u32("clap vertical offset numerator")? as i32;
    let vod = r.u32("clap vertical offset denominator")?;
    if wd == 0 || hd == 0 || hod == 0 || vod == 0 {
        return Err(Error::Malformed("clap has a zero denominator"));
    }
    Ok(Clap {
        width: (wn, wd),
        height: (hn, hd),
        horiz_off: (hon, hod),
        vert_off: (von, vod),
    })
}

/// What an auxiliary item carries.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AuxKind {
    /// An alpha plane.
    Alpha,
    /// A depth map.
    Depth,
    /// Something else; the URN is available from [`AuxC::urn`].
    Other,
}

/// `auxC`: what an auxiliary image is for.
#[derive(Debug, Clone, Copy)]
pub struct AuxC<'a> {
    /// The auxiliary type URN, verbatim.
    pub urn: &'a str,
    /// The URN, interpreted.
    pub kind: AuxKind,
}

/// Parse `auxC`.
pub fn parse_auxc<'a>(b: &BoxHeader<'a>) -> Result<AuxC<'a>> {
    let (_v, _f, mut r) = b.full_box("auxC")?;
    let urn = r.cstr("auxC aux type")?;
    let kind = if urn.ends_with("auxiliary:alpha") || urn == "urn:mpeg:hevc:2015:auxid:1" {
        AuxKind::Alpha
    } else if urn.ends_with("auxiliary:depth") || urn == "urn:mpeg:hevc:2015:auxid:2" {
        AuxKind::Depth
    } else {
        AuxKind::Other
    };
    Ok(AuxC { urn, kind })
}