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): theiomodule, andstd::error::ErrorforError. Turn it off forno_stdand for wasm.parallel(default): decode grid tiles and convert colour on arayonpool. Impliesstd, and is absent from theno_stdand wasm builds. The output is identical either way; seeDecodeOptions::threadsfor 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
probeanddecodeask of it. - decode
decode: container to pixels.- error
- The crate’s hand-written error type.
- ftyp
- The
ftypbox and the brands this crate recognises. - grid
- The
gridderived 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.
- io
std - Filesystem convenience, and the only module in this crate that performs I/O.
- meta
- The
metabox: 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,irotandimirto a decoded image. - upsample
- Chroma upsampling.