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
ImageOutputwrites files, whole or in scanline and tile pieces, with subimages, mip levels and multi-part files.ImageCacheserves regions from many files under a memory budget, withImageHandleto skip repeated name lookups andTileGuardto borrow one tile at a time.ImageBufholds an image in memory andalgooperates on it: arithmetic, compositing, resizing, channel shuffling and colour conversion.DeepImagereads deep files, where each pixel holds a list of samples rather than one value.ColorConfigreports which colour spaces the active OpenColorIO configuration defines, so conversions need not guess at names.make_texturewrites the tiled, MIP-mapped files a renderer wants, andTextureSystemdoes the filtered lookups into them.- Neither reading nor writing needs the filesystem:
ImageInput::from_memoryandImageOutput::to_memorywork 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’sImageBufAlgo. - config
- Process-wide OpenImageIO settings.
Structs§
- Color
Config - The colour spaces available to
color_convert. - Deep
Channel - One channel of a
DeepImage. - Deep
Image - A deep image: every pixel holds a list of samples rather than one value.
- Derivatives
- How far the texture coordinate moves per screen pixel.
- Image
Buf - An image held in memory, the unit OpenImageIO’s algorithms operate on.
- Image
Cache - A thread-safe OpenImageIO image cache.
- Image
Cache Builder - Typed configuration for constructing an
ImageCache. - Image
Handle - A file name already resolved against an
ImageCache. - Image
Input - An open image, either a file or a buffer in memory.
- Image
Output - An image file open for writing.
- Image
Spec - 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.
- Texture
Config - How
make_textureshould write a texture. - Texture
Handle - A texture name already resolved against a
TextureSystem. - Texture
Options - How one lookup should be filtered.
- Texture
System - A filtered texture reader.
- Tile
Guard - A tile borrowed from an
ImageCache, released when dropped. - Udim
Inventory - The concrete files of a UDIM set; see
TextureSystem::inventory_udim. - f16
- A 16-bit floating point type implementing the IEEE 754-2008 standard
binary16a.k.a “half” format.
Enums§
- Attribute
Value - A metadata value attached to an
ImageSpec. - Error
- Errors reported by the safe OpenImageIO wrappers.
- Interpolation
Mode - How samples are interpolated inside one mip level.
- MipMode
- How mip levels are chosen.
- Pixel
Format - The scalar type of one channel value.
- Storage
- Where an
ImageBuf’s pixels live. - Texture
Mode - What kind of texture
make_textureshould write. - Wrap
- What a point read outside the data window answers with.
- Wrap
Mode - 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_pathas a texture atoutput_path. - make_
texture_ from_ buffer - Write an image already in memory as a texture at
output_path.
Type Aliases§
- Image
Input IoError - Backwards-compatible name for errors returned by
ImageInput. - Result
- Result type used by the safe OpenImageIO wrappers.