Forem: muhammed shahid

How to Computes CLAHE Parameters Dynamically for Every Image.

muhammed shahid — Thu, 30 Apr 2026 16:07:57 +0000

No sliders. No presets. Just math that listens to your image.

If you've ever used CLAHE (Contrast Limited Adaptive Histogram Equalization) in OpenCV, you've probably written something like this:

clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))

And then spent the next hour tweaking those two magic numbers until the result looked "good enough."

PACE doesn't do that.

PACE is a perceptual image enhancement pipeline I've been building that analyses each image's statistical fingerprint and derives its own clipLimit and tileSize — before a single pixel of CLAHE is applied. This post is a deep dive into exactly how that works.

The Two Parameters That Define CLAHE

Before getting into the adaptive logic, let's establish what these parameters actually control:

clipLimit — The clipping threshold applied to each tile's histogram before redistribution. Higher values allow more aggressive contrast stretching. Lower values keep the enhancement conservative. Set it too high and you get halos and noise amplification. Too low and you might as well not bother.

tileSize — The spatial granularity of the local enhancement. Smaller tiles capture fine local structure but risk over-enhancing noise. Larger tiles are smoother but might miss subtle detail.

The challenge: the "right" value for both of these is image-dependent. A low-key portrait shot needs very different treatment than a high-contrast landscape or a noisy night photograph.

Step 1: Reading the Image

PACE starts by extracting a statistical fingerprint from the luminance channel (after converting to OKLab). This happens in extractGlobalFeatures.js and produces:

{
  distribution: {
    mean,           // average luminance
    variance,       // spread of tones
    entropy,        // information density (normalized to [0,1])
    dynamicRange,   // p95 - p5 percentile range
    shadowRatio,    // fraction of pixels below 0.2
    highlightRatio, // fraction of pixels above 0.8
    skewness,
    kurtosis
  },
  structure: {
    edgeDensity,    // noise-adjusted, soft-normalised edge signal
    textureIndex    // gradient variance / mean gradient
  },
  noise: {
    noiseRatio,     // local deviation vs global variance
    microContrast
  }
}

This isn't just metadata. These values are the inputs to a small analytical engine that computes the CLAHE parameters.

Step 2: Computing `clipLimit`

Inside computeControlParams(), the clip limit is derived from a single intermediate called structureConfidence:

const structureConfidence = edgeDensity / (1 + noiseRatio);

This is a signal-to-noise ratio for spatial structure. It asks: how much of the gradient energy in this image is real structure, as opposed to noise?

A sharp, textured image (high edgeDensity, low noiseRatio) → high structureConfidence
A soft or noisy image → low structureConfidence

Then:

const clipLimit = 0.02 + 0.08 * structureConfidence;

This maps structureConfidence ∈ [0, 1] to clipLimit ∈ [0.02, 0.10].

Why this makes sense:

When structure confidence is high, the image genuinely has strong local contrast variation that CLAHE should bring out. A higher clip limit allows the histogram redistribution to be more aggressive — safe to do because the edges are real.

When the image is noisy or flat, a conservative clip limit prevents the CLAHE from amplifying noise into artificial "texture." The floor of 0.02 ensures some enhancement always happens.

Step 3: Computing `tileSize`

The tile size logic introduces one more intermediate — granularity:

const granularity = structureConfidence - 0.5 * noiseRatio;

This refines the structure signal by penalising noise more directly. Even if edgeDensity is high, if a significant chunk of it is noise-driven, we want larger tiles.

Then:

let tileSize = 32 - 16 * granularity;
tileSize = Math.max(8, Math.min(64, tileSize));
tileSize = Math.round(tileSize / 8) * 8;

Reading this:

`granularity`	Raw `tileSize`	Meaning
1.0 (sharp, clean)	16px	Fine-grained — trust local structure
0.5 (balanced)	24px	Moderate
0.0 (flat/noisy)	32px	Coarser — smooth out noise
-0.5 (very noisy)	40px	Conservative

