Public API and runtime contracts.

ImageLibrary

Create a frozen library with the codec implementations your application accepts. Registration order is preserved in formats(); duplicate format names are rejected.

function createImageLibrary(registration: Iterable<ImageCodec> | ImageLibraryConfiguration): ImageLibrary

interface ImageLibrary {
  formats(): readonly string[]
  open(input: ImageInput, options?: ImageOpenOptions): Promise<Image>
}

interface ImageOpenOptions {
  frame?: number
  resolutionLevel?: number
  tolerantDecoding?: boolean
  limits?: ImageLimitOptions
}

Codec imports

allWebCodecs is the compact common-web group. TIFF remains a direct import because its broader implementation would substantially increase that bundle. allCodecs contains all 14 stable codecs. Both aggregates intentionally exclude experimental HEIF/HEIC.

Experimental HEIC opt-in

import { createImageLibrary } from 'purejsimage'
import { allCodecs } from 'purejsimage/codecs/all'
import { experimentalHeicCodec } from 'purejsimage/codecs/experimental/heic'

const images = createImageLibrary({
  codecs: [...allCodecs, experimentalHeicCodec],
})

purejsimage/hdr provisional

Explicit gain-map HDR inspection, extraction, caller-selected linear rendering, paired geometry, and constrained JPEG or AVIF output. Importing the root package, browser entry, or ordinary JPEG and AVIF codec entries does not load this subsystem. Ordinary JPEG decode continues to return the SDR primary.

import { openGainMapImage } from 'purejsimage/hdr'

const image = await openGainMapImage(input)
try {
  for await (const block of image.render({ displayBoost: 4 })) {
    // Linear rgbf32 or rgbaf32. Values above 1 are retained.
  }

  const jpeg = await image
    .crop({ x: 100, y: 50, width: 1200, height: 800 })
    .resize({ width: 600, height: 400, kernel: 'lanczos3' })
    .jpeg({ metadataMode: 'dual' })
} finally {
  image.close()
}

See the gain-map HDR guide and the local browser workbench.

purejsimage/evidence alpha

Creates a caller-owned, opt-in execution evidence session. Summary mode retains bounded counters, merged source ranges, and PureJsImage-managed byte totals. Trace mode adds bounded events, child scopes, dependency IDs, cache activity, and allocation leases. Importing the root package does not create a collector or include the Raster X-Ray interface.

import { createEvidenceSession, explainImage, instrumentImageSource } from 'purejsimage/evidence'

const evidence = createEvidenceSession({ mode: 'trace' })
const source = instrumentImageSource(inputSource, evidence.context)
const image = await images.open(source)
const plan = await explainImage(image.resize({ width: 800 }).png())
const output = await image.resize({ width: 800 }).png().toBuffer({
  evidence: evidence.context,
})
const report = evidence.finalize()

Reports are versioned, immutable, and JSON safe. Source names are excluded by default. Managed bytes cover only allocations explicitly owned and accounted by PureJsImage, not process RSS or total browser memory. See the Raster X-Ray browser inspector and the execution evidence guide.

Application-platform package entries

The application platform is an alpha API introduced in PureJsImage 0.10.0. Provider and trusted-extension APIs are experimental. The ordinary purejsimage codec pipeline remains the established path: these opt-in entries do not change resize().jpeg() behavior or load analysis code into the root entry.

purejsimage/scientific alpha

Portable labeled-axis datasets, explicit reader registries, document and source identity, RasterBlock reads, and native NumericTile conversion. Concrete formats remain optional through individual reader entries. Use createScientificLibrary(), select a summary from document.datasets, then call openDataset(id). resolveNumericTileSource() uses a compatible direct native source when supplied or the permanent RasterBlock conversion adapter otherwise.

purejsimage/scientific/browser alpha

createScientificFileContext(file, options?) wraps a browser File and explicit companion files without exposing Node paths. For remote data, pass an HTTP Range-backed ImageSource through the portable scientific context. Browsers cannot open arbitrary local path strings.

purejsimage/scientific/node alpha

createScientificPathContext(path, options?) opens the primary file and resolves constrained sibling companions. Filesystem paths and Node resources remain in this adapter and do not enter the portable browser module graph.

