OpenImageIO Documentation

OpenImageIO is an extensible image I/O library designed to abstract the reading and writing of 2D image file formats. It uses a plugin-based architecture where specific format support is implemented in dynamic libraries (DLLs, DSOs, etc.) loaded at runtime.

Core Components

• ImageInput & ImageOutput APIs: The primary interfaces for reading and writing image files. They are format-agnostic; the application interacts with the API, and the appropriate plugin handles the format details.
• ImageBuf: A helper class for storing and manipulating images in memory. It uses ImageInput and ImageOutput for file operations and is compatible with the ImageBufAlgo namespace for common image processing operations.
• ImageCache: A class that manages large amounts of image data (potentially terabytes) efficiently by using a small runtime memory footprint (megabytes to a few gigabytes).
• TextureSystem: Provides filtered MIP-map texture lookups, built on top of ImageCache.
• Utility Programs: Includes oiiotool (a command-line image processing engine) and iv (an image viewer).

OpenImageIO (OIIO) is a toolset for reading, writing, and manipulating image files of any format relevant to VFX and animation using a format-agnostic API.

Key components include:

• ImageInput and ImageOutput APIs: High-level abstractions for reading and writing image files without needing to know specific format details. Implementation is handled via plugins loaded at runtime.
• Plugin System: Manages format-specific I/O (e.g., TIFF, JPEG, OpenEXR, PNG, OpenVDB, etc.) as plug-ins.
• Command Line Tools:
  • oiiotool: Format conversion and image processing.
  • iinfo: Prints detailed image information.
  • iconvert: Converts formats, data types, or modifies metadata.
  • idiff: Compares images.
  • igrep: Searches images for matching metadata.
  • iv: An image viewer.
• ImageCache: Manages large amounts of image data (TB scale) efficiently using minimal runtime memory (MB scale).
• TextureSystem: Provides filtered MIP-map texture lookups built on top of ImageCache.
• ImageBuf and ImageBufAlgo: A class for in-memory image storage and a collection of image processing operations.
• Python Bindings: Available for all major APIs.

This prototype implements a texture system designed for GPU-like kernel environments where host and device memory are treated as distinct. It uses a manager/managed architecture to handle texture lookups, missing-resource requests, and retry-based execution.

Core Workflow

1. Host Launch: The host launches a kernel on the device.
2. Kernel Execution: The kernel performs lookups. If a texture or tile is missing, the kernel records a request.
3. Host Resolution: The host detects missing resources via sync_from_managed(), resolves them (e.g., via a TextureLoader), and relaunches the kernel.
4. Convergence: This loop repeats until all required data is resident.

Memory Modes

• non-unified (default): Host and device allocations are distinct; explicit copy_to and copy_from calls are required.
• unified (--unified): Host and device may share the same underlying pointer, though the synchronization flow remains the same.

Overview

ImageCache is a utility class designed for applications that need to read pixels from a large number of image files (potentially thousands of files totaling hundreds of GBs) while maintaining a very small memory footprint (e.g., ~50 MB).

Key Advantages

• Simplified Interface: You refer to images by filename only. You do not need to manually manage ImageInput objects, file handles, or explicit open/close operations.
• Thread Safety: The class is completely thread-safe; it handles internal locking and resource sharing when multiple threads access the same file.
• Automatic Resource Management:
  • File Handles: It maintains a reasonable number of simultaneously open files and automatically closes those not recently used.
  • Memory Management: It loads only requested tiles and automatically releases memory from tiles that haven't been used recently as memory limits are approached.
• Granular Access: Supports retrieving blocks of pixels or locking/reading/releasing individual tiles.

The SeedCorpus consists of small, valid image files used to initialize the fuzzer. The implementation uses two distinct types of corpora:

1. Committed Corpus: Located in src/fuzz/corpora/<format>/. This contains committed synthetic files for specific formats (e.g., dpx, fits, hdr, iff, jpeg2000, jpegxl, openexr, sgi).
2. CI-time Corpus: Located in corpus/<format>/ within the runner workspace. For all other formats, the populate_corpora.py script pulls real-world seeds from the testsuite/ and companion repositories (like oiio-images or dicom-images-pvt) during the CI run. This avoids committing large binary files to the repository.

Seed Corpus Requirements:

• Files must be valid images parseable by OIIO for that specific format.
• Total size should not exceed 5 MB per format to ensure fast loading.
• Files must not contain copyrighted content (must be Apache-2.0 compatible).