@bb-studio/exr

OpenEXR scanline parser/decoder for browser and Node.js.

Install

npm install @bb-studio/exr

Core API

import { parseExr, decodeExrPart, readExr, writeExr } from '@bb-studio/exr';

const buffer = await fetch('/image.exr').then((r) => r.arrayBuffer());
const structure = parseExr(buffer);
const decoded = decodeExrPart(buffer, structure, { partId: structure.parts[0].id });

// Convenience parse+decode in one call
const result = readExr(buffer);

// Encode scanline EXR
const encoded = writeExr({
  parts: [
    {
      compression: 3, // ZIP
      dataWindow: { xMin: 0, yMin: 0, xMax: 1, yMax: 1 },
      channels: [{ name: 'R', pixelType: 2, data: new Float32Array([0, 1, 2, 3]) }],
    },
  ],
});

Each part may also provide typed string, int, float, or chromaticities attributes:

const attributes = {
  ocioColorSpace: { type: 'string', value: 'ACEScg' },
  chromaticities: {
    type: 'chromaticities',
    value: {
      redX: 0.713,
      redY: 0.293,
      greenX: 0.165,
      greenY: 0.83,
      blueX: 0.128,
      blueY: 0.044,
      whiteX: 0.32168,
      whiteY: 0.33767,
    },
  },
} as const;

decodeExrPart returns sampled-native channel planes with sampling metadata.

Browser Worker Helpers

import { decodeExrPartWithWorkers, expandDecodedPartChannels } from '@bb-studio/exr/browser';

• decodeExrPartWithWorkers optionally pre-decodes ZIP/DWA chunks using workers.
• expandDecodedPartChannels converts sampled channels into full-resolution planes.

Error/Diagnostics

• Typed failures via ExrError and ExrErrorCode.
• Structured progress events via onEvent callbacks (ExrEvent, ExrEventCode).

Writer Support

• Scanline single-part and multipart writing.
• Compression: NO_COMPRESSION, RLE_COMPRESSION, ZIPS_COMPRESSION, ZIP_COMPRESSION, PIZ_COMPRESSION, PXR24_COMPRESSION, B44_COMPRESSION, B44A_COMPRESSION.
• Pixel types: UINT, HALF, FLOAT.

License

• Package license: MIT (LICENSE)
• Third-party dependency notices: THIRD_PARTY_LICENSES.md