Scientific reader entries alpha

Interchange and detector entries: purejsimage/scientific/readers/rpl, purejsimage/scientific/readers/emsa, purejsimage/scientific/readers/nrrd, purejsimage/scientific/readers/meta-image, purejsimage/scientific/readers/nifti, purejsimage/scientific/readers/npy, purejsimage/scientific/readers/blockfile, purejsimage/scientific/readers/mib, and purejsimage/scientific/readers/ebsd-text.

DICOM Part 10 grayscale images are available from purejsimage/scientific/readers/dicom. The first public subset is native uncompressed MONOCHROME1/2 Implicit or Explicit VR Little Endian, Encapsulated Uncompressed Explicit VR Little Endian, RLE Lossless, JPEG Baseline 8-bit, JPEG Lossless Process 14 Selection Value 1, and JPEG 2000 lossless/lossy grayscale, with 8-bit or 16-bit allocation as the transfer syntax permits, signed or unsigned stored values, 12-bit-in-16 normalization, homogeneous multi-frame selection, Pixel Spacing, linear rescale slope/intercept metadata, and Window Center/Width presets. Stored samples are not rescaled, windowed, or inverted. Color, LUT-based presentation, other JPEG Lossless selection values, JPEG-LS, HTJ2K, DICOMweb, and series discovery remain unsupported. The reader is not validated for diagnostic use.

HDF5 dialect readers are available from purejsimage/scientific/readers/ncem-emd and purejsimage/scientific/readers/velox-emd. They identify their internal hierarchy rather than relying on the shared .emd extension.

Import only the formats an application registers: purejsimage/scientific/readers/gsf, purejsimage/scientific/readers/envi, purejsimage/scientific/readers/fits, purejsimage/scientific/readers/mrc, purejsimage/scientific/readers/cbf, purejsimage/scientific/readers/digital-micrograph, purejsimage/scientific/readers/tia-ser, purejsimage/scientific/readers/tia-emi, purejsimage/scientific/readers/tiff, purejsimage/scientific/readers/ome-tiff, purejsimage/scientific/readers/ome-zarr, purejsimage/scientific/readers/aperio-svs, purejsimage/scientific/readers/png, purejsimage/scientific/readers/jpeg, purejsimage/scientific/readers/webp, purejsimage/scientific/readers/bmp, or purejsimage/scientific/readers/jp2. PNG, JPEG, WebP, BMP, and JP2 are low-confidence uint8 codec fallbacks, so specialized scientific readers retain precedence. DigitalMicrograph exposes supported rank-2 through rank-4 scalar and fixture-backed BGRA entries as separate datasets. Ordinary rank-3 arrays use X/Y/Z, while EELS uses X/Y/energy and 4D-STEM uses logical scanX/scanY/kx/ky only when exact Gatan metadata identifies those roles; ambiguous rank-4 arrays remain dimension-0 through dimension-3. Direct reads cover the first physical storage plane: X/Y for images, volumes, and EELS; kx/ky for the verified C-ordered 4D-STEM layout. TIA SER exposes v528 and v544 scalar spectra, spectrum images, and image series with lazy payload reads. The preferred TIA EMI path resolves numbered SER companions, adds bounded acquisition metadata, includes both resources in identity, and applies reciprocal-space interpretation only when EMI mode and SER calibration agree. OME-Zarr 0.4 and 0.5 read directory-like Zarr v2 and v3 stores from a root zarr.json, .zgroup, or .zattrs, or a ZIP archive with that root metadata, map image multiscales, labels, and plate wells onto scientific datasets, and fetch only intersecting regular or sharded chunks, including Blosc 1 LZ4 payloads. Ordinary TIFF instead preserves native signed, floating-point, planar, and N-channel samples, uses labeled page axes for compatible pages, keeps incompatible series separate, and exposes SubIFDs as levels without guessing Z/time or arbitrary-band RGB semantics. Its generic probe remains below OME-TIFF and Aperio. The base scientific entry exports createImageCodecScientificReader({ descriptor, codec, limits }) for deliberate composition without linking concrete codecs into that entry. Selectable frames become separate datasets and codec-declared resolution levels remain within each frame dataset; metadata-only frame counts and decode scaling do not create scientific coordinates. The Aperio entry exports the secure default reader plus createAperioSvsReader({ limits }) for explicit WSI source, dimension, directory, region, decoded-byte, and associated-image ceilings. It exposes a calibrated multiresolution pyramid dataset and separate associated-image datasets without eagerly embedding ICC payload bytes. Applications that deliberately need every first-party format can import purejsimage/scientific/readers/all. These entries export reader values without registering them globally, and the all-readers entry excludes experimental HEIC.

