0xBeycan-ComfyUI-ImageQualityGate/README.md

# ComfyUI-ImageQualityGate

> [!IMPORTANT]
> **This repository is no longer maintained.** This node has been ported to
> **[ComfyUI-BCNodes](https://github.com/0xBeycan/ComfyUI-BCNodes)** and all further
> development happens there. Install that pack instead of this one.
>
> | Node here | Node in BCNodes |
> | --- | --- |
> | `ImageQualityGate` | `BC_ImageQualityGate` |
>
> The registration key changes, so a workflow saved against this pack has to be
> re-wired to the `BC_` node once. Everything below is kept for reference only;
> no fixes or new features will land here.

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

```bash
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