rsraw

A comprehensive Rust wrapper for the LibRaw library, providing safe and idiomatic access to raw image processing capabilities, works on Linux/Windows/MacOS/iOS/Android.

This workspace contains two main crates that work together to provide raw image file support for Rust applications.

Overview

rsraw provides Rust bindings for the LibRaw C++ library, enabling developers to read, process, and extract metadata from raw image files from various camera manufacturers. The library supports over 400 camera models and provides access to both raw image data and processed images.

Workspace Structure

This workspace contains two main crates:

1. rsraw-sys - Low-level FFI bindings

• Purpose: Direct FFI bindings to the LibRaw C++ library
• Features:
  • Auto-generated bindings using bindgen
  • Raw C API access
  • Memory-safe wrappers for C structures
  • Build system integration with cc crate

2. rsraw - High-level Rust API

• Purpose: Safe, idiomatic Rust interface for raw image processing
• Features:
  • Memory-safe raw image handling
  • Metadata extraction (EXIF, GPS, lens info)
  • Thumbnail extraction
  • Image processing and demosaicing
  • Serialization support with serde

Features

Raw Image Processing

• File Format Support: 400+ camera models and raw formats
• Image Processing: Demosaicing, white balance, color correction
• Bit Depth Support: 8-bit and 16-bit output
• Memory Management: Automatic resource cleanup with Drop implementations

Metadata Extraction

• Camera Information: Make, model, software version
• Exposure Settings: ISO, shutter speed, aperture, focal length
• Lens Information: Focal length range, aperture range, mount type, serial numbers
• GPS Data: Latitude, longitude, altitude, timestamp
• Timestamps: Image capture date and time
• Artist/Description: Image metadata fields

Thumbnail Support

• Multiple Formats: JPEG, Bitmap, Bitmap16, Layer, Rollei, H265
• Automatic Sorting: Thumbnails sorted by size
• Format Detection: Automatic thumbnail format recognition

Error Handling

• Comprehensive Error Types: All LibRaw error codes mapped to Rust enums
• Result Types: Safe error propagation with Result<T, Error>
• Debug Information: Detailed error descriptions and representations

Installation

Add the following to your Cargo.toml:

[dependencies]
rsraw = { git = "https://github.com/hexilee/rsraw.git" }

Or add both crates if you need low-level access:

[dependencies]
rsraw = { git = "https://github.com/hexilee/rsraw.git" }
rsraw-sys = { git = "https://github.com/hexilee/rsraw.git", package = "rsraw-sys" }

Alternatively, you can specify a specific branch or commit:

[dependencies]
rsraw = { git = "https://github.com/hexilee/rsraw.git", branch = "main" }
# or
rsraw = { git = "https://github.com/hexilee/rsraw.git", rev = "abc1234" }

Quick Start

Basic Raw Image Processing

use rsraw::{RawImage, BIT_DEPTH_16};

// Load raw image from file
let data = std::fs::read("image.ARW")?;
let mut raw_image = RawImage::open(&data)?;

// Extract metadata
let info = raw_image.full_info();
println!("Camera: {} {}", info.make, info.model);
println!("ISO: {}, Shutter: 1/{}s, Aperture: f/{}", 
         info.iso_speed, 
         (1.0 / info.shutter) as u32, 
         info.aperture);

// Process image to 16-bit
raw_image.unpack()?;
let processed = raw_image.process::<BIT_DEPTH_16>()?;
println!("Processed image: {}x{} pixels", processed.width(), processed.height());

Metadata Extraction

use rsraw::RawImage;

let mut raw_image = RawImage::open(&data)?;

// Basic image properties
println!("Dimensions: {}x{}", raw_image.width(), raw_image.height());
println!("Colors: {}", raw_image.colors());

// Camera and lens information
let lens_info = raw_image.lens_info();
println!("Lens: {} {}", lens_info.lens_make, lens_info.lens_name);
println!("Focal length: {}mm", lens_info.min_focal);
println!("Mount: {}", lens_info.mounts);

// GPS information
let gps = raw_image.gps();
if gps.latitude[0] != 0.0 {
    println!("GPS: {:.6}, {:.6}", gps.latitude[0], gps.longitude[0]);
}

Thumbnail Extraction

use rsraw::RawImage;

let mut raw_image = RawImage::open(&data)?;
let thumbnails = raw_image.extract_thumbs()?;

for thumb in thumbnails {
    println!("Thumbnail: {}x{} ({:?})", 
             thumb.width, thumb.height, thumb.format);
    // Save thumbnail data
    std::fs::write("thumb.jpg", &thumb.data)?;
}

API Reference

Core Types

• RawImage: Main struct for raw image processing
• ProcessedImage<D>: Processed image data with configurable bit depth
• FullRawInfo: Complete metadata structure
• LensInfo: Detailed lens information
• GpsInfo: GPS coordinates and altitude
• ThumbnailImage: Thumbnail data with format information

Key Methods

RawImage

• open(data: &[u8]) -> Result<Self>: Load raw image from byte buffer
• unpack() -> Result<()>: Unpack raw data for processing
• process<const D: BitDepth>() -> Result<ProcessedImage<D>>: Process image
• extract_thumbs() -> Result<Vec<ThumbnailImage>>: Extract thumbnails
• full_info() -> FullRawInfo: Get complete metadata

ProcessedImage

• width() -> u32: Image width in pixels
• height() -> u32: Image height in pixels
• colors() -> u16: Number of color channels
• bits() -> u16: Bits per sample
• data_size() -> usize: Total data size in bytes

Supported Formats

The library supports raw formats from major camera manufacturers:

• Canon: CR2, CR3
• Nikon: NEF, NRW
• Sony: ARW
• Fujifilm: RAF
• Panasonic: RW2
• Olympus: ORF
• Pentax: PEF, DNG
• Leica: DNG, RWL
• Phase One: IIQ
• Hasselblad: 3FR, FFF
• And many more...

Dependencies

• rsraw-sys: libc, cc, bindgen
• rsraw: rsraw-sys, chrono, tracing, serde

Building

The library requires a C++ compiler and the LibRaw source code (included as a submodule). The build process:

1. Compiles the LibRaw C++ library
2. Generates Rust bindings using bindgen
3. Links the static library

Requirements

• Rust 1.70+
• C++ compiler (GCC, Clang, or MSVC)
• CMake (for LibRaw build)

Testing

Run the test suite:

cargo test --all

The tests include sample raw files from Nikon and Sony cameras to verify functionality.

License

This project is licensed under the MIT License. See the LICENSE file for details.

The underlying LibRaw library has its own licensing terms. Please refer to the LibRaw documentation for information about its license and usage restrictions.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Changelog

v0.1.0

• Initial release
• Basic raw image processing
• Metadata extraction
• Thumbnail support
• Memory-safe API design