DigitalMicrograph applications that need different admission ceilings can use createDigitalMicrographReader({ limits }) to configure source bytes, dataset count, dimension length, individual dataset bytes, and selected-region bytes.

TIA SER applications can use createTiaSerReader({ limits }) to configure structural metadata, element, source, dataset, selected-region, and source-read ceilings.

TIA EMI applications can use createTiaEmiReader({ limits, ser }) to configure binary-envelope, XML, metadata, companion, dataset, and delegated SER ceilings.

purejsimage/operations alpha

JSON-safe, versioned value-type and operation descriptors, parameter schemas, local registries, provider contracts, semantic support checks, and cost-based provider planning. Executable providers remain separate from descriptors. The strict TypeScript reference provider is permanent; future WASM or WebGPU providers require explicit registration and exact semantic support.

purejsimage/analysis alpha

The intentional application workflow entry: controllers, built-in bundle construction, graph/workspace commands, planning and execution, primary project/ROI/result types, operation IDs, and bounded numeric-raster plans. Initial graph operations include resolution-level selection, crop, resampling, thresholding, Gaussian blur, projection, statistics, histograms, line profiles, and deterministic connected components with lazy uint32 labels and a columnar object table. Stateless tile primitives add parsed band math, normalized difference, linear combination, subtraction, terrain derivatives, regional results, and explicit target-grid resampling or caller-supplied inverse reprojection. See the complete compiled application example.

Raster plans are versioned JSON-safe data. They explicitly record raw or scaled band values, nodata, units, resampling, and coordinate-transform identity and accuracy. Executors expose explicit tile and memory limits and consume only caller-provided bounded NumericTile values; they do not discover transforms, read whole datasets, or create a global cache.

Analysis specialist entries alpha

purejsimage/analysis/results exposes full result schemas, validation, summaries, and memory accounting. purejsimage/analysis/roi exposes geometry, coordinate conversion, masks, and line sampling. purejsimage/analysis/runtime exposes TileRuntime, semantic source/derived identities, tile sources, cache keys, memory estimates, and provider-facing derived tiles. purejsimage/analysis/project exposes canonical project hashes, persistence contracts, explicit migrations, and canonical JSON helpers.

Source cache identity uses complete reader/dataset/resource evidence when available and an explicit session or instance scope otherwise. Derived identity includes source, operation/version, normalized parameters, output, provider/implementation, and generation.

purejsimage/extensions experimental

Composes explicitly supplied trusted bundles into isolated application-owned registries. Reader IDs must begin with the extension ID plus /; value type, operation, provider, and migration IDs must begin with the extension ID plus .. No package-global singleton or hidden auto-registration exists.

TIFF documents, rasters, and profiles

purejsimage/tiff exposes the validated TIFF IFD graph independently of the display-image pipeline. openTiffDocument(source, options?) returns a TiffDocument with stable top-level and SubIFD directory objects. Each TiffDirectory exposes its absolute source offset; getDirectoryByOffset(offset) resolves parsed metadata pointers. getTagInfo(tag) reports bounded field/count/byte-length metadata without fetching an external payload; getTag() reads bounded cached values. A directory creates either an ImageDecoder for display pixels or a RasterDecoder for native-precision, arbitrary-channel samples. readBytes(offset, length, { maxBytes }) performs an exact bounded private-metadata read and returns a defensive copy without exposing the underlying ImageSource.

TiffDocumentOptions adds maxSegmentCount (1,048,576), maxSegmentTableBytes (32 MiB), and maxEncodedSegmentBytes (128 MiB). Segment count and the raw-plus-converted table construction peak are admitted before table payload reads. Display and raster requests include the largest intersecting encoded segment with retained decoded segments, output, and predictor scratch under maxDecodedBytes.

