TinyEXR

https://github.com/syoyo/tinyexr
Admin
TinyEXR is a small, single header-only C++ library for loading and saving OpenEXR (.exr) images with...
Tokens:40,862
Snippets:516
Trust Score:10
License:BSD-3-Clause
Update:3 months ago
Show doc for...
Tokens:
Raw
### Launch local HTTP server

Source: https://github.com/syoyo/tinyexr/blob/release/experimental/js/README.md

Start a local server to host the browser example.

```bash
$ python3 -m http.server
```

--------------------------------

### Build the spectral example

Source: https://github.com/syoyo/tinyexr/blob/release/examples/spectral/README.md

Compile the spectral example utility using make.

```bash
make
```

--------------------------------

### Installation Configuration

Source: https://github.com/syoyo/tinyexr/blob/release/test/CMakeLists.txt

Commented out installation instructions for the library and header files.

```cmake
#install ( TARGETS
#  tinyexr
#  DESTINATION
#  lib
#  )
#install ( FILES
#  tinyexr.h
#  DESTINATION
#  include
#  )
```

--------------------------------

### Compile Example Program

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V2_README.md

Commands to compile and run the example usage program.

```bash
g++ -std=c++11 -Wall -Wextra -I. example_v2_usage.cc -o example_v2_usage
./example_v2_usage input.exr
```

--------------------------------

### Install and run the KTX2 interoperability test

Source: https://github.com/syoyo/tinyexr/blob/release/tools/texpipe/test/three_ktx2_loader/README.md

Standard procedure to install dependencies and execute the test target from the repository root.

```sh
cd tools/texpipe/test/three_ktx2_loader
npm install
cd ../../../..
make texpipe-three-ktx2-test
```

--------------------------------

### Benchmark Output Example

Source: https://github.com/syoyo/tinyexr/blob/release/examples/wasm-benchmark/README.md

Sample output showing performance metrics for different compression types.

```text
TinyEXR V3 WASM Performance Benchmark
=====================================

=== Testing 1920x1080 ===
Generating random 1920x1080 RGBA float image...
Raw image size: 31.64 MB
  NONE   enc=   12.45ms dec=    8.32ms size=  31.64 MB (100.0%)
  RLE    enc=   28.76ms dec=   15.43ms size=  18.25 MB ( 57.7%)
  ZIPS   enc=  125.32ms dec=   42.18ms size=   8.92 MB ( 28.2%)
  ZIP    enc=  118.54ms dec=   38.65ms size=   8.78 MB ( 27.8%)
  PIZ    enc=   85.21ms dec=   52.34ms size=   6.45 MB ( 20.4%)
  PXR24  enc=   35.18ms dec=   18.92ms size=  23.73 MB ( 75.0%)
  B44    enc=   22.45ms dec=   12.67ms size=  12.55 MB ( 39.7%)
  B44A   enc=   23.12ms dec=   13.01ms size=  12.55 MB ( 39.7%)

=== Summary ===

Size         | Comp     | Encoded      | Ratio    | Enc(ms)    | Dec(ms)    | Enc MB/s   | Dec MB/s
-------------|----------|--------------|----------|------------|------------|------------|----------
1920x1080    | NONE     | 31.64 MB     | 100.0%   | 12.45      | 8.32       | 2541.0     | 3802.4
1920x1080    | RLE      | 18.25 MB     | 57.7%    | 28.76      | 15.43      | 1100.3     | 2051.2
...
```

--------------------------------

### Run Browser Benchmarks

Source: https://github.com/syoyo/tinyexr/blob/release/examples/wasm-benchmark/README.md

Start a local HTTP server to host the browser-based benchmark interface.

```bash
# Start HTTP server
python3 -m http.server 8080

# Or use Make
make run-browser
```

--------------------------------

### Serve with openexr-images directory

Source: https://github.com/syoyo/tinyexr/blob/release/web/tocio/README.md

Starts a local HTTP server when the repository and openexr-images are siblings.

```bash
# if /work/tinyexr-tocio and /work/openexr-images are siblings:
cd /work && python3 -m http.server 8000
# open http://localhost:8000/tinyexr-tocio/web/tocio/
```

--------------------------------

### Serve the demo locally

Source: https://github.com/syoyo/tinyexr/blob/release/web/texcomp/README.md

Command to start a local HTTP server from the repository root to host the demo.

```sh
python3 -m http.server
```

--------------------------------

### Serve the demo locally

Source: https://github.com/syoyo/tinyexr/blob/release/web/tocio/README.md

Starts a local HTTP server to host the ES modules and WASM files.

```bash
# from the repo root
python3 -m http.server 8000
# open http://localhost:8000/web/tocio/
```

--------------------------------

### Example output

Source: https://github.com/syoyo/tinyexr/blob/release/examples/spectral/README.md

Sample output from reading a spectral EXR file.

```text
Loading spectral EXR: test_emissive.exr
Confirmed: File is a spectral EXR
Spectrum type: emissive
Spectral units: W.m^-2.sr^-1.nm^-1
Number of wavelengths: 31
Wavelength range: 400.0 nm - 700.0 nm
Wavelengths: 400, 410, 420, 430, 440, 450, 460, 470, 480, 490,
            500, 510, 520, 530, 540, 550, 560, 570, 580, 590,
            600, 610, 620, 630, 640, 650, 660, 670, 680, 690,
            700 nm

Channels (31 total):
  [0] S0.400,000000nm (wavelength=400.0nm, stokes=S0)
  [1] S0.410,000000nm (wavelength=410.0nm, stokes=S0)
  ...
```

