SSIM

If you've ever compared two upscalers, two VAEs, or two finetunes and said "the numbers say one thing but my eyes say another," this node is the reason that mismatch exists - and the partial fix for it. SSIM (Structural Similarity Index) is the 2004 classic that finally stopped treating an image as a bag of pixels and started comparing structure: luminance, contrast, and local texture. Higher is better, 1.0 means the images are identical, and it's still the default sanity metric in half the image-compression literature.

It's part of comfyui-piq, a pack of seventeen thin wrappers around the piq library. All nodes follow the same shape - image_a and image_b in, a single FLOAT score out, everything under the "piq" category. SSIM is closed-form math, so there's no model download and it runs on CPU in milliseconds.

How it works. SSIM slides a Gaussian window (11×11 by default) across both images and computes three local statistics: luminance (mean), contrast (variance), and structure (covariance). Those three get combined into a per-pixel similarity map with two stability constants (k1, k2) that stop division from exploding on flat regions, and the map is averaged into one score. The original paper downsamples the image before scoring, and piq keeps that behavior - downsample defaults to true in this node, which you generally want for the score to match how SSIM was validated.

Inputs a beginner actually sets:

• image_a / image_b - your candidate and your reference. image_b is the ground truth; swap them and the result is usually still symmetric-ish, but build the habit of keeping image_b as the reference.
• data_range - keep 1.0; ComfyUI IMAGE tensors are floats in 0–1, and this node doesn't know that unless you tell it.
• kernel_size and kernel_sigma - leave alone. 11 and 1.5 are the canonical values.
• reduction - mean for a single number, sum if you're chaining your own pooling.

The ssim output is a FLOAT in roughly [0, 1] for real use. The gap between, say, 0.93 and 0.95 is where you live when comparing two decent generations.

Installing. ComfyUI Manager → search "comfyui-piq" → Install, or:

cd ComfyUI/custom_nodes
git clone https://github.com/Laurent2916/comfyui-piq.git
pip install -r custom_nodes/comfyui-piq/requirements.txt

That requirements file is just piq>=0.8.0. Python 3.12+ required. The repo is archived as of early 2026, but these are stable, done-deal metrics - archived doesn't mean broken.

Where people get burned. SSIM is blind to semantic content. An image with the same structure but completely different subject matter can score surprisingly high, and it's insensitive to blur that your brain finds offensive. Don't use it alone to rank aesthetics; it's the "did this pipeline hold the image together" metric, not "does this look better." The community's upscale-comparison messes are mostly people over-trusting one traditional metric - pair SSIM with a learned one like LPIPS or DISTS, and only trust them when they agree. It's also stricter about identical resolutions than you might expect, so compare like-sized images.