Git Product home page Git Product logo

tinyexr's Introduction

Tiny OpenEXR image library.

Example

AppVeyor build status

Travis 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 into your project.

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?
  • 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 scanline image
    • Saving scanline image
    • 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.
  • C interface.
    • You can easily write language bindings(e.g. golang)

Use case

New TinyEXR(v0.9.5+)

  • Your project here!

Older TinyEXR(v0.9.0)

Examples

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).

#define TINYEXR_IMPLEMENTATION
#include "tinyexr.h"

Compile flags

  • TINYEXR_USE_MINIZ Use embedded miniz(default = 1)
  • TINYEXR_USE_PIZ Enable PIZ compression support(default = 1)
  • TINYEXR_USE_ZFP Enable ZFP compression supoort(TinyEXR extension, 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;

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

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);

  ret = ParseEXRHeaderFromFile(&exr_header, &exr_version, argv[1], &err);
  if (ret != 0) {
    fprintf(stderr, "Parse EXR err: %s\n", err);
    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);
    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);

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;

  // 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);
    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);
    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;
    int ret = SaveEXRImageToFile(&image, &header, argv[2], &err);
    if (ret != TINYEXR_SUCCESS) {
      fprintf(stderr, "Save EXR err: %s\n", err);
      return ret;
    }
    printf("Saved exr file. [ %s ] \n", argv[2]);

    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;
  DeepImage deepImage;

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

  // acccess 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

Defines

  • TINYEXR_USE_MINIZ Set 1(default) to use embedded miniz compression. If you want zlib or custom zlib compatible library, set 0 and link zlib library.
  • TINYEXR_USE_ZFP Set 1 to use ZFP compression.

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 dep/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, 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
    • 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.

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)

tinyexr's People

Contributors

syoyo avatar bkaradzic avatar mattsarett avatar selfshadow avatar andrewfb avatar mmp avatar richardeakin avatar baldurk avatar mwkm avatar

Watchers

babooppa6 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.