--------------------------------

### Compress and decompress with BC7

Source: https://github.com/syoyo/tinyexr/blob/release/doc/texcomp.md

Example of initializing BC7 options, compressing RGBA8 data, and performing decompression.

```c
#include "texcomp.h"

tc_bc7_options opt;
tc_bc7_options_init(&opt);
opt.quality = TC_BC7_QUALITY_MEDIUM;

size_t n = tc_bc7_compressed_size(w, h);
uint8_t *blocks = malloc(n);
tc_bc7_compress_rgba8(rgba, w, h, w * 4, &opt, blocks, n);

/* and back — the same decoder the KTX2 reader uses */
tc_bc7_decompress_rgba8(blocks, w, h, w * 4, out_rgba, w * h * 4);
```

--------------------------------

### Serve Browser Benchmark via HTTP

Source: https://github.com/syoyo/tinyexr/blob/release/examples/wasm-benchmark/README.md

Command to start a local HTTP server to bypass browser restrictions on ES modules.

```bash
python3 -m http.server 8080
```

--------------------------------

### Configure OpenEXR paths for comparison

Source: https://github.com/syoyo/tinyexr/blob/release/benchmark/README.md

Specify custom installation paths for OpenEXR when running the comparison benchmark.

```sh
make bench-compare OPENEXR_ROOT=/path/to/openexr OPENEXR_BUILD=/path/to/openexr/_build
```

--------------------------------

### Run Local Development Server

Source: https://github.com/syoyo/tinyexr/blob/release/web/viewer/README.md

Starts a local HTTP server to serve ES6 modules and WASM files, which cannot be loaded via the file:// protocol.

```sh
python3 -m http.server
# open http://localhost:8000/
```

--------------------------------

### Pipeline integration with texpipe

Source: https://github.com/syoyo/tinyexr/blob/release/tools/envmap/README.md

Example of piping an octahedral projection output into texpipe for compression.

```sh
envmap convert -i env.exr --to octa --size 512 -o octa.exr
texpipe -i octa.exr -o octa.ktx2 --format bc6h --octa --container ktx2
```

--------------------------------

### Resize an image using the CLI tool

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Example command to resize an EXR image with specific scaling, filtering, and clamping options.

```sh
./build/tir_resize in.exr -o out.exr --scale 0.5 --filter lanczos3 \
    --antiring 1 --clamp-min 0 --stats
```

--------------------------------

### Run test with custom dependency paths

Source: https://github.com/syoyo/tinyexr/blob/release/tools/texpipe/test/three_ktx2_loader/README.md

Execute the test using an existing node_modules installation and a specific browser executable.

```sh
THREE_KTX2_NODE_ROOT=/path/to/web-project \
PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome \
  make texpipe-three-ktx2-test
```

--------------------------------

### Invalid Version Error

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V2_README.md

Example of an error message triggered when an unsupported EXR version is encountered.

```text
[ERROR] Invalid Version
  Message: Unsupported EXR version 3. Only version 2 is supported.
  Context: Parsing EXR version header
  Position: byte 4 (0x4)
```

--------------------------------

### Retrieving Error Context

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V3_README.md

Examples of how to retrieve and display error information using the C++ and C APIs.

```cpp
// C++ API
auto result = decoder.parse_header();
if (!result) {
    for (const auto& err : result.errors) {
        std::cerr << err.to_string() << "\n";
        // Output: "Invalid data: Unsupported compression type [parsing header] at byte 1234"
    }
}
```

```c
// C API
ExrErrorInfo error;
if (exr_context_get_last_error(ctx, &error) == EXR_SUCCESS) {
    printf("Error: %s at byte %llu\n", error.message, error.byte_position);
}
```

--------------------------------

### Decode EXR in JavaScript

Source: https://github.com/syoyo/tinyexr/blob/release/examples/wasm/README.md

Example of loading an EXR file into memory, decoding it using the WASM module, and accessing the resulting RGBA float buffer.

```js
import createModule from './build/exr_v3.mjs';
const M = await createModule();

// decode
const bytes = /* Uint8Array of an .exr file */;
const inPtr = M._malloc(bytes.length);
M.HEAPU8.set(bytes, inPtr);
const wPtr = M._malloc(4), hPtr = M._malloc(4);
const rgbaPtr = M._exrw_decode_rgba(inPtr, bytes.length, wPtr, hPtr);
const w = M.HEAP32[wPtr >> 2], h = M.HEAP32[hPtr >> 2];
const rgba = M.HEAPF32.subarray(rgbaPtr >> 2, (rgbaPtr >> 2) + w * h * 4);
// ... use rgba ...
M._exrw_free(rgbaPtr); M._free(inPtr); M._free(wPtr); M._free(hPtr);
```

--------------------------------

### Manual Build Steps

Source: https://github.com/syoyo/tinyexr/blob/release/web/viewer/README.md

Equivalent manual commands for configuring, building, and deploying the viewer files.

```sh
emcmake cmake -S . -B build -DCMAKE_BUILD_TYPE=MinSizeRel
cmake --build build
cp build/exr_viewer.mjs build/exr_viewer.wasm .
```

--------------------------------

### Create sample files

Source: https://github.com/syoyo/tinyexr/blob/release/examples/spectral/README.md

Generate sample spectral EXR files.

```bash
make samples
```

--------------------------------

### Build and Run Web Demo

Source: https://github.com/syoyo/tinyexr/blob/release/doc/texcomp.md

Commands to compile the web demo using emscripten and serve it locally.

