# academysoftwarefoundation/openimageio architecture

> Architecture diagram of the GitHub repository academysoftwarefoundation/openimageio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/academysoftwarefoundation/openimageio
- Repository: https://github.com/academysoftwarefoundation/openimageio

## Overview

##### Project Type and Purpose
- This is OpenImageIO (OIIO), a C++/Python tool-set and library for image file I/O, image buffering/processing, texture MIP-map lookups, and command-line utilities.
- It uses a plugin architecture: a core API (ImageInput/ImageOutput/ImageCache/TextureSystem/ImageBuf/ImageBufAlgo) dynamically loads format-specific plugins at runtime.
- It also provides command-line tools (oiiotool, iconvert, idiff, iinfo, igrep, iv) and Python bindings.

##### Main Components
a. Build & Configuration
- CMake project (CMakeLists.txt, src/cmake, conanfile.txt)
- Build-scripts (src/build-scripts)
- CI/CD workflows (.github/workflows)
b. Core Library
- libOpenImageIO (src/libOpenImageIO) – core classes and image algorithms
- libutil and libtexture – supporting utilities and texture subsystem
c. Plugin Manager
- Plugin registry within core library that discovers/loads format plugins
d. Format Plugins
- One directory per format (e.g., jpeg.imageio, openexr.imageio, png.imageio, raw.imageio, etc.)
- Each compiles to a shared library implementing ImageInput/ImageOutput interface
- External codec libs: libpng, libjpeg, OpenEXR, libraw, zlib, etc.
e. Command-line Tools
- oiiotool, iconvert, idiff, iinfo, igrep, iv (src/oiiotool, src/iconvert, …)
- Linked against core library and load plugins at runtime
f. Python Bindings
- PyBind11 wrappers (src/python) exposing core APIs to Python
g. Testsuite
- testsuite/… organizes tests by format and tool, invoking command-line tools or APIs
h. Documentation
- docs/… and docs/dev/Architecture.md describe high-level architecture

##### Relationships & Interactions
- Tools and Python bindings → call Core Library APIs → Plugin Manager → Format Plugin → External image-format libraries → Read/Write image files
- TextureSystem → built on top of ImageCache → manages on-disk caching + MIP-map filtering
- Build system compiles Core Library, Plugin Libraries, Tools, Python module; CI/CD automates testing/deployment

##### Architectural Patterns & Principles
- Plugin/Factory pattern: core API defines abstract ImageInput/ImageOutput; concrete implementations are discovered via registry and loaded dynamically
- Modular layering: core logic (libOpenImageIO) separated from format implementations (plugins) and front-ends (tools, Python)
- Separation of concerns:
- Core algorithms and data structures in libOpenImageIO
- Utilities (filesystem, threading, logging) in libutil
- Texture caching in libtexture
- Format-specific I/O in plugins
- User-facing interfaces in tools and Python module
- Build-time decoupling of external dependencies via CMake “Find…” modules and build-scripts

