Most CLAHE implementations ship with hardcoded clipLimit = 2.0 and tileSize = 8. This works acceptably on some images and badly on many. PACE takes a different approach: it reads the image first, then computes the right parameters for that specific image. Here's exactly how it does it.

GitHub: github.com/muhammedshahid/pace
Paper preprint: dx.doi.org/10.2139/ssrn.6661421
Archived source: zenodo.org/doi/10.5281/zenodo.19203394
Demo: https://muhammedshahid.github.io/pace-beta/src/

The Problem With Fixed CLAHE Parameters

CLAHE (Contrast Limited Adaptive Histogram Equalization) is one of the most effective local contrast enhancement algorithms ever designed. It's used in medical imaging, satellite photography, computational photography, and a hundred other fields.

It also has two parameters that most people never think carefully about, and that profoundly affect the output:

clipLimit — the threshold at which histogram bins are clipped before equalization. A low clip limit produces conservative enhancement. A high clip limit produces aggressive enhancement that amplifies noise.

tileSize — the size of the local regions over which independent histograms are built. Small tiles capture fine local detail but are sensitive to noise. Large tiles behave more like global histogram equalization.

The problem is that the right values for these parameters are image-dependent. A noisy underexposed photo needs a low clip limit (to avoid amplifying grain) and a large tile size (for stability). A crisp high-detail architectural photo can tolerate a high clip limit and benefits from a small tile size to capture local contrast at the edge level.

Using a single fixed pair of values is a compromise that serves no image particularly well.

The question PACE is designed to answer is: can we compute the right parameters automatically, directly from the image's own statistics?

The answer is yes. Here's how.

The Two Parameters, Perceptually Explained

Before looking at the math, it's worth being precise about what each parameter actually controls, because the names are somewhat misleading.

clipLimit — What It Really Controls

The clip limit is usually described as "the maximum value of a histogram bin before clipping." But what it's really controlling is the maximum local contrast amplification ratio.

A higher clip limit allows more redistribution of histogram probability mass, which produces stronger local contrast. But it also amplifies whatever is in the local region — including noise. For a noisy image, a high clip limit produces a result that looks like enhanced noise. For a smooth image, it produces the strong local contrast expansion you actually wanted.

The clip limit should therefore scale with the image's structure-to-noise ratio: high when the image has clear, coherent structure; low when it doesn't.

tileSize — What It Really Controls

The tile size controls the spatial scale of the adaptation. A tile of 8×8 pixels means CLAHE is building a separate histogram for every tiny 8×8 block — it's adapting to very local intensity statistics. A tile of 64×64 is adapting to broader regional patterns.

Small tiles are appropriate when the image has fine, high-frequency structure that needs local contrast adaptation. Large tiles are appropriate for smooth or noisy images where you want a more global, stable enhancement.

The tile size should therefore scale inversely with the image's structural granularity: small tiles for high-detail coherent images, large tiles for smooth or noisy ones.

Both parameters, in other words, depend on the same underlying question: how much coherent structure does this image have relative to its noise floor?

That's the key insight PACE is built on.

Stage 1: Measuring the Image — Feature Extraction

PACE doesn't start with enhancement. It starts with measurement. Before any CLAHE parameters are chosen, the pipeline extracts a statistical fingerprint from the luminance plane.

The two measurements that drive CLAHE parameter selection are edge density and noise ratio.

Measuring Edge Density

Edge density captures how much coherent structure the image contains. PACE computes it in three steps.

First, compute the raw gradient mean using forward differences across every pixel:

// computeStructure() in extractGlobalFeatures2.js
for (let y = 1; y < height; y++) {
    for (let x = 1; x < width; x++) {
        const i = y * width + x;

        const gx = L[i] - L[i - 1];
        const gy = L[i] - L[i - width];

        // Alpha-Max + Beta-Min approximation: avoids Math.sqrt, within 4% of L2 norm
        const ax = Math.abs(gx);
        const ay = Math.abs(gy);
        const max = ax > ay ? ax : ay;
        const min = ax > ay ? ay : ax;

        const grad = max + 0.25 * min; // ≈ √(gx² + gy²)

        sumGrad += grad;
        sumGradSq += grad * grad;
        count++;
    }
}

const meanGradient = sumGrad / count;
const gradientVariance = (sumGradSq / count) - (meanGradient * meanGradient);
const stdGradient = Math.sqrt(gradientVariance);

The Alpha-Max + Beta-Min approximation (max(|gx|,|gy|) + 0.25 × min(|gx|,|gy|)) is a classic trick for approximating Euclidean gradient magnitude without a square root. In a tight inner loop over every pixel of an image, eliminating Math.sqrt is meaningful.

Second, adjust the raw gradient mean by the noise level (computed in the next section):

const noiseAdjusted = meanGradient / (1 + 0.5 * noiseRatio);

This is important. A noisy image has a high meanGradient — noise creates high-frequency gradients everywhere. Dividing by a noise-adjusted factor prevents the algorithm from misreading noise energy as real structural content.

Third, soft-normalize into a [0, 1] value using an adaptive denominator:

// k adapts to the gradient's own spread, not a fixed constant
const k = 0.3 * stdGradient + 0.02;
const edgeDensity = noiseAdjusted / (noiseAdjusted + k);

