open-ultrahdr 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# Open UltraHDR
+
+TypeScript/JavaScript library for UltraHDR (ISO 21496-1) gain map support.
+
+See the [main README](../README.md) for full documentation.
+
+## Installation
+
+```bash
+npm install open-ultrahdr
+```
+
+## Quick Start
+
+```typescript
+import { isUltraHdr, extractSdrBase, setLocation } from 'open-ultrahdr';
+
+// Set WASM file location
+setLocation('/assets/wasm/');
+
+// Check if image is UltraHDR
+const buffer = await file.arrayBuffer();
+if (await isUltraHdr(buffer)) {
+    const sdrBuffer = await extractSdrBase(buffer);
+    // Use sdrBuffer for display on non-HDR screens
+}
+```
+
+## License
+
+GPL-2.0-or-later

package/dist/index.d.mts

@@ -0,0 +1,266 @@
+/**
+ * Unique identifier for an item being processed.
+ */
+type ItemId = string;
+/**
+ * ISO 21496-1 Gain Map Metadata.
+ *
+ * Contains all the metadata required to interpret and apply a gain map
+ * according to the ISO 21496-1 specification.
+ */
+interface GainMapMetadata {
+    /** Specification version (e.g., "1.0") */
+    version: string;
+    /** Whether the base rendition is HDR (false = SDR base, true = HDR base) */
+    baseRenditionIsHdr: boolean;
+    /** Minimum gain value per channel (RGB), in log2 scale */
+    gainMapMin: number[];
+    /** Maximum gain value per channel (RGB), in log2 scale */
+    gainMapMax: number[];
+    /** Gamma correction per channel (RGB) */
+    gamma: number[];
+    /** SDR offset per channel (RGB), used for black point adjustment */
+    offsetSdr: number[];
+    /** HDR offset per channel (RGB), used for black point adjustment */
+    offsetHdr: number[];
+    /** Minimum HDR capacity (log2 scale) where gain map starts to apply */
+    hdrCapacityMin: number;
+    /** Maximum HDR capacity (log2 scale) for full HDR output */
+    hdrCapacityMax: number;
+}
+/**
+ * Result of decoding an UltraHDR image.
+ */
+interface UltraHdrDecodeResult {
+    /** The SDR base image as JPEG bytes */
+    sdrImage: Uint8Array;
+    /** The gain map as JPEG bytes */
+    gainMap: Uint8Array;
+    /** Gain map metadata */
+    metadata: GainMapMetadata;
+    /** Image width in pixels */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+    /** Gain map width in pixels (may differ from image width) */
+    gainMapWidth: number;
+    /** Gain map height in pixels (may differ from image height) */
+    gainMapHeight: number;
+}
+/**
+ * Options for encoding UltraHDR images.
+ */
+interface UltraHdrEncodeOptions {
+    /** JPEG quality for the base image (1-100) */
+    baseQuality: number;
+    /** JPEG quality for the gain map (1-100) */
+    gainMapQuality: number;
+    /** Target HDR capacity (typically 2.0-4.0) */
+    targetHdrCapacity: number;
+    /** Whether to include ISO 21496-1 metadata */
+    includeIsoMetadata: boolean;
+    /** Whether to include UltraHDR v1 metadata for Android compatibility */
+    includeUltrahdrV1: boolean;
+    /** Downscale factor for the gain map (1 = same size, 2 = half, 4 = quarter) */
+    gainMapScale: number;
+}
+/**
+ * Color gamut enumeration for HDR images.
+ */
+declare enum ColorGamut {
+    /** Standard sRGB color space (BT.709 primaries) */
+    Srgb = 0,
+    /** Display P3 wide color gamut */
+    DisplayP3 = 1,
+    /** BT.2100/BT.2020 wide color gamut (HDR) */
+    Bt2100 = 2
+}
+/**
+ * Transfer function for encoding luminance.
+ */
+declare enum TransferFunction {
+    /** sRGB transfer function (gamma ~2.2) */
+    Srgb = 0,
+    /** Linear (no gamma) */
+    Linear = 1,
+    /** Perceptual Quantizer (PQ) - SMPTE ST 2084 */
+    Pq = 2,
+    /** Hybrid Log-Gamma (HLG) - BT.2100 */
+    Hlg = 3
+}
+/**
+ * Default encoding options.
+ */
+declare const defaultEncodeOptions: UltraHdrEncodeOptions;
+/**
+ * High quality encoding options.
+ */
+declare const highQualityEncodeOptions: UltraHdrEncodeOptions;
+/**
+ * Small size encoding options.
+ */
+declare const smallSizeEncodeOptions: UltraHdrEncodeOptions;
+
+/**
+ * Open UltraHDR Library
+ *
+ * TypeScript bindings for the UltraHDR WASM library.
+ * Provides detection, encoding, and decoding of UltraHDR JPEG images
+ * implementing ISO 21496-1 (gain map) specification.
+ *
+ * @example
+ * ```typescript
+ * import { isUltraHdr, decodeUltraHdr, setLocation } from 'open-ultrahdr';
+ *
+ * // Set the location for WASM files
+ * setLocation('/path/to/wasm/');
+ *
+ * // Check if an image is UltraHDR
+ * const buffer = await file.arrayBuffer();
+ * if (await isUltraHdr(buffer)) {
+ *     const result = await decodeUltraHdr('item-1', buffer);
+ *     console.log('HDR headroom:', result.metadata.hdrCapacityMax);
+ * }
+ * ```
+ */
+
+/**
+ * Sets the location/public path for loading WASM files.
+ *
+ * This must be called before using any other functions when the WASM
+ * files are not in the same directory as the JavaScript bundle.
+ *
+ * @param newLocation - Base URL or path where WASM files are located.
+ *
+ * @example
+ * ```typescript
+ * // Set location before any other calls
+ * setLocation('/assets/wasm/');
+ * ```
+ */
+declare function setLocation(newLocation: string): void;
+/**
+ * Checks if a buffer contains an UltraHDR image.
+ *
+ * This is a fast check that looks for gain map metadata without
+ * fully decoding the image.
+ *
+ * @param buffer - JPEG file contents.
+ * @return True if the image contains UltraHDR/gain map data.
+ *
+ * @example
+ * ```typescript
+ * const buffer = await file.arrayBuffer();
+ * if (await isUltraHdr(buffer)) {
+ *     console.log('This is an UltraHDR image!');
+ * }
+ * ```
+ */
+declare function isUltraHdr(buffer: ArrayBuffer): Promise<boolean>;
+/**
+ * Decodes an UltraHDR image, extracting all components.
+ *
+ * @param id     - Unique identifier for this operation (for cancellation).
+ * @param buffer - UltraHDR JPEG file contents.
+ * @return Decoded result with SDR image, gain map, and metadata.
+ *
+ * @throws Error if the buffer is not a valid UltraHDR JPEG.
+ *
+ * @example
+ * ```typescript
+ * const buffer = await file.arrayBuffer();
+ * const result = await decodeUltraHdr('upload-1', buffer);
+ *
+ * // Access components
+ * const sdrBlob = new Blob([result.sdrImage], { type: 'image/jpeg' });
+ * console.log('Image size:', result.width, 'x', result.height);
+ * console.log('HDR capacity:', result.metadata.hdrCapacityMax);
+ * ```
+ */
+declare function decodeUltraHdr(id: ItemId, buffer: ArrayBuffer): Promise<UltraHdrDecodeResult>;
+/**
+ * Encodes an UltraHDR JPEG from SDR and HDR inputs.
+ *
+ * @param id        - Unique identifier for this operation.
+ * @param sdrBuffer - SDR JPEG image bytes.
+ * @param hdrBuffer - HDR linear RGB data (Float32Array, 3 values per pixel).
+ * @param options   - Encoding options.
+ * @return Encoded UltraHDR JPEG as ArrayBuffer.
+ *
+ * @throws Error if inputs are invalid or dimensions don't match.
+ *
+ * @example
+ * ```typescript
+ * const sdrBuffer = await sdrFile.arrayBuffer();
+ * const hdrData = await getHdrLinearData(); // Float32Array
+ *
+ * const ultraHdr = await encodeUltraHdr('encode-1', sdrBuffer, hdrData, {
+ *     ...defaultEncodeOptions,
+ *     targetHdrCapacity: 4.0,
+ * });
+ *
+ * // Create downloadable file
+ * const blob = new Blob([ultraHdr], { type: 'image/jpeg' });
+ * ```
+ */
+declare function encodeUltraHdr(id: ItemId, sdrBuffer: ArrayBuffer, hdrBuffer: ArrayBuffer, options?: Partial<UltraHdrEncodeOptions>): Promise<ArrayBuffer>;
+/**
+ * Extracts the SDR base image from an UltraHDR JPEG.
+ *
+ * This produces a standard JPEG that can be displayed on any device,
+ * without the gain map metadata. Useful for backwards compatibility.
+ *
+ * @param buffer - UltraHDR JPEG file contents.
+ * @return Standard JPEG without gain map.
+ *
+ * @example
+ * ```typescript
+ * const ultraHdrBuffer = await file.arrayBuffer();
+ * const sdrBuffer = await extractSdrBase(ultraHdrBuffer);
+ *
+ * // Use the SDR image for non-HDR displays
+ * const blob = new Blob([sdrBuffer], { type: 'image/jpeg' });
+ * ```
+ */
+declare function extractSdrBase(buffer: ArrayBuffer): Promise<ArrayBuffer>;
+/**
+ * Gets gain map metadata from an UltraHDR JPEG.
+ *
+ * This is faster than `decodeUltraHdr` when you only need the metadata.
+ *
+ * @param buffer - UltraHDR JPEG file contents.
+ * @return Gain map metadata.
+ *
+ * @throws Error if the buffer doesn't contain gain map metadata.
+ *
+ * @example
+ * ```typescript
+ * const metadata = await getMetadata(buffer);
+ * console.log('Version:', metadata.version);
+ * console.log('HDR headroom:', metadata.hdrCapacityMax, 'stops');
+ * ```
+ */
+declare function getMetadata(buffer: ArrayBuffer): Promise<GainMapMetadata>;
+/**
+ * Validates gain map metadata.
+ *
+ * @param metadata - The metadata to validate.
+ * @return True if the metadata is valid.
+ */
+declare function validateMetadata(metadata: GainMapMetadata): Promise<boolean>;
+/**
+ * Estimates the HDR headroom from metadata.
+ *
+ * @param metadata - The gain map metadata.
+ * @return Maximum additional stops of dynamic range above SDR.
+ */
+declare function estimateHdrHeadroom(metadata: GainMapMetadata): Promise<number>;
+/**
+ * Checks if metadata indicates a meaningful HDR image.
+ *
+ * @param metadata - The gain map metadata.
+ * @return True if the gain map provides significant dynamic range extension.
+ */
+declare function isMeaningfulHdr(metadata: GainMapMetadata): Promise<boolean>;
+
+export { ColorGamut, type GainMapMetadata, type ItemId, TransferFunction, type UltraHdrDecodeResult, type UltraHdrEncodeOptions, decodeUltraHdr, defaultEncodeOptions, encodeUltraHdr, estimateHdrHeadroom, extractSdrBase, getMetadata, highQualityEncodeOptions, isMeaningfulHdr, isUltraHdr, setLocation, smallSizeEncodeOptions, validateMetadata };

