Shared image optimization core built on sharp + ssim.js. Consumed by the pixel-wand app and (eventually) the Atlas DAM app.

import {
  optimizeImage,
  encodeImage,
  findOptimalQuality,
  findOptimalSizeKB,
  calculateSSIM,
  getFormatRecommendation,
  FORMAT_QUALITY_RANGES,
  MIN_QUALITY_FLOOR,
  SSIM_TARGETS,
  type ImageFormat,
  type OptimizationLevel,
  type OptimizationOptions,
  type OptimizationResult,
} from "@thomashartdev/image-processing";

Top-level entry point. Picks a quality via SSIM-guided binary search (or hits a target file size if level: "custom" + customTargetSizeKB is passed) and returns the encoded buffer plus metadata.

optimizeImage can also resize the source before running the quality search:

• maxWidth?: number — clamp output width. Never upsizes beyond the source.
• maxHeight?: number — clamp output height. Never upsizes beyond the source.
• preserveAspect?: boolean — defaults to true. When true, the output fits inside the maxWidth x maxHeight box with aspect ratio preserved (sharp fit: "inside"). When false, each dimension is clamped independently (sharp fit: "fill"), which can stretch the image.

All three are optional. Omitting them preserves pre-0.2.0 behavior exactly. Resize happens BEFORE the SSIM search so quality is measured against the already-downscaled source, not the original.

Low-level encoder wrapper around sharp. Supports webp, avif, jpeg, png, gif, tiff, heif.

Building blocks used by optimizeImage. Exported for callers that want to run the search without the outer wrapper.

Compare two buffers and get the mean SSIM score. Used for quality gates in tests + smoke scripts.

See FORMAT_QUALITY_RANGES for the actual numbers. Each format has its own min/max/default; sane floors in MIN_QUALITY_FLOOR stop the optimizer from collapsing to useless quality on modern codecs (webp/avif can hit 0.99 SSIM even at quality=1).

• types.ts — type definitions + the lookup tables (FORMAT_QUALITY_RANGES, SSIM_TARGETS, MIN_QUALITY_FLOOR).
• encode.ts — encodeImage (sharp dispatch per format).
• ssim.ts — calculateSSIM (raw-pixel diff via ssim.js).
• optimizer.ts — optimizeImage, findOptimalQuality, findOptimalSizeKB, getFormatRecommendation.
• index.ts — barrel export (this is what consumers import from).