```sh
cd web/texcomp
./build.sh            # needs emcc on PATH; SIMD=1 for -msimd128
python3 -m http.server
# open http://localhost:8000/web/texcomp/  (serve from the repo root)
```

--------------------------------

### Out of Bounds Read Error

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V2_README.md

Example of an error message triggered when a read operation exceeds the file boundaries.

```text
[ERROR] Out of Bounds
  Message: Failed to read 5 bytes
  Context: Reading pixel data
  Position: byte 1024 (0x400)
```

--------------------------------

### Build ZFP Library

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Commands to build the ZFP library from source.

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

--------------------------------

### Initialize and Use TinyEXR WASM Module

Source: https://github.com/syoyo/tinyexr/blob/release/examples/wasm-benchmark/README.md

Demonstrates the lifecycle of the V3BenchmarkContext, including image generation, encoding, decoding, and memory management.

```javascript
import createTinyExrV3Module from './dist/tinyexr_v3_wasm.js';

// Initialize module
const Module = await createTinyExrV3Module();

// Create context
const ctx = new Module.V3BenchmarkContext();

// Generate random test image (returns RGBA float data as string)
const imageData = Module.V3BenchmarkContext.generateRandomImage(width, height, seed);

// Encode image
const encoded = ctx.encodeImage(width, height, 4, imageData, Module.COMPRESSION_PIZ);
if (encoded.ok()) {
    console.log('Encode time:', encoded.encodeTimeMs(), 'ms');
    console.log('Size:', encoded.size(), 'bytes');
    const bytes = encoded.getBytes(); // Uint8Array
}
encoded.delete();

// Decode image
const decoded = ctx.decodeImage(exrDataString);
if (decoded.ok()) {
    console.log('Decode time:', decoded.decodeTimeMs(), 'ms');
    console.log('Dimensions:', decoded.width(), 'x', decoded.height());
    const pixels = decoded.getBytes(); // Float32Array
}
decoded.delete();

// Get memory info
const mem = Module.V3BenchmarkContext.getMemoryInfo();
console.log('Heap:', mem.heapUsed, '/', mem.heapTotal);

// Cleanup
ctx.delete();
```

--------------------------------

### Run exrview

Source: https://github.com/syoyo/tinyexr/blob/release/examples/exrview/README.md

Execute the viewer with an input EXR file.

```bash
$ ./bin/native/Release/exrview input.exr
```

--------------------------------

### Build and execute resize CLI

Source: https://github.com/syoyo/tinyexr/blob/release/tools/resize/README.md

Compile the resize tool and run it with various scaling, filtering, and mode options.

```bash
make resize-cli
./build/tir_resize in.exr -o out.exr --scale 0.5 --filter lanczos3 \
    --antiring 1 --clamp-min 0 --stats
./build/tir_resize height.exr -o small.exr --mode height --reg vertex
./build/tir_resize normal.exr -o mip1.exr --mode normal
```

--------------------------------

### Missing Required Attribute Error

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V2_README.md

Example of an error message triggered when a mandatory EXR header attribute is missing.

```text
[ERROR] Missing Required Attribute
  Message: Required attribute 'dataWindow' not found
  Context: Parsing EXR header attributes
  Position: byte 56 (0x38)
```

--------------------------------

### Build Sample Executable

Source: https://github.com/syoyo/tinyexr/blob/release/CMakeLists.txt

Configures the sample executable build, including Windows-specific definitions and debugger working directory settings.

```cmake
if (TINYEXR_BUILD_SAMPLE)

  set(TINYEXR_SAMPLE_SOURCES
      ${PROJECT_SOURCE_DIR}/test_tinyexr.cc
      )

  add_executable(${SAMPLE_TARGET} ${TINYEXR_SAMPLE_SOURCES})
  target_link_libraries(${SAMPLE_TARGET} ${TINYEXR_EXT_LIBRARIES})
  add_sanitizers(${SAMPLE_TARGET})
  if (WIN32)
    target_compile_definitions(${SAMPLE_TARGET} PUBLIC UNICODE)
    target_compile_definitions(${SAMPLE_TARGET} PUBLIC _UNICODE)

    # Set ${SAMPLE_TARGET} as a startup project for VS IDE
    set_property(DIRECTORY PROPERTY VS_STARTUP_PROJECT ${SAMPLE_TARGET})

    # For easier debugging in VS IDE(cmake 3.8.0 or later required) Set working
    # directory to ${BUILD_TARGET} git repo root.
    if(CMAKE_VERSION VERSION_GREATER 3.8.0)
      set_target_properties(${SAMPLE_TARGET}
              PROPERTIES VS_DEBUGGER_WORKING_DIRECTORY
              "${CMAKE_CURRENT_SOURCE_DIR}")
    endif()
  endif(WIN32)

endif (TINYEXR_BUILD_SAMPLE)
```

--------------------------------

### Benchmark TinyEXR with different deflate backends

Source: https://github.com/syoyo/tinyexr/blob/release/doc/performance-vs-openexr.md

Use these make commands to toggle between the libdeflate backend and the in-tree pure-C codec for performance benchmarking.

```sh
make bench-compare                  # DEFLATE=auto (libdeflate, level 4 = OpenEXR)
make bench-compare DEFLATE=intree   # in-tree pure-C codec
```

--------------------------------

### Invalid Magic Number Error

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V2_README.md

Example of an error message triggered when the file header does not match the expected OpenEXR magic number.