The clamp to [8, 64] prevents pathological cases. The Math.round(.../ 8) * 8 snaps to multiples of 8 — a practical optimisation since tile boundaries align better with typical image dimensions and cache lines.

The Full `computeControlParams` Function

Here's the complete logic, stripped down:

function computeControlParams(features) {
  const { entropy, dynamicRange, shadowRatio, highlightRatio } = features.distribution;
  const { edgeDensity } = features.structure;
  const { noiseRatio } = features.noise;

  // How much contrast improvement does this image need?
  const contrastNeed = (1 - entropy) * (1 - dynamicRange);

  // How much can we trust the edge signal?
  const structureConfidence = edgeDensity / (1 + noiseRatio);

  // Tonal imbalance (is one end of the histogram overloaded?)
  const imbalance = Math.abs(shadowRatio - highlightRatio);

  // --- Global Alpha (blending weight) ---
  const alphaRaw =
    0.5 * imbalance +
    0.3 * contrastNeed +
    0.4 * structureConfidence;
  const globalAlpha = alphaRaw / (alphaRaw + 0.5);

  // --- Tile Size ---
  const granularity = structureConfidence - 0.5 * noiseRatio;
  let tileSize = 32 - 16 * granularity;
  tileSize = Math.max(8, Math.min(64, tileSize));
  tileSize = Math.round(tileSize / 8) * 8;

  // --- Clip Limit ---
  const clipLimit = 0.02 + 0.08 * structureConfidence;

  return { globalAlpha, tileSize, clipLimit };
}

Notice that globalAlpha — which controls how strongly the CLAHE result is blended into the final output — is computed from the same intermediates. The whole parameter set is internally consistent. An image that earns a high structureConfidence gets a higher clip limit and a finer tile size and a stronger blend weight. The enhancement scales coherently.

Step 4: The CLAHE Implementation

PACE implements CLAHE from scratch in CLAHE.js. The core is a two-phase process:

Phase 1 — Build tile LUTs:

function buildTileLUTs(gray, w, h, tileSize, clipLimit) {
  // For each tile:
  // 1. Build a 256-bin histogram
  // 2. Clip the histogram at: Math.floor(clipLimit * tileArea)
  // 3. Redistribute the clipped excess uniformly across all bins
  // 4. Compute CDF → LUT mapping [0..255] → [0..255]
}

The clip threshold is computed as clipLimit * tileArea — so the same clipLimit value naturally scales with tile size. A 16×16 tile has 256 pixels; a 32×32 tile has 1024. The clip is proportional, not absolute.

Phase 2 — Bilinear interpolation:

Rather than applying one tile's LUT per pixel (which creates visible block boundaries), PACE maps each pixel into the tile grid and bilinearly interpolates between the four surrounding tile LUTs:

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

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

This is the standard CLAHE bilinear interpolation scheme. The output is smooth regardless of tile boundaries.

A Worked Example

Say you feed PACE a foggy landscape — low contrast, flat histogram, minimal noise:

Feature	Value
`entropy`	~0.85 (information-rich despite low contrast)
`dynamicRange`	~0.3 (compressed tones)
`edgeDensity`	~0.25 (soft, diffuse edges)
`noiseRatio`	~0.1 (relatively clean)

Computing:

structureConfidence = 0.25 / (1 + 0.1) ≈ 0.23
clipLimit = 0.02 + 0.08 × 0.23 ≈ 0.038 → conservative stretching
granularity = 0.23 - 0.5 × 0.1 = 0.18
tileSize = 32 - 16 × 0.18 ≈ 29 → rounded to 32

Now feed it a sharp architectural photo — strong edges, clean capture:

Feature	Value
`edgeDensity`	~0.72
`noiseRatio`	~0.05

Computing:

structureConfidence = 0.72 / 1.05 ≈ 0.69
clipLimit = 0.02 + 0.08 × 0.69 ≈ 0.075 → more aggressive
granularity = 0.69 - 0.025 = 0.665
tileSize = 32 - 16 × 0.665 ≈ 21 → rounded to 24

The architecture shot gets a higher clip limit (more contrast punch) and a smaller tile size (finer local detail). The fog shot gets conservative treatment with larger tiles that smooth over the low-signal regions. No manual tuning. Just the image telling PACE what it needs.

Here is the visual as well as quantitative comparison between original image(input) and CLAHE image(output)

Visual comparison

Fig. 1

Fig. 2

Quantitative comparison

Why Not Just Use a Global Histogram Equalization?

Because global equalization is blind to spatial structure. It will happily blow out a bright sky to recover shadow detail in a corner, creating unnatural tonal shifts. CLAHE's tile-based approach means the histogram is equalized locally, so regions with different tonal characteristics are treated independently.

But static CLAHE parameters mean you're still guessing — just at a coarser level. PACE's adaptive approach closes the loop: the image's own statistics define the operating point for CLAHE, which then feeds into a broader perceptual blending pipeline (Retinex detail, Laplacian texture, edge gain, halo suppression) that further sculpts the final output.

What's Next

The current structureConfidence formulation is relatively simple — a ratio of edge density to noise. There's room to refine this further:

Using the textureIndex (gradient variance / mean gradient) to distinguish between fine texture and strong structural edges
Feeding kurtosis into the clip limit to handle bimodal histograms (silhouette shots, backlit subjects)
A per-channel confidence estimate rather than a single luminance-based signal

The structureConfidence file already hints at a more sophisticated version:

function computeStructureConfidence(edgeDensity, noiseRatio) {
  const edgeSignal = 1 - Math.exp(-3.0 * edgeDensity);
  const noiseSuppression = 1 / (1 + 2.5 * noiseRatio);
  const baseline = 0.55;
  return baseline + (1 - baseline) * edgeSignal * noiseSuppression;
}

This exponential formulation gives a softer, more robust curve than the current linear ratio — less sensitive to extreme values of edgeDensity. It's on the roadmap.

Wrapping Up

The key insight driving all of this is that CLAHE parameters aren't free variables — they're functions of image structure. Edge density, noise ratio, and tonal distribution each contain actionable information about how aggressively the enhancement should operate and at what spatial scale.

PACE makes this explicit: extract the features, compute the parameters analytically, apply consistently. The result is an enhancement pipeline that adapts to each image without needing a human in the loop to dial in settings.

If you're building image processing tools and you're still hardcoding clip limits, try deriving them. Your images will tell you what they need.

PACE is an open research project. The full source including the adaptive parameter controller, CLAHE implementation, and perceptual blending pipeline is on GitHub.

I Built a Zero-Parameter Image Enhancement Pipeline — Here's How It Works

muhammed shahid — Tue, 28 Apr 2026 16:52:40 +0000

Most image enhancement pipelines have a dirty secret: they need you to tune them.
Clip limit too high and CLAHE halos. Strength too aggressive and skin looks plastic.
Tile size wrong for your image and you get block artifacts.

PACE (Perceptual Adaptive Contrast Enhancement) is my attempt to fix that.
It analyzes the image, derives every enhancement parameter from its own statistics, and enhances it — without a single slider you need to touch.

This article is for people who care about why the math works, not just that it does.
If you're a web dev or just want to see what it can do, I'll be writing follow-up articles for you — but start here if you want the full picture.

🚀 Try Live Demo

👉 Open Demo

The core problem with "just use CLAHE"

CLAHE is everywhere, and for good reason — it's fast, effective, and well-understood.
But it has two parameters that matter enormously: tileSize and clipLimit.

A clipLimit of 2.0 is a rule of thumb. It has nothing to do with your image.
A tileSize of 8 might be perfect for a high-frequency texture scene and completely wrong for a portrait. And that's before you layer in any post-processing — sharpening, tone mapping, detail recovery.

