The Gate That Stops Visual Damage Before You Hand Bulk Image Optimization to an Agent

Collapsing the gate into a single checker

The decision lives in one function: take the original and the converted image, compute the three axes, return a verdict. The only dependencies are Pillow, scikit-image, and numpy. I avoided heavier libraries so it runs in a few seconds even inside an isolated CI environment.

# image_quality_gate.py
from dataclasses import dataclass
from pathlib import Path
import numpy as np
from PIL import Image
from skimage.metrics import structural_similarity as ssim
 
 
@dataclass
class GateResult:
    ssim: float
    delta_e: float
    size_ratio: float  # converted / original
    passed: bool
    reasons: list[str]
 
 
def _load_rgb(path: Path, size: tuple[int, int] | None = None) -> Image.Image:
    img = Image.open(path).convert("RGB")
    if size is not None and img.size != size:
        img = img.resize(size, Image.LANCZOS)
    return img
 
 
def _mean_delta_e(a: Image.Image, b: Image.Image) -> float:
    # Pillow packs L,a,b into 0-255, so scale back to real ranges
    la = np.asarray(a.convert("LAB"), dtype=np.float64)
    lb = np.asarray(b.convert("LAB"), dtype=np.float64)
    la[..., 0] *= 100.0 / 255.0
    lb[..., 0] *= 100.0 / 255.0
    la[..., 1:] -= 128.0
    lb[..., 1:] -= 128.0
    # CIE76: Euclidean distance in LAB, averaged over pixels
    diff = la - lb
    return float(np.sqrt((diff ** 2).sum(axis=-1)).mean())
 
 
def evaluate(
    original: Path,
    converted: Path,
    *,
    ssim_floor: float = 0.985,
    delta_e_ceiling: float = 2.0,
    size_ratio_floor: float = 0.10,  # over 90% off suggests over-compression
    size_ratio_ceiling: float = 0.95,  # under 5% off means the conversion barely helps
) -> GateResult:
    orig = _load_rgb(original)
    conv = _load_rgb(converted, size=orig.size)
 
    g_orig = np.asarray(orig.convert("L"), dtype=np.float64)
    g_conv = np.asarray(conv.convert("L"), dtype=np.float64)
    s = float(ssim(g_orig, g_conv, data_range=255))
 
    de = _mean_delta_e(orig, conv)
    ratio = converted.stat().st_size / original.stat().st_size
 
    reasons: list[str] = []
    if s < ssim_floor:
        reasons.append(f"SSIM {s:.4f} < {ssim_floor}")
    if de > delta_e_ceiling:
        reasons.append(f"delta_e {de:.2f} > {delta_e_ceiling}")
    if ratio < size_ratio_floor:
        reasons.append(f"possible over-compression: size_ratio {ratio:.2f}")
    if ratio > size_ratio_ceiling:
        reasons.append(f"optimization not effective: size_ratio {ratio:.2f}")
 
    return GateResult(s, de, ratio, len(reasons) == 0, reasons)

The important part is that the verdict comes back not as a bare boolean but with reasons attached. When you route a failure back to the agent, telling it "SSIM was 0.971, below the floor" lets it pick a next move — switch the conversion preset, or drop that single image to lossless. Return only "failed" and it tends to repeat the same mistake.

A word on why SSIM is computed in grayscale. You can run SSIM per channel and average, but color drift is ΔE's job. Keeping SSIM strictly on structure means the two metrics do not overlap in responsibility, so whichever one trips tells you the cause directly.

Deciding the thresholds — from measurement

Thresholds are not something you know upfront. I ran my own assets through the representative conversion presets and looked at the distribution before deciding. Below are rough measurements from 20 images each of three kinds of wallpaper preview (photographic, flat illustration, gradient-heavy).

From this spread I set the SSIM floor at 0.985 and the ΔE ceiling at 2.0. WebP q=80 became my baseline preset; only gradient-heavy images cluster near the threshold, so the gate picks those up naturally. A picked-up image gets bumped to q=90 or routed to lossless WebP.

