PureJsImage

Zero-runtime-dependency image processing in strict TypeScript

Images, scientific data and geographic rasters · optional WASM acceleration

Documentation · Image demo · Scientific explorer · 4D-STEM explorer · Whole-slide demo · OME-Zarr demo · Raster X-Ray · HDR Surgery · PureJsImage Lab

Sometimes the wrong tool for the job is the right one 😉

Why I started building PureJsImage

Whole-slide viewing reads the tiles needed for a viewport where the source supports selective access. The screenshot records one session, not a promise that every operation reads the same fraction.

Measured HTTP Range session from the live browser viewer: only the visible pyramid tiles were read.

PureJsImage opens, inspects, transforms and writes images in Node.js and modern browsers. Its first-party TypeScript codecs have no runtime dependency tree, native addon or system executable. It is useful when the same image workflow needs to run in a browser and on a server, or when source-sized RGBA buffers make a JavaScript pipeline too expensive in AWS Lambda.

• Lower memory use: process rows, strips, tiles or regions when the format allows it. Some operations need a full image or saved coefficients; those limits are documented.
• Clear errors: unsupported files and options fail with an explanation. Benchmarks check that the output is correct before reporting speed.
• Optional acceleration: add JPEG, PNG or WebP WASM accelerators when they help your application. You import and register them yourself; the default TypeScript path never loads them.

A TIFF can be an ordinary image, a scientific dataset or a geographic raster depending on its data and the API you use. These areas overlap; their format counts are not additive. JPEG XL's native-channel API does not register it as a scientific reader, and recognizing a container does not imply support for every schema it can hold.

Install · JPEG XL tools · Format tables · Package size · Benchmarks · Development

All formats below have a TypeScript implementation. WASM is optional and covers only the listed work; other supported operations use TypeScript. Click a format for its full support list.

“Limited” means only the documented subset is supported. Experimental codecs need a separate import and are excluded from allCodecs.

WASM does not cover every file the TypeScript codec can read. JPEG acceleration handles common baseline images; PNG handles common non-interlaced 8-bit images; WebP accelerates selected color and transform steps. Setup, supported cases and fallback behavior.

See the exact codec support matrix →

These examples time the whole decode, resize and encode operation. Median time in milliseconds; lower is faster. WASM does not improve every operation.

Recorded 2026-08-24 with PureJsImage 0.16.0 (workspace), Node v24.16.0, Linux 6.17.0-41-generic/x64, Intel(R) Core(TM) i7-10700 CPU @ 2.90GHz. These are Node results; browser and device speeds differ. The WASM configuration can also use TypeScript for steps without an accelerator.

Full report, settings and results for other libraries. Other formats have different costs; see the benchmark charts for more operations.

npm install purejsimage

PureJsImage requires Node.js 22 or newer. Browser applications import the core API from purejsimage/browser. Public APIs are pre-1.0 and may still receive breaking refinements.

This Node.js example reads a JPEG, applies its orientation, resizes it and writes a JPEG. Register only the codecs an application needs:

import { createImageLibrary } from "purejsimage";
import { jpegCodec } from "purejsimage/codecs/jpeg";
import { pngCodec } from "purejsimage/codecs/png";

const images = createImageLibrary({ codecs: [jpegCodec, pngCodec] });
const image = await images.open("input.jpg");

await image
  .autoOrient()
  .resize({ width: 1200, withoutEnlargement: true })
  .jpeg({ quality: 80, background: "#ffffff" })
  .toFile("output.jpg");

Import the core from purejsimage/browser. Use File, Blob, ArrayBuffer, Uint8Array or an explicit ImageSource as input. A browser cannot open a local path string or call toFile(); return a Blob or bytes instead. This example uses the prebuilt JPEG, PNG, WebP and AVIF group:

import { createImageLibrary } from "purejsimage/browser";
import { allWebCodecs } from "purejsimage/codecs/web";

