rsraw-sys 0.1.0

# 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`:

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

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

```toml
[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:

```toml
[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

```rust
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

```rust
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

```rust
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:

```bash
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](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