```text
[ERROR] Invalid Magic Number
  Message: Invalid EXR magic number. Expected [0x76 0x2f 0x31 0x01], got [0x00 0x00 0x00 0x00]. This is not a valid OpenEXR file.
  Context: Parsing EXR version header
```

--------------------------------

### Build and serve the browser viewer

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Commands to build the WebGL2 EXR viewer using Emscripten and serve it locally.

```sh
cd web/viewer
./build.sh          # emcmake cmake -S . -B build -DCMAKE_BUILD_TYPE=MinSizeRel && cmake --build build
python3 -m http.server   # then open http://localhost:8000/
```

--------------------------------

### Build exrview on Windows

Source: https://github.com/syoyo/tinyexr/blob/release/examples/exrview/README.md

Generate Visual Studio 2015 project files.

```bash
$ premake5 vs2015
```

--------------------------------

### Define Project and Library

Source: https://github.com/syoyo/tinyexr/blob/release/test/CMakeLists.txt

Sets up the project requirements and defines the library target using the source files.

```cmake
project(tinyexr)
cmake_minimum_required(VERSION 2.8)

set(tinyexr-Source
	${CMAKE_CURRENT_SOURCE_DIR}/../tinyexr.cc
	${CMAKE_CURRENT_SOURCE_DIR}/../tinyexr.h
	)

add_library(tinyexr
			${tinyexr-Source}
	)
```

--------------------------------

### Write spectral EXR files

Source: https://github.com/syoyo/tinyexr/blob/release/examples/spectral/README.md

Generate emissive or reflective spectral EXR files using the spectral_example utility.

```bash
# Create emissive spectrum (blackbody at 6500K)
./spectral_example write output.exr emissive 256 256 6500

# Create reflective spectrum
./spectral_example write output.exr reflective 256 256
```

--------------------------------

### Build and Test nanozlib

Source: https://github.com/syoyo/tinyexr/blob/release/deps/nanozlib/README.md

Compile the project using make and execute the test decoder with a compressed file and its expected uncompressed size.

```bash
$ make
# 11 = uncompressed size
$ ./test_nanozdec test/test-000.txt.zz 11
```

--------------------------------

### Compile and Run Test Suite

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V3_README.md

Commands to compile the test suite with AddressSanitizer and execute the resulting binary.

```bash
# With ASAN
g++ -std=c++17 -I. -I deps/miniz -DTINYEXR_IMPLEMENTATION \
    -fsanitize=address -g -O0 \
    -o tester-v3 test/unit/tester-v3.cc tinyexr_c_impl.c deps/miniz/miniz.c

# Run tests
./tester-v3
```

--------------------------------

### Initialize ZFP Submodule

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Command to initialize the ZFP dependency submodule.

```bash
$ git submodule update --init
```

--------------------------------

### Build the WASM demo

Source: https://github.com/syoyo/tinyexr/blob/release/web/tocio/README.md

Compiles the tocio web demo module using the Emscripten SDK.

```bash
make wasm-tocio-demo          # -> web/tocio/tocio_demo.mjs + .wasm
```

--------------------------------

### Load Multipart EXR from File

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Demonstrates reading version information, parsing headers, and loading image data from a multipart EXR file.

```cpp
  // 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);
```

--------------------------------

### Build and test commands

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Standard make targets for building the library, CLI tool, and running test suites.

```sh
make resize-lib          # build/libtir.a
make resize-cli          # build/tir_resize (EXR in/out)
make resize-test         # unit tests (ASan+UBSan) vs a double-precision oracle
make resize-test-tsan    # ThreadSanitizer
make resize-bench        # MP/s vs exr_resize_float (STB=1 adds stb2)
make resize-fuzz-corpus  # deterministic fuzz replay (ASan+UBSan)
```

--------------------------------

### Build V1 API with ninja on Windows

Source: https://github.com/syoyo/tinyexr/blob/release/test/unit/README.md

Configures and builds the project using ninja and MSVC on Windows.

```batch
> python kuroga.py config-msvc.py
> vcbuild.bat
```

--------------------------------

### Generate Sample EXR File

Source: https://github.com/syoyo/tinyexr/blob/release/web/viewer/README.md

Compiles and runs the C utility to create a small HDR test pattern.

```sh
c++ -x c++ -DTINYEXR_USE_MINIZ=0 -DTINYEXR_USE_STB_ZLIB=0 -include zlib.h \
    gen_sample.c -o gen_sample -lz -lm
./gen_sample          # writes sample.exr
```

--------------------------------

### Build and run texcomp CLI

Source: https://github.com/syoyo/tinyexr/blob/release/doc/texcomp.md

Commands to build the texcomp tool and display help information.

```sh
make texcomp                        # CLI + static lib
build/texcomp/texcomp --help
```

--------------------------------

### Load EXR with V1 API

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V2_README.md

Demonstrates the legacy V1 API approach, which requires manual memory management for error strings and basic return code checking.

```cpp
const char* err = nullptr;
float* rgba = nullptr;
int width, height;

int ret = LoadEXRFromMemory(&rgba, &width, &height, memory, size, &err);
if (ret != TINYEXR_SUCCESS) {
  if (err) {
    fprintf(stderr, "Error: %s\n", err);
    FreeEXRErrorMessage(err);
  }
  return -1;
}
```

--------------------------------

### Run V1 API tests with make

Source: https://github.com/syoyo/tinyexr/blob/release/test/unit/README.md

Executes the test suite using the standard makefile.

```bash
$ make check
```

--------------------------------

### Compile and run the fuzzer

Source: https://github.com/syoyo/tinyexr/blob/release/test/fuzzer/README.md