import { MemorySource } from 'purejsimage'
import { createScientificLibrary } from 'purejsimage/scientific'
import { omeTiffReader } from 'purejsimage/scientific/readers/ome-tiff'

const science = createScientificLibrary({ readers: [omeTiffReader] })
const document = await science.open({ primary: { id: 'image', source: new MemorySource(bytes) } })
const dataset = await document.openDataset(document.datasets[0].id)
for await (const block of dataset.readPlane({
  displayAxes: ['x', 'y'], fixedIndices: [{ axisId: 'channel', index: 0 }], resolutionLevel: 0,
  x: 0, y: 0, width: 512, height: 512,
})) {
  consume(block)
}

omeTiffReader validates OME dimensions, sample type, labeled axes, channel metadata, physical pixel size, dimension order, and explicit or implicit TiffData mappings before exposing a ScientificDataset. readPlane() preserves native sample types without materializing a source-sized display bitmap.

purejsimage/pathology exports openAperioSvs(), aperioSvsProfile, and the generic WholeSlideImage contract. Aperio levels and label, macro, or thumbnail images decode by requested region. TIFF compression tags 33003 and 33005 use the reusable createJpeg2000CodestreamDecoder(); JPEG 2000 reconstruction remains bounded to the current TIFF tile or strip, though the current codestream decoder retains that segment's complete component state.

Third-party TIFF profile authoring

A separately shipped integration implements TiffProfile<T> using only package exports. Register profiles with createTiffProfileRegistry(). Detection runs every profile in isolation, orders matches by descending integer priority then id, reports detector failures, and rejects equal-priority matches as ambiguous. For an explicitly selected profile, registry.openWith(document, profile) preserves T and returns Promise<T>.

import { createTiffProfileRegistry } from 'purejsimage/tiff'
import type { TiffProfile } from 'purejsimage/tiff'

export const vendorProfile: TiffProfile<VendorDataset> = {
  id: 'vendor-format',
  priority: 50,
  async detect({ document }) {
    const tag = await document.topLevelDirectories[0]?.getTag(270, {
      maxBytes: 1024 * 1024,
    })
    return tag?.kind === 'ascii' && tag.value.startsWith('Vendor')
  },
  async open({ document }) {
    const pointer = await document.topLevelDirectories[0]?.getTag(65000, {
      maxBytes: 24,
    })
    if (pointer?.kind !== 'numbers') throw new Error('Vendor pointer is missing')
    const directory = document.getDirectoryByOffset(pointer.values[0] ?? -1)
    if (!directory) throw new Error('Vendor IFD is missing')
    const length = pointer.values[2] ?? -1
    const metadata = await document.readBytes(
      pointer.values[1] ?? -1, length, { maxBytes: 1024 * 1024 },
    )
    return openVendorDataset(directory, metadata)
  },
}

const registry = createTiffProfileRegistry([vendorProfile])
const dataset = await registry.openWith(document, vendorProfile)

See the dedicated TIFF guide for the complete supported-format list, scientific and whole-slide workflows, output profile, memory model, and current limitations →

Zstandard decompression

The portable purejsimage/compression/zstd subpath exports the reusable first-party decoder used by TIFF Compression=50000. It has no format-specific parameters and does not load native code, WebAssembly, or a runtime dependency.

import { decodeZstd } from 'purejsimage/compression/zstd'

const output = decodeZstd(compressed, {
  expectedOutputBytes: 8192,
  maxOutputBytes: 8192,
  maxWindowBytes: 64 * 1024 * 1024,
})

maxOutputBytes and maxWindowBytes default to 64 MiB. Supplying expectedOutputBytes preallocates the exact bounded output and rejects a different decoded size. Dictionary-dependent frames fail with UNSUPPORTED_OPERATION.

Optional WASM acceleration

JPEG, PNG, and WebP provide first-party WebAssembly accelerators as explicit package entries. The root, browser, and codec imports never load them automatically. Register a provider through ImageLibraryConfiguration; ineligible or unavailable work continues through the corresponding TypeScript codec.

