Tiny OpenEXR image library.

tinyexr is a small, single header-only library to load and save OpenEXR (.exr) images. tinyexr is written in portable C++ (no library dependency except for STL), thus tinyexr is good to embed into your application. To use tinyexr, simply copy tinyexr.h, miniz.c and miniz.h(for zlib. You can use system-installed zlib instead of miniz, or the zlib implementation included in stb_image[_write].h. Controlled with TINYEXR_USE_MINIZ and TINYEXR_USE_STB_ZLIB compile flags) into your project.

Security

TinyEXR does not use C++ exception.

TinyEXR now does not use assert from v1.0.4(2023/06/04), except for miniz's assert. (We plan to use wuff's zlib for better security and performance)

TinyEXR is fuzz tested and currently no security issues(No seg fault for any malcious/corrupted input EXR data) as of v1.0.7.

Features

Current status of tinyexr is:

• OpenEXR v1 image
  • [x] Scanline format
  • [x] Tiled format
    • [x] Tile format with no LoD (load).
    • [x] Tile format with LoD (load).
    • [x] Tile format with no LoD (save).
    • [x] Tile format with LoD (save).
  • [x] Custom attributes
• OpenEXR v2 image
  • [ ] Multipart format
    • [x] Load multi-part image
    • [x] Save multi-part image
    • [ ] Load multi-part deep image
    • [ ] Save multi-part deep image
  • [ ] deepscanline
• OpenEXR v2 deep image
  • [x] Loading scanline + ZIPS + HALF or FLOAT pixel type.
• Compression
  • [x] NONE
  • [x] RLE
  • [x] ZIP
  • [x] ZIPS
  • [x] PIZ
  • [x] ZFP (tinyexr extension)
  • [x] B44/B44A (OpenEXR compatible)
  • [x] PXR24 (OpenEXR compatible)
  • [ ] DWA (not planned, patent encumbered)
• Spectral EXR (JCGT 2021)
  • [x] Emissive spectra (S{n}.{wavelength}nm)
  • [x] Reflective spectra (T.{wavelength}nm)
  • [x] Polarised spectra (Stokes S0-S3)
• Line order.
  • [x] Increasing, decreasing (load)
  • [ ] Random?
  • [x] Increasing (save)
  • [ ] decreasing (save)
• Pixel format (UINT, FLOAT).
  • [x] UINT, FLOAT (load)
  • [x] UINT, FLOAT (deep load)
  • [x] UINT, FLOAT (save)
  • [ ] UINT, FLOAT (deep save)
• Support for big endian machine.
  • [x] Loading scanline image
  • [x] Saving scanline image
  • [x] Loading multi-part channel EXR (not tested)
  • [x] Saving multi-part channel EXR (not tested)
  • [ ] Loading deep image
  • [ ] Saving deep image
• Optimization
  • [x] C++11 thread loading
  • [ ] C++11 thread saving
  • [ ] ISPC?
  • [x] OpenMP multi-threading in EXR loading.
  • [x] OpenMP multi-threading in EXR saving.
  • [ ] OpenMP multi-threading in deep image loading.
  • [ ] OpenMP multi-threading in deep image saving.

• C interface.
  • You can easily write language bindings (e.g. golang)

Supported platform

• [x] x86-64
  • [x] Windows 7 or later
  • [x] Linux(posix) system
  • [x] macOS
• [x] AARCH64
  • [x] aarch64 linux(e.g. Raspberry Pi)
  • [x] Android
  • [x] iOS
  • [x] macOS
• [ ] RISC-V(Should work)
• [x] Big endian machine(not maintained, but should work)
  • SPARC, PowerPC, ...
• [x] WebAssembly(JavaScript)
  • Loader only(See )
• [x] Python binding
  • Loader only https://pypi.org/project/pytinyexr/

Requirements

• C++ compiler(C++11 recommended. C++03 may work)

Use case

New TinyEXR (v0.9.5+)

• Godot. Multi-platform 2D and 3D game engine https://godotengine.org/
• Filament. PBR engine(used in a converter tool). https://github.com/google/filament
• PyEXR. Loading OpenEXR (.exr) images using Python. https://github.com/ialhashim/PyEXR
• The-Forge. The Forge Cross-Platform Rendering Framework PC, Linux, Ray Tracing, macOS / iOS, Android, XBOX, PS4 https://github.com/ConfettiFX/The-Forge
• psdr-cuda. Path-space differentiable renderer. https://github.com/uci-rendering/psdr-cuda
• Studying Microfacets BSDFs https://virtualgonio.pages.xlim.fr/
• Your project here!

Older TinyEXR (v0.9.0)

• mallie https://github.com/lighttransport/mallie
• Cinder 0.9.0 https://libcinder.org/notes/v0.9.0
• Piccante (develop branch) http://piccantelib.net/
• Your project here!

Examples

• examples/deepview/ Deep image view
• examples/rgbe2exr/ .hdr to EXR converter
• examples/exr2rgbe/ EXR to .hdr converter
• examples/ldr2exr/ LDR to EXR converter
• examples/exr2ldr/ EXR to LDR converter
• examples/exr2fptiff/ EXR to 32bit floating point TIFF converter
  • for 32bit floating point TIFF to EXR convert, see https://github.com/syoyo/tinydngloader/tree/release/examples/fptiff2exr
• examples/cube2longlat/ Cubemap to longlat (equirectangler) converter
• examples/spectral/ Spectral EXR read/write example

Experimental

• experimental/js/ JavaScript port using Emscripten

