OpenEXR

绑定版本：3.0.5

openexr crate 提供了对 ASWF OpenEXR 库 的高级绑定，允许读取和写入 OpenEXR 格式（EXR 代表 EXtended Range）的文件。OpenEXR 格式是电影行业的实际图像存储格式。

EXR 格式的目的是准确地高效地表示高动态范围场景线性图像数据和相关的元数据，并强烈支持多部分、多通道的使用案例。

OpenEXR 在需要高精度的主机应用程序软件中得到广泛应用，如真实感渲染、纹理访问、图像合成、深度合成和 DI。OpenEXR 是 Academy Software Foundation 的一个项目。该格式和库最初由工业光魔公司开发，并于 2003 年首次发布。Weta Digital、华特迪士尼动画工作室、索尼影业数字制作公司、皮克斯动画工作室、梦工厂和其他工作室、公司和个人都对代码库做出了贡献。

OpenEXR 包含在 VFX 参考平台 中。

openexr crate 由 vfx-rs 项目 维护。

快速入门

使用包含的 C++ OpenEXR 源代码

cargo add openexr
cargo build

虽然此方法得到支持并且是最容易开始的方法，但强烈建议您单独构建和安装 C++ 库，并像这样针对它构建 crate

cargo add openexr
CMAKE_PREFIX_PATH=/path/to/cmake/configs cargo build

请注意，您必须确保您指向的OpenEXR版本与crate的此版本相同，否则由于所有OpenEXR符号都有版本号，您将遇到链接错误。

prelude 汇入了您进行基本RGBA和任意通道图像文件I/O所需的一组类型

use openexr::prelude::*;

fn write_rgba1(filename: &str, pixels: &[Rgba], width: i32, height: i32)
-> Result<(), Box<dyn std::error::Error>> {
    let header = Header::from_dimensions(width, height);
    let mut file = RgbaOutputFile::new(
        filename,
        &header,
        RgbaChannels::WriteRgba,
        1,
    )?;

    file.set_frame_buffer(&pixels, 1, width as usize)?;
    file.write_pixels(height)?;

    Ok(())
}

fn read_rgba1(path: &str) -> Result<(), Box<dyn std::error::Error>> {
    use imath_traits::Zero;

    let mut file = RgbaInputFile::new(path, 1).unwrap();
    // Note that windows in OpenEXR are ***inclusive*** bounds, so a
    // 1920x1080 image has window [0, 0, 1919, 1079].
    let data_window: [i32; 4] = *file.header().data_window();
    let width = data_window.width() + 1;
    let height = data_window.height() + 1;

    let mut pixels = vec![Rgba::zero(); (width * height) as usize];
    file.set_frame_buffer(&mut pixels, 1, width as usize)?;
    file.read_pixels(0, height - 1)?;

    Ok(())
}

除此之外，与深度图像相关的类型位于 deep 模块中，而分块图像位于 tiled 模块中。

阅读和写入OpenEXR图像文件 文档是探索crate完整功能的好起点。它包含了几乎所有内容的示例用法。

Math Crate互操作性

OpenEXR（以及VFX生态系统的很大一部分）依赖于Imath来处理基本数学原语，如向量和边界框。

Rust已经拥有几个针对图形等线性代数的成熟crate，例如 cgmath、nalgebra、nalgebra-glm 和 glam。我们不是在这个拥挤的领域添加另一个竞争者，而是提供一组特质，允许这些crate中的任何一个以 imath-traits 的形式与openexr一起使用。默认情况下，这些特质为数组和切片实现，因此您会发现本文档中的示例倾向于使用例如 [i32; 4] 来表示边界框

use openexr::prelude::*;
fn read_rgba1(path: &str) -> Result<(), Box<dyn std::error::Error>> {
    use imath_traits::Zero;
    let mut file = RgbaInputFile::new(path, 1).unwrap();
    let data_window = file.header().data_window::<[i32; 4]>().clone();
    let width = data_window.width() + 1;
    let height = data_window.height() + 1;
    Ok(())
}

要使用您首选的数学crate，只需在openexr中启用相应的功能，这将是一个 imath_<name>，例如

cargo build --features=imath_cgmath

现在您可以使用该crate中的类型与openexr无缝配合。如果数学crate不提供边界框类型，则将作为 imath_traits::Box2i 和 imath_traits::Box3i 提供

use openexr::prelude::*;
#[cfg(feature = "imath_cgmath")]
fn read_rgba1(path: &str) -> Result<(), Box<dyn std::error::Error>> {
   use imath_traits::Zero;
    use imath_traits::Box2i;

    let mut file = RgbaInputFile::new(path, 1).unwrap();
    let data_window: Box2i = *file.header().data_window();
    let width = data_window.width() + 1;
    let height = data_window.height() + 1;
    Ok(())
}

安全性

OpenEXR API的一些部分在安全Rust中不容易表示。值得注意的是，Slice、FrameBuffer 和各种文件类型之间的交互本质上在像素数据背后的内存和文件之间创建了一个（可变的）引用链。

// set_frame_buffer internally stores a slice in a frame buffer on the file
// struct. pixels must live until the write_pixels call below has completed.
file.set_frame_buffer(&pixels, 1, width as usize)?;
unsafe {
    file.write_pixels(height)?;
}