Skip to main content

heic_rs/
lib.rs

1//! A pure-Rust decoder for HEIC and HEIF still images.
2//!
3//! No C, no `unsafe`, one optional dependency, and a `no_std` core that
4//! builds for `wasm32-unknown-unknown` with no dependencies at all.
5//!
6//! # Status
7//!
8//! Complete and self-contained: boxes, `ftyp`, `meta` and its children, item
9//! properties, `grid` derivation and tile compositing, transforms, EXIF and
10//! ICC extraction, YCbCr to RGB conversion, and the HEVC still-picture intra
11//! decoder in [`hevc`]. [`decode()`] turns a HEIC file into pixels with no C
12//! and no `unsafe` anywhere in the chain.
13//!
14//! # The rule this crate is built on
15//!
16//! Business logic performs no I/O. [`decode()`] and [`probe()`] take `&[u8]`
17//! and return values; nothing beneath them opens a file, reads the environment
18//! or touches the network. Filesystem convenience lives in [`io`], behind the
19//! default-on `std` feature, and nowhere else. That separation is what lets
20//! the core be `no_std`, what makes it build for the browser, and what makes
21//! every parser in it testable against a byte array written by hand.
22//!
23//! # Reading a file
24//!
25//! ```no_run
26//! # fn main() -> Result<(), heic_rs::Error> {
27//! let bytes = std::fs::read("photo.heic").unwrap_or_default();
28//!
29//! // Ask what the file is, without decoding it.
30//! let info = heic_rs::probe(&bytes)?;
31//! println!("{}x{}, {} bit", info.width, info.height, info.bit_depth);
32//!
33//! // Decode it.
34//! let options = heic_rs::DecodeOptions::default();
35//! let image = heic_rs::decode(&bytes, &options)?;
36//! assert_eq!(image.data.len(), image.row_bytes() * image.height as usize);
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! # Untrusted input
42//!
43//! HEIF files are untrusted input. Every parser here is bounds-checked and
44//! returns an error rather than panicking, and
45//! [`DecodeOptions::max_pixels`] — [`DEFAULT_MAX_PIXELS`], 256 megapixels —
46//! stops a small file from asking for an enormous allocation.
47//!
48//! # Features
49//!
50//! - `std` (default): the [`io`] module, and `std::error::Error` for
51//!   [`Error`]. Turn it off for `no_std` and for wasm.
52//! - `parallel` (default): decode grid tiles and convert colour on a `rayon`
53//!   pool. Implies `std`, and is absent from the `no_std` and wasm builds.
54//!   The output is identical either way; see [`DecodeOptions::threads`] for
55//!   the knob and for what happens inside a caller's own pool.
56
57#![cfg_attr(not(test), no_std)]
58#![forbid(unsafe_code)]
59#![deny(missing_docs)]
60#![cfg_attr(docsrs, feature(doc_cfg))]
61
62extern crate alloc;
63
64#[cfg(all(feature = "std", not(test)))]
65extern crate std;
66
67pub mod boxes;
68pub mod color;
69pub mod context;
70pub mod decode;
71pub mod error;
72pub mod ftyp;
73pub mod grid;
74pub mod hevc;
75pub mod image;
76pub mod meta;
77pub mod metadata;
78mod parallel;
79pub mod probe;
80pub mod props;
81pub mod reader;
82pub mod transform;
83pub mod upsample;
84
85#[cfg(feature = "std")]
86#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
87pub mod io;
88
89pub use crate::decode::decode;
90pub use crate::error::{Error, Result};
91pub use crate::ftyp::Brand;
92pub use crate::grid::Grid;
93pub use crate::hevc::ChromaFormat;
94pub use crate::image::{DEFAULT_MAX_PIXELS, DecodeOptions, Image, PixelLayout};
95pub use crate::probe::{GridInfo, ImageInfo, probe};
96pub use crate::props::Transform;
97pub use crate::props::colr::{MatrixCoefficients, Nclx, Range};
98pub use crate::props::simple::{Mirror, Rotation};