ComfyUI-ImageQualityGate

A single-node image quality control system for ComfyUI. Designed for automated filtering of AI-generated images in LoRA training dataset pipelines.

Analyzes 5 quality metrics, applies shot-type-aware threshold scaling, and outputs a visual PASS / SO-SO / FAIL badge — all in one node.

Features

• 5 Quality Metrics — Blur, Sharpness, Noise, Clipping, Entropy
• Three-Tier Verdict — PASS (green), SO-SO (yellow), FAIL (red). No more hard binary decisions on borderline images.
• Center-Weighted Blur Detection — Ignores background bokeh, focuses on subject sharpness
• Shot Type Presets + Custom Mode — Use built-in profiles or go fully manual with raw slider values
• Visual Badge Output — Color-coded badge with per-metric breakdown, directly previewable in ComfyUI
• Integer Verdict Output — 0=FAIL, 1=SO-SO, 2=PASS for routing through Switch nodes

The Problem This Solves

Standard blur detection treats the entire image uniformly. Portrait shots with shallow depth of field get flagged as blurry even when the subject is perfectly sharp. The center-weighted blur mode weights the center of the image 3x heavier than the edges, so background bokeh doesn't inflate scores.

Additionally, AI-generated images (especially from distilled models like Z-Image Turbo) have inherently lower block-level Laplacian variance than real photographs. The blur_var_threshold parameter lets you calibrate for this — set it to 20-50 for AI content instead of the 80-150 range used for real photos.

Installation

cd ComfyUI/custom_nodes/
git clone https://github.com/0xBeycan/ComfyUI-ImageQualityGate.git
pip install -r ComfyUI-ImageQualityGate/requirements.txt

Restart ComfyUI. The node appears under image/analysis → Image Quality Gate.

Shot Type Modes

Presets (close-up, medium, wide / full-body)

When a preset is selected, your slider values are multiplied by the profile's scaling factors. This means the same base thresholds automatically adapt to different shot types.

Metric	Close-up	Medium	Wide / Full-body
Blur	×0.6 (stricter)	×1.0	×1.6 (looser)
Sharpness	×1.5 (stricter)	×1.0	×0.6 (looser)
Noise	×0.8	×1.0	×1.3
Clipping	×0.8	×1.0	×1.2
Entropy	×1.1	×1.0	×0.85
Block size	16px	24px	32px

Custom Mode

When custom is selected, all multipliers are 1.0. Slider values are used exactly as-is. Block size defaults to 24px. Use this when you want full manual control or when calibrating thresholds for a new model.

Three-Tier Verdict System

Instead of a hard PASS/FAIL binary, the node evaluates each metric into three states:

State	Badge Color	Meaning
PASS	Green	All metrics within threshold
SO-SO	Yellow	No hard failures, but some metrics in the margin zone (within 1.4× of threshold)
FAIL	Red	At least one metric exceeds the margin zone

The verdict output is an integer: 0 = FAIL, 1 = SO-SO, 2 = PASS. Use this with a Switch node to route images into three buckets: auto-accept, manual review, and auto-reject.

Margin Zone Logic

For "lower is better" metrics (blur, noise, clipping):

• score ≤ threshold → PASS
• threshold < score ≤ threshold × 1.4 → MARGINAL (contributes to SO-SO)
• score > threshold × 1.4 → FAIL

For "higher is better" metrics (sharpness, entropy):

• score ≥ threshold → PASS
• threshold / 1.4 ≤ score < threshold → MARGINAL
• score < threshold / 1.4 → FAIL

Node Inputs

Input	Type	Default	Description
image	IMAGE	—	Input image tensor
shot_type	Dropdown	custom	custom, close-up, medium, wide / full-body
blur_mode	Dropdown	full image	full image or center-weighted
blur_threshold	Float	0.40	Max blur ratio
blur_var_threshold	Float	30.0	Laplacian variance per block (AI: 20-50, photo: 80-150)
sharpness_threshold	Float	15.0	Min sharpness score
noise_threshold	Float	25.0	Max noise level
clipping_threshold	Float	0.02	Max clipping ratio
entropy_threshold	Float	5.0	Min entropy in bits

Node Outputs

Output	Type	Description
badge	IMAGE	Visual PASS/SO-SO/FAIL badge
verdict	INT	0=FAIL, 1=SO-SO, 2=PASS
report	STRING	Text report with per-metric breakdown
blur_score	FLOAT	Raw blur ratio
sharpness_score	FLOAT	Raw sharpness value
noise_score	FLOAT	Raw noise level
clipping_score	FLOAT	Raw clipping ratio
entropy_score	FLOAT	Shannon entropy in bits

Recommended Workflow

                                        ┌─ verdict=2 → [SaveImage] (dataset/)
[Generate] → [ImageQualityGate] → verdict → verdict=1 → [SaveImage] (review/)
                                        └─ verdict=0 → (discard)

Threshold Calibration

1. Generate 30–50 images with your pipeline
2. Run through the node in custom mode
3. Check the report output — look at score distributions
4. Adjust thresholds so ~70-80% of your "good" images pass
5. Switch to a preset for production runs

License

MIT