• Stars
    star
    620
  • Rank 72,387 (Top 2 %)
  • Language
    C++
  • Created about 10 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Tiny OpenEXR image loader/saver library

Tiny OpenEXR image library.

Example

AppVeyor build status

Coverity Scan Build Status

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 input EXR data).

Features

Current status of tinyexr is:

  • OpenEXR v1 image
    • Scanline format
    • Tiled format
      • Tile format with no LoD (load).
      • Tile format with LoD (load).
      • Tile format with no LoD (save).
      • Tile format with LoD (save).
    • Custom attributes
  • OpenEXR v2 image
    • Multipart format
      • Load multi-part image
      • Save multi-part image
      • Load multi-part deep image
      • Save multi-part deep image
  • OpenEXR v2 deep image
    • Loading scanline + ZIPS + HALF or FLOAT pixel type.
  • Compression
    • NONE
    • RLE
    • ZIP
    • ZIPS
    • PIZ
    • ZFP (tinyexr extension)
    • B44?
    • B44A?
    • PIX24?
    • DWA (not planned, patent encumbered)
  • Line order.
    • Increasing, decreasing (load)
    • Random?
    • Increasing (save)
    • decreasing (save)
  • Pixel format (UINT, FLOAT).
    • UINT, FLOAT (load)
    • UINT, FLOAT (deep load)
    • UINT, FLOAT (save)
    • UINT, FLOAT (deep save)
  • Support for big endian machine.
    • Loading scanline image
    • Saving scanline image
    • Loading multi-part channel EXR (not tested)
    • Saving multi-part channel EXR (not tested)
    • Loading deep image
    • Saving deep image
  • Optimization
    • C++11 thread loading
    • C++11 thread saving
    • ISPC?
    • OpenMP multi-threading in EXR loading.
    • 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

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

Requirements

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

Use case

New TinyEXR (v0.9.5+)

Older TinyEXR (v0.9.0)

Examples

Experimental

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 supoort (TinyEXR extension, default = 0)
  • TINYEXR_USE_THREAD Enable threaded loading using C++11 thread (Requires C++11 compiler, 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.

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]);
    return -1;
  }

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

  // 2. Read EXR headers in the EXR.
  EXRHeader **exr_headers; // list of EXRHeader pointers.
  int num_exr_headers;
  const char *err = NULL; // or nullptr in C++11 or later

  // Memory for EXRHeader is allocated inside of ParseEXRMultipartHeaderFromFile,
  ret = ParseEXRMultipartHeaderFromFile(&exr_headers, &num_exr_headers, &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;
  }

  printf("num parts = %d\n", num_exr_headers);


  // 3. Load images.

  // Prepare array of EXRImage.
  std::vector<EXRImage> images(num_exr_headers);
  for (int i =0; i < num_exr_headers; i++) {
    InitEXRImage(&images[i]);
  }

  ret = LoadEXRMultipartImageFromFile(&images.at(0), const_cast<const EXRHeader**>(exr_headers), num_exr_headers, 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;
  }

  printf("Loaded %d part images\n", num_exr_headers);

  // 4. 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.

  // 5. Free images
  for (int i =0; i < num_exr_headers; i++) {
    FreeEXRImage(&images.at(i));
  }

  // 6. Free headers.
  for (int i =0; i < num_exr_headers; i++) {
    FreeEXRHeader(exr_headers[i]);
    free(exr_headers[i]);
  }
  free(exr_headers);