The standard answer is "tune it per image." That's fine for a research dataset you've seen before. It breaks down the moment you're processing arbitrary inputs.

PACE asks a different question: what does the image itself say it needs?

The pipeline at a glance

PACE runs seven stages in sequence:

┌──────────────────────────────────────────────┐
│              Input: RGB Image                │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│ 1. Color Space Transformation                │
│    (RGB → OKLab)                             │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│ 2. Global Perceptual Analysis                │
│    (Distribution, Structure, Noise)          │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│ 3. Adaptive Parameter Estimation             │
│    (α, λ, β, τ, tileSize, clipLimit)         │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│ 4. Local Contrast Enhancement CLAHE          │
│    (adaptive tileSize, clipLimit)            │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│ 5. Control Map Synthesis                     │
│    (Edge, Structure, Skin, Alpha Maps)       │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│ 6. Perceptual Fusion                         │
│    (CLAHE + Retinex + Laplacian (nonlinear)) │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│ 7. Inverse Transformation                    │
│    (OKLab → RGB)                             │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│          Output: Enhanced Image              │
└──────────────────────────────────────────────┘

Every parameter used in stages 4–6 is computed in stages 2–3.
There is no configuration file.

Why OKLab instead of sRGB or Lab?

The pipeline works entirely on the luminance (L) channel of OKLab, leaving the chroma planes (a, b) untouched.

OKLab is perceptually uniform in a way that CIE Lab is not in practice — a Euclidean distance of 0.05 in OKLab corresponds to roughly the same perceived difference regardless of hue. This matters because the blending math in stage 6 adds deltas to L directly. In sRGB those deltas would cause perceptually inconsistent results across the tonal range: aggressive in shadows, gentle in highlights. In OKLab, the math has consistent perceptual meaning everywhere.

The conversion is LUT-accelerated: a 256-entry table for sRGB→linear, and a 4096-entry table for the cube root (cbrt) needed in the OKLab transform. At the inner loop scale of a 12-megapixel image, those two lookups save meaningful time over calling Math.cbrt() on every pixel.

Stage 2: Reading the image

Before any enhancement, PACE does a full statistical read of the luminance plane. Three feature groups:

Distribution features

A 512-bin histogram gives us mean, variance, skewness, kurtosis, and Shannon entropy. Dynamic range is computed as the p95–p5 spread (robust to outliers at either tail). Shadow and highlight ratios count pixels below 0.2 and above 0.8 respectively.

Entropy is normalized by log2(512) so it sits in [0, 1] regardless of bin count.

Structure features

Gradient magnitude uses the Alpha-Max + Beta-Min approximation:

grad ≈ max(|gx|, |gy|) + 0.25 * min(|gx|, |gy|)

This trades a small amount of accuracy for a significant speedup — no square root, no multiply. Edge density is then noise-adjusted before it leaves this stage:

edgeDensity = (rawEdge / (1 + 0.5 * noiseRatio)) / (adjusted + 0.25)

The soft normalization in the denominator prevents high-texture images from saturating the density estimate.

Noise features

Each pixel's absolute deviation from its 4-neighbor mean is the noise proxy. It's not as precise as a Laplacian-of-Gaussian approach, but it's a single pass, requires no window allocation, and correlates well enough with perceived noise to drive the downstream parameters correctly.

Stage 3: Deriving every parameter

This is where PACE diverges from conventional pipelines. Rather than exposing parameters to the user, it maps features to parameters through a set of monotonic functions with smooth clamping.

λ — nonlinear compression strength

contrastStrength = 0.6√variance + 0.5 * dynamicRange + 0.4 * edgeDensity

noiseEnergy = noiseRatio + 0.7 * microContrast

λ_raw = 0.3 + 0.8 * (1 − contrastStrength) + 1.2 * noiseEnergy + 0.4 * textureIndex

λ = λ_raw / (1 + λ_raw)      ← smooth clamp to [0, 1)

