Getting Started

Getting Started

Install

[dependencies]
heifer = "0.2"

No system library or C toolchain is needed.

Decode a photo

let bytes = std::fs::read("photo.heic")?;
let image = heifer::decode(&bytes)?;

println!("{}×{}, {}-bit, alpha: {}", image.width, image.height, image.bit_depth, image.has_alpha);
let rgba: Vec<u8> = image.to_rgba8();   // 8-bit RGBA, 4 bytes per pixel
let rgb: Vec<u8> = image.to_rgb8();     // 8-bit RGB, 3 bytes per pixel

heifer::decode returns the primary image of the file with crop, rotation and mirror already applied. image.data holds the samples at full precision (u16, RGBA order), which is useful for 10- and 12-bit photos.

Options

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

On a server that accepts uploads, set max_pixels to protect memory.

Metadata

let meta = heifer::read_metadata(&bytes)?;      // does not decode pixels
if let Some(exif) = meta.exif_fields() {
    println!("{:?} {:?}", exif.make(), exif.model());
    println!("taken {:?}, GPS: {}", exif.date_time(), exif.has_gps());
}
// Raw blocks: meta.exif (TIFF), meta.xmp (XML), meta.icc_profile

With the image crate

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

heifer::image_crate::register_image_decoder_hooks();
let img = image::open("photo.heic")?;
img.save("photo.png")?;

After registration, image::open, image::ImageReader and image::load_from_memory all decode HEIC files. This needs image 0.25.8 or later.

Command-line examples

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