The denominator k = 0.3σ_gradient + 0.02 is what makes this "adaptive" rather than just a sigmoid. When the gradient distribution has high variance (lots of both strong and weak gradients — typical of complex scenes), k grows, which softens the normalization and produces a more conservative edge density estimate. When the gradient distribution is narrow (either uniformly flat or uniformly textured), k is small and the normalization is sharper.

The result: edgeDensity ∈ [0, 1], where 0 is a completely flat image and 1 is a maximally structured one.

Measuring Noise: The MAD Estimator

The noise estimator is the most statistically careful part of PACE, and the most important for getting CLAHE parameters right.

The naive approach — using image variance as a noise proxy — fails because texture and noise are both high-variance. A detailed brick wall has high variance but zero noise. Treating it as noisy causes the algorithm to over-suppress enhancement on exactly the images that would benefit most.

PACE instead uses a Laplacian MAD estimator — the same principle underlying Donoho's wavelet-domain denoising (1994). The key insight is that the median of the absolute Laplacian response is robust to structured edges and textures in a way the mean is not.

Here's the implementation:

// computeNoise() in extractGlobalFeatures2.js

const NOISE_BINS = 512;
const NOISE_MAX = 0.5;          // natural images rarely exceed 0.5 Laplacian
const NOISE_INV_MAX = NOISE_BINS / NOISE_MAX;
const MAD_SCALE = 1.4826;       // standard MAD→σ factor for Gaussian distributions

const hist = new Uint32Array(NOISE_BINS);
const STRIDE = 2; // subsample: every other pixel in each axis

for (let y = 1; y < height - 1; y += STRIDE) {
    const row = y * width;
    for (let x = 1; x < width - 1; x += STRIDE) {
        const i = row + x;

        // 4-neighbour discrete Laplacian
        const lap = Math.abs(
            L[i - 1] + L[i + 1] +
            L[i - width] + L[i + width] -
            4 * L[i]
        );

        const bin = lap >= NOISE_MAX
            ? NOISE_BINS - 1
            : (lap * NOISE_INV_MAX) | 0;

        hist[bin]++;
    }
}

The discrete Laplacian operator (L[left] + L[right] + L[top] + L[bottom] - 4×L[center]) measures the second derivative of luminance. On smooth regions, this is close to zero. On real edges, it's large. On noise, it's large and incoherent — it points every direction randomly.

The median of this distribution separates noise from edges because edges are sparse (they affect a small fraction of pixels) but noise is dense (it affects every pixel uniformly). The median ignores the sparse large outliers and settles on the bulk of the distribution — which is the noise floor.

// Histogram median — O(NOISE_BINS), no sort required
const half = count * 0.5;
let cumulative = 0;
let median = 0;

for (let b = 0; b < NOISE_BINS; b++) {
    const prev = cumulative;
    cumulative += hist[b];

    if (cumulative >= half) {
        // Sub-bin linear interpolation for accuracy
        const frac = hist[b] > 0 ? (half - prev) / hist[b] : 0;
        median = ((b + frac) / NOISE_BINS) * NOISE_MAX;
        break;
    }
}

// Convert MAD to Gaussian sigma
const sigma = median * MAD_SCALE;

The 1.4826 constant is the exact scale factor that converts median absolute deviation to standard deviation for a Gaussian distribution (1 / Φ^{-1}(0.75)). This gives a physically meaningful noise estimate in the same units as the luminance plane.

Finally, convert sigma to a structure-aware ratio:

// Self-damping: prevents runaway ratios in extremely noisy images
const noiseRatio = sigma / (meanGradient + 0.02 + 0.5 * sigma);

The denominator has three terms. meanGradient normalizes noise relative to actual signal strength — an image with strong gradients can tolerate more absolute noise. The constant 0.02 prevents division explosion on completely flat images. The 0.5 × sigma term is self-damping: when sigma is large, the denominator grows with it, preventing noiseRatio from going to infinity on pathologically noisy inputs.

The result: noiseRatio ∈ [0, ~1], where values near 0 mean the image is clean relative to its structure, and values near 1 mean noise dominates.

Stage 2: Structure Confidence — The Unified Signal

edgeDensity and noiseRatio are now combined into a single structure confidence value that drives both CLAHE parameters:

// computeStructureConfidence() in computeAdaptiveParams.js

function computeStructureConfidence(edgeDensity, noiseRatio) {

    // Edge signal: saturates smoothly as edges become denser
    // exp(-3x) decays to near-zero by x=1, giving good dynamic range
    const edgeSignal = 1 - Math.exp(-3.0 * edgeDensity);

    // Noise suppression: high noise → strong suppression
    // 2.5 coefficient calibrated so noiseRatio=0.4 halves the confidence
    const noiseSuppression = 1 / (1 + 2.5 * noiseRatio);

    // Product: confidence is high only when BOTH conditions hold
    // (strong edges AND low noise)
    const confidence = edgeSignal * noiseSuppression;

    return Math.min(1, Math.max(0, confidence));
}

This is an elegant formulation. The product of edgeSignal and noiseSuppression means both conditions have to be true for confidence to be high:

• High edge density alone isn't enough — a noisy image can have high apparent edge density (noise creates gradients everywhere), but noiseSuppression will pull confidence down.

• Low noise alone isn't enough — a clean but completely flat image has near-zero edge density, so edgeSignal stays near zero.

Structure confidence is high only when the image has genuine coherent structure that isn't explained by noise. That's exactly the condition under which aggressive CLAHE is safe and productive.

Let's trace through two example images to see how this plays out:

