Crate heic 

Pure Rust HEIC/HEIF image decoder

This crate decodes HEIC/HEIF images (as used by iPhones and modern cameras) without any C/C++ dependencies. #![forbid(unsafe_code)], no_std + alloc compatible, and SIMD-accelerated on x86-64 (AVX2).

Quick Start

use heic::{DecoderConfig, PixelLayout};

let data = std::fs::read("image.heic").unwrap();
let output = DecoderConfig::new().decode(&data, PixelLayout::Rgba8).unwrap();
println!("Decoded {}x{} image", output.width, output.height);

Decode with Limits and Cancellation

use heic::{DecoderConfig, PixelLayout, Limits};

let data = std::fs::read("image.heic").unwrap();
let mut limits = Limits::default();
limits.max_width = Some(8192);
limits.max_height = Some(8192);
limits.max_pixels = Some(64_000_000);

let output = DecoderConfig::new()
    .decode_request(&data)
    .with_output_layout(PixelLayout::Rgba8)
    .with_limits(&limits)
    .decode()
    .unwrap();

Zero-Copy into Pre-Allocated Buffer

use heic::{DecoderConfig, ImageInfo, PixelLayout};

let data = std::fs::read("image.heic").unwrap();
let info = ImageInfo::from_bytes(&data).unwrap();
let mut buf = vec![0u8; info.output_buffer_size(PixelLayout::Rgb8).unwrap()];
let (w, h) = DecoderConfig::new()
    .decode_request(&data)
    .with_output_layout(PixelLayout::Rgb8)
    .decode_into(&mut buf)
    .unwrap();

For grid-based images (most iPhone photos), DecodeRequest::decode_into uses a streaming path that color-converts tiles directly into the output buffer, avoiding the intermediate full-frame YCbCr allocation.

Features

Feature	Default	Description
std	yes	Standard library support. Disable for no_std + alloc.
parallel	no	Parallel tile decoding via rayon. Implies std.

Error Handling

Decode methods return Result<T>, which is core::result::Result<T, At<HeicError>>. The At wrapper from the whereat crate attaches source location to errors for easier debugging. Use .error() to inspect the inner HeicError, or .decompose() to separate the error from its trace.

For probing, ImageInfo::from_bytes returns a separate ProbeError enum that distinguishes “not enough data” from “not a HEIC file” from “corrupt header”.

Advanced: Raw YCbCr Access

use heic::DecoderConfig;

let data = std::fs::read("image.heic").unwrap();
let frame = DecoderConfig::new().decode_to_frame(&data).unwrap();
println!("{}x{}, bit_depth={}, chroma={}",
    frame.cropped_width(), frame.cropped_height(),
    frame.bit_depth, frame.chroma_format);

// Access raw YCbCr planes
let (y_plane, y_stride) = frame.plane(0);
let (cb_plane, c_stride) = frame.plane(1);
let (cr_plane, _) = frame.plane(2);

Memory

Use DecoderConfig::estimate_memory to check memory requirements before decoding. For grid-based images, DecodeRequest::decode_into reduces peak memory by ~60% compared to DecodeRequest::decode by streaming tiles directly to the output buffer.

Macros

at

Start tracing an error with crate metadata for repository links.

Structs

At

An error with location tracking - wraps any error type.

AuxiliaryImageDescriptor

Descriptor for an auxiliary image found in the container.

DecodeOutput

Decoded image output

DecodeRequest

A decode request binding data, output format, limits, and cancellation.

DecodedFrame

Decoded video frame with YCbCr plane data.

DecoderConfig

Decoder configuration. Reusable across multiple decode operations.

DepthMap

Decoded depth map from a HEIF auxiliary depth image.

DepthRepresentationInfo

Depth representation information parsed from auxC subtype data.

HdrGainMap

HDR gain map data extracted from an auxiliary image.

ImageInfo

Image metadata without full decode

Limits

Resource limits for decoding.

SegmentationMatte

A decoded segmentation matte from a HEIC file.

Unstoppable

A Stop implementation that never stops (no cooperative cancellation).

VideoDecoder

Stateful HEVC video decoder with decoded picture buffer (DPB).

Enums

AuxiliaryImageType

Identifies the type of an auxiliary image in a HEIF container.

DepthRepresentationType

How the depth values in a depth auxiliary image should be interpreted.

HeicError

Errors that can occur during HEIC decoding

HevcError

Errors specific to HEVC decoding

PixelLayout

Pixel layout for decoded output.

ProbeError

Errors from probing image headers

StopReason

Why an operation was stopped.

Traits

RowSink

Sink for receiving decoded pixel rows during streaming decode.

Stop

Cooperative cancellation check.

Functions

at

Wrap any value in At<E> and capture the caller’s location.

cabac_bin_trace

Enable per-bin CABAC trace for the next limit bins (0 = disable)

enable_deblock_trace

Enable deblocking filter trace output (writes to /tmp/our_deblock_trace.txt)

Type Aliases

Result

Result type for HEIC operations, with error location tracking.