heifer 0.1.3

A pure-Rust HEIF/HEIC image decoder. No C dependencies · no unsafe code · runs everywhere Rust runs, including the browser.

▶ Try it in your browser — drop a .heic photo; it is decoded locally by heifer compiled to WebAssembly.

Why Heifer?

HEIC is the default photo format on iPhones and many Android phones, yet reading it from Rust has meant leaning on C and C++.

Heifer is an independent implementation of HEIF and HEVC written entirely in safe Rust, validated against the official conformance bitstreams. Add one line to Cargo.toml and it builds anywhere Rust builds (Linux, macOS, Windows and WebAssembly are tested in CI), with no system library to install.

Features

• Correct: identical to ffmpeg on 62/62 comparable HEVC conformance bitstreams; 41 also verified against the reference decoder's MD5 hashes.
• Real photos: iPhone (48-tile grids, rotation, spatial photos), Samsung 200 MP, Xiaomi, Sony.
• Safe: #![forbid(unsafe_code)], size limits against malicious files, fuzzed continuously on CI.
• Complete: alpha, overlays, crop/rotation/mirror, 8–12 bit, EXIF/XMP/ICC metadata.
• Portable: optional image integration, and it compiles to WebAssembly (≈ 250 KB).

Quick start

[dependencies]
heifer = "0.1"

Or try the examples on your own photos:

cargo run --release -p heifer --example heic2png -- photo.heic photo.png
cargo run --release -p heifer --example metadata -- photo.heic

Decode a HEIC

let bytes = std::fs::read("photo.heic")?;
let image = heifer::decode(&bytes)?;    // primary image, with alpha, crop/rotation/mirror applied

println!("{}×{}, {}-bit, alpha: {}", image.width, image.height, image.bit_depth, image.has_alpha);
let rgba: Vec<u8> = image.to_rgba8();   // or to_rgb8(); image.data keeps 16-bit samples

Limit threads and image size, for example on a server that accepts uploads:

let options = heifer::Options {
    max_threads: 1,            // 0 = all cores (default); grid tiles are decoded in parallel
    max_pixels: 50_000_000,    // reject larger images (default: 2^28 pixels)
};
let image = heifer::decode_with_options(&bytes, &options)?;

Read metadata

Read EXIF, XMP and the ICC profile without decoding pixels:

let meta = heifer::read_metadata(&bytes)?;
if let Some(exif) = meta.exif_fields() {
    println!("{:?} {:?} taken {:?}", exif.make(), exif.model(), exif.date_time());
}
let icc: Option<Vec<u8>> = meta.icc_profile;   // also meta.exif (raw TIFF) and meta.xmp

HDR photos

Recent iPhones store an HDR gain map next to the normal image. decode_hdr applies it and returns linear-light RGB where 1.0 is SDR white and highlights go up to the photo's headroom, matching Apple's own decoder (within 0.3% on average on an iPhone 12 Pro photo):

let hdr = heifer::decode_hdr(&bytes)?;          // f32 RGB, Display P3 primaries for iPhone photos
println!("headroom {:.2}×", hdr.headroom);      // e.g. 4.00: highlights up to 4× SDR white

// Or apply the gain map yourself, e.g. on the GPU:
if let Some(gain) = heifer::read_gain_map(&bytes)? {
    println!("{}×{} gain map, headroom {:.2}", gain.width, gain.height, gain.headroom);
}

image crate integration

heifer = { version = "0.1", features = ["image"] }

heifer::image_crate::register_image_decoder_hooks();
let img = image::open("photo.heic")?;   // .heic / .heif / .hif, plus content detection

HeifDecoder implements image::ImageDecoder (8- and 16-bit RGB/RGBA, EXIF/XMP/ICC). The HEIF orientation is already applied, so it is never applied twice.

Supported formats / features

Conformance

The first picture of 66 official conformance bitstreams (ITU-T H.265.1) covering Main, Main 10 and the Range Extensions:

Robustness

Five cargo-fuzz targets with HEIF/HEVC dictionaries run around the clock on GitHub Actions (5h15 sessions every 6 hours): full decoding, container parsing, HEVC decoding, a parallel-vs-sequential differential check and a CABAC round trip. Fuzzing already found and fixed a memory exhaustion bug.