λ controls how aggressively the final delta is compressed via Δ / (1 + λ|Δ|). High noise → high λ → stronger compression → less noise amplification. High existing contrast → low λ → lighter touch. The x/(1+x) clamp guarantees λ never reaches 1 and the denominator never explodes.

β — highlight protection

highlightDominance = highlightRatio + 0.4 * max(0, skewness) + 0.3 * mean + 0.2 * dynamicRange

x = highlightDominance − 0.5 * shadowRatio

β = 0.8 * (x / (1 + |x|))

β feeds into a luminance mask max(0.15, 1 − β*L[i]). A bright, positively-skewed image gets high β, which pulls the mask down toward 0.15 in the highlights — protecting them from over-enhancement without a hard clip.

τ — tone limiter threshold

τ = 0.35 + 0.8 * (1 − √variance) * (1 − 0.5 * entropy)
τ ∈ [0.35, 1.2]

Low-contrast, low-entropy images (flat skies, underexposed shots) get high τ — the tone limiter allows more headroom because the image needs more work. High-contrast scenes get lower τ — the limiter kicks in earlier to prevent clipping.

globalAlpha and CLAHE parameters

contrastNeed = (1 − entropy) * (1 − dynamicRange)
structureConfidence = edgeDensity / (1 + noiseRatio)
imbalance = |shadowRatio − highlightRatio|

globalAlpha = f(imbalance, contrastNeed, structureConfidence)
tileSize ∈ [8, 64], rounded to nearest 8
clipLimit = 0.02 + 0.08 * structureConfidence

Structured, noise-free images get smaller tiles (capturing local contrast at the right scale) and higher clip limits (allowing more redistribution). Noisy images get larger tiles and conservative clip limits.

Stage 5: Spatial control maps

Six maps are generated from a single gradient pass over L. The key ones:

Edge map: Alpha-Max + Beta-Min magnitude, same approximation as stage 2.

Structure mask: Euclidean gradient magnitude, normalized globally by its maximum. Used to boost enhancement in structurally confident regions via structureMask^0.7.

Skin damp map: A Gaussian centered at L=0.5 with σ=0.18, producing values in [0.3, 1.0]. Mid-luminance pixels receive suppressed enhancement. This is a luminance heuristic, not color-based skin detection — it works because skin tones in OKLab tend to cluster near mid-L, and it naturally protects smooth gradients (faces, fabric) from over-sharpening.

Local alpha map: Computed tile-by-tile. Each tile measures gradient coherence (mean gradient / gradient std dev) weighted by noise, then modulates globalAlpha spatially. High-structure tiles get more enhancement; flat or noisy tiles get less. This map is then smoothed by a guided filter to prevent block boundaries from appearing in the output.

Lsmall and Lmedium: A 3×3 Gaussian-approximated smooth and a 5×5 box smooth of that result. These two scales provide the illumination estimates used in the Retinex computation.

Stage 6: The blending stack

This is the core of PACE. Per pixel:

Three signals combined into one delta

// Retinex
reflectance = log(Lsmall[i]) − log(Lmedium[i])
detailMask = clamp(reflectance * 0.8 + 0.5, 0, 1)

localMean = mean of 4 neighbors in Lsmall
textureMask = edge / (edge + 0.015)
deltaDetail = clamp((Lsmall[i] − localMean) * textureMask, −0.25, 0.25)

deltaClahe = Lclahe[i] − L[i]
edgeAdaptive = edge / (edge + 0.03)

delta = deltaClahe + 0.45 * deltaDetail * detailMask * skinDamp * structureBoost * edgeAdaptive
delta = clamp(delta, −0.5, 0.5)

The Retinex term (log(Lsmall) − log(Lmedium)) approximates the reflectance component of the image by treating Lmedium as the illumination estimate. A positive reflectance means the pixel is brighter than its local surround — a highlight or edge — and the detail mask opens up to let more Laplacian texture through.

