How our compression and exact-size engine works

1. The exact-size search algorithm

Unlike naive compressors that guess a quality level from a slider or pad files with dummy bytes, our exact-size engine executes a bounded, measured search to find the highest possible visual quality that strictly satisfies your target limit.

The optimization pipeline follows four deterministic phases:

1. Initial size check: If the uploaded image is already at or below the requested byte target, the engine avoids unnecessary re-encoding and preserves the original bytes.
2. Native-dimension binary search: The engine keeps 100% of the original pixel dimensions and executes a binary search over codec quality parameters (bounded between a configurable minimum, typically quality 35, and maximum quality 90). Each candidate is encoded in memory and its byte size measured.
3. Controlled resolution step-down: If the candidate image exceeds the target size even at the lowest acceptable quality threshold, the engine steps down resolution progressively (e.g. 90%, 80%, 70%, 50% scale) and re-evaluates the quality curve at each step. This preserves visual clarity better than crushing a full-resolution grid into extreme quantization noise.
4. Strict verification pass: Every final output is decoded again by the processing pipeline to verify that byte count is strictly less than or equal to the target, dimensions match expectations, and the resulting file is structurally intact.

2. Impossible target handling

Some combinations of image content and file size limits are mathematically or visually impossible (for example, attempting to fit a complex 4K photograph with transparency into a 5 KB PNG).

Rather than silently degrading the image into an unrecognizable blur or returning a 500 server error, our engine detects when bounds cannot be met and returns a clean, actionable422 TARGET_IMPOSSIBLE response with specific advice (such as converting to WebP/JPEG, cropping whitespace, or raising the target limit).

3. Codec configurations and tuning

Our native processor builds on libvips and Sharp, utilizing optimized compilation flags and conservative resource budgets:

• JPEG: Progressive output, optimized Huffman coding, fixed 4:2:0 chroma subsampling, and a default quality of 82 through Sharp and libvips.
• PNG: Lossless optimization uses zlib level 9 compression with adaptive row filtering. Lower quality requests enable a palette with codec-controlled quantization, while lossless mode keeps the full decoded color values.
• WebP: Encoded using libwebp with effort 5, combining high compression efficiency with predictable processing latency. Alpha channels and animation metadata are preserved for supported static inputs.
• AVIF: Uses AV1 image encoding at effort 3 and 4:4:4 chroma. On the deterministic photographic release fixture, effort 3 produced a smaller result in about 2.1 seconds, while effort 4 took about 9.8 seconds and produced more bytes. Those numbers describe this fixture and revision, not every photograph.
• HEIC / HEIF: iPhone and modern mobile camera HEIC inputs are safely decoded via an isolated libheif pipeline, normalizing orientation and color profiles before encoding into your selected web format.

4. Visual quality and perceptual measurement

Mathematical metrics such as Peak Signal-to-Noise Ratio (PSNR) and Structural Similarity (SSIM) provide valuable guidance during automated testing, but they can fail to capture human perceptual priorities (such as facial skin tones, high-contrast text legibility, and ringing artifacts around sharp edges).

We benchmark our engine against an open-source test suite spanning multiple asset classes:

• Continuous-tone photographs: Natural landscapes, portraits, high dynamic range scenes.
• User interface & screenshots: Crisp text, single-pixel borders, solid background blocks.
• Alpha transparency: Logos, iconography, cut-out graphics with soft drop shadows.
• Form scans & signatures: Monochrome ink on paper, high contrast documents.

5. Reproducible testing and benchmarks

All benchmark suites are checked into our repository and executed inside the production Docker environment. Run the benchmark scripts directly to verify compression metrics against your own hardware:

npm run benchmark:compression
npm run benchmark:exact

Every release gate is verified against real file fixtures before deployment to ensure no regressions in file size, processing speed, or output fidelity.