Saving Scanline EXR file.

  // See `examples/rgbe2exr/` for more details.
  bool SaveEXR(const float* rgb, int width, int height, const char* outfilename) {

    EXRHeader header;
    InitEXRHeader(&header);

    EXRImage image;
    InitEXRImage(&image);

    image.num_channels = 3;

    std::vector<float> images[3];
    images[0].resize(width * height);
    images[1].resize(width * height);
    images[2].resize(width * height);

    // Split RGBRGBRGB... into R, G and B layer
    for (int i = 0; i < width * height; i++) {
      images[0][i] = rgb[3*i+0];
      images[1][i] = rgb[3*i+1];
      images[2][i] = rgb[3*i+2];
    }

    float* image_ptr[3];
    image_ptr[0] = &(images[2].at(0)); // B
    image_ptr[1] = &(images[1].at(0)); // G
    image_ptr[2] = &(images[0].at(0)); // R

    image.images = (unsigned char**)image_ptr;
    image.width = width;
    image.height = height;

    header.num_channels = 3;
    header.channels = (EXRChannelInfo *)malloc(sizeof(EXRChannelInfo) * header.num_channels);
    // Must be (A)BGR order, since most of EXR viewers expect this channel order.
    strncpy(header.channels[0].name, "B", 255); header.channels[0].name[strlen("B")] = '\0';
    strncpy(header.channels[1].name, "G", 255); header.channels[1].name[strlen("G")] = '\0';
    strncpy(header.channels[2].name, "R", 255); header.channels[2].name[strlen("R")] = '\0';

    header.pixel_types = (int *)malloc(sizeof(int) * header.num_channels);
    header.requested_pixel_types = (int *)malloc(sizeof(int) * header.num_channels);
    for (int i = 0; i < header.num_channels; i++) {
      header.pixel_types[i] = TINYEXR_PIXELTYPE_FLOAT; // pixel type of input image
      header.requested_pixel_types[i] = TINYEXR_PIXELTYPE_HALF; // pixel type of output image to be stored in .EXR
    }

    const char* err = NULL; // or nullptr in C++11 or later.
    int ret = SaveEXRImageToFile(&image, &header, outfilename, &err);
    if (ret != TINYEXR_SUCCESS) {
      fprintf(stderr, "Save EXR err: %s\n", err);
      FreeEXRErrorMessage(err); // free's buffer for an error message
      return ret;
    }
    printf("Saved exr file. [ %s ] \n", outfilename);

    free(rgb);

    free(header.channels);
    free(header.pixel_types);
    free(header.requested_pixel_types);

  }

Reading deep image EXR file. See example/deepview for actual usage.

  const char* input = "deepimage.exr";
  const char* err = NULL; // or nullptr
  DeepImage deepImage;

  int ret = LoadDeepEXR(&deepImage, input, &err);

  // access to each sample in the deep pixel.
  for (int y = 0; y < deepImage.height; y++) {
    int sampleNum = deepImage.offset_table[y][deepImage.width-1];
    for (int x = 0; x < deepImage.width-1; x++) {
      int s_start = deepImage.offset_table[y][x];
      int s_end   = deepImage.offset_table[y][x+1];
      if (s_start >= sampleNum) {
        continue;
      }
      s_end = (s_end < sampleNum) ? s_end : sampleNum;
      for (int s = s_start; s < s_end; s++) {
        float val = deepImage.image[depthChan][y][s];
        ...
      }
    }
  }

deepview

examples/deepview is simple deep image viewer in OpenGL.

DeepViewExample

TinyEXR extension

ZFP

NOTE

TinyEXR adds ZFP compression as an experimemtal support (Linux and MacOSX only).

ZFP only supports FLOAT format pixel, and its image width and height must be the multiple of 4, since ZFP compresses pixels with 4x4 pixel block.

Setup

Checkout zfp repo as an submodule.

$ git submodule update --init

Build

Then build ZFP

$ cd deps/ZFP
$ mkdir -p lib   # Create `lib` directory if not exist
$ make

Set 1 to TINYEXT_USE_ZFP define in tinyexr.h

Build your app with linking deps/ZFP/lib/libzfp.a

ZFP attribute

For ZFP EXR image, the following attribute must exist in its EXR image.

  • zfpCompressionType (uchar).
    • 0 = fixed rate compression
    • 1 = precision based variable rate compression
    • 2 = accuracy based variable rate compression

And the one of following attributes must exist in EXR, depending on the zfpCompressionType value.

  • zfpCompressionRate (double)
    • Specifies compression rate for fixed rate compression.
  • zfpCompressionPrecision (int32)
    • Specifies the number of bits for precision based variable rate compression.
  • zfpCompressionTolerance (double)
    • Specifies the tolerance value for accuracy based variable rate compression.