const webImages = createImageLibrary(allWebCodecs);

export async function resizeUpload(file: File): Promise<Blob> {
  const image = await webImages.open(file);
  return image.autoOrient().resize({ width: 1200, withoutEnlargement: true }).png().toBlob();
}

Run expensive codec operations in a worker to keep the page responsive. The image demo uses the same public pipeline.

TIFF remains an explicit purejsimage/codecs/tiff import because including it would substantially increase the web-focused bundle. Use purejsimage/codecs/all when you need every stable codec. See the API reference for inputs, outputs and limits, and the native precision guide for supported high-depth transforms, color handling and explicit sample conversion.

Node orientation and rotation use lazy chunked memory by default. They do not open temporary files. This default is portable and was 20–28% faster than file storage across the measured orientation and arbitrary-rotation cases.

Applications can opt into temporary files when reducing Node process RSS matters more than runtime or filesystem portability:

const images = createImageLibrary([jpegCodec, pngCodec], { temporaryFiles: true });

The opt-in path stores about one padded decoded frame under os.tmpdir(). In the measured 4000x3000 RGBA orientation case, file storage reduced peak process RSS from 147.69 MiB to 90.90 MiB and increased median runtime from 654.72 ms to 820.48 ms. A tmpfs still consumes host memory even though its pages are outside process RSS. PureJsImage probes file creation, writing, reading, and truncation before consuming image rows. Failed setup or later file writes, including ENOSPC, move the spool to chunked memory and preserve output. An error that prevents recovery of bytes already written to the file is reported as a structured ImageError.

Use the separate purejsimage/hdr entry for Ultra HDR and ISO 21496-1 gain-map JPEG or AVIF workflows. 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 })) {
    consumeLinearHdrBlock(block);
  }

  const output = await image
    .crop({ x: 100, y: 50, width: 1200, height: 800 })
    .resize({ width: 600, height: 400, kernel: "lanczos3" })
    .jpeg({ metadataMode: "dual", baseQuality: 90, gainMapQuality: 92 });
} finally {
  image.close();
}

The renderer returns independently owned linear rgbf32 or rgbaf32 row blocks and preserves values above SDR white. Transformed rendering keeps the decoded and transformed 8-bit component rasters inside one shared memory limit chosen by the caller. It does not allocate a complete adapted Float32 image. JPEG gain-map input is limited to an SDR primary. Re-encoded JPEG primaries carry PureJsImage's deterministic sRGB ICC profile. The first gain-map AVIF writer is limited to an opaque sRGB SDR base and one-channel gain map. See the gain-map HDR guide and the local HDR Surgery browser workbench.

The six new tool pages below are included in this repository’s docs build. Their public URLs will become available when that build is deployed.

Try the JPEG XL encoder and decoder hub, converter or exact JPEG round-trip tool. Static lossy encoding is Stable for the documented integer subset; lossless remains the default. Lossy animation remains Experimental.

Pixel-lossless encoding preserves supported sample values. Exact JPEG recompression preserves the eligible original JPEG bytes, including reconstruction data. Native sample preservation is separate from a resized or display-mapped export. Explore those differences in the native inspector and the progressive/region explorer.

The JavaScript comparison reports measured quality, size, speed and API boundaries for PureJsImage, jSquash, jxl-oxide-wasm and wasm-vips. It retains failures and incomplete comparisons, along with each library’s strengths. The tools use the repository build, which can be ahead of npm; the comparison names its tested revision. See the API and precision guide and comparison methods and results.

Raster X-Ray connects an output block or tile to its recorded reads and file ranges. Use it to see which parts of a large source an operation reads.

Whole-slide demo · OME-Zarr demo · How Raster X-Ray tracks reads · Tile memory model

Scientific readers preserve labeled axes, calibration, native sample types, and the ability to read only the parts you need. Numeric data becomes display pixels only when an application explicitly chooses a range, palette, slice, or projection.

