Crate flashraw 

FlashRaw

Fast, safe camera RAW decoding: DNG, CR2, CR3, NEF, ARW, RAF, RW2, ORF, PEF, X3F and more (flashraw supported lists every format and the status of each compression mode). Of the 2,016 files in the raw.pixls.us corpus, 1,980 decode (98.2%); the other 36 are valid files in formats that are not supported yet (28 Nikon High Efficiency NEF, Light L16, Casio CAM, JPEG-in-DNG).

The crate parses the container with bounds-checked readers, reports metadata and embedded previews without touching the sensor data, and decodes the sensor data in parallel into sensor-domain samples (OutputFormat::RawU16) or developed RGB (OutputFormat::Rgba8, OutputFormat::Rgb16, linear 16-bit, half and single-precision float). The same API is available from the flashraw command line tool, WebAssembly (npm), Python and C.

Quick start

use flashraw::{Backend, DecodeOptions, FlashRaw, OutputFormat};

// Memory-maps the file and parses the headers; no sensor data is read yet.
let raw = FlashRaw::open_path("photo.NEF")?;
let meta = raw.metadata();
println!("{} {}x{}", meta.camera(), meta.width, meta.height);

// The embedded JPEG preview, without decoding the sensor data:
if let Some(p) = raw.preview() {
    std::fs::write("preview.jpg", raw.preview_bytes(p)?)?;
}

// Develop to 8-bit sRGB RGBA (orientation applied):
let frame = raw.decode(DecodeOptions {
    backend: Backend::Auto,
    output: OutputFormat::Rgba8,
    ..Default::default()
})?;
let rgba: &[u8] = frame.as_u8().expect("Rgba8 output is u8");
assert_eq!(rgba.len(), frame.width() as usize * frame.height() as usize * 4);
for w in frame.warnings() {
    eprintln!("warning: {w:?}"); // repaired corruption, preview fallback, ...
}

Input that is not a RAW file is an error, never a panic:

use flashraw::FlashRaw;

assert!(flashraw::supports(&[0u8; 64]).is_none());
assert!(FlashRaw::open(vec![0u8; 64]).is_err());

Untrusted files

Open files from users with explicit Limits (FlashRaw::open_with, and DecodeOptions::limits): the defaults allow 1.2 G samples and 65,535 pixels per side, which suits 400 MP medium format but permits several GB of allocation. Truncated or corrupt sensor data is zero-filled and reported in RawFrame::warnings unless CorruptionPolicy::Strict is set. Limit threads in services. Memory-mapped input (FlashRaw::open_path) can raise SIGBUS if another process truncates the file while it is mapped; read the bytes yourself (std::fs::read, then FlashRaw::open) when that matters.

What the decode returns

A RawFrame holds the samples (RawPixelData: u8, u16, f16 bits, f32 or a GPU buffer) and the metadata needed to interpret them (CFA, black and white levels, white balance, colour matrices, crops, orientation). Raw and linear outputs keep the sensor orientation (RawFrame::orientation); only OutputFormat::Rgba8 and OutputFormat::Rgb16 apply it. Do not assume 8-bit sensor data: raw samples are u16 (or f32 for floating-point DNG) and the white level is in the metadata.

Cargo features

Feature	Default	Effect
rayon	yes	Multithreaded decoding (native targets).
simd	yes	SIMD unpack kernels with runtime dispatch (SSSE3/SSE4.1 on x86-64, NEON on aarch64, SIMD128 on WebAssembly); scalar fallbacks are always built.
mmap	yes	FlashRaw::open_path memory-maps the file instead of reading it.
icc	yes	Arbitrary ICC output profiles (DecodeOptions::output_profile), pure Rust. The built-in colour spaces never need it.
gpu	no	wgpu compute backend (Vulkan, Metal, DX12, WebGPU): Backend::Gpu, GPU-resident outputs, the gpu module. Not built on docs.rs.
jpegxl	no	JPEG XL compressed DNG (needs Rust 1.88).
serde	no	Serialize/Deserialize for metadata and option types.

With default-features = false the crate is single-threaded and portable (wasm32 included).

Links

• Repository and guide: CLI, Python, JavaScript and C bindings, benchmarks, supported cameras.
• Packages: every crate, the npm and PyPI packages and the C library.
• Formats, colour management, GPU, security policy.

The internal crates (flashraw-core, -codecs, -formats, -camera-db, -gpu) have no semver guarantee of their own; depend on this crate.

Structs

BackendReport

Which backend actually ran each part of the decode.

BlackLevel

Black level description, anchored at sensor-buffer (0, 0).

Capabilities

File capabilities.

CfaPattern