Real-world compatibility

The remaining differences with ffmpeg are in heifer's favour: it honours the declared image sizes and grid crops, and decodes the file's primary image rather than the largest one.

Performance

Decode time on a 10-core Apple Silicon Mac (release build, median of several runs), compared with ffmpeg decoding the same file:

Grid tiles are decoded in parallel; the iPhone photo scales from 184 ms on 1 thread to 35 ms on 10:

On multi-core machines heifer decodes these photos faster than ffmpeg. Single-threaded decoding is still slower than ffmpeg. The hot loops are written so that the compiler vectorizes them (NEON, SSE/AVX), without any unsafe code.

Architecture

 photo.heic ──▶ container ──▶ HEVC bitstream ──▶ HEVC decoder ──▶ assembly ──▶ RGB(A)
              (heifer-isobmff)   per tile        (heifer-hevc-dec)   (heifer)

1. Container: the ISOBMFF boxes are parsed into items and properties: grids, alpha planes, transforms, metadata.
2. Bitstream: each tile's HEVC data is extracted with its parameter sets.
3. Decoding: CABAC, intra prediction, inverse transforms, deblocking and SAO; grid tiles are decoded in parallel.
4. Assembly: tiles are stitched, alpha attached, YCbCr converted to RGB, and crop/rotation/mirror applied.

Crates

heifer               decode(), read_metadata(), image crate integration
├── heifer-isobmff   HEIF container: boxes, items, properties, grids, metadata
└── heifer-hevc-dec  HEVC decoder: CABAC, intra prediction, transforms, deblocking, SAO
    heifer-hevc-enc  HEVC encoder (work in progress: CABAC encoder)

The lower-level crates can be used directly, for example to extract an HEVC stream:

let file = heifer_isobmff::HeifFile::parse(&bytes)?;
let tiles = file.referenced_items(file.primary_id, b"dimg");
let hevc = file.hevc_bitstream(tiles[0])?;   // Annex B, decodable by heifer-hevc-dec or ffmpeg

Roadmap

• 0.1 — Decoder: container, HEVC, conformance, real photos, metadata, image, WebAssembly, fuzzing
• HDR: Apple gain maps (iPhone photos)
• Next: ISO 21496-1 gain maps, ICC colour management
• Encoder: HEIF writing, minimal HEVC intra encoder, then better compression, 10-bit and alpha

See CHANGELOG.md for details.

Development

./scripts/fetch-fixtures.sh      # sample HEIC files (not committed)
./scripts/fetch-real.sh          # real-world photos from pillow-heif's test suite (not committed)
cargo test --workspace --all-features

Inspecting files

cargo run -p heifer-isobmff --example dump -- photo.heic                       # box tree
cargo run -p heifer-isobmff --example info -- photo.heic --extract 1002 t.h265 # items, HEVC stream
cargo run -p heifer-hevc-dec --example params -- t.h265                        # parameter sets
cargo run --release -p heifer-hevc-dec --example decode -- t.h265 t.yuv        # raw YUV

Conformance (≈ 23 MB from itu.int, not committed)

./scripts/fetch-conformance.sh
cargo test --release -p heifer-hevc-dec --test conformance   # reference picture hashes
cargo build --release -p heifer-hevc-dec --example decode
./scripts/conformance.py                                     # comparison with ffmpeg

Fuzzing (nightly toolchain and cargo install cargo-fuzz)

./scripts/fetch-fuzz-corpus.sh   # libheif's fuzzing corpus as extra seeds
./scripts/fuzz.sh 8h             # all targets on all cores; Ctrl+C to stop

WebAssembly demo (rustup target add wasm32-unknown-unknown, cargo install wasm-bindgen-cli --version 0.2.129)

./scripts/build-demo.sh && python3 -m http.server -d demo/web 8000

License

Licensed under either of Apache License 2.0 or MIT, at your option.

Patents. HEVC is covered by patents. Heifer is an independent implementation for research and interoperability; users are responsible for complying with applicable patent licensing in their jurisdiction.

Acknowledgements. Validation relies on the ITU-T HEVC conformance bitstreams, the test files of pillow-heif and Nokia's HEIF samples, the fuzzing corpus of libheif, and ffmpeg as a reference decoder.