# academysoftwarefoundation/openexr architecture

> Architecture diagram of the GitHub repository academysoftwarefoundation/openexr, 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/openexr
- Repository: https://github.com/academysoftwarefoundation/openexr

## Overview

##### Project type and purpose
- OpenEXR is an open-source, multi-language, multi-platform reference implementation of the high-dynamic-range EXR image file format. It consists of:
- Core C library (“OpenEXRCore”) providing low-level file I/O, compression, header parsing.
- C++ libraries (Imf, Iex, IlmThread, OpenEXRUtil) building atop the core to expose rich image, multi-part, deep-compositing APIs.
- Command-line tools (“exr*” binaries) demonstrating and bundling common workflows.
- Python bindings wrapping the C++ API for scripting.
- Extensive test suites (unit, fuzz, integration).
- Documentation and website generator sources.
- Cross-platform build support via CMake and Bazel.

##### File structure
- Top-level build files: WORKSPACE.bazel, BUILD.bazel, CMakeLists.txt → dual build systems.
- “src/lib/OpenEXRCore”: Pure C code, lowest layer.
- “src/lib/OpenEXR”: C++ API implementation (Imf).
- “src/lib/Iex”: exception and base utilities.
- “src/lib/IlmThread”: threading primitives.
- “src/lib/OpenEXRUtil”: helper classes for common tasks.
- “src/bin”: multiple executables (exrinfo, exr2aces, exrmultipart, etc.) all linking against the C++ libraries.
- “src/wrappers/python”: Python extension module and tests.
- “src/test”: C++ unit and fuzz tests.
- “website”: documentation sources (Sphinx, Doxygen, example apps).

##### README
- Confirms the layering: Imf::RgbaFile writer example uses the OpenEXR::OpenEXR CMake target.
- Emphasizes core objectives: performance, robustness, backwards compatibility.
- References technical docs and examples under the “website” directory.

a. Main components:
- Build System (CMake & Bazel)
- Core C Library (“OpenEXRCore”)
- Exception & Math Library (“Iex” & “Imath”)
- Threading Library (“IlmThread”)
- C++ API Library (“OpenEXR/Imf”)
- Utility Library (“OpenEXRUtil”)
- Command-Line Tools (exrinfo, exr2aces, etc.)
- Python Wrapper Module (“PyOpenEXR”)
- Test Suites (Unit, Fuzz, Integration)
- Documentation Generator & Website
- External Dependencies (zlib/libdeflate, Python, Sphinx, Doxygen)

b. Relationships and interactions:
- The Build System resolves external dependencies, compiles and links all components.
- OpenEXRCore is the lowest dependency; Iex/Imath and IlmThread depend on core only.
- OpenEXR/Imf (C++ API) depends on OpenEXRCore, Iex/Imath, IlmThread.
- OpenEXRUtil depends on Imf and core.
- Command-Line Tools and Examples link against Imf and Util.
- Python Wrapper uses C-API or directly binds Imf symbols.
- Test Suites exercise all layers: core, C++, utilities, CLI, Python.
- Documentation generator parses headers and sources to produce API docs.

c. Architectural patterns & principles:
- Layered modular architecture: Core → Utilities → API → Clients.
- Separation of concerns: compression, threading, math, I/O are separate modules.
- Plugin-style extensibility for compressors (PIZ, ZIP, DWAA, etc.) loaded via dynamic code paths.
- Dual build backends for Bazel and CMake.
- Multi-language support via language bindings.

d. Key technologies/frameworks:
- C++17 standard libraries
- Bazel and CMake build systems
- Python (CPython extension building)
- zlib/libdeflate for compression
- Sphinx & Doxygen for documentation
- GoogleTest (or custom harness) and libFuzzer for tests