A repeating colour filter array pattern anchored at sensor-buffer (0, 0).

ColorMatrices

Colour calibration data.

ColorMatrix

A colour matrix in DNG ColorMatrix convention: maps CIE XYZ to camera space, rows (camera channels, usually 3) x 3. The rows of a 4-row matrix follow CfaPattern::four_colour_order.

DecodeOptions

Options for crate::FlashRaw::decode.

DecodeStatistics

Timing and resource statistics for one decode.

DecodeUnit

An independently decodable unit of the payload.

DecodeWarning

Something a decode repaired or substituted instead of failing: under the recover policy (truncated or corrupt units), or with the preview fallback (see CorruptReason::PreviewFallback).

DngExtras

DNG rendering hints from IFD0 / the raw IFD that FlashRaw does not apply itself.

DngProfileInfo

DNG camera-profile tags an editor needs to know about (presence and sizes; the tables themselves are not decoded).

ExposureInfo

Exposure / capture parameters.

FlashRaw

An opened RAW file. Metadata and previews are available immediately; sensor data is decoded on demand with FlashRaw::decode.

FrameInfo

Geometry and calibration of the decoded sensor buffer.

GpsInfo

GPS position.

Illuminant

EXIF LightSource / DNG CalibrationIlluminant code.

LensInfo

Lens information.

Limits

Safety limits applied while decoding untrusted input.

OrientationMetadata

Orientation records of a file and the value resolved from them.

OutputProfile

An ICC profile to convert RGB outputs to (DecodeOptions::output_profile).

ParseOptionError

Error returned when parsing an unknown option name.

PreviewImage

A decoded embedded preview (FlashRaw::decode_preview_rgb).

PreviewInfo

An embedded preview / thumbnail stored in the RAW container.

RawFrame

A decoded frame: sensor-domain samples plus everything needed to interpret them.

RawMetadata

Normalised metadata for a RAW file, available without decoding sensor data.

Rect

An axis-aligned rectangle in sensor-buffer coordinates.

Truncation

A sensor-data range that the file does not fully contain.

WhiteBalance

As-shot white-balance multipliers in [R, G, B, G2/4th] order, normalised so G = 1.

WhiteLevel

Saturation (white) level per sample plane / CFA colour.

Enums

Backend

Execution backend.

CfaColor

Colour of a single CFA site.

ColorSource

Where colour calibration came from.

ColorSpace

Colour space of the RGB outputs (crate::OutputFormat::LinearRgbF32, crate::OutputFormat::Rgba8, crate::OutputFormat::Rgb16, …).

Compression

Payload compression / packing scheme (normalised across vendors).

CorruptReason

Structured cause of an Error::CorruptFile (or of a recovered DecodeWarning).

CorruptionPolicy

What a decode does when the sensor data is corrupt or truncated.

DataUnit

Which part of the sensor payload a report refers to.

Demosaic

Demosaic algorithm for RGB outputs.

Error

All errors produced while parsing or decoding a RAW file.

FrameSource

Where the pixels of a RawFrame come from.

Orientation

EXIF orientation.

OrientationPolicy

How the standard and vendor orientation records of a camera are combined.

OrientationSource

Which record the resolved orientation was taken from.

OutputFormat

What the decode produces.

PreviewEncoding

Encoding of an embedded preview image.

PreviewKind

What the container labels a preview as.

RandomAccess

How the payload can be accessed independently.

RawFormat

RAW container formats.

RawPixelData

Pixel storage of a decoded frame.

RenderingIntent

ICC rendering intent of a profile conversion (only profiles with lookup tables choose between them; matrix/TRC profiles convert the same way for every intent).

SampleFormat

Numeric format of decoded samples.

SensorLayout

How samples are arranged on the sensor / in the decoded buffer.

Source

Bytes a crate::FlashRaw can decode from.

Stage

Decode pipeline stages reported by --profile and DecodeStatistics.

Constants

EXTRA_CROP_SOURCE

RawMetadata::extra key: where the default crop came from: file (the format’s own crop field), image-size (EXTRA_IMAGE_SIZE), preview (the embedded full-size JPEG) or camera-db. Absent when the crop is the active area.

EXTRA_IMAGE_SIZE

RawMetadata::extra key: the camera’s own image size as the file records it ("<width>x<height>", from the EXIF pixel dimensions or a maker-note field).

Functions

gpu_available

Whether a GPU backend is compiled in and an adapter is available.

icc_supported

True when this build can use arbitrary ICC profiles (cargo feature icc).

read_metadata

Metadata only (no sensor decoding).

supports

Cheap check whether bytes look like a supported RAW file.

Type Aliases

Result

Result alias used throughout FlashRaw.