##### Essential Elements
- Clear labels: “libOpenImageIO”, “Plugin Manager”, “jpeg.imageio plugin”, “oiiotool”, “pybind11”, “CMake”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI Layer
    subgraph "Build & CI"
        CMake["CMakeLists.txt"]:::build
        CMakeMod["src/cmake/"]:::build
        Conan["conanfile.txt"]:::build
        BuildScripts["src/build-scripts/"]:::build
        CI[".github/workflows/"]:::build
    end

    %% Core Libraries Layer
    subgraph "Core Libraries"
        Core["libOpenImageIO"]:::core
        Util["libutil"]:::core
        Texture["libtexture"]:::core
        PluginMgr["Plugin Manager"]:::core
    end

    %% Plugins Layer
    subgraph "Format Plugins"
        BMP["bmp.imageio plugin"]:::plugin
        JPEG["jpeg.imageio plugin"]:::plugin
        PNG["png.imageio plugin"]:::plugin
        EXR["openexr.imageio plugin"]:::plugin
        RAW["raw.imageio plugin"]:::plugin
        TIFF["tiff.imageio plugin"]:::plugin
    end

    %% Tools & Bindings Layer
    subgraph "Tools & Bindings"
        OIIOtool["oiiotool"]:::tool
        Iconv["iconvert"]:::tool
        Idiff["idiff"]:::tool
        Iinfo["iinfo"]:::tool
        Igrep["igrep"]:::tool
        IV["iv"]:::tool
        PyBind["Python Bindings (PyBind11)"]:::tool
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PngLib["libpng"]:::ext
        JpegLib["libjpeg"]:::ext
        ExrLib["OpenEXR"]:::ext
        RawLib["libraw"]:::ext
        Zlib["zlib"]:::ext
    end

    %% Tests & Documentation
    subgraph "Tests & Docs"
        Tests["testsuite"]:::test
        DocsUser["docs/"]:::test
        DocsDev["docs/dev/Architecture.md"]:::test
    end

    %% Build System Compiles
    CMake -->|"compiles"| Core
    CMake -->|"compiles"| Util
    CMake -->|"compiles"| Texture
    CMake -->|"compiles"| PluginMgr
    CMake -->|"compiles"| BMP
    CMake -->|"compiles"| JPEG
    CMake -->|"compiles"| PNG
    CMake -->|"compiles"| EXR
    CMake -->|"compiles"| RAW
    CMake -->|"compiles"| TIFF
    CMake -->|"compiles"| OIIOtool
    CMake -->|"compiles"| Iconv
    CMake -->|"compiles"| Idiff
    CMake -->|"compiles"| Iinfo
    CMake -->|"compiles"| Igrep
    CMake -->|"compiles"| IV
    CMake -->|"compiles"| PyBind

    %% Runtime Interactions
    OIIOtool -->|"calls APIs"| Core
    Iconv -->|"calls APIs"| Core
    Idiff -->|"calls APIs"| Core
    Iinfo -->|"calls APIs"| Core
    Igrep -->|"calls APIs"| Core
    IV -->|"calls APIs"| Core
    PyBind -->|"wraps APIs"| Core

    Core -->|"uses"| Util
    Core -->|"uses"| Texture
    Core -->|"uses"| PluginMgr

    PluginMgr -->|"loads"| BMP
    PluginMgr -->|"loads"| JPEG
    PluginMgr -->|"loads"| PNG
    PluginMgr -->|"loads"| EXR
    PluginMgr -->|"loads"| RAW
    PluginMgr -->|"loads"| TIFF

    BMP -->|"links"| JpegLib
    JPEG -->|"links"| JpegLib
    PNG -->|"links"| PngLib
    EXR -->|"links"| ExrLib
    RAW -->|"links"| RawLib
    TIFF -->|"links"| Zlib

    Tests -->|"invokes"| OIIOtool
    Tests -->|"invokes"| Iconv
    Tests -->|"invokes"| Idiff
    Tests -->|"invokes"| Iinfo
    Tests -->|"invokes"| Igrep
    Tests -->|"invokes"| IV
    Tests -->|"invokes"| PyBind

    %% Click Events
    click CMakeLists.txt "https://github.com/academysoftwarefoundation/openimageio/blob/main/CMakeLists.txt"
    click CMakeMod "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/cmake"
    click Conan "https://github.com/academysoftwarefoundation/openimageio/blob/main/conanfile.txt"
    click BuildScripts "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/build-scripts"
    click CI "https://github.com/academysoftwarefoundation/openimageio/tree/main/.github/workflows"
    click Core "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/libOpenImageIO"
    click Util "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/libutil"
    click Texture "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/libtexture"
    click PluginMgr "https://github.com/academysoftwarefoundation/openimageio/blob/main/src/libOpenImageIO/imageioplugin.cpp"
    click PluginMgr "https://github.com/academysoftwarefoundation/openimageio/blob/main/src/libutil/plugin.cpp"
    click BMP "https://github.com/academysoftwarefoundation/openimageio/blob/main/src/bmp.imageio"
    click JPEG "https://github.com/academysoftwarefoundation/openimageio/blob/main/src/jpeg.imageio"
    click PNG "https://github.com/academysoftwarefoundation/openimageio/blob/main/src/png.imageio"
    click EXR "https://github.com/academysoftwarefoundation/openimageio/blob/main/src/openexr.imageio"
    click RAW "https://github.com/academysoftwarefoundation/openimageio/blob/main/src/raw.imageio"
    click TIFF "https://github.com/academysoftwarefoundation/openimageio/blob/main/src/tiff.imageio"
    click OIIOtool "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/oiiotool"
    click Iconv "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/iconvert"
    click Idiff "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/idiff"
    click Iinfo "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/iinfo"
    click Igrep "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/igrep"
    click IV "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/iv"
    click PyBind "https://github.com/academysoftwarefoundation/openimageio/tree/main/src/python"
    click Tests "https://github.com/academysoftwarefoundation/openimageio/tree/main/testsuite"
    click DocsUser "https://github.com/academysoftwarefoundation/openimageio/tree/main/docs"
    click DocsDev "https://github.com/academysoftwarefoundation/openimageio/blob/main/docs/dev/Architecture.md"

    %% Styles
    classDef build fill:#cccccc,stroke:#333;
    classDef core fill:#cce5ff,stroke:#0366d6;
    classDef plugin fill:#ccffcc,stroke:#2d862d;
    classDef tool fill:#ffebcc,stroke:#d69f00;
    classDef ext fill:#ffcccc,stroke:#d63638,stroke-dasharray:5 5;
    classDef test fill:#e5ccff,stroke:#7f3fbf;
```
