Skip to main content

Crate heic_rs

Crate heic_rs 

Source
Expand description

A pure-Rust decoder for HEIC and HEIF still images.

No C, no unsafe, one optional dependency, and a no_std core that builds for wasm32-unknown-unknown with no dependencies at all.

§Status

Complete and self-contained: boxes, ftyp, meta and its children, item properties, grid derivation and tile compositing, transforms, EXIF and ICC extraction, YCbCr to RGB conversion, and the HEVC still-picture intra decoder in hevc. decode() turns a HEIC file into pixels with no C and no unsafe anywhere in the chain.

§The rule this crate is built on

Business logic performs no I/O. decode() and probe() take &[u8] and return values; nothing beneath them opens a file, reads the environment or touches the network. Filesystem convenience lives in io, behind the default-on std feature, and nowhere else. That separation is what lets the core be no_std, what makes it build for the browser, and what makes every parser in it testable against a byte array written by hand.

§Reading a file

let bytes = std::fs::read("photo.heic").unwrap_or_default();

// Ask what the file is, without decoding it.
let info = heic_rs::probe(&bytes)?;
println!("{}x{}, {} bit", info.width, info.height, info.bit_depth);

// Decode it.
let options = heic_rs::DecodeOptions::default();
let image = heic_rs::decode(&bytes, &options)?;
assert_eq!(image.data.len(), image.row_bytes() * image.height as usize);

§Untrusted input

HEIF files are untrusted input. Every parser here is bounds-checked and returns an error rather than panicking, and DecodeOptions::max_pixels — DEFAULT_MAX_PIXELS, 256 megapixels — stops a small file from asking for an enormous allocation.

§Features

  • std (default): the io module, and std::error::Error for Error. Turn it off for no_std and for wasm.
  • parallel (default): decode grid tiles and convert colour on a rayon pool. Implies std, and is absent from the no_std and wasm builds. The output is identical either way; see DecodeOptions::threads for the knob and for what happens inside a caller’s own pool.

Re-exports§

pub use crate::decode::decode;
pub use crate::error::Error;
pub use crate::error::Result;
pub use crate::ftyp::Brand;
pub use crate::grid::Grid;
pub use crate::hevc::ChromaFormat;
pub use crate::image::DEFAULT_MAX_PIXELS;
pub use crate::image::DecodeOptions;
pub use crate::image::Image;
pub use crate::image::PixelLayout;
pub use crate::probe::GridInfo;
pub use crate::probe::ImageInfo;
pub use crate::probe::probe;
pub use crate::props::Transform;
pub use crate::props::colr::MatrixCoefficients;
pub use crate::props::colr::Nclx;
pub use crate::props::colr::Range;
pub use crate::props::simple::Mirror;
pub use crate::props::simple::Rotation;

Modules§

boxes
ISOBMFF box traversal (ISO/IEC 14496-12).
color
Turning decoded YCbCr samples into the caller’s chosen pixel layout.
context
One parsed file, and the questions both probe and decode ask of it.
decode
decode: container to pixels.
error
The crate’s hand-written error type.
ftyp
The ftyp box and the brands this crate recognises.
grid
The grid derived item: a picture stored as a mosaic of coded tiles.
hevc
The HEVC (ITU-T H.265) still-picture intra decoder.
image
The public output types: what a decode produces and how to ask for it.
iostd
Filesystem convenience, and the only module in this crate that performs I/O.
meta
The meta box: the catalogue that makes a HEIF file navigable.
metadata
EXIF and XMP, extracted as borrowed slices.
probe
probe: everything the file says about itself, without decoding it.
props
Item properties: parsing them, and gathering the ones that belong to a given item into one struct.
reader
A non-allocating, panic-free cursor over a byte slice.
transform
Applying clap, irot and imir to a decoded image.
upsample
Chroma upsampling.