Use these commands to build the project and execute the fuzzer tests.

```bash
$ make
$ make t
```

--------------------------------

### Run Tocio Validation Harness

Source: https://github.com/syoyo/tinyexr/blob/release/sandbox/tocio/tests/VALIDATION.md

Commands to download reference configurations and execute the validation harness.

```sh
make tocio-fetch-ref     # one-time: download configs into ref/ (needs network)
make tocio-validate      # build + run the harness against ref/configs
```

--------------------------------

### Run TinyEXR standalone benchmarks

Source: https://github.com/syoyo/tinyexr/blob/release/benchmark/README.md

Build and execute the micro-benchmark suite for TinyEXR, optionally specifying custom input files.

```sh
make bench                 # build + run on asakusa.exr
./build/bench foo.exr bar.exr   # run on your own files
```

--------------------------------

### Build and Run SIMD Tests

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_SIMD_README.md

Commands to compile the test suite with scalar or SIMD support and execute benchmarks.

```bash
# Basic (scalar fallback)
g++ -std=c++11 -O2 -o test_simd test_simd.cc

# x86_64 with AVX2+F16C
g++ -std=c++11 -O2 -mavx2 -mf16c -DTINYEXR_ENABLE_SIMD=1 -o test_simd test_simd.cc

# Run tests
./test_simd

# Run benchmarks
./test_simd --bench
```

--------------------------------

### Build exrview on Linux

Source: https://github.com/syoyo/tinyexr/blob/release/examples/exrview/README.md

Generate makefiles for Linux, with optional native file dialog support.

```bash
$ premake5 gmake
```

```bash
$ premake5 --with-gtk3nfd gmake
```

--------------------------------

### Build exrview on Mac

Source: https://github.com/syoyo/tinyexr/blob/release/examples/exrview/README.md

Generate makefiles for macOS.

```bash
$ premake5 gmake
```

--------------------------------

### Build V1 API with ninja on Linux/MacOSX

Source: https://github.com/syoyo/tinyexr/blob/release/test/unit/README.md

Configures and builds the project using ninja on POSIX systems.

```bash
$ python kuroga.py config-posix.py
$ ninja
```

--------------------------------

### Replace Sample Image

Source: https://github.com/syoyo/tinyexr/blob/release/web/viewer/README.md

Copies the full-size test image to the local directory for use in the viewer.

```sh
cp ../../asakusa.exr sample.exr
```

--------------------------------

### Run Test Harness

Source: https://github.com/syoyo/tinyexr/blob/release/test/v3/README.md

Commands to build and execute the test harness against the EXR corpus.

```bash
# Build the harness (also builds build/libtinyexr3.a):
test/v3/parse-tester.py --build

# Run over the default corpus (~/work/openexr-images):
test/v3/parse-tester.py

# Or point at any tree / subset:
test/v3/parse-tester.py ~/work/openexr-images/ScanLines
test/v3/parse-tester.py -v --progress ~/work/openexr-images   # list every file + live progress
test/v3/parse-tester.py --timeout 600 ~/work/openexr-images    # per-file timeout (s)
```

--------------------------------

### Run Node.js CLI Benchmarks

Source: https://github.com/syoyo/tinyexr/blob/release/examples/wasm-benchmark/README.md

Execute the benchmark suite in a Node.js environment with various command-line options.

```bash
# Run benchmark
node js/benchmark.mjs

# With JSON output
node js/benchmark.mjs --json

# Verbose mode
node js/benchmark.mjs -v

# Help
node js/benchmark.mjs --help
```

--------------------------------

### Benchmark with libdeflate

Source: https://github.com/syoyo/tinyexr/wiki/Performance-vs-OpenEXR

Run the benchmark comparison with the libdeflate backend enabled using the specified make flag.

```sh
make bench-compare LIBDEFLATE=1     # -DEXR_USE_LIBDEFLATE, level 4 (= OpenEXR)
```

--------------------------------

### Enable SIMD via Preprocessor

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_SIMD_README.md

Define the SIMD enable macro before including the TinyEXR header to activate hardware acceleration.

```cpp
#define TINYEXR_ENABLE_SIMD 1
#include "tinyexr_v2.hh"
```

--------------------------------

### Build libdeflate with CMake

Source: https://github.com/syoyo/tinyexr/blob/release/deps/libdeflate/README.md

Standard command to configure and build the project using CMake.

```bash
cmake -B build && cmake --build build
```

--------------------------------

### Build the envmap tool

Source: https://github.com/syoyo/tinyexr/blob/release/tools/envmap/README.md

Commands to compile the envmap tool and its associated test suite.

```sh
make envmap            # build/envmap/envmap
make envmap-c11-gate   # strict pure-C11 (no <stdio.h> outside the CLI)
make envmap-test       # projection round-trips, solid-angle, SH/SG
```

--------------------------------

### Project Directory Structure

Source: https://github.com/syoyo/tinyexr/blob/release/examples/wasm-benchmark/README.md

Overview of the file layout for the WASM benchmark project.

```text
examples/wasm-benchmark/
├── README.md           # This file
├── build.sh            # Build script
├── Makefile            # Alternative build
├── src/
│   └── v3_benchmark_bindings.cc   # C++ Emscripten bindings
├── js/
│   ├── benchmark.mjs              # Node.js CLI benchmark
│   ├── benchmark-browser.js       # Browser benchmark
│   ├── utils.js                   # Shared utilities
│   └── results-formatter.js       # Result formatting
├── html/
│   ├── index.html      # Browser UI
│   └── style.css       # Styles
└── dist/               # Build output (generated)
    ├── tinyexr_v3_wasm.js
    ├── tinyexr_v3_wasm.wasm
    └── tinyexr_v3_wasm.d.ts
```

