Skip to main content

Crate oiio

Crate oiio 

Source
Expand description

Safe Rust bindings to OpenImageIO 3.1 and 3.2.

Read and write every format OpenImageIO supports, in u8, u16, f16 or f32. Dimensions, regions and buffer lengths are all checked before anything crosses into C++, so a mistake is a typed error rather than undefined behaviour.

§Reading

use oiio::ImageInput;
use std::path::Path;

let mut input = ImageInput::from_path(Path::new("image.exr"))?;
let spec = input.image_spec()?;
let mut pixels = vec![0.0_f32; spec.element_count()?];
input.read_image_into(&mut pixels)?;
input.close()?;

Part of an image is a Roi, which selects pixels and channels, so reading one AOV out of a 38-channel EXR does not decode the other 37:

let roi = spec.data_window()?.with_y(0..64)?.with_channels(0..3)?;
let mut pixels = vec![0.0_f32; roi.element_count()?];
input.read_region_into(roi, &mut pixels)?;

§What else is here

  • ImageOutput writes files, whole or in scanline and tile pieces, with subimages, mip levels and multi-part files.
  • ImageCache serves regions from many files under a memory budget, with ImageHandle to skip repeated name lookups and TileGuard to borrow one tile at a time.
  • ImageBuf holds an image in memory and algo operates on it: arithmetic, compositing, resizing, channel shuffling and colour conversion.
  • DeepImage reads deep files, where each pixel holds a list of samples rather than one value.
  • ColorConfig reports which colour spaces the active OpenColorIO configuration defines, so conversions need not guess at names.
  • make_texture writes the tiled, MIP-mapped files a renderer wants, and TextureSystem does the filtered lookups into them.
  • Neither reading nor writing needs the filesystem: ImageInput::from_memory and ImageOutput::to_memory work on buffers.

§Metadata

Attributes arrive as AttributeValue. Integers, floats and strings are modelled directly; everything else keeps the bytes OpenImageIO stored, so an attribute this crate does not understand still survives being read from one image and written to another.

Modules§

algo
Operations on ImageBuf, mirroring OpenImageIO’s ImageBufAlgo.
config
Process-wide OpenImageIO settings.

Structs§

ColorConfig
The colour spaces available to color_convert.
DeepChannel
One channel of a DeepImage.
DeepImage
A deep image: every pixel holds a list of samples rather than one value.
Derivatives
How far the texture coordinate moves per screen pixel.
ImageBuf
An image held in memory, the unit OpenImageIO’s algorithms operate on.
ImageCache
A thread-safe OpenImageIO image cache.
ImageCacheBuilder
Typed configuration for constructing an ImageCache.
ImageHandle
A file name already resolved against an ImageCache.
ImageInput
An open image, either a file or a buffer in memory.
ImageOutput
An image file open for writing.
ImageSpec
A value-owned description of an image.
Perthread
Per-thread cache state, which speeds up repeated lookups.
Roi
A half-open pixel and channel region.
TextureConfig
How make_texture should write a texture.
TextureHandle
A texture name already resolved against a TextureSystem.
TextureOptions
How one lookup should be filtered.
TextureSystem
A filtered texture reader.
TileGuard
A tile borrowed from an ImageCache, released when dropped.
UdimInventory
The concrete files of a UDIM set; see TextureSystem::inventory_udim.
f16
A 16-bit floating point type implementing the IEEE 754-2008 standard binary16 a.k.a “half” format.

Enums§

AttributeValue
A metadata value attached to an ImageSpec.
Error
Errors reported by the safe OpenImageIO wrappers.
InterpolationMode
How samples are interpolated inside one mip level.
MipMode
How mip levels are chosen.
PixelFormat
The scalar type of one channel value.
Storage
Where an ImageBuf’s pixels live.
TextureMode
What kind of texture make_texture should write.
Wrap
What a point read outside the data window answers with.
WrapMode
What happens to texture coordinates outside the unit square.

Traits§

Pixel
A scalar pixel channel type that OpenImageIO can read and write directly.

Functions§

make_texture
Write input_path as a texture at output_path.
make_texture_from_buffer
Write an image already in memory as a texture at output_path.

Type Aliases§

ImageInputIoError
Backwards-compatible name for errors returned by ImageInput.
Result
Result type used by the safe OpenImageIO wrappers.