package/dist/index.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Unique identifier for an item being processed.
+ */
+type ItemId = string;
+/**
+ * ISO 21496-1 Gain Map Metadata.
+ *
+ * Contains all the metadata required to interpret and apply a gain map
+ * according to the ISO 21496-1 specification.
+ */
+interface GainMapMetadata {
+    /** Specification version (e.g., "1.0") */
+    version: string;
+    /** Whether the base rendition is HDR (false = SDR base, true = HDR base) */
+    baseRenditionIsHdr: boolean;
+    /** Minimum gain value per channel (RGB), in log2 scale */
+    gainMapMin: number[];
+    /** Maximum gain value per channel (RGB), in log2 scale */
+    gainMapMax: number[];
+    /** Gamma correction per channel (RGB) */
+    gamma: number[];
+    /** SDR offset per channel (RGB), used for black point adjustment */
+    offsetSdr: number[];
+    /** HDR offset per channel (RGB), used for black point adjustment */
+    offsetHdr: number[];
+    /** Minimum HDR capacity (log2 scale) where gain map starts to apply */
+    hdrCapacityMin: number;
+    /** Maximum HDR capacity (log2 scale) for full HDR output */
+    hdrCapacityMax: number;
+}
+/**
+ * Result of decoding an UltraHDR image.
+ */
+interface UltraHdrDecodeResult {
+    /** The SDR base image as JPEG bytes */
+    sdrImage: Uint8Array;
+    /** The gain map as JPEG bytes */
+    gainMap: Uint8Array;
+    /** Gain map metadata */
+    metadata: GainMapMetadata;
+    /** Image width in pixels */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+    /** Gain map width in pixels (may differ from image width) */
+    gainMapWidth: number;
+    /** Gain map height in pixels (may differ from image height) */
+    gainMapHeight: number;
+}
+/**
+ * Options for encoding UltraHDR images.
+ */
+interface UltraHdrEncodeOptions {
+    /** JPEG quality for the base image (1-100) */
+    baseQuality: number;
+    /** JPEG quality for the gain map (1-100) */
+    gainMapQuality: number;
+    /** Target HDR capacity (typically 2.0-4.0) */
+    targetHdrCapacity: number;
+    /** Whether to include ISO 21496-1 metadata */
+    includeIsoMetadata: boolean;
+    /** Whether to include UltraHDR v1 metadata for Android compatibility */
+    includeUltrahdrV1: boolean;
+    /** Downscale factor for the gain map (1 = same size, 2 = half, 4 = quarter) */
+    gainMapScale: number;
+}
+/**
+ * Color gamut enumeration for HDR images.
+ */
+declare enum ColorGamut {
+    /** Standard sRGB color space (BT.709 primaries) */
+    Srgb = 0,
+    /** Display P3 wide color gamut */
+    DisplayP3 = 1,
+    /** BT.2100/BT.2020 wide color gamut (HDR) */
+    Bt2100 = 2
+}
+/**
+ * Transfer function for encoding luminance.
+ */
+declare enum TransferFunction {
+    /** sRGB transfer function (gamma ~2.2) */
+    Srgb = 0,
+    /** Linear (no gamma) */
+    Linear = 1,
+    /** Perceptual Quantizer (PQ) - SMPTE ST 2084 */
+    Pq = 2,
+    /** Hybrid Log-Gamma (HLG) - BT.2100 */
+    Hlg = 3
+}
+/**
+ * Default encoding options.
+ */
+declare const defaultEncodeOptions: UltraHdrEncodeOptions;
+/**
+ * High quality encoding options.
+ */
+declare const highQualityEncodeOptions: UltraHdrEncodeOptions;
+/**
+ * Small size encoding options.
+ */
+declare const smallSizeEncodeOptions: UltraHdrEncodeOptions;
+
+/**
+ * Open UltraHDR Library
+ *
+ * TypeScript bindings for the UltraHDR WASM library.
+ * Provides detection, encoding, and decoding of UltraHDR JPEG images
+ * implementing ISO 21496-1 (gain map) specification.
+ *
+ * @example
+ * ```typescript
+ * import { isUltraHdr, decodeUltraHdr, setLocation } from 'open-ultrahdr';
+ *
+ * // Set the location for WASM files
+ * setLocation('/path/to/wasm/');
+ *
+ * // Check if an image is UltraHDR
+ * const buffer = await file.arrayBuffer();
+ * if (await isUltraHdr(buffer)) {
+ *     const result = await decodeUltraHdr('item-1', buffer);
+ *     console.log('HDR headroom:', result.metadata.hdrCapacityMax);
+ * }
+ * ```
+ */
+
+/**
+ * Sets the location/public path for loading WASM files.
+ *
+ * This must be called before using any other functions when the WASM
+ * files are not in the same directory as the JavaScript bundle.
+ *
+ * @param newLocation - Base URL or path where WASM files are located.
+ *
+ * @example
+ * ```typescript
+ * // Set location before any other calls
+ * setLocation('/assets/wasm/');
+ * ```
+ */
+declare function setLocation(newLocation: string): void;
+/**
+ * Checks if a buffer contains an UltraHDR image.
+ *
+ * This is a fast check that looks for gain map metadata without
+ * fully decoding the image.
+ *
+ * @param buffer - JPEG file contents.
+ * @return True if the image contains UltraHDR/gain map data.
+ *
+ * @example
+ * ```typescript
+ * const buffer = await file.arrayBuffer();
+ * if (await isUltraHdr(buffer)) {
+ *     console.log('This is an UltraHDR image!');
+ * }
+ * ```
+ */
+declare function isUltraHdr(buffer: ArrayBuffer): Promise<boolean>;
+/**
+ * Decodes an UltraHDR image, extracting all components.
+ *
+ * @param id     - Unique identifier for this operation (for cancellation).
+ * @param buffer - UltraHDR JPEG file contents.
+ * @return Decoded result with SDR image, gain map, and metadata.
+ *
+ * @throws Error if the buffer is not a valid UltraHDR JPEG.
+ *
+ * @example
+ * ```typescript
+ * const buffer = await file.arrayBuffer();
+ * const result = await decodeUltraHdr('upload-1', buffer);
+ *
+ * // Access components
+ * const sdrBlob = new Blob([result.sdrImage], { type: 'image/jpeg' });
+ * console.log('Image size:', result.width, 'x', result.height);
+ * console.log('HDR capacity:', result.metadata.hdrCapacityMax);
+ * ```
+ */
+declare function decodeUltraHdr(id: ItemId, buffer: ArrayBuffer): Promise<UltraHdrDecodeResult>;
+/**
+ * Encodes an UltraHDR JPEG from SDR and HDR inputs.
+ *
+ * @param id        - Unique identifier for this operation.
+ * @param sdrBuffer - SDR JPEG image bytes.
+ * @param hdrBuffer - HDR linear RGB data (Float32Array, 3 values per pixel).
+ * @param options   - Encoding options.
+ * @return Encoded UltraHDR JPEG as ArrayBuffer.
+ *
+ * @throws Error if inputs are invalid or dimensions don't match.
+ *
+ * @example
+ * ```typescript
+ * const sdrBuffer = await sdrFile.arrayBuffer();
+ * const hdrData = await getHdrLinearData(); // Float32Array
+ *
+ * const ultraHdr = await encodeUltraHdr('encode-1', sdrBuffer, hdrData, {
+ *     ...defaultEncodeOptions,
+ *     targetHdrCapacity: 4.0,
+ * });
+ *
+ * // Create downloadable file
+ * const blob = new Blob([ultraHdr], { type: 'image/jpeg' });
+ * ```
+ */
+declare function encodeUltraHdr(id: ItemId, sdrBuffer: ArrayBuffer, hdrBuffer: ArrayBuffer, options?: Partial<UltraHdrEncodeOptions>): Promise<ArrayBuffer>;
+/**
+ * Extracts the SDR base image from an UltraHDR JPEG.
+ *
+ * This produces a standard JPEG that can be displayed on any device,
+ * without the gain map metadata. Useful for backwards compatibility.
+ *
+ * @param buffer - UltraHDR JPEG file contents.
+ * @return Standard JPEG without gain map.
+ *
+ * @example
+ * ```typescript
+ * const ultraHdrBuffer = await file.arrayBuffer();
+ * const sdrBuffer = await extractSdrBase(ultraHdrBuffer);
+ *
+ * // Use the SDR image for non-HDR displays
+ * const blob = new Blob([sdrBuffer], { type: 'image/jpeg' });
+ * ```
+ */
+declare function extractSdrBase(buffer: ArrayBuffer): Promise<ArrayBuffer>;
+/**
+ * Gets gain map metadata from an UltraHDR JPEG.
+ *
+ * This is faster than `decodeUltraHdr` when you only need the metadata.
+ *
+ * @param buffer - UltraHDR JPEG file contents.
+ * @return Gain map metadata.
+ *
+ * @throws Error if the buffer doesn't contain gain map metadata.
+ *
+ * @example
+ * ```typescript
+ * const metadata = await getMetadata(buffer);
+ * console.log('Version:', metadata.version);
+ * console.log('HDR headroom:', metadata.hdrCapacityMax, 'stops');
+ * ```
+ */
+declare function getMetadata(buffer: ArrayBuffer): Promise<GainMapMetadata>;
+/**
+ * Validates gain map metadata.
+ *
+ * @param metadata - The metadata to validate.
+ * @return True if the metadata is valid.
+ */
+declare function validateMetadata(metadata: GainMapMetadata): Promise<boolean>;
+/**
+ * Estimates the HDR headroom from metadata.
+ *
+ * @param metadata - The gain map metadata.
+ * @return Maximum additional stops of dynamic range above SDR.
+ */
+declare function estimateHdrHeadroom(metadata: GainMapMetadata): Promise<number>;
+/**
+ * Checks if metadata indicates a meaningful HDR image.
+ *
+ * @param metadata - The gain map metadata.
+ * @return True if the gain map provides significant dynamic range extension.
+ */
+declare function isMeaningfulHdr(metadata: GainMapMetadata): Promise<boolean>;
+
+export { ColorGamut, type GainMapMetadata, type ItemId, TransferFunction, type UltraHdrDecodeResult, type UltraHdrEncodeOptions, decodeUltraHdr, defaultEncodeOptions, encodeUltraHdr, estimateHdrHeadroom, extractSdrBase, getMetadata, highQualityEncodeOptions, isMeaningfulHdr, isUltraHdr, setLocation, smallSizeEncodeOptions, validateMetadata };