Note on ZFP compression.

At least ZFP code itself works well on big endian machine.

Unit tests

See test/unit directory.

TODO

Contribution is welcome!

  • Compression
    • B44?
    • B44A?
    • PIX24?
  • Custom attributes
    • Normal image (EXR 1.x)
    • Deep image (EXR 2.x)
  • JavaScript library (experimental, using Emscripten)
    • LoadEXRFromMemory
    • SaveMultiChannelEXR
    • Deep image save/load
  • Write from/to memory buffer.
    • Deep image save/load
  • Tile format.
    • Tile format with no LoD (load).
    • Tile format with LoD (load).
    • Tile format with no LoD (save).
    • Tile format with LoD (save).
  • Support for custom compression type.
    • zfp compression (Not in OpenEXR spec, though)
    • zstd?
  • Multi-channel.
  • Multi-part (EXR2.0)
    • Load multi-part image
    • Load multi-part deep image
  • Line order.
    • Increasing, decreasing (load)
    • Random?
    • Increasing, decreasing (save)
  • Pixel format (UINT, FLOAT).
    • UINT, FLOAT (load)
    • UINT, FLOAT (deep load)
    • UINT, FLOAT (save)
    • UINT, FLOAT (deep save)
  • Support for big endian machine.
    • Loading multi-part channel EXR
    • Saving multi-part channel EXR
    • Loading deep image
    • Saving deep image
  • Optimization
    • ISPC?
    • OpenMP multi-threading in EXR loading.
    • OpenMP multi-threading in EXR saving.
    • OpenMP multi-threading in deep image loading.
    • OpenMP multi-threading in deep image saving.

Python bindings

pytinyexr is available: https://pypi.org/project/pytinyexr/ (loading only as of 0.9.1)

Similar or related projects

License

3-clause BSD

tinyexr uses miniz, which is developed by Rich Geldreich [email protected], and licensed under public domain.

tinyexr tools uses stb, which is licensed under public domain: https://github.com/nothings/stb tinyexr uses some code from OpenEXR, which is licensed under 3-clause BSD license.

Author(s)

Syoyo Fujita ([email protected])

Contributor(s)

More Repositories

1

tinygltf

Header only C++11 tiny glTF 2.0 library
C++
1,582
star
2

tinyobjloader-c

Header only tiny wavefront .obj loader in pure C99
C
346
star
3

tinyusdz

Tiny, dependency-free USDZ/USDA/USDC library written in C++14
C++
283
star
4

tinygltfloader

Header only C++ Tiny glTF loader.
C
247
star
5

tinydng

Header-only Tiny DNG/TIFF loader and writer in C++
C
126
star
6

MMDLoader

Simple MMD(PMD/VMD) loader in C++
C++
105
star
7

lucille

lucille global illumination renderer
C
89
star
8

tacotron-tts-cpp

Tacotron text to speech in C++(synthesize only)
C++
71
star
9

nanovg-nanort

NanoRT(SW ray tracer) backend for NanoVG
C
49
star
10

nanocanvas

NanoCanvas, portable JavaScript vector graphics engine.
C
43
star
11

tinymeshutils

Tiny Mesh utilities(e.g. compute half-edge data structure) in C++11
C++
35
star
12

docker-utils

Docker utilities
Shell
33
star
13

tinyvdbio

TinyVDBIO header-only C++ OpenVDB IO library
C++
32
star
14

eson

ESON, Exa-scale Storage Object Notation
Python
31
star
15

window-bootstrap

Cross-platform C++ Window/UI bootstrap
C
29
star
16

python-rdma-examples

Python RDMA sample scripts
Python
18
star
17

tinyshrot

TinySHRot, header-only C89 spherical harmonics rotation codes.
C
17
star
18

aobench

Automatically exported from code.google.com/p/aobench
HTML
16
star
19

aobench_cs

aobench in OpenGL compute shader!
C++
12
star
20