Usage

NOTE: API is still subject to change. See the source code for details.

Include tinyexr.h with TINYEXR_IMPLEMENTATION flag (do this only for one .cc file).

//Please include your own zlib-compatible API header before
//including `tinyexr.h` when you disable `TINYEXR_USE_MINIZ`
//#define TINYEXR_USE_MINIZ 0
//#include "zlib.h"
//Or, if your project uses `stb_image[_write].h`, use their
//zlib implementation:
//#define TINYEXR_USE_STB_ZLIB 1
#define TINYEXR_IMPLEMENTATION
#include "tinyexr.h"

Compile flags

• TINYEXR_USE_MINIZ Use miniz (default = 1). Please include zlib.h header before tinyexr.h if you disable miniz support(e.g. use system's zlib).
• TINYEXR_USE_STB_ZLIB Use zlib from stb_image[_write].h instead of miniz or the system's zlib (default = 0).
• TINYEXR_USE_PIZ Enable PIZ compression support (default = 1)
• TINYEXR_USE_ZFP Enable ZFP compression support (TinyEXR extension, default = 0)
• TINYEXR_USE_THREAD Enable threaded loading/storing using C++11 thread (Requires C++11 compiler, default = 0)
  • Use TINYEXR_MAX_THREADS over 0 to use MIN(TINYEXR_MAX_THREADS,hardware_concurrency()) in stead off hardware_concurrency(). (default = 0)
• TINYEXR_USE_OPENMP Enable OpenMP threading support (default = 1 if _OPENMP is defined)
  • Use TINYEXR_USE_OPENMP=0 to force disable OpenMP code path even if OpenMP is available/enabled in the compiler.
• TINYEXR_USE_COMPILER_FP16 Enable use of compiler provided FP16<>FP32 conversions when available (default = 0)

Quickly reading RGB(A) EXR file.

  const char* input = "asakusa.exr";
  float* out; // width * height * RGBA
  int width;
  int height;
  const char* err = NULL; // or nullptr in C++11

  int ret = LoadEXR(&out, &width, &height, input, &err);

  if (ret != TINYEXR_SUCCESS) {
    if (err) {
       fprintf(stderr, "ERR : %s\n", err);
       FreeEXRErrorMessage(err); // release memory of error message.
    }
  } else {
    ...
    free(out); // release memory of image data
  }

Reading layered RGB(A) EXR file.

If you want to read EXR image with layer info (channel has a name with delimiter .), please use LoadEXRWithLayer API.

You need to know layer name in advance (e.g. through EXRLayers API).

  const char* input = ...;
  const char* layer_name = "diffuse"; // or use EXRLayers to get list of layer names in .exr
  float* out; // width * height * RGBA
  int width;
  int height;
  const char* err = NULL; // or nullptr in C++11

  // will read `diffuse.R`, `diffuse.G`, `diffuse.B`, (`diffuse.A`) channels
  int ret = LoadEXRWithLayer(&out, &width, &height, input, layer_name, &err);

  if (ret != TINYEXR_SUCCESS) {
    if (err) {
       fprintf(stderr, "ERR : %s\n", err);
       FreeEXRErrorMessage(err); // release memory of error message.
    }
  } else {
    ...
    free(out); // release memory of image data
  }

Loading Singlepart EXR from a file.

Scanline and tiled format are supported.

  // 1. Read EXR version.
  EXRVersion exr_version;

  int ret = ParseEXRVersionFromFile(&exr_version, argv[1]);
  if (ret != 0) {
    fprintf(stderr, "Invalid EXR file: %s\n", argv[1]);
    return -1;
  }

  if (exr_version.multipart) {
    // must be multipart flag is false.
    return -1;
  }

  // 2. Read EXR header
  EXRHeader exr_header;
  InitEXRHeader(&exr_header);

  const char* err = NULL; // or `nullptr` in C++11 or later.
  ret = ParseEXRHeaderFromFile(&exr_header, &exr_version, argv[1], &err);
  if (ret != 0) {
    fprintf(stderr, "Parse EXR err: %s\n", err);
    FreeEXRErrorMessage(err); // free's buffer for an error message
    return ret;
  }

  // // Read HALF channel as FLOAT.
  // for (int i = 0; i < exr_header.num_channels; i++) {
  //   if (exr_header.pixel_types[i] == TINYEXR_PIXELTYPE_HALF) {
  //     exr_header.requested_pixel_types[i] = TINYEXR_PIXELTYPE_FLOAT;
  //   }
  // }

  EXRImage exr_image;
  InitEXRImage(&exr_image);

  ret = LoadEXRImageFromFile(&exr_image, &exr_header, argv[1], &err);
  if (ret != 0) {
    fprintf(stderr, "Load EXR err: %s\n", err);
    FreeEXRHeader(&exr_header);
    FreeEXRErrorMessage(err); // free's buffer for an error message
    return ret;
  }

  // 3. Access image data
  // `exr_image.images` will be filled when EXR is scanline format.
  // `exr_image.tiled` will be filled when EXR is tiled format.

  // 4. Free image data
  FreeEXRImage(&exr_image);
  FreeEXRHeader(&exr_header);

Loading Multipart EXR from a file.

Scanline and tiled format are supported.

  // 1. Read EXR version.
  EXRVersion exr_version;

  int ret = ParseEXRVersionFromFile(&exr_version, argv[1]);
  if (ret != 0) {
    fprintf(stderr, "Invalid EXR file: %s\n", argv[1]);
    ret