The Laplacian term (Lsmall − localMean) is a band-pass detail signal. The textureMask gates it by edge strength so it only amplifies where there's genuine structure, not flat regions or noise.

Three successive nonlinear compressions

// Halo suppression
deltaStable = delta / (1 + 2|delta| + ε)

// Tone limiter (luminance-adaptive)
deltaLimited = deltaStable / (1 + |deltaStable| / (τ * (0.5 + L[i])))

// Soft nonlinear compression (Reinhard-style)
compressed = deltaLimited / (1 + λ * |deltaLimited|)

Each stage compresses large values more than small ones. Together they form a cascaded soft clipper that prevents any single large delta from blowing through — but doesn't hard-clip anything, so gradients remain smooth.

The tone limiter has a luminance term (0.5 + L[i]) in the denominator. In highlights, L[i] is large, so the divisor is large, so the limit is gentler — the signal is allowed to pass through more easily when there's already little headroom for error. In shadows, the divisor is small, so the limit is stricter — protecting shadow detail from noise amplification.

Final luminance

edgeResponse = edge / (edge + kAdaptive)
edgeGain = edgeResponse^0.8 * (1 + 0.6 * edgeResponse)
lumMask = max(0.15, 1 − β * L[i])
contrastGain = 1 + finalAlpha * (1 − 0.5 * L[i])

enhanced = L[i] + compressed * edgeGain * lumMask * contrastGain

edgeGain is a soft edge boost that scales superlinearly with edge strength. lumMask provides the highlight rolloff from β. contrastGain provides a luminance-weighted global intensity that naturally lifts shadows more than highlights.

Results

A comparison across image categories (these use the live demo):
👉 Open Demo

Underexposed portraits: shadows lift without skin posterization or highlight clipping
Hazy landscapes: contrast recovers without halo artifacts at sky/ground boundaries
High-noise low-light: texture enhanced, noise suppressed rather than amplified
Already well-exposed images: minimal change — the pipeline reads the statistics and backs off

The live demo is available at the repository — you can drag in your own images and watch the per-stage progress in real time.

Try it / contribute

The full source implementations, is on GitHub:

👉 github.com/muhammedshahid/pace

The pipeline runs in a Web Worker, is framework-free, and exposes a single async function:

import { applyPACE } from 'pace-enhance';

const enhanced = await applyPACE(imageData, {
  strength: 1.0,   // default 1.0 = PACE auto
  debug: false     // true = downloadable trace JSON per stage
});

There's also an override option for researchers who want to fix specific parameters and experiment with the rest:

const enhanced = await applyPACE(imageData, {
  override: {
    controlParams: { clipLimit: 0.05 },
    perceptualParams: { lambda: 0.4, tau: 0.8 }
  }
});

What's next

Several directions I'm actively thinking about:

No-op path: an early exit for images that statistically don't need enhancement, based on entropy + dynamic range thresholds
True structure confidence: the standalone structureConfidence function in the repo is more sophisticated than what's currently wired up — it uses exponential edge decay and noise suppression rather than the raw ratio
Boundary handling: the current 1-pixel border exclusion in blending needs proper edge-extension
Perceptual evaluation: SSIM and PSNR don't capture perceptual enhancement quality well. I want to build a feature-based evaluation that correlates with human preference

If any of this overlaps with your work, I'd genuinely love to hear from you — open an issue, or find me here in the comments.

To ensure transparency and reproducibility, PACE is backed by DOI-archived records. The research is available on SSRN (https://dx.doi.org/10.2139/ssrn.6661421), the implementation is preserved on Zenodo (https://doi.org/10.5281/zenodo.19437397), and the source code is openly available on GitHub (https://github.com/muhammedshahid/pace).

Live Demo: https://muhammedshahid.github.io/pace/src/

This is the first in a series. Next up: the same pipeline explained for frontend developers — what it does without the math, how to drop it into a project, and when you'd actually want to use it.