standalone-pocketfft

pocketfft in standalone C
C
12
star
21

tinyxpd

Dependency-free and header-only C++11 XGen XPD cache I/O library.
C++
11
star
22

USD-build-aarch64

USD build script for aarch64 target
C++
10
star
23

dynamic_bitset

Simple dynamic bitset template class
C++
10
star
24

oi-build

OpenIndiana Unified Build System
C
9
star
25

minioptix

Mini OptiX sample
C
8
star
26

libphm

PHM: Simple Portable Half float(fp16) Map fileformat in C/C++
C
7
star
27

tinylinalg

Tiny linear algebra and matrix math library
7
star
28

xgen-spline-to-cyhair

XGen Interactive Grooming spline to CyHair exporter
C++
7
star
29

node.rdma

RDMA transport layer for node.js
C++
6
star
30

tinylosslessjpeg

Tiny LosslessJPEG decoder in C++11
6
star
31

flutter_native_vulkan_experiment

Experiment to call Vulkan function from Flutter(dart ffi)
Dart
6
star
32

espnet-tts-streamlit

ESPNet TTS with Streamlit GUI
Python
6
star
33

tinycolorio

Header-only C++11 color IO library
Jupyter Notebook
6
star
34

OpenVDB-Android

Android port of OpenVDB
C++
5
star
35

staticstruct

Simple statically typed struct serialization/deserialization library in C++11
C++
5
star
36

raw-images

RAW photo images
5
star
37

espnet-tts

ESPNet TTS standalone execution
Python
4
star
38

mudalang

MUDA(MUltiple Data Accelerator) language
Haskell
4
star
39

solaris-infiniband-tools

Tcl
4
star
40

minijit

Minimal clang/LLVM JIT experiment
CMake
4
star
41

usda-to-usdc-experiment

USDA to USDC conversion experiment in C++
C++
4
star
42

cycles

cycles experimental
C++
3
star
43

tinyarchive

Tiny binary archive library.
C++
3
star
44

parallella-playground

Parallella Epiphany playground
C
3
star
45

aobench_oculus

aobench for Oculus Rift
C++
3
star
46

libtorch_mobile_build

libtorch mobile build script
CMake
2
star
47

libjsonnet-cpp

Embed jsonnet to your C++11 application
C++
2
star
48

francine

Render backend
2
star
49

MUDA

MUDA is a MUltiple Data Accleleration language
Haskell
2
star
50

cmake-rpath-experiment

CMake + RPATH experiment
CMake
2
star
51

alembic-converters

Alembic file formart converters in C++11
C++
2
star
52

jsmuda

optimized code generator written in node.js
JavaScript
2
star
53

llvm-project-mingw-build

llvm-project MinGW build script using llvm-mingw
Shell
2
star
54

LLL

Lucille Light transport Language
Haskell
2
star
55

cyhair-combiner

Simple CyHair combiner tool
C++
2
star
56

jch-vis

Visualize Jump Consistent Hash
1
star
57

visemenet-docker

Run VisnemeNet inference in nvidia-docker container
Dockerfile
1
star
58

klee-avx

avx support branch for klee
1
star
59

OSOgraph

Simple script visualizing OSO instructions using graphviz
Python
1
star
60

orelatex

俺得 latex 環境テンプレート
1
star
61

oremake

oremake
JavaScript
1
star
62

aobench-fortran

Fortran 90 port of aobench
Fortran
1
star
63

aobench-osv

OSv port of aobench
C++
1
star
64

nanostl

NanoSTL, small subset of C++ STL
1
star
65

llvm-win-build

llvm-win-build
1
star
66

aobench-ios

aobench-ios
C
1
star
67

orevfx

ore vfx tool build
1
star
68

clapack-cmake-android-arm64

clapack cmake build for Android ARM64(NDK r20 or later)
C
1
star
69

orebuildenv

俺得ビルド環境
Shell
1
star
70

naiad-tools

Naiad emp processing tools
C
1
star
71

lesh

continuos building tool
JavaScript
1
star