import { FileSource } 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: "input",
    name: "input.ome.tif",
    source: await FileSource.open("input.ome.tif"),
  },
});
try {
  const first = document.datasets[0];
  if (!first) throw new Error("No scientific dataset found");
  const dataset = await document.openDataset(first.id);
  console.log(dataset.descriptor.axes); // Choose axes before reading a plane or region.
} finally {
  await document.close?.();
}

In a browser, keep the same scientific library and reader imports. Replace the Node FileSource with a BlobSource from purejsimage/browser, or use the file/companion helpers in purejsimage/scientific/browser. Files with sidecars need those companion resources too. See the browser resource guide.

Direct-range readers can request only the source spans needed for metadata, a native-precision region, a spectrum, a volume plane, or a whole-slide tile. This includes workflows across DM3 and DM4, TIA SER and EMI, NCEM and Velox EMD, NIfTI, NRRD, MRC, OME-TIFF, Aperio SVS, AFM and surface metrology, and 4D-STEM data.

Scientific format reference → · Scientific API reference → · Scientific application guide → · OME-Zarr reader and validation policy → · OME-Zarr compatibility results → · Reading numeric tiles → · Bounded raster analysis →

Use purejsimage/geo with explicit readers from purejsimage/geo/readers when coordinates and spatial reference are part of the operation. Displaying a TIFF through the ordinary pipeline does not by itself apply its georeferencing or reproject it.

Ordinary GeoTIFFs opened through tiffReader expose a typed dataset.descriptor.spatialReference with CRS identity/citation, pixel-to-model affine, inverse when invertible, model bounds, pixel interpretation, nodata, and GeoTIFF source metadata. readPlane() regions remain raster pixel coordinates.

For Cloud Optimized GeoTIFF workflows, inspectCog() reports container, IFD/SubIFD, tile, overview, compression, and sample layout plus likely structural issues. The checked COG compatibility matrix distinguishes display-only compression from native scientific-raster support and includes the simulated-range viewport benchmark.

GeoTIFF and GeoZarr are also available as lazy GeoRasterDataset readers under purejsimage/geo/readers. The GeoZarr reader supports v2 and v3 metadata, regular chunks, supported v3 shards, multiscales, HTTP stores, local directories, and ZIP stores without adding another Zarr decoder. Band, time, vertical, ensemble, and custom dimensions remain selectable axes. World-file TIFF, JPEG, and PNG images, georeferenced ENVI, Esri ASCII Grid, and SRTM HGT use the same geo API, with region-read support that depends on the format. Classic NetCDF CDF-1 and CDF-2 files with regular rectilinear CF coordinates are available through purejsimage/geo/readers/netcdf. Time and vertical dimensions remain selectable. CDF-5, HDF5-backed NetCDF4, irregular coordinate lookup, and curvilinear grids are reported explicitly.

“Fixture-limited” is implemented behavior with a narrow current corpus. “Metadata only” does not claim the related pixel operation. See the full geographic support table and the machine-readable manifest.

Geo raster architecture → · GeoZarr reader → · Contained geo formats → · Classic NetCDF and CF grids →