import { createImageLibrary } from 'purejsimage'
import { wasmJpegAccelerator } from 'purejsimage/accelerators/wasm/jpeg'
import { wasmPngAccelerator } from 'purejsimage/accelerators/wasm/png'
import { wasmWebpAccelerator } from 'purejsimage/accelerators/wasm/webp'
import { allCodecs } from 'purejsimage/codecs/all'

const images = createImageLibrary({
  codecs: allCodecs,
  accelerators: [wasmJpegAccelerator, wasmPngAccelerator, wasmWebpAccelerator],
})

Browser applications use createImageLibrary from purejsimage/browser. The accelerator import paths stay the same and resolve to browser-safe loaders.

Configuration

The ready-made providers use defaults chosen to avoid paying module and copy overhead on small images. Use the factory exports when an application needs different thresholds or input limits.

interface WasmJpegAcceleratorOptions {
  minimumPixels?: number
  minimumEncodePixels?: number
  maximumInputBytes?: number
  maximumEncoderRowBytes?: number
}

interface WasmPngAcceleratorOptions {
  minimumPixels?: number
  minimumEncodePixels?: number
  maximumRowBytes?: number
}

interface WasmWebpAcceleratorOptions {
  minimumPixels?: number
  minimumEncodePixels?: number
  maximumPixels?: number
}

function createWasmJpegAccelerator(options?: WasmJpegAcceleratorOptions): ImageCodecAccelerator
function createWasmPngAccelerator(options?: WasmPngAcceleratorOptions): ImageCodecAccelerator
function createWasmWebpAccelerator(options?: WasmWebpAcceleratorOptions): ImageCodecAccelerator

JPEG and PNG pixel thresholds default to 65,536. WebP defaults to 16,384 pixels and accepts at most 64 million pixels. JPEG accepts at most 32 MiB of compressed input and a 16 MiB encoder row by default; PNG accepts at most a 16 MiB row. Every supplied value must be a positive integer.

Eligible workflows

Image

Every transform returns a new immutable Image sharing the same input context. No pixel work occurs until an output method is called.

Operation options

CropOptions

interface CropOptions {
  x: number
  y: number
  width: number
  height: number
}

ResizeOptions

type ResizeFit = 'contain' | 'cover' | 'fill' | 'inside' | 'outside'
type ResizeKernel = 'nearest' | 'bilinear' | 'lanczos3'
type Background = 'transparent' | `#${string}`

type ResizeOptions = {
  width?: number
  height?: number
  fit?: ResizeFit
  position?: 'center'
  background?: Background
  withoutEnlargement?: boolean
  kernel?: ResizeKernel
} // width or height is required

WindowOptions and LutOptions

interface WindowOptions {
  center: number
  width: number
}

interface LutOptions {
  table: Uint8Array // 256 × output channel count, interleaved
  format: 'gray8' | 'rgb8' | 'rgba8'
}

Windowing precedes geometric transforms and converts native numeric grayscale blocks directly to gray8. A grayscale LUT treats each table entry as an output color. An RGBA LUT maps each input channel through the corresponding interleaved channel table.

RotateOptions

interface RotateOptions {
  background?: Background // transparent by default
}

Positive degrees rotate clockwise. Arbitrary angles expand to the smallest integer canvas that contains the result and use the requested six- or eight-digit hex background, or transparency by default.

Encoder options

interface JpegEncodeOptions {
  quality?: number                // 1–100
  progressive?: boolean          // refinement-based output; false by default
  background?: Background
  chromaSubsampling?: '420' | '422' | '444'
  restartInterval?: number       // 0–65535; 0 disables restart markers
}

interface PngEncodeOptions { compressionLevel?: number } // 0–9
interface WebpEncodeOptions { lossless?: boolean; quality?: number }
interface BmpEncodeOptions { alpha?: boolean }
interface HdrEncodeOptions { exposure?: number; gamma?: number }
interface QoiEncodeOptions {
  channels?: 3 | 4
  colorspace?: 'srgb' | 'linear'
}
interface NetpbmEncodeOptions {
  format?: 'pbm' | 'pgm' | 'ppm' | 'pam' | 'pfm'
  ascii?: boolean
  bitDepth?: 8 | 16
  endian?: 'little' | 'big'
  scale?: number
}
interface TgaEncodeOptions { alpha?: boolean; rle?: boolean }
interface TiffEncodeOptions {
  compression?: 'deflate'
  predictor?: 'horizontal'
  layout?: 'strips'
  compressionLevel?: number       // 0–9; browser supports 6
}

