Color Correction Agent Skill

Color Correction (measure, don't eyeball)

The core principle

You cannot reliably judge color from a storyboard / contact sheet. "Is it washed

out?" flip-flops by eye, especially on AI-gen video. Make color measurable with the

analyze_color MCP tool, read the numbers like a colorist reads scopes, then pick the

fix the data points to — and re-measure to confirm. The whole skill is this loop:

extract a frame ─► analyze_color ─► read black/white points + contrast + saturation
       ▲                                          │
       │                                          ▼
   re-measure  ◄──── apply fix (levels / contrast / match) ◄── diagnose from the numbers

> Origin: on a WAN-Animate render we argued for many turns over whether the clip was

> "washed out." The instant we measured it, the answer was unambiguous and the *correct*

> fix (a contrast stretch, NOT the color-match nodes we'd been adding) fell straight out.

The analyze_color tool

Read-only. Source = asset_id, a ComfyUI output ref (filename/subfolder/type), or

an image path (absolute, or under the output dir). It returns per-image stats + heuristic

flags + a one-line verdict, and (optional) an overlaid R/G/B/luma histogram PNG.

analyze_color({ filename: "render_00007_.png" })                 # absolute numbers
analyze_color({ path: "frame.png", reference_path: "src.jpg" })  # + shot-match deltas
analyze_color({ filename: "x.png", histogram: true })            # + histogram image

Videos: analyze_color is image-only (no ffmpeg dep). Extract a frame first with the

ComfyUI venv's cv2:

"<comfy-venv>/python" -c "import cv2; c=cv2.VideoCapture(r'IN.mp4'); n=int(c.get(7)); \
  c.set(1, n//2); _,f=c.read(); cv2.imwrite(r'frame.png', f)"

(grab the middle frame, or frame 0; for window-drift checks grab a frame from each window.)

What the numbers mean (8-bit)

| Field | Reads like a scope | Healthy-ish |

|---|---|---|

| luma.blackPoint (1st pct) | where shadows bottom out | ~0–16 (lifted if >16) |

| luma.whitePoint (99th pct) | where highlights top out | ~240–255 (dim if <235) |

| luma.contrast (std) | overall punch | ~45+ (flat if <45) |

| luma.dynamicRange | white−black | wide is good |

| saturation.meanSaturation (HSV S) | vectorscope spread | ~0.25+ (dull if <0.22) |

| channels.{r,g,b}Mean + castHint | RGB parade / white balance | spread <~12 = neutral |

| luma.clippedHighPct/LowPct | blown / crushed pixels | keep low (<~2%) |

Flags: washedOut, lowContrast, liftedBlacks, dimHighlights, lowSaturation, colorCast.

The "washed out" signature

Washed out = compressed tonal range, and it has an exact fingerprint:

• whitePoint well below 255 (e.g. 191) — highlights never reach white
• blackPoint lifted off 0 (e.g. 45) — milky shadows
• contrast low (std < 45)
• often *normal* saturation — washout is usually NOT a saturation problem.

If you see that, the fix is a levels / contrast stretch, not a color match. (Real case:

a WAN-Animate frame measured blackPoint 45 / whitePoint 191 / contrast 43 — clearly a range

problem; saturation 0.25 was fine.)

The load-bearing insight: a reference-match can't add contrast the source lacks

The instinct is to "match the render to the input photo" with a color-match node

(ColorMatchV2 mkl/hm, ImageColorMatchAdobe+, easy imageColorMatch). **Measure the

reference first.** If the reference is itself flat (e.g. a casual phone selfie:

blackPoint 40, contrast 44), matching to it cannot produce punch — you'll match your way

to the *same* flat numbers. In the real case, mkl and Adobe matches both left the frame

flagged washedOut (whitePoint only crept 191→~218).

So:

• Use a reference-match (ColorMatchV2, ImageColorMatchAdobe+) when you want to *match

a known-good graded frame / shot-match across clips*, and the reference is actually good.

• Use a levels / contrast stretch when the defect is compressed range (the washout case)

— it targets full range *regardless* of the reference. This is usually the real fix.

The fix: contrast / levels stretch (core nodes, no install)

AdjustContrast (core comfy_extras.nodes_dataset, category *image/adjustments*) — one

factor (1.0 = none, >1 = more). Pivots around mid-gray, so it pushes the white point up

and the black point down together. Tune it by measurement, not feel. Real measured sweep

on the washout frame:

| factor | blackPoint | whitePoint | contrast | sat | clippedHigh | verdict |

|---|---|---|---|---|---|---|

| 1.3 | 29 | 239 | 56 | 0.33 | 0% | ✅ not washed (slightly soft) |

| ~1.4 | ~20 | ~247 | ~60 | ~0.38 | ~1–2% | ✅ sweet spot |

| 1.6 | 7 | 254 | 67 | 0.44 | 7.2% ⚠️ | punchy but blows highlights |

Pick the factor that lands whitePoint ~248–255 with clippedHighPct < ~2%. Going too far

(1.6 here) blows highlights *and* over-warms (per-channel contrast drops blue more than red →

castHint worsens). Sweet spot was ~1.4.

Other levers when contrast alone isn't enough:

• CurveEditor (core, *utilities*) → feeds a CURVE for precise black/white-point + gamma

control (a true levels curve) when you need more than a single contrast pivot.

• AdjustContrast + a small saturation/brightness adjust (same *image/adjustments* family)

to fine-tune after the stretch.

• A mild reference-match *after* the stretch only if you genuinely need to shot-match.

The sandbox pattern (test corrections side by side, then measure)

Don't tune blind on the full pipeline. Build a tiny separate workflow (panel_new_workflow)

and let one run produce several candidates you then measure:

LoadImage (the washed frame, staged into input/)
LoadImage (the reference, if shot-matching)
        │
        ├─► AdjustContrast factor 1.3 ─► SaveImage "contrast13"
        ├─► AdjustContrast factor 1.6 ─► SaveImage "contrast16"
        ├─► ColorMatchV2 (mkl, ref)   ─► SaveImage "balance_mkl"
        └─► ImageColorMatchAdobe+(LAB)─► SaveImage "balance_adobe"

Run once, then analyze_color every output (+ the reference + the untouched frame) and

compare blackPoint / whitePoint / contrast / saturation / clippedHigh. Whichever lands the

numbers in range wins; interpolate the factor (1.3 vs 1.6 → 1.4) and confirm with one more

pass. Stage the frame into the ComfyUI input dir first (cp the extracted PNG there) so

LoadImage can see it — input/output dirs may be custom, so don't guess paths.

Porting the fix into a render graph

Place the chosen correction after decode, before the save — for a WAN/video graph that's

right after WanVideoDecode (or the per-chunk color-match) and feeding the

VHS_VideoCombine/save node. One AdjustContrast node is usually the whole fix; keep it as a

single inline node (or a small bypassable group) so it's easy to toggle and re-tune. Re-render

a clip, extract a frame, analyze_color it, and nudge the factor to hit whitePoint ~250.

Video-specific gotchas

• Per-window drift (WAN long video): WAN-Animate/long clips render in temporal windows and

can desaturate/dim across them. Measure a frame from the *first* window and a *late* window —

if they differ, that's drift, not a global grade issue (use the embeds' between-window

colormatch, not a final stretch).

• Relight LoRA ≠ levels: a WanAnimate relight LoRA changes *lighting*, not black/white

points — it won't fix a compressed-range washout. Measure before and after to prove it.

• Don't over-stretch: watch clippedHighPct — blown highlights are unrecoverable. Prefer

the lower factor that still clears dimHighlights.

• Cast is often inherited: if the reference has the same warm/cool cast (festival/sunset

light), a matching cast on the render is *correct* — don't "fix" it.

Quick reference — the decision tree

analyze_color the frame
  ├─ washedOut / lowContrast / dimHighlights ........ contrast/levels stretch (AdjustContrast ~1.4 → measure)
  ├─ lowSaturation only ............................. saturation boost (small)
  ├─ colorCast (and reference is neutral) ........... white-balance / neutralization, or reference-match
  ├─ want to MATCH a known-good graded frame ........ ColorMatchV2 / ImageColorMatchAdobe+ (ref must be good)
  └─ blackPoint/whitePoint already 0/255, sat ok .... color is healthy — stop touching it

Always re-measure after the fix. If analyze_color still flags it, the fix was wrong —

adjust and measure again. Numbers over vibes.