Example A: Clean, sharp landscape photo

• meanGradient ≈ 0.045 (clear edges)

• sigma ≈ 0.004 (low noise)

• noiseRatio ≈ 0.004 / (0.045 + 0.02 + 0.002) ≈ 0.060

• edgeDensity ≈ 0.045 / (0.045 + 0.015) ≈ 0.75 (using typical k value)

• edgeSignal = 1 - exp(-3.0 × 0.75) ≈ 0.895

• noiseSuppression = 1 / (1 + 2.5 × 0.060) ≈ 0.870

• structureConfidence ≈ 0.779 — high

Example B: Noisy underexposed indoor photo

• meanGradient ≈ 0.030 (moderate, partially noise-driven)

• sigma ≈ 0.018 (high noise)

• noiseRatio ≈ 0.018 / (0.030 + 0.02 + 0.009) ≈ 0.305

• edgeDensity ≈ 0.026 / (0.026 + 0.018) ≈ 0.59 (noise-adjusted gradient)

• edgeSignal = 1 - exp(-3.0 × 0.59) ≈ 0.834

• noiseSuppression = 1 / (1 + 2.5 × 0.305) ≈ 0.567

• structureConfidence ≈ 0.473 — moderate-low

Same CLAHE algorithm, same codebase, but two very different parameter sets. Here's how.

Stage 3: Computing clipLimit From Structure Confidence

// computeControlParams() in computeAdaptiveParams.js

const clipLimit = 0.02 + 0.08 * structureConfidence;

That's it. One line. But every number in it is deliberate.

0.02 — the minimum floor. Even a completely flat, noisy image should get some CLAHE enhancement. Zero clip limit would mean no equalization at all. The floor ensures there's always a minimal enhancement pass.

0.08 × structureConfidence — the adaptive range. At maximum confidence (≈1.0), clip limit reaches 0.10. At minimum confidence (≈0), it stays at 0.02. The total range [0.02, 0.10] was calibrated against the 256-bin histogram that PACE uses internally — these are fractional values relative to the reference tile area, not raw bin counts.

Tracing through our examples:

The clean landscape gets a clip limit 41% higher than the noisy photo — allowing correspondingly more aggressive local contrast expansion where the image can support it.

Stage 4: Computing tileSize From Structure Confidence and Noise

The tile size calculation has one more ingredient: the noise ratio feeds in directly alongside structure confidence.

// computeControlParams() in computeAdaptiveParams.js

// Granularity: positive when structured, negative when noisy
const granularity = structureConfidence - 0.5 * noiseRatio;

// Linear interpolation: 32px baseline, ±16px range
let tileSize = 32 - 16 * granularity;

// Hard clamp to [8, 64]
tileSize = Math.max(8, Math.min(64, tileSize));

// Round to multiple of 8 (efficient memory alignment + bilateral symmetry)
tileSize = Math.round(tileSize / 8) * 8;

The granularity signal combines both axes:

• High structure confidence and low noise → high granularity → smaller tiles (fine local adaptation where the image can support it)

• Low structure confidence or high noise → low or negative granularity → larger tiles (stable, regional adaptation)

The 0.5 × noiseRatio coefficient in the granularity formula means noise has half the influence of structure confidence. This is intentional: noise should pull toward larger tiles, but not so aggressively that a moderately noisy-but-detailed image ends up with huge tiles that miss its fine structure.

The 32 - 16 × granularity formula means:

• When granularity = 0 (balanced): tileSize = 32 (the natural midpoint)

• When granularity = 1 (maximum structure, no noise): tileSize = 16 (fine adaptation)

• When granularity = -1 (no structure, maximum noise): tileSize = 48 → clamped to 48

After rounding to the nearest multiple of 8:

The clean landscape gets 24px tiles — fine enough to capture local edge contrast. The noisy photo gets 32px tiles — stable enough to average over enough pixels that noise doesn't dominate each tile's histogram.

The CLAHE Implementation: Why 12-Bit Precision Matters

With parameters computed, PACE runs its own CLAHE implementation rather than a stock one. The key upgrade over standard implementations is 12-bit internal precision.

Standard CLAHE: float → 8-bit (255 levels) → LUT → 8-bit output → float. PACE CLAHE: float → 12-bit (4095 levels) → LUT (8-bit bins, 12-bit output) → float.

Here's why this matters. CLAHE works by remapping each pixel through a LUT derived from the local histogram CDF. If the input is quantized to 8 bits before entering the LUT, you have only 256 distinct input values. In regions with gentle gradients — clear sky, smooth skin, shallow depth-of-field backgrounds — this 256-level quantization creates visible stairstepping in what should be smooth tonal transitions.

12-bit quantization gives 4096 input levels. The staircase artifact essentially disappears.

// applyCLAHE() in newCLAHE.js

const bins = 256;     // histogram stays 8-bit — memory efficient
const scale = 4095;   // but float quantization is 12-bit

// Float → 12-bit Uint16
const L = new Uint16Array(size);
for (let i = 0; i < size; i++) {
    const v = Lfloat[i] * scale;
    L[i] = v < 0 ? 0 : v > scale ? scale : v | 0;
}

The trick is that the histogram bins stay 8-bit (256 bins). Building a 12-bit histogram would require 4096 bins per tile — for 32×32 tiles at 16 tiles per axis, that's 16×16×4096×4 bytes ≈ 16MB just for histograms. Instead, PACE bins the 12-bit input values into 8-bit histogram slots by right-shifting 4 bits:

// buildTileLUTs() in newCLAHE.js

for (let y = y0; y < y1; y++) {
    const row = y * w;
    for (let x = x0; x < x1; x++) {
        // shift 12-bit value right by 4 → 8-bit bin index
        hist[gray[row + x] >> 4]++;
    }
}

And the LUT outputs are stored in Uint16 at 12-bit resolution:

// LUT output: 12-bit range [0, 4095]
const luts = Array.from({ length: tilesY }, () =>
    Array.from({ length: tilesX }, () => new Uint16Array(bins))
);

// CDF → LUT scaled to 12-bit output
let acc = 0;
const cdfScale = outputScale / tileArea; // outputScale = 4095
for (let i = 0; i < bins; i++) {
    acc += hist[i];
    luts[ty][tx][i] = Math.min(outputScale, Math.round(acc * cdfScale));
}

The result: 8-bit memory cost for histograms, 12-bit precision for the actual tonal remapping. It's a genuine free lunch.

Bilinear Tile Interpolation

At tile boundaries, naive CLAHE produces visible block artifacts — the local histogram statistics jump discontinuously from one tile to the next, and you see a grid pattern in smooth regions of the enhanced image.

PACE eliminates this with bilinear interpolation across the four nearest tile LUTs for every pixel:

// claheGrayBilinear() in newCLAHE.js

for (let y = 0; y < h; y++) {
    // Map pixel into fractional tile-grid coordinates
    const gy = (y + 0.5) / tileSize - 0.5;
    let ty = Math.floor(gy);
    const fy = gy - ty; // fractional position within tile cell

    ty = Math.max(0, Math.min(ty, tilesY - 1));
    const ty1 = Math.min(ty + 1, tilesY - 1);

    for (let x = 0; x < w; x++) {
        const gx = (x + 0.5) / tileSize - 0.5;
        let tx = Math.floor(gx);
        const fx = gx - tx;
        tx = Math.max(0, Math.min(tx, tilesX - 1));
        const tx1 = Math.min(tx + 1, tilesX - 1);

        // 8-bit bin lookup from 12-bit input
        const bin = gray[y * w + x] >> 4;

        // Four corner LUT values
        const v_tl = luts[ty][tx][bin];
        const v_tr = luts[ty][tx1][bin];
        const v_bl = luts[ty1][tx][bin];
        const v_br = luts[ty1][tx1][bin];

        // Bilinear blend
        out[y * w + x] = Math.round(
            v_tl * (1 - fx) * (1 - fy) +
            v_tr *      fx  * (1 - fy) +
            v_bl * (1 - fx) *      fy  +
            v_br *      fx  *      fy
        );
    }
}

The (y + 0.5) / tileSize - 0.5 mapping centers each pixel within its tile cell rather than aligning to the tile origin. This ensures the interpolation is symmetric and that the center of each tile gets the pure LUT value without any blending contribution from neighboring tiles.

Bias-Free Histogram Redistribution

Standard CLAHE redistributes clipped histogram excess uniformly: divide by 256, add to every bin. This creates a systematic bias — the first bins always get slightly more than the last when excess % bins ≠ 0, because the remainder gets distributed to the leading bins.

PACE eliminates this by rotating the starting position of the remainder distribution:

// Bias-free redistribution in buildTileLUTs()

const redist = Math.floor(excess / bins);
const remainder = excess % bins;

// Every bin gets the base redistribution
for (let i = 0; i < bins; i++) hist[i] += redist;

// Remainder starts at a tile-dependent offset — no systematic bias
const start = (tx * tilesX + ty) % bins;
for (let i = 0; i < remainder; i++) hist[(start + i) % bins]++;

The start offset varies by tile position. Over the full image, the remainder gets distributed without systematic preference to any particular intensity range.

The Complete Parameter Flow

Putting it all together, here's the complete chain from raw pixels to CLAHE parameters:

Raw luminance pixels (Float32Array)
    ↓
computeStructure()
    meanGradient, stdGradient
    ↓
computeNoise()  [MAD estimator on subsampled Laplacian]
    sigma → noiseRatio
    ↓
edgeDensity = noiseAdjustedGradient / (noiseAdjustedGradient + adaptiveK)
    ↓
computeStructureConfidence(edgeDensity, noiseRatio)
    = (1 - exp(-3·edgeDensity)) × (1 / (1 + 2.5·noiseRatio))
    ↓
clipLimit  = 0.02 + 0.08 × structureConfidence
tileSize   = round8(clamp(32 - 16 × (structureConfidence - 0.5·noiseRatio), 8, 64))
    ↓
applyCLAHE(L, width, height, tileSize, clipLimit)

Every step is deterministic and derived from the image's own pixel data. No user input. No presets. No scene classification. The image tells the algorithm what it needs.

What This Looks Like in Practice

To give a sense of the parameter space PACE explores automatically:

The algorithm naturally gravitates toward conservative parameters for difficult images and aggressive parameters for images that can support it — without any explicit scene labels or conditional logic.

Using PACE in Your Project

import { applyPACE } from 'https://raw.githubusercontent.com/muhammedshahid/pace/main/dist/pace.esm.js';

// Fully automatic — parameters computed per-image
const enhanced = await applyPACE(imageData);

// Inspect what parameters were computed (via override + debug)
const enhanced = await applyPACE(imageData, {
    debug: true,  // logs each stage including computed params
    strength: 1.0
});