The numbers depend heavily on the character of the artwork, so rather than borrowing this table wholesale, I would encourage you to take the distribution on your own assets first, then decide. Adding a --report mode that dumps SSIM, ΔE, and size to CSV makes revisiting thresholds much easier later.

Wiring the gate into the agent's workflow

The gate slots in as an independent verification step after the agent's optimization step. If you fold the two into one step, the same actor that did the optimizing also grades it, and slack creeps in.

Before, my instruction to the agent read like this:

Convert the PNGs under assets/preview/ to WebP, replace the originals, and commit.

After, conversion and judgment are separated, and judgment is delegated to the script:

1. Write each PNG under assets/preview/ out to assets/_staging/ as WebP (do not delete originals)
2. Run: python image_quality_gate.py --check <original> <converted> on each
3. Replace the original only for the ones that pass
4. Leave failures in _staging, list the reasons in quality_report.md, and stop

Not overwriting the originals immediately is the crux. Staging first lets you safely return the failures while finalizing only the passes. Instead of asking the agent to judge, you ask it to obey the gate's output.

Give the script a thin CLI entry point so it works from CI and from the agent's shell alike:

# image_quality_gate.py (append at the end)
import sys
 
if __name__ == "__main__":
    # usage: python image_quality_gate.py --check original.png converted.webp
    if len(sys.argv) == 4 and sys.argv[1] == "--check":
        r = evaluate(Path(sys.argv[2]), Path(sys.argv[3]))
        print(f"SSIM={r.ssim:.4f} dE={r.delta_e:.2f} ratio={r.size_ratio:.2f}")
        if not r.passed:
            print("FAIL: " + "; ".join(r.reasons))
            sys.exit(1)
        print("PASS")

Mapping the exit code to the verdict means CI and the agent's shell can both branch on it directly. A non-zero exit simply stops the run, and the following commit never happens.

The axis people miss — color profiles

Even with three axes measured, one kind of degradation slips through: a stripped color profile.

Some conversion tools discard the embedded ICC profile (Display P3, for instance) and write the file as if it were sRGB. Because the numeric pixel values are unchanged, even the ΔE above may show little difference. Yet on a wide-gamut display, reds and greens that should have been vivid render dulled.

This is better prevented at conversion time than judged after. Preserve the profile explicitly on write, and check separately that it was not dropped.

from PIL import Image
 
def has_icc_profile(path) -> bool:
    with Image.open(path) as im:
        return "icc_profile" in im.info and bool(im.info["icc_profile"])

If the original had a profile and the converted file lost it, that alone is a failure. Until I added this one-line check, my P3 assets had been silently falling back to sRGB for a long time without my noticing. Even when you measure what you measure, whatever axis you do not measure slips through. A gate is not omnipotent; it is a tool for reliably stopping known failures.

What running it taught me

After a few months with this gate, a few things settled into place.

One: the gate makes instructions to the agent shorter. I used to pile on vague requests — "don't over-compress," "keep the color" — but now that the pass/fail criteria live outside as numbers, the instruction is just "convert and run it through the gate." Peeling the definition of quality out of the prompt and moving it into verification code helped more than I expected.

Two: the single image near the threshold teaches the most. Nothing is learned from artwork that passes reliably. The "deep gradient" pictures the gate occasionally catches are exactly the weak point of my asset set, and they prompted me to branch conversion presets by artwork type. A gate is a gatekeeper, but also an observation point that tells you the character of your own assets.

Finally — and this is a note to myself — the easier a number is to read, the more it deserves suspicion. The better the report, the more worth pausing to check what happened behind it. The wider you spread automation, the more that one beat of hesitation pays off.

If this becomes a prompt to think about "which number you accept an agent's work by," beyond images specifically, I would be glad. Start by running your own assets through the checker once and looking at the SSIM and ΔE distributions. From there, the shape of "passing" for your app will start to come into view. Thank you for reading.