--------------------------------

### Include TinyEXR Implementation

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Define the implementation flag and include the header in exactly one source file.

```cpp
//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"
```

--------------------------------

### Run Cubemap to Longlat Conversion

Source: https://github.com/syoyo/tinyexr/blob/release/examples/cube2longlat/README.md

Execute the conversion tool by providing the six cubemap face images, the desired output resolution, and the output filename.

```bash
$ ./cube2longlat px.exr nx.exr py.exr ny.exr pz.exr nz.exr 512 longlat.exr (phi_offset)
```

--------------------------------

### CLI Usage

Source: https://github.com/syoyo/tinyexr/blob/release/tools/texpipe/README.md

Basic command-line usage for converting image formats.

```sh
texpipe -i in.{exr,png} -o out.{ktx2,dds} --format bc7 [opts]
```

--------------------------------

### Build Harness Manually

Source: https://github.com/syoyo/tinyexr/blob/release/test/v3/README.md

Manual compilation commands for the C harness using the TinyEXR library.

```bash
make lib
cc -std=c11 -Iinclude -O2 test/v3/parse_harness.c build/libtinyexr3.a -lm \
   -o test/v3/parse_harness
```

--------------------------------

### Build and Test Targets

Source: https://github.com/syoyo/tinyexr/blob/release/tools/resize/README.md

Available Makefile targets for building the library, running tests with sanitizers, and executing benchmarks.

```makefile
make resize-lib            # build/libtir.a
make resize-c11-gate       # strict C11 -Werror syntax gate + stdio scan
make resize-test           # unit tests under ASan+UBSan (vs a naive
                           #   double-precision reference resampler)
make resize-test-threads   # same, with -DTIR_ENABLE_THREADS
make resize-test-tsan      # ThreadSanitizer build
make resize-bench          # MP/s vs exr_resize_float; STB=1 adds a
                           #   stb_image_resize2 column (drop the header
                           #   into tools/resize/tests/ first, not vendored)
make resize-cli            # build/tir_resize (EXR in/out)
make resize-arm-test       # aarch64 NEON cross-build, runs under qemu
make resize-sve-test       # +SVE unit, qemu -cpu max,sve=on (HWCAP gate)
```

--------------------------------

### Run GPU Benchmarks

Source: https://github.com/syoyo/tinyexr/blob/release/doc/performance-vs-openexr.md

Commands to execute performance benchmarks comparing CPU and GPU paths for various codecs.

```sh
make bench-gpu-jph                                   # asakusa (0.29 MP)
EXR_BENCH_IMG=path/to/img.exr make bench-gpu-jph     # any image
./build/bench_gpu_jph synth:4096x4096                # synthetic NxN probe
```

--------------------------------

### Initialize and process textures with texpipe

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Configures texture processing options and executes the pipeline to generate a KTX2 container.

```c
#include "texpipe.h"          /* resize -> mips -> compress -> container */
tp_options opt;
tp_options_init(&opt, TP_CONTENT_COLOR, TP_CODEC_BC7);
opt.container  = TP_CONTAINER_KTX2;
opt.srgb_aware = 1;           /* filter in linear light, not in sRGB */

uint8_t *ktx2; size_t n;
tp_process(NULL, &view, 1, &opt, &ktx2, &n);
```

--------------------------------

### Sampler API

Source: https://github.com/syoyo/tinyexr/blob/release/tools/resize/README.md

Functions for managing prebuilt samplers for image resizing.

```APIDOC
## Sampler API

### Description
Functions to create, run, and destroy prebuilt samplers for reuse across frames.

### Signatures
- `tir_sampler_create`
- `tir_sampler_run`
- `tir_sampler_destroy`
```

--------------------------------

### Build and test tocio

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Commands to compile the library, run unit tests, fetch reference configurations, and validate numerical accuracy.

```sh
make tocio-lib         # build/libtocio.a
make tocio-test        # unit tests
make tocio-fetch-ref   # fetch the ACES OCIO configs (once)
make tocio-validate    # numerical validation vs PyOpenColorIO
make wasm-tocio-demo   # web/tocio/ browser demo (needs Emscripten)
```

--------------------------------

### CMake Build Configuration

Source: https://github.com/syoyo/tinyexr/blob/release/web/viewer/CMakeLists.txt

The primary CMakeLists.txt file for building the exr_viewer executable with Emscripten.