EXIF and ICC preservation

Encoders strip EXIF and ICC metadata unless the pipeline calls keepExif() or keepIcc(). The two choices are independent and apply when the pipeline executes.

With keepIcc(), tagged samples remain in their source color space and the original profile is embedded in the output, avoiding a double conversion. The profile must match the output pixel model. With keepExif(), autoOrient(), rotate(), flip(), and flop() normalize a retained EXIF orientation to 1 because the pixels have already moved.

ImageMetadata

interface ImageMetadata {
  width: number
  height: number
  format: string
  mimeType: string
  hasAlpha: boolean
  orientation?: number
  colorSpace?: string
  colorProfile?:
    | { kind: 'icc'; description?: string }
    | {
        kind: 'nclx'
        primaries: number
        transferCharacteristics: number
        matrixCoefficients: number
        fullRange: boolean
      }
  bitDepth?: number
  chromaSubsampling?: '400' | '411' | '420' | '422' | '440' | '444'
  codecProfile?: number
  frames?: number
}

Optional fields depend on what the container and registered codec can determine safely. HEIF and AVIF expose validated ICC descriptions when present or the numeric nclx primaries, transfer characteristics, matrix coefficients, and range. Animated formats may report frame counts even when the current pixel decoder handles only a still subset.

Scientific raster API

Import display mapping, volume operations, statistics, spectral helpers, and the reader registry from purejsimage/scientific. Import concrete formats from their purejsimage/scientific/readers/* entries. Explicit registries return labeled-axis ScientificDataset values and native RasterBlock samples instead of registering photographic ImageCodec entries.

const spatial = dataset.descriptor.spatialReference
if (spatial?.pixelToModel) {
  const [a, b, c, d, e, f] = spatial.pixelToModel
  console.log(a * x + b * y + c, d * x + e * y + f, spatial.crs)
}

const document = await openTiffDocument(source)
const report = await inspectCog(document)
console.log(report.likelyCog, report.directories, report.issues)

Scientific Raster Explorer · ENVI guide · GSF guide · FITS guide · MRC guide · CBF guide · Volume operations

Inputs & sources

type BrowserImageInput = ArrayBuffer | Blob | ImageSource | Uint8Array
type NodeImageInput = BrowserImageInput | string

interface ImageSource {
  readonly size: number
  read(offset: number, length: number, options?: { signal?: AbortSignal }): Promise<Uint8Array>
}

For an in-range read, custom read() implementations must return exactly min(length, size - offset) bytes as a Uint8Array, or reject when the backing read fails. Returned bytes may be reused or invalidated when the next read begins. Short, oversized, detached, and rejected reads surface as ImageError results. Public open, metadata, decode, raster, whole-slide, source-read, and terminal output options accept an optional AbortSignal; cancellation aborts the active sink and is rethrown as AbortError.

Safety limits

Pass a partial limits object to open(). Every provided value must be a positive safe integer.

ImageError

type ImageErrorCode =
  | 'INVALID_INPUT'
  | 'LIMIT_EXCEEDED'
  | 'TRUNCATED_INPUT'
  | 'UNSUPPORTED_FORMAT'
  | 'UNSUPPORTED_OPERATION'

Advanced contracts

The Node root and browser entry export the primitives used to author custom codecs, accelerators, and sinks: ImageCodec, ImageCodecAccelerator, ImageLibraryConfiguration, ImageDecoder, ImageEncoder, CodecRegistry, ImageSink, Uint8ArraySink, PixelBlock, PixelFormat, and BufferPool. Node additionally exports BufferSink, FileSink, and FileSource.

These interfaces support custom codecs and sinks. A decoder yields ordered pixel blocks; an encoder consumes them and writes encoded chunks to a sink. Implementations must preserve the release callback and source-buffer lifetime contracts.

View public exports on GitHub →