##### Essential elements to capture
- Clearly separate OpenEXRCore, Imf API, Python bindings, CLI tools, tests, and docs.
- External dependencies and CI as part of the ecosystem.
- Both build-time (CMake/Bazel) and runtime relationships.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build and CI
    subgraph "Build & CI" 
        BS["Build System\n(CMake & Bazel)"]:::management
        CI["CI & Scripts"]:::management
    end

    %% Core Layer
    subgraph "Low-level Core" 
        Core["OpenEXRCore"]:::core
    end

    %% Mid-level Libraries
    subgraph "Mid-level Libraries"
        Iex["Iex & Imath"]:::mid
        Thread["IlmThread"]:::mid
    end

    %% API Layer
    subgraph "C++ API"
        API["OpenEXR/Imf"]:::mid
        Util["OpenEXRUtil"]:::mid
    end

    %% High-level Clients
    subgraph "Clients & Tools"
        Tools["exr* Command-Line Tools"]:::high
        Python["PyOpenEXR (Python Wrapper)"]:::high
        Examples["C++ Examples"]:::high
    end

    %% Testing
    subgraph "Test Suites"
        Unit["Unit & Integration Tests"]:::testing
        Fuzz["Fuzz Tests"]:::testing
        CLITests["CLI Tool Tests"]:::testing
    end

    %% Documentation
    subgraph "Documentation"
        Docs["Docs & Website Generator"]:::documentation
    end

    %% External Dependencies
    subgraph "External Deps"
        Deps["zlib/libdeflate, Python, Sphinx, Doxygen"]:::external
    end

    %% Relationships
    BS -->|"resolves deps & builds"| Core
    BS -->|"resolves deps & builds"| Iex
    BS -->|"resolves deps & builds"| Thread
    BS -->|"resolves deps & builds"| API
    BS -->|"resolves deps & builds"| Util
    BS -->|"resolves deps & builds"| Tools
    BS -->|"resolves deps & builds"| Python
    BS -->|"resolves deps & builds"| Examples
    BS -->|"resolves deps & builds"| Docs
    BS -->|"runs"| CI

    Core -->|"dependency"| Iex
    Core -->|"dependency"| Thread

    Core -->|"calls into"| API
    Iex -->|"dependency"| API
    Thread -->|"dependency"| API

    API -->|"link against"| Util
    Core -->|"core for"| Util

    API -->|"link against"| Tools
    Util -->|"link against"| Tools

    API -->|"binds"| Python

    API -->|"sample apps"| Examples

    Core -->|"tested by"| Unit
    Iex -->|"tested by"| Unit
    Thread -->|"tested by"| Unit
    API -->|"tested by"| Unit
    Util -->|"tested by"| Unit
    Tools -->|"tested by"| CLITests
    Python -->|"tested by"| Unit
    Python -->|"tested by"| Fuzz

    Docs -->|"parses sources"| Core
    Docs -->|"parses sources"| API
    Docs -->|"parses sources"| Util

    Deps -->|"used by"| BS
    Deps -->|"used by"| Python
    Deps -->|"used by"| Docs

    CI -->|"executes tests"| Unit
    CI -->|"executes tests"| Fuzz
    CI -->|"executes tests"| CLITests
    CI -->|"deploys docs"| Docs

    %% Click Events
    click BS "https://github.com/academysoftwarefoundation/openexr/blob/main/CMakeLists.txt"
    click BS "https://github.com/academysoftwarefoundation/openexr/blob/main/WORKSPACE.bazel"
    click BS "https://github.com/academysoftwarefoundation/openexr/tree/main/bazel/"
    click BS "https://github.com/academysoftwarefoundation/openexr/tree/main/cmake/"
    click Core "https://github.com/academysoftwarefoundation/openexr/tree/main/src/lib/OpenEXRCore"
    click Iex "https://github.com/academysoftwarefoundation/openexr/tree/main/src/lib/Iex"
    click Thread "https://github.com/academysoftwarefoundation/openexr/tree/main/src/lib/IlmThread"
    click API "https://github.com/academysoftwarefoundation/openexr/tree/main/src/lib/OpenEXR"
    click Util "https://github.com/academysoftwarefoundation/openexr/tree/main/src/lib/OpenEXRUtil"
    click Tools "https://github.com/academysoftwarefoundation/openexr/tree/main/src/bin"
    click Python "https://github.com/academysoftwarefoundation/openexr/tree/main/src/wrappers/python"
    click Unit "https://github.com/academysoftwarefoundation/openexr/tree/main/src/test"
    click Fuzz "https://github.com/academysoftwarefoundation/openexr/tree/main/src/test/OpenEXRFuzzTest"
    click CLITests "https://github.com/academysoftwarefoundation/openexr/tree/main/src/test/bin"
    click Docs "https://github.com/academysoftwarefoundation/openexr/tree/main/website"
    click Deps "https://github.com/academysoftwarefoundation/openexr/tree/main/share/ci/scripts"
    click CI "https://github.com/academysoftwarefoundation/openexr/tree/main/.github/workflows"

    %% Styles
    classDef core fill:#E0ECF8,stroke:#0366d6,stroke-width:1px
    classDef mid fill:#D9EFE5,stroke:#238636,stroke-width:1px
    classDef high fill:#FDE2BD,stroke:#bd561d,stroke-width:1px
    classDef management fill:#E8E8E8,stroke:#6a737d,stroke-width:1px
    classDef testing fill:#F0E68C,stroke:#b58600,stroke-width:1px
    classDef documentation fill:#FFF5E5,stroke:#d15704,stroke-width:1px
    classDef external fill:#F2F2F2,stroke:#888888,stroke-width:1px
```