```cmake
cmake_minimum_required(VERSION 3.13)
project(exr_viewer C)

if(NOT EMSCRIPTEN)
  message(FATAL_ERROR
    "Configure with emcmake, e.g. `emcmake cmake -S . -B build`. "
    "This target only builds with the Emscripten toolchain.")
endif()

# Default to a small build; -Oz is added explicitly below regardless.
if(NOT CMAKE_BUILD_TYPE)
  set(CMAKE_BUILD_TYPE MinSizeRel CACHE STRING "" FORCE)
endif()

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)

set(TINYEXR_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../..")

# v3 core sources: all of src/*.c except the stdio + freestanding shims (matches
# the Makefile's V3_CORE_SRC), plus the bundled zstd codec.
file(GLOB V3_SOURCES "${TINYEXR_ROOT}/src/*.c")
list(FILTER V3_SOURCES EXCLUDE REGEX "/exr_stdio\\.c$")
list(FILTER V3_SOURCES EXCLUDE REGEX "/exr_freestanding\\.c$")

set(ZSTD_SOURCE "${TINYEXR_ROOT}/deps/zstd/tinyexr_zstd.c")

add_executable(exr_viewer
  exr_viewer_wasm.c
  ${V3_SOURCES}
  ${ZSTD_SOURCE})

target_include_directories(exr_viewer PRIVATE
  "${TINYEXR_ROOT}/include"
  "${TINYEXR_ROOT}/src"
  "${TINYEXR_ROOT}/deps/zstd")

# Size-first optimization. -Oz on both compile and link; warnings off (the core
# is exercised by its own test suite, not this example build).
target_compile_options(exr_viewer PRIVATE -Oz -w)

set_target_properties(exr_viewer PROPERTIES SUFFIX ".mjs")

target_link_options(exr_viewer PRIVATE
  -Oz
  "-sMODULARIZE=1"
  "-sEXPORT_ES6=1"
  "-sENVIRONMENT=web"
  "-sFILESYSTEM=0"
  "-sALLOW_MEMORY_GROWTH=1"
  "-sEXPORTED_FUNCTIONS=['_exrv_open','_exrv_close','_exrv_num_parts','_exrv_header_json','_exrv_select','_exrv_select_channels','_exrv_select_ycc','_exrv_level_width','_exrv_level_height','_exrv_decode_block','_exrv_rgba','_exrv_deep_load','_exrv_deep_points','_exrv_deep_count','_exrv_is_spectral','_exrv_spectral_open','_exrv_spectral_width','_exrv_spectral_height','_exrv_spectral_wavelengths','_exrv_spectral_show','_exrv_spectral_composite','_exrv_spectral_pixel','_exrv_free','_malloc','_free']"
  "-sEXPORTED_RUNTIME_METHODS=['HEAPU8','HEAPF32','HEAP32','HEAPU32','UTF8ToString']")
```

--------------------------------

### Load EXR with V2 API

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V2_README.md

Demonstrates the modern V2 API, which uses a Result object to provide structured error information and automatic memory management.

```cpp
auto result = tinyexr::v2::LoadFromMemory(data, size);

if (!result.success) {
  // Human-readable error with full context
  std::cerr << result.error_string() << "\n";

  // Access structured error information
  for (const auto& err : result.errors) {
    std::cerr << "Error at byte " << err.byte_position
              << ": " << err.message << "\n";
  }
  return -1;
}

// Access image data
const auto& img = result.value;
std::cout << "Loaded " << img.width << "x" << img.height << " image\n";
```

--------------------------------

### Build the texcomp project

Source: https://github.com/syoyo/tinyexr/blob/release/web/texcomp/README.md

Commands to build the project using the Emscripten SDK, with options for SIMD support and custom compiler paths.

```sh
./build.sh              # baseline
SIMD=1 ./build.sh       # -msimd128; noticeably faster ASTC/BC7 encode
EMCC=/path/to/emcc ./build.sh
```

--------------------------------

### Build Commands

Source: https://github.com/syoyo/tinyexr/blob/release/tools/texpipe/README.md

Use these make commands to build the texpipe CLI, the C11 gate, or run unit tests.

```sh
make texpipe           # build/libtexpipe.a + build/texpipe/texpipe CLI
make texpipe-c11-gate  # strict pure-C11 gate (no <stdio.h> outside the CLI)
make texpipe-test      # unit tests (per-mip PSNR, alpha coverage, containers)
```

--------------------------------

### Run TinyEXR benchmarks

Source: https://github.com/syoyo/tinyexr/wiki/Performance-vs-OpenEXR

Shell commands to execute performance comparisons between TinyEXR and OpenEXR with varying thread and library configurations.

```sh
make bench-compare THREADS=1                         # single thread (default)
EXR_THREADS=16 ./build/bench_compare                 # 16 threads, both libs
make bench-compare THREADS=1 LIBDEFLATE=1            # + libdeflate backend
```

--------------------------------

### Build the WASM Benchmark

Source: https://github.com/syoyo/tinyexr/blob/release/examples/wasm-benchmark/README.md

Commands to compile the TinyEXR V3 WASM module using the provided build scripts.

```bash
# Navigate to benchmark directory
cd examples/wasm-benchmark

# Build with shell script
./build.sh

# Or use Make
make
```

--------------------------------

### Open a File Dialog in C

Source: https://github.com/syoyo/tinyexr/blob/release/examples/exrview/ThirdPartyLibs/nativefiledialog/README.md

Demonstrates the basic usage of NFD_OpenDialog to prompt the user for a file selection and handle the result.

```C
#include <nfd.h>
#include <stdio.h>
#include <stdlib.h>

int main( void )
{
    nfdchar_t *outPath = NULL;
    nfdresult_t result = NFD_OpenDialog( NULL, NULL, &outPath );
        
    if ( result == NFD_OKAY ) {
        puts("Success!");
        puts(outPath);
        free(outPath);
    }
    else if ( result == NFD_CANCEL ) {
        puts("User pressed cancel.");
    }
    else {
        printf("Error: %s\n", NFD_GetError() );
    }

    return 0;
}
```

--------------------------------

### Implementation instructions for TinyEXR v3 JPH/HTJ2K

Source: https://github.com/syoyo/tinyexr/blob/release/tasks.md

Instructions for continuing the implementation of JPH/HTJ2K decoding, including requirements for error handling, licensing, and testing.

