[−][src]Crate openexr

Rust bindings for the OpenEXR C++ library.

OpenEXR is a bitmap image file format that can store high dynamic range (HDR) images along with other arbitrary per-pixel data. It is used heavily in the VFX and 3D animation industries.

Although this wrapper's API differs a little from the C++ library, it tries not to differ wildly. Therefore the C++ OpenEXR documentation is still useful as an introduction and rough reference. Moreover, the file format itself is also documented there.

Overview

There are three primary parts to this crate:

The various input and output types. These are used for reading and writing OpenEXR files. They utilize the Header and FrameBuffer(Mut) types, listed below.
Header: this is used for querying and specifying the properties of an OpenEXR file (such as resolution, channels, etc.), for reading and writing respectively.
FrameBuffer and FrameBufferMut: these are intermediaries that tell the OpenEXR APIs how to interpret your in-memory image data. Rather than passing your image data to the APIs directly, you construct a FrameBuffer that points at and describes it, and then you pass that FrameBuffer.

Examples

Writing a scanline floating point RGB file.

// Pixel data for a 256x256 floating point RGB image.
let pixel_data = vec![(0.82f32, 1.78f32, 0.21f32); 256 * 256];

// Create a file to write to.  The `Header` determines the properties of the
// file, like resolution and what channels it has.
let mut file = std::fs::File::create("output_file.exr").unwrap();
let mut output_file = ScanlineOutputFile::new(
    &mut file,
    Header::new()
        .set_resolution(256, 256)
        .add_channel("R", PixelType::FLOAT)
        .add_channel("G", PixelType::FLOAT)
        .add_channel("B", PixelType::FLOAT)).unwrap();

// Create a `FrameBuffer` that points at our pixel data and describes it as
// RGB data.
let mut fb = FrameBuffer::new(256, 256);
fb.insert_channels(&["R", "G", "B"], &pixel_data);

// Write pixel data to the file.
output_file.write_pixels(&fb).unwrap();

Reading a floating point RGB file.


// Open the EXR file.
let mut file = std::fs::File::open("input_file.exr").unwrap();
let mut input_file = InputFile::new(&mut file).unwrap();

// Get the image dimensions, so we know how large of a buffer to make.
let (width, height) = input_file.header().data_dimensions();

// Buffer to read pixel data into.
let mut pixel_data = vec![(0.0f32, 0.0f32, 0.0f32); (width*height) as usize];

// New scope because `FrameBufferMut` mutably borrows `pixel_data`, so we
// need it to go out of scope before we can access our `pixel_data` again.
{
    // Get the input file data origin, which we need to properly construct
    // the `FrameBufferMut`.
    let (origin_x, origin_y) = input_file.header().data_origin();

    // Create a `FrameBufferMut` that points at our pixel data and describes
    // it as RGB data.
    let mut fb = FrameBufferMut::new_with_origin(
        origin_x,
        origin_y,
        width,
        height,
    );
    fb.insert_channels(&[("R", 0.0), ("G", 0.0), ("B", 0.0)], &mut pixel_data);

    // Read pixel data from the file.
    input_file.read_pixels(&mut fb).unwrap();
}

Re-exports

pub use error::Error;

pub use error::Result;

pub use frame_buffer::FrameBuffer;

pub use frame_buffer::FrameBufferMut;

pub use header::Envmap;

pub use header::Header;

pub use input::InputFile;

Modules

error	Result and Error types.
frame_buffer	A `FrameBuffer` points to and describes image data in memory to be used for input and output.
header	Header and related types.
input	Input file types.
output	Output file types.
threads	I/O compression/decompression threading control.

Structs

Box2i	A 2d integer bounding box.
ScanlineOutputFile	Writes scanline OpenEXR files.

Enums

PixelType

Describes the datatype of an image channel.