Import the 33 scientific readers from purejsimage/scientific/readers/* or choose a group below. Counts come from the reader manifest and package exports.

Find imports and supported variants in the scientific format reference, the API reference, and the machine-readable capability manifest.

The browser explorer includes sample files for Gwyddion Simple Field (purejsimage/scientific/readers/gsf), ENVI (purejsimage/scientific/readers/envi), FITS (purejsimage/scientific/readers/fits), MRC/CCP4 (purejsimage/scientific/readers/mrc), CBF/imgCIF (purejsimage/scientific/readers/cbf). For other files, its generic tab uses the filename and media type to select likely readers, then checks a limited number of bytes to confirm the format. You can also select a reader yourself.

Experimental HEIF/HEIC is available only from purejsimage/codecs/experimental/heic. It remains excluded from allCodecs because HEIC commonly carries HEVC/H.265 content that may be subject to third-party patent rights. The project’s MIT license grants no third-party patent rights; users and distributors must evaluate their own licensing obligations.

Web codec benchmarks (2026-08-24): 122 passing cases, 25 unsupported cases, and no invalid outputs or errors across JPEG, PNG, WebP, TIFF, and AVIF workflows. On the 24-megapixel photo pipeline, the TypeScript path used 84.7% less absolute peak RSS than Jimp (181.8 MiB versus 1189.1 MiB).

Scientific readers (2026-08-17): 43 correctness and startup checks passed across 31 readers in that snapshot. Separate tests of medium and large datasets checked 13 representative workloads; 6 had a coefficient of variation below 10%; the rest are marked noisy in the report. Results include time to first data, operation time, peak memory, requests and bytes read, extra data fetched, startup time and output checks.

Ordinary and scientific reports use separately fingerprinted harnesses. No cross-section speed or memory ratio is claimed.

Median wall time in milliseconds; lower is better. Native Sharp/libvips results are not WASM measurements.

Absolute process peak RSS in MiB; lower is better. This includes runtime overhead, not just codec-managed buffers.

Web codec benchmarks · Scientific methodology and report · Benchmark harness · Generated result index

Historical AWS Lambda measurements remain useful for memory-tier and CPU-allocation context, but are kept separate from current local benchmark headlines. See the performance page for dates, architecture, and exact artifacts.

Generated from the repository manifests and recorded package metrics (package version 0.17.0). A repository checkout can include APIs newer than the published package.

14 stable ordinary codecs and 1 experimental codec are listed in the format tables. Read/write subsets remain separate.

33 scientific readers are grouped in the reader table. This count includes ordinary image adapters; it is not an additional count of unique file formats.

The extracted npm package is 8.1 MiB with 1 production package, including PureJsImage itself. This is unpacked size, not the compressed npm tarball.

Generated for purejsimage 0.17.0. Use these imports to select an entry point; the table above also includes the geographic API and readers. Per-codec, per-reader, competitor, installed-package and WASM measurements are linked below.

The 8 optional JPEG, PNG, and WebP accelerator assets total 175.7 KiB raw WASM and are loaded only through explicit accelerator imports. See the unpacked package total above; these assets are separate from the JavaScript transfer sizes.

Complete size and footprint tables → · Machine-readable package metrics

• How Raster X-Ray tracks reads
• Benchmark methodology and current charts
• Date-stamped benchmark results and indexes
• Machine-readable package metrics
• Capability manifest
• Pinned benchmark corpus
• Detailed benchmark harness guide

The checked 2026-08-13 snapshot compared documented TIFF capabilities separately from independent RGBA output. PureJsImage decoded 104/106 comparable display cases; 57 were exact and 47 had pixel differences. “Oracle unavailable” means the independent Sharp/ImageMagick path could not produce ground truth, not that an engine failed. Current performance headlines come from the newer generated benchmark index above.

Full grouped capability matrix, methods, sources, and per-library results

If you can install native libvips and mainly need high throughput, consider Sharp. PureJsImage is useful when you need the same code in Node and a browser, original scientific samples, or image processing without installing a native library.

Use the metadata in CITATION.cff to cite PureJsImage. The file records the current software release, author, source repository, npm package, license, and project keywords in Citation File Format 1.2.0. The DOI for release 0.16.0 is 10.5281/zenodo.22071815. Use 10.5281/zenodo.22071814 to cite the project across all versions.

npm install
npm run check

Read CONTRIBUTING.md, the architecture, and the roadmap before larger changes.

MIT. The HEIF/HEIC patent notice above is separate from the project license.

Thanks to Imazen for the real-world image corpus used in compatibility and (especially) TIFF validation.

Thanks to PgRust for inspiring me to do this work.