```text
Continue implementing TinyEXR v3 JPH/HTJ2K decode in /mnt/nvme02/work/tinyexr.

Read tasks.md, jph.md, src/exr_jph.c, src/exr_internal.h, and test/unit/test_exr_v3.c first. The current JPH front end parses OpenEXR HT wrapper/JPEG2000 profile, validates RPCL packet metadata and HT codeblock segment structure, has HT forward/reverse/MEL readers, allocates coefficient planes, decodes complete all-empty JPH codestreams through inverse 5/3/RCT/NLT and block store, and returns EXR_ERROR_UNSUPPORTED for non-empty codeblocks.

Continue from the non-empty codeblock boundary. Implement the next smallest verifiable piece toward HT cleanup entropy decode in pure C11, keeping it portable, low-memory, and hardened. Do not use assert(), abort(), or exit(); return exr_result errors for all malformed input. Preserve permissive licensing: if referencing/copying OpenJPH tables or code from /mnt/nvme02/work/openexr/external/OpenJPH, keep BSD-2 copyright/license attribution and do not introduce GPL code.

Use apply_patch for edits. Keep unrelated dirty files untouched. After each slice run:
- make c11-gate
- make test-c
- rg -n "assert\(|abort\(|exit\(" src/exr_jph.c

Current known passing state before this continuation: make c11-gate passes, make test-c reports 129 passed, 0 failed.
```

--------------------------------

### Integrate TinyEXR V2 API with SIMD

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_SIMD_README.md

Enable SIMD support by defining the macro before including headers, then use the v2 namespace functions for accelerated data processing.

```cpp
#define TINYEXR_ENABLE_SIMD 1
#include "tinyexr_v2.hh"
#include "tinyexr_v2_impl.hh"

// Check SIMD status
printf("SIMD: %s\n", tinyexr::v2::GetSIMDInfo());
printf("Enabled: %s\n", tinyexr::v2::IsSIMDEnabled() ? "yes" : "no");

// Convert FP16 to FP32 (SIMD-accelerated)
std::vector<uint16_t> half_data(1024);
std::vector<float> float_data(1024);
tinyexr::v2::ConvertHalfToFloat(half_data.data(), float_data.data(), 1024);

// Convert FP32 to FP16
tinyexr::v2::ConvertFloatToHalf(float_data.data(), half_data.data(), 1024);

// Interleave separate channels into RGBA
std::vector<float> r(256), g(256), b(256), a(256);
std::vector<float> rgba(256 * 4);
tinyexr::v2::InterleaveRGBA(r.data(), g.data(), b.data(), a.data(), rgba.data(), 256);

// Deinterleave RGBA into separate channels
tinyexr::v2::DeinterleaveRGBA(rgba.data(), r.data(), g.data(), b.data(), a.data(), 256);
```

--------------------------------

### Migrate LoadEXR from V1 to V3

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V3_README.md

Comparison of loading an EXR file between the legacy V1 API and the modern V3 C++ API.

```cpp
// V1:
const char* err = nullptr;
float* rgba = nullptr;
int width, height;

int ret = LoadEXR(&rgba, &width, &height, "input.exr", &err);
if (ret != TINYEXR_SUCCESS) {
    fprintf(stderr, "Error: %s\n", err);
    FreeEXRErrorMessage(err);
    return -1;
}
// Use rgba...
free(rgba);
```

```cpp
// V3 (C++):
auto ctx = tinyexr::v3::Context::create().value;
auto decoder = tinyexr::v3::Decoder::from_file(ctx, "input.exr");
if (!decoder) {
    std::cerr << decoder.error_string() << "\n";
    return -1;
}
auto image = decoder.value.parse_header();
// Use image...
// Automatic cleanup via RAII
```

--------------------------------

### Load Singlepart EXR File

Source: https://github.com/syoyo/tinyexr/blob/release/README.md

Manually parse version, header, and image data for full control over the loading process.

```cpp
  // 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);
```

--------------------------------

### Load and process EXR files with C API

Source: https://github.com/syoyo/tinyexr/blob/release/attic/TINYEXR_V3_README.md

Use the pure C API with opaque handles and explicit context management for loading and parsing EXR files.

```c
#include "tinyexr_c.h"

// Create context
ExrContext ctx = NULL;
ExrContextCreateInfo ctx_info = {0};
ctx_info.api_version = TINYEXR_C_API_VERSION;
exr_context_create(&ctx_info, &ctx);

// Create decoder from file
ExrDataSource source;
exr_data_source_from_file("input.exr", &source);

ExrDecoderCreateInfo dec_info = {0};
dec_info.source = source;

ExrDecoder decoder = NULL;
exr_decoder_create(ctx, &dec_info, &decoder);

// Parse header
ExrImage image = NULL;
exr_decoder_parse_header(decoder, &image);

// Get part info
ExrPart part;
exr_image_get_part(image, 0, &part);

ExrPartInfo info;
exr_part_get_info(part, &info);
printf("Size: %dx%d, Channels: %d\n", info.width, info.height, info.num_channels);

// Cleanup
exr_decoder_destroy(decoder);
exr_context_destroy(ctx);
```

--------------------------------

### Configure Emscripten Build

Source: https://github.com/syoyo/tinyexr/blob/release/web/viewer/CMakeLists.txt

Commands to configure and build the project using the Emscripten toolchain.

```bash
emcmake cmake -S . -B build -DCMAKE_BUILD_TYPE=MinSizeRel
cmake --build build
```

--------------------------------

### Run TinyEXR tests

Source: https://github.com/syoyo/tinyexr/blob/release/experimental/js/README.md

Execute the test suite using Node.js.

```bash
$ node test.js
```
Tokens:
Raw