open-ultrahdr 0.1.0

package/src/index.ts

@@ -0,0 +1,368 @@
+/**
+ * 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);
+ * }
+ * ```
+ */
+
+// Re-export types
+export type { ItemId, GainMapMetadata, UltraHdrDecodeResult, UltraHdrEncodeOptions } from './types';
+
+export {
+	ColorGamut,
+	TransferFunction,
+	defaultEncodeOptions,
+	highQualityEncodeOptions,
+	smallSizeEncodeOptions,
+} from './types';
+
+import type { ItemId, GainMapMetadata, UltraHdrDecodeResult, UltraHdrEncodeOptions } from './types';
+
+import { defaultEncodeOptions } from './types';
+
+// WASM class types (these are actual classes from the generated WASM bindings)
+interface WasmUltraHdrEncodeOptions {
+	baseQuality: number;
+	gainMapQuality: number;
+	targetHdrCapacity: number;
+	includeIsoMetadata: boolean;
+	includeUltrahdrV1: boolean;
+	gainMapScale: number;
+}
+
+interface WasmGainMapMetadata {
+	version: string;
+	baseRenditionIsHdr: boolean;
+	gainMapMin: number[];
+	gainMapMax: number[];
+	gamma: number[];
+	offsetSdr: number[];
+	offsetHdr: number[];
+	hdrCapacityMin: number;
+	hdrCapacityMax: number;
+}
+
+// WASM module type (these come from the generated WASM bindings)
+interface UltraHdrWasmModule {
+	default: (moduleOrPath?: string | URL | Response | BufferSource) => Promise<unknown>;
+	isUltraHdr: (buffer: Uint8Array) => boolean;
+	decodeUltraHdr: (buffer: Uint8Array) => UltraHdrDecodeResult;
+	encodeUltraHdr: (
+		sdrBuffer: Uint8Array,
+		hdrBuffer: Float32Array,
+		options: WasmUltraHdrEncodeOptions
+	) => Uint8Array;
+	extractSdrBase: (buffer: Uint8Array) => Uint8Array;
+	getMetadata: (buffer: Uint8Array) => WasmGainMapMetadata;
+	createDefaultOptions: () => WasmUltraHdrEncodeOptions;
+	createHighQualityOptions: () => WasmUltraHdrEncodeOptions;
+	createSmallSizeOptions: () => WasmUltraHdrEncodeOptions;
+	createDefaultMetadata: () => WasmGainMapMetadata;
+	validateMetadata: (metadata: WasmGainMapMetadata) => boolean;
+	estimateHdrHeadroom: (metadata: WasmGainMapMetadata) => number;
+	isMeaningfulHdr: (metadata: WasmGainMapMetadata) => boolean;
+}
+
+/**
+ * Location prefix for WASM files.
+ * Set this before calling any other functions.
+ */
+let location = '';
+
+/**
+ * Cached WASM module instance.
+ */
+let wasmInstance: UltraHdrWasmModule | null = null;
+
+/**
+ * Promise for ongoing WASM initialization.
+ */
+let initPromise: Promise<UltraHdrWasmModule> | null = null;
+
+/**
+ * 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/');
+ * ```
+ */
+export function setLocation(newLocation: string): void {
+	location = newLocation;
+}
+
+/**
+ * Checks if metadata is a WASM class instance (has __wbg_ptr property).
+ */
+function isWasmMetadataInstance(metadata: unknown): boolean {
+	return typeof metadata === 'object' && metadata !== null && '__wbg_ptr' in metadata;
+}
+
+/**
+ * Converts a plain metadata object to a WASM class instance.
+ */
+async function toWasmMetadata(metadata: GainMapMetadata): Promise<WasmGainMapMetadata> {
+	// If it's already a WASM instance, return as-is
+	if (isWasmMetadataInstance(metadata)) {
+		return metadata as unknown as WasmGainMapMetadata;
+	}
+
+	// Create a new WASM instance and copy properties
+	const wasm = await getWasm();
+	const wasmMetadata = wasm.createDefaultMetadata();
+
+	wasmMetadata.version = metadata.version;
+	wasmMetadata.baseRenditionIsHdr = metadata.baseRenditionIsHdr;
+	wasmMetadata.gainMapMin = metadata.gainMapMin;
+	wasmMetadata.gainMapMax = metadata.gainMapMax;
+	wasmMetadata.gamma = metadata.gamma;
+	wasmMetadata.offsetSdr = metadata.offsetSdr;
+	wasmMetadata.offsetHdr = metadata.offsetHdr;
+	wasmMetadata.hdrCapacityMin = metadata.hdrCapacityMin;
+	wasmMetadata.hdrCapacityMax = metadata.hdrCapacityMax;
+
+	return wasmMetadata;
+}
+
+/**
+ * Gets the WASM module, initializing it if necessary.
+ */
+async function getWasm(): Promise<UltraHdrWasmModule> {
+	if (wasmInstance) {
+		return wasmInstance;
+	}
+
+	if (initPromise) {
+		return initPromise;
+	}
+
+	initPromise = (async () => {
+		// Dynamic import of the WASM package
+		const UltraHdrWasm = (await import('open-ultrahdr-wasm')) as unknown as UltraHdrWasmModule;
+
+		// Initialize WASM with the location prefix for the .wasm file
+		// If location is set, construct the full URL to the WASM file
+		if (location) {
+			const wasmUrl = location + 'open_ultrahdr_bg.wasm';
+			await UltraHdrWasm.default(wasmUrl);
+		} else {
+			// Let the WASM module use its default URL resolution (import.meta.url)
+			await UltraHdrWasm.default();
+		}
+
+		wasmInstance = UltraHdrWasm as unknown as UltraHdrWasmModule;
+		return wasmInstance;
+	})();
+
+	return initPromise;
+}
+
+/**
+ * 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!');
+ * }
+ * ```
+ */
+export async function isUltraHdr(buffer: ArrayBuffer): Promise<boolean> {
+	const wasm = await getWasm();
+	return wasm.isUltraHdr(new Uint8Array(buffer));
+}
+
+/**
+ * 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);
+ * ```
+ */
+export async function decodeUltraHdr(
+	id: ItemId,
+	buffer: ArrayBuffer
+): Promise<UltraHdrDecodeResult> {
+	const wasm = await getWasm();
+	return wasm.decodeUltraHdr(new Uint8Array(buffer));
+}
+
+/**
+ * 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' });
+ * ```
+ */
+export async function encodeUltraHdr(
+	id: ItemId,
+	sdrBuffer: ArrayBuffer,
+	hdrBuffer: ArrayBuffer,
+	options?: Partial<UltraHdrEncodeOptions>
+): Promise<ArrayBuffer> {
+	const wasm = await getWasm();
+
+	// Create a proper WASM options instance
+	const wasmOpts = wasm.createDefaultOptions();
+
+	// Apply user-provided options
+	const mergedOpts = { ...defaultEncodeOptions, ...options };
+	wasmOpts.baseQuality = mergedOpts.baseQuality;
+	wasmOpts.gainMapQuality = mergedOpts.gainMapQuality;
+	wasmOpts.targetHdrCapacity = mergedOpts.targetHdrCapacity;
+	wasmOpts.includeIsoMetadata = mergedOpts.includeIsoMetadata;
+	wasmOpts.includeUltrahdrV1 = mergedOpts.includeUltrahdrV1;
+	wasmOpts.gainMapScale = mergedOpts.gainMapScale;
+
+	const result = wasm.encodeUltraHdr(
+		new Uint8Array(sdrBuffer),
+		new Float32Array(hdrBuffer),
+		wasmOpts
+	);
+
+	// Ensure we return a proper ArrayBuffer (not SharedArrayBuffer)
+	return result.buffer.slice(0) as 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' });
+ * ```
+ */
+export async function extractSdrBase(buffer: ArrayBuffer): Promise<ArrayBuffer> {
+	const wasm = await getWasm();
+	const result = wasm.extractSdrBase(new Uint8Array(buffer));
+	// Ensure we return a proper ArrayBuffer (not SharedArrayBuffer)
+	return result.buffer.slice(0) as 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');
+ * ```
+ */
+export async function getMetadata(buffer: ArrayBuffer): Promise<GainMapMetadata> {
+	const wasm = await getWasm();
+	return wasm.getMetadata(new Uint8Array(buffer));
+}
+
+/**
+ * Validates gain map metadata.
+ *
+ * @param metadata - The metadata to validate.
+ * @return True if the metadata is valid.
+ */
+export async function validateMetadata(metadata: GainMapMetadata): Promise<boolean> {
+	const wasm = await getWasm();
+	const wasmMetadata = await toWasmMetadata(metadata);
+	return wasm.validateMetadata(wasmMetadata);
+}
+
+/**
+ * Estimates the HDR headroom from metadata.
+ *
+ * @param metadata - The gain map metadata.
+ * @return Maximum additional stops of dynamic range above SDR.
+ */
+export async function estimateHdrHeadroom(metadata: GainMapMetadata): Promise<number> {
+	const wasm = await getWasm();
+	const wasmMetadata = await toWasmMetadata(metadata);
+	return wasm.estimateHdrHeadroom(wasmMetadata);
+}
+
+/**
+ * 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.
+ */
+export async function isMeaningfulHdr(metadata: GainMapMetadata): Promise<boolean> {
+	const wasm = await getWasm();
+	const wasmMetadata = await toWasmMetadata(metadata);
+	return wasm.isMeaningfulHdr(wasmMetadata);
+}

package/src/types.ts

@@ -0,0 +1,150 @@
+/**
+ * Unique identifier for an item being processed.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export const defaultEncodeOptions: UltraHdrEncodeOptions = {
+	baseQuality: 85,
+	gainMapQuality: 75,
+	targetHdrCapacity: 3.0,
+	includeIsoMetadata: true,
+	includeUltrahdrV1: true,
+	gainMapScale: 1,
+};
+
+/**
+ * High quality encoding options.
+ */
+export const highQualityEncodeOptions: UltraHdrEncodeOptions = {
+	baseQuality: 95,
+	gainMapQuality: 85,
+	targetHdrCapacity: 4.0,
+	includeIsoMetadata: true,
+	includeUltrahdrV1: true,
+	gainMapScale: 1,
+};
+
+/**
+ * Small size encoding options.
+ */
+export const smallSizeEncodeOptions: UltraHdrEncodeOptions = {
+	baseQuality: 75,
+	gainMapQuality: 65,
+	targetHdrCapacity: 3.0,
+	includeIsoMetadata: true,
+	includeUltrahdrV1: true,
+	gainMapScale: 2,
+};