// Override specific parameters for experimentation
const enhanced = await applyPACE(imageData, {
    override: {
        controlParams: {
            clipLimit: 0.04,   // fixed, bypasses auto-computation
            tileSize: 16       // fixed tile size
        }
    }
});

The library runs entirely in a Web Worker — the image never leaves the browser.

Open Questions

The parameter computation described here is deliberately hand-crafted: the coefficients (0.02, 0.08, 3.0, 2.5, 0.5, 16, 32) were derived from empirical calibration against a range of test images. They work well, but they're not optimal in any formal sense.

The natural next step is replacing the hand-crafted controller with a small learned model — a ~500KB MLP trained on human-rated image pairs, predicting clipLimit and tileSize directly from the 12-dimensional feature vector that PACE already computes. This would preserve the zero-config, browser-native design while replacing engineering judgment with data-driven optimization.

If you've worked on preference learning for image quality metrics or have thoughts on the MAD estimator design, I'd genuinely like to hear them in the comments.

Links

PACE is submitted to Elsevier SoftwareX and is currently under peer review. All source code is available under the MIT license. If you use PACE in research, the Zenodo DOI provides a permanent citable reference.

PACE (Perceptual Adaptive Contrast Enhancement) is an open-source image enhancement library that analyzes and enhances images fully client-side — no server, no upload, no API key. Here's the full engineering story behind it.

GitHub: github.com/muhammedshahid/pace
Paper (preprint): dx.doi.org/10.2139/ssrn.6661421
Archived source (Zenodo): zenodo.org/doi/10.5281/zenodo.19203394
Live Demo:https://muhammedshahid.github.io/pace-beta/src/

Why I Built This

Most browser-side image enhancement libraries are, if you look past the marketing, a CanvasRenderingContext2D call with hardcoded brightness and contrast values. They don't look at the image. They apply a fixed transform and call it done.

That always bothered me. A dark underexposed photo and an overexposed washed-out photo need opposite treatments. A noisy image needs conservative clipping to avoid amplifying grain. A high-detail architectural shot deserves aggressive texture sharpening that would destroy a portrait. One size never fits all.

I wanted a library that actually analyzed the image before touching it — one that adapted its enhancement to what was in the image, automatically, without the user adjusting a single slider.

The additional constraint I set for myself: it had to run entirely in the browser. No server round-trip. The image never leaves the device. This isn't just a privacy story — it's an engineering constraint that forces you to be serious about performance in JavaScript, which turns out to be a very interesting problem.

The result is PACE. It's been submitted to Elsevier SoftwareX (currently under peer review) and is fully open-source under the MIT license.

The Pipeline at a Glance

PACE runs a 7-stage pipeline, all inside a Web Worker to keep the main thread unblocked:

RGB Input
    ↓
Stage 1: OKLab Color Conversion
    ↓
Stage 2: Global Feature Extraction
    ↓
Stage 3: Adaptive Parameter Computation
    ↓
Stage 4: CLAHE (12-bit precision)
    ↓
Stage 5: Perceptual Control Maps
    ↓
Stage 6: Multi-Signal Blending
    ↓
OKLab → RGB Reconstruction

Each stage feeds the next. Stages 2 and 3 are the brain — everything downstream is the execution. Let me walk through the decisions that weren't obvious.

Stage 1: Why OKLab Instead of HSL or YCbCr

The classic approach to luminance-only enhancement is to convert to HSL or HSV, manipulate the L channel, and convert back. It's simple and fast. It's also perceptually wrong.

HSL is not perceptually uniform. A 10% increase in L at hue 240° (blue) looks like a massive change; the same increase at hue 60° (yellow) barely registers. When you enhance luminance in a non-uniform space, you inadvertently shift perceived hue and saturation in ways that look unnatural — the classic "colors look weird" complaint about automated enhancement.

OKLab (Björn Ottosson, 2020) is a modern perceptually uniform color space designed specifically to fix this. The L channel in OKLab corresponds closely to perceived lightness. When you only touch L and leave the a and b chrominance channels alone, the colors genuinely don't shift.

The conversion itself uses lookup tables for the sRGB gamma correction (the expensive Math.pow call):

// Precomputed LUT: sRGB uint8 [0-255] → linear float [0-1]
const SRGB_TO_LINEAR = new Float32Array(256);
for (let i = 0; i < 256; i++) {
    const c = i / 255;
    SRGB_TO_LINEAR[i] = c <= 0.04045
        ? c / 12.92
        : Math.pow((c + 0.055) / 1.055, 2.4);
}

And the inner loop processes two pixels per iteration to give the JS JIT compiler enough to work with:

// Process 2 pixels per loop for better JIT optimization
for (; j < end; j += 2, i += 8) {
    // Pixel 1
    const lr1 = srgbToLinear[src[i]];
    const lg1 = srgbToLinear[src[i + 1]];
    const lb1 = srgbToLinear[src[i + 2]];
    // ... OKLab matrix multiply ...

    // Pixel 2
    const lr2 = srgbToLinear[src[i + 4]];
    // ...
}

Stage 2: Feature Extraction — What the Algorithm Actually Measures

Before any enhancement happens, PACE extracts a 12-dimensional feature vector from the luminance plane:

[mean, variance, skewness, kurtosis, entropy, dynamicRange,
 shadowRatio, highlightRatio, edgeDensity, textureIndex,
 noiseRatio, microContrast]

This is the image's "fingerprint." Let me explain the less obvious ones.

Dynamic Range via Percentiles, Not Min/Max

Raw min/max dynamic range is dominated by outliers — a single blown-out pixel or a crushed shadow pixel skews the whole measurement. Instead, PACE computes the P5–P95 range:

// Walk the histogram CDF to find percentile positions
if (!p5 && cumulative >= 0.05) {
    p5 = i / (HIST_BINS - 1);
}
if (!p95 && cumulative >= 0.95) {
    p95 = i / (HIST_BINS - 1);
}
const dynamicRange = p95 - p5;

A low dynamicRange means the image is flat and needs aggressive contrast expansion. A high value means it already uses the tonal range well and needs a lighter touch.

Noise Estimation: MAD Over Mean

The noise estimator is the part of PACE I'm most invested in technically, and the one I'm most open to critique on.

The naive approach — divide mean absolute Laplacian by image variance — conflates noise with texture. A sharply-detailed brick wall has high variance and high Laplacian response, but it's not noisy. Treating it as noisy causes the algorithm to under-enhance exactly the images that benefit most from it.

Instead, PACE uses a histogram-median Laplacian estimator, which is the same statistical principle underlying Donoho's wavelet-domain denoising (1994):

// 4-neighbour discrete Laplacian
const lap = Math.abs(
    L[i - 1] + L[i + 1] +
    L[i - width] + L[i + width] -
    4 * L[i]
);

// Accumulate into histogram bins
const bin = lap >= NOISE_MAX
    ? NOISE_BINS - 1
    : (lap * NOISE_INV_MAX) | 0;
hist[bin]++;

Then find the median of that histogram:

const half = count * 0.5;
let cumulative = 0;
let median = 0;

for (let b = 0; b < NOISE_BINS; b++) {
    const prev = cumulative;
    cumulative += hist[b];
    if (cumulative >= half) {
        const frac = hist[b] > 0 ? (half - prev) / hist[b] : 0;
        median = ((b + frac) / NOISE_BINS) * NOISE_MAX;
        break;
    }
}

// MAD → σ conversion for Gaussian noise
const sigma = median * 1.4826;

The median is robust to outliers (edges, textures) in a way the mean is not. The 1.4826 constant is the standard MAD→σ scale factor for Gaussian distributions. The result is a noiseRatio that correctly separates "this image has sensor noise" from "this image has a lot of detail."

Subsampling (stride = 2) drops computation to O(n/4) with negligible accuracy loss since the median of a representative sample converges quickly.

Stage 3: Adaptive Parameter Computation — The Control Theory Layer

This is where the feature vector gets translated into actual enhancement parameters. The goal was to make every parameter derivable from the image statistics, with no magic numbers that a user needs to touch.

Alpha (Enhancement Strength)

globalAlpha controls how aggressively the final blending step applies enhancement. It's derived from three signals:

// How much enhancement is needed?
const alphaNeed =
    0.5 * imbalance +          // tonal imbalance (shadow vs highlight ratio)
    0.3 * contrastNeed +       // low entropy × low dynamic range
    0.4 * structureConfidence; // edge signal, noise-suppressed

// What's the safe baseline?
const alphaBase =
    0.08 +                     // unconditional minimum
    0.10 * safety +            // clear structure → safer to enhance
    0.02 * textureConfidence;  // tonally rich images respond predictably

// Final alpha: need-driven, bounded, never collapses to zero
const globalAlpha =
    alphaBase + (alphaNeed / (alphaNeed + 0.5)) * (1 - alphaBase);

The soft normalization x / (x + 0.5) is used throughout the parameter controller. It maps [0, ∞) to [0, 1) smoothly without any hard clamps that create discontinuities.

Beta (Highlight/Shadow Protection)

Rather than a single beta scalar that either protects highlights or shadows, PACE computes independent betaHighlight and betaShadow values with adaptive coupling:

// Scene-aware coupling reduces dual activation
const couplingStrength =
    0.6 * dynamicRange +
    0.4 * Math.abs(highlightRatio - shadowRatio);

const k = couplingStrength / (1 + couplingStrength);

betaHighlight = betaHighlight / (1 + k * total);
betaShadow = betaShadow / (1 + k * total);

This prevents the pathological case where both highlight and shadow protection activate simultaneously and cancel each other out.

Stage 4: CLAHE With 12-Bit Internal Precision

Contrast Limited Adaptive Histogram Equalization (CLAHE) is the workhorse of the enhancement pipeline. The standard implementation is 8-bit throughout. PACE uses 12-bit internal precision — the input is quantized to 4096 levels, histograms are built with 256 bins (8-bit bin index for memory efficiency), and LUT outputs are stored in Uint16 at 12-bit resolution.

const bins = 256;     // histogram bin count (8-bit)
const scale = 4095;   // output precision (12-bit)

// Float → 12-bit
const L = new Uint16Array(size);
for (let i = 0; i < size; i++) {
    const v = Lfloat[i] * scale;
    L[i] = v < 0 ? 0 : v > scale ? scale : v | 0;
}

The payoff is smoother tonal gradations in the equalized output — the 8-bit staircase artifact in smooth gradients is eliminated without the memory cost of a full 12-bit histogram (which would be 4096 bins × tile count × 2 bytes).

Bilinear tile interpolation is non-negotiable for avoiding the blocky artifact that makes naive CLAHE implementations look terrible at tile boundaries:

const v_tl = luts[ty][tx][bin];
const v_tr = luts[ty][tx1][bin];
const v_bl = luts[ty1][tx][bin];
const v_br = luts[ty1][tx1][bin];

out[y * w + x] = Math.round(
    v_tl * (1 - fx) * (1 - fy) +
    v_tr * fx * (1 - fy) +
    v_bl * (1 - fx) * fy +
    v_br * fx * fy
);

Stage 5: Perceptual Control Maps

Four spatial maps modulate how enhancement is applied pixel-by-pixel:

Edge map — gradient magnitude using the Alpha-Max + Beta-Min approximation instead of Euclidean distance. max(|gx|, |gy|) + 0.25 × min(|gx|, |gy|) approximates the L2 norm to within 4% without a Math.sqrt call in the inner loop.

Structure mask — normalized gradient magnitude. High-structure regions (sharp edges, detailed textures) receive more aggressive enhancement.

Skin damping map — a Gaussian bell centered at luminance 0.5 that softly suppresses enhancement in mid-tone regions likely to contain skin. No face detection, just a perceptual heuristic that works surprisingly well in practice.

Local alpha map — per-tile alpha values computed from gradient coherence and noise. Tiles with coherent gradients (real structure) get higher alpha; tiles with incoherent high-frequency response (noise) get suppressed.

The local alpha map is then passed through guided alpha smoothing — a bilateral-filter-inspired 3×3 pass where neighbor weights are determined by luminance similarity:

const idx = Math.min(
    Math.abs(L[neighbor] - centerL) * lutScale | 0,
    lutScale
);
const w = weightLUT[idx]; // precomputed Gaussian LUT

This prevents alpha map discontinuities at edges without blurring across them.

Stage 6: Multi-Signal Blending With Nonlinear Stability

The final enhancement delta combines three signals:

1. CLAHE delta — Lclahe[i] - L[i], the contrast equalization component

2. Retinex detail — log(Lsmall) - log(Lmedium), the illumination-invariant reflectance estimate

3. Laplacian texture — (Lsmall[i] - localMean) × textureMask, the local detail sharpening

let delta =
    deltaClahe +
    0.45 * deltaDetail * detailMask * skinDampMap[i]
    * structureBoost * edgeAdaptive;

That combined delta is then passed through a chain of compressors to prevent the two most common enhancement artifacts — halos and blown highlights:

// Halo suppression: high delta gets progressively compressed
const deltaStable = delta / (1 + 2 * Math.abs(delta) + EPS);

// Tone limiter: delta is bounded relative to current luminance
const deltaLimited = deltaStable /
    (1 + Math.abs(deltaStable) / (tau * (0.5 + Li)));

// Nonlinear stability model: the core PACE contribution
const compressed = deltaLimited / (1 + lambda * Math.abs(deltaLimited));

The final expression Δ / (1 + λ|Δ|) is the key formula. It behaves linearly for small deltas (good), saturates smoothly for large ones (prevents clipping), and the lambda parameter is derived from image statistics so the saturation point adapts to each image's content.

Stage 7: Reconstructing OKLab to RGB

All decisions come together here, transforming processed luminance into the final enhanced image.

Performance in JavaScript: What Actually Works

Running a 7-stage image processing pipeline in JS on a 12MP image is not trivial. Things that made a real difference:

Lookup tables everywhere. Math.pow, Math.log, Math.cbrt, Math.exp are expensive in tight loops. PACE precomputes LUTs for sRGB gamma, linear-to-sRGB, OKLab cube roots, log values, and the power functions used in edge gain. The LUT pattern is always the same:

const LUT = new Float32Array(LUT_SIZE);
for (let i = 0; i < LUT_SIZE; i++) {
    LUT[i] = expensiveFunction(i / (LUT_SIZE - 1));
}

// At runtime:
const result = LUT[(x * (LUT_SIZE - 1)) | 0];

Separable passes for blur. All spatial filtering (smooth3x3, smooth5x5, smooth7x7) uses horizontal + vertical passes rather than 2D convolution, dropping complexity from O(n×k²) to O(n×k).

Zero-copy transfer to Web Worker. The ImageData buffer is transferred (not cloned) to the worker:

worker.postMessage({ imgData, options }, [imgData.data.buffer]);

After transfer, imgData.data.buffer is detached in the main thread. The worker owns the memory. On completion the result is transferred back the same way.

Row-cached indexing. Inner loops precompute const row = y * width outside the x-loop to eliminate a multiply per pixel.

Using PACE

import { applyPACE } from "https://raw.githubusercontent.com/muhammedshahid/pace/main/dist/pace.esm.js";

// Basic usage — fully automatic
const enhanced = await applyPACE(imageData);

// With strength control (1.0 = default, >1.0 = aggressive)
const enhanced = await applyPACE(imageData, { strength: 0.8 });

// With parameter override for research/experimentation
const enhanced = await applyPACE(imageData, {
    override: {
        controlParams: { clipLimit: 0.04, tileSize: 16 },
        perceptualParams: { tau: 0.6, lambda: 0.4 }
    }
});

// With progress callback (useful for progress bars on large images)
const enhanced = await applyPACE(imageData, {}, (progress) => {
    console.log(`\({progress.stage}: \){progress.progressPercent.toFixed(0)}%`);
});

What's Next

The feature vector that stage 2 produces is richer than what the hand-crafted parameter controller in stage 3 can fully exploit. The natural next step is training a small MLP on human-rated image pairs to predict the parameter vector directly from the feature vector — a ~500KB ONNX model deployable via ONNX Runtime Web, staying entirely browser-native. If anyone has done this kind of preference-learning pipeline for image quality I'd genuinely like to compare notes.

Longer term: a WebAssembly port of the inner loops would unlock 12MP+ images without worker timeout pressure, and temporal coherence across video frames is an interesting research direction that hasn't been touched yet.

Links

PACE is submitted to Elsevier SoftwareX and is currently under peer review. All source code is available on GitHub under the MIT license.

If you use PACE in your research, you can cite the Zenodo archive directly — it has a permanent DOI.

PACE runs entirely in the browser with no heavy dependencies, keeping the install footprint minimal.

Why I Built This

Most browser image “enhancers” don’t actually look at the image.

They apply fixed brightness/contrast transforms and call it done.

That breaks immediately in real cases:

• Underexposed → needs expansion

• Overexposed → needs compression

• Noisy → needs restraint

• High-detail scenes → benefit from strong local contrast

A single static transform can’t solve all of these.

So I built something different:

A system that first understands the image, then decides how to enhance it.

And I constrained it deliberately:

It must run entirely in the browser.

No server. No uploads. Just JavaScript.

How PACE Thinks (in 20 seconds)

At a high level, PACE does three things:

1. Understand the image — contrast, noise, structure, tone

2. Decide behavior — how aggressive, where to protect

3. Apply enhancement selectively — not globally

Everything else is implementation detail.

The Pipeline (High Level)

RGB Input
    ↓
OKLab Conversion
    ↓
Feature Extraction
    ↓
Adaptive Control (the brain)
    ↓
Local Contrast (CLAHE)
    ↓
Spatial Maps
    ↓
Perceptual Blending
    ↓
Final Image

Two stages matter most:

• Feature Extraction → what the image is

• Adaptive Control → what to do about it

Everything after executes those decisions.

Why Not HSL / HSV?

The common approach is:

Convert to HSL → tweak L → convert back

It’s simple. It’s also perceptually wrong.

A small luminance change affects colors unevenly across hues. Blues shift heavily, yellows barely move.

PACE uses OKLab instead:

• Perceptually uniform

• L ≈ perceived lightness

• Changing L preserves color relationships

Result:

You can enhance brightness without breaking colors.

What the System Measures (Intuition)

Before modifying anything, PACE extracts a set of signals from the image:

• Contrast → how spread out tones are

• Dynamic range → how much of the tonal space is used

• Tone balance → shadows vs highlights

• Structure → edges and textures

• Noise → unstable high-frequency signal

This acts as the image’s fingerprint.

Important detail

Dynamic range is measured using percentiles (P5–P95), not min/max.

Why?

Because outliers lie.

A single bright pixel shouldn’t define the entire image.

Noise vs Texture (Why This Matters)

A common mistake:

Treating all high-frequency detail as noise

That causes systems to:

• suppress real texture (brick, fabric, hair)

• under-enhance detailed images

PACE uses a robust, median-based approach to separate:

• consistent variation → noise

• structured variation → detail

This is critical for safe enhancement.

(I’ll break down the exact method in Part 2.)

The Brain: Adaptive Control

This is where PACE becomes a system, not just an algorithm.

Instead of fixed parameters, everything is derived from the image.

Example idea:

• Flat image → increase contrast

• Noisy image → reduce aggressiveness

• Structured image → allow stronger enhancement

These signals are combined into a bounded control value.

Important property:

The system never collapses to zero and never explodes.

It stays alive but controlled.

Local Contrast (CLAHE)

PACE uses CLAHE (Contrast Limited Adaptive Histogram Equalization) as a base signal.

PACE auto compute clipLimit and tileSize. For more details checkout CLAHE Auto-Compute Parameters article.

What it does:

• Enhances contrast locally (tile-based)

• Prevents over-amplification using clipping

• Interpolates between regions to avoid seams

On its own, CLAHE can look harsh (see CLAHE output).

PACE doesn’t use it directly — it uses it as one signal among many.

Spatial Intelligence (Why Global Filters Fail)

Global filters apply the same change everywhere.

PACE builds spatial maps that vary across the image:

• Where edges exist → enhance more

• Where noise dominates → suppress

• Where tones are sensitive → protect

This shifts control from:

global decisions → local decisions

Final Blending

Instead of a single transformation, PACE combines multiple signals:

• Local contrast (CLAHE)

• Structural detail

• Tone protection

These compete under perceptual constraints.

Enhancement is not applied — it is negotiated.

Visual Walkthrough

1. Input

2. Enhancement Map

3. CLAHE Output

4. Final Output

5. Comparative Visualization

Why This Works (In One Line)

Most libraries apply fixed transforms.

PACE:

analyzes → decides → applies selectively

That difference is everything.

What’s Next (Part 2)

This post focused on how the system behaves.

In Part 2, I’ll break down:

• Noise modeling (Laplacian + MAD)

• Adaptive control math (alpha, beta, lambda)

• CLAHE precision and clipLimit issues

• Failure modes and how they were fixed

Final Thoughts

PACE isn’t a filter.

It’s a decision system for image enhancement.

And building it in the browser forced every part of it to be:

• efficient

• adaptive

• perceptually grounded

If you’ve built something similar — or see flaws — I’d like to hear your take.