Color Harmony Analyzer

Every grading tutorial eventually says "use complementary colors" or "this is triadic," and then you're left wondering whether your frame actually does that. Color Harmony Analyzer takes a guess: it pulls the dominant hues out of your image, compares their spacing against classical color-theory patterns, and tells you which harmony it matches - complementary, analogous, triadic, split-complementary, or tetradic - plus a polar wheel showing the hue positions.

Straight talk up front: this is the most "art-school, your-millage-may-vary" node in ThatGlennD's ComfyUI-Image-Analysis-Tools pack. The others measure physics - sharpness, noise, clipping - things that are objectively measurable. Harmony is a heuristic. The node is honest about that; treat harmony_score as a coarse suggestion, not a verdict on your taste.

How it works

The image gets converted to HSV, then the hue channel alone is fed into K-means clustering to find the num_clusters dominant hues (2–8, default 3). Those hues are compared pairwise:

• Two hues ~180° apart → Complementary
• All hues within 30° → Analogous
• Three hues ~120° apart → Triadic
• A base plus its split-complementary neighbors → Split-Complementary
• Four hues in two complementary pairs → Tetradic

Because the matcher works on exact hue-distance windows, the score comes back either 1.0 (matched) or 0.0 ("No clear harmony") - there's no partial credit. The harmony_type string names the winner, and with visualize_harmony on, hue_wheel_visual renders a matplotlib polar plot with your dominant hues as dots on a 0–360° wheel, labeled with the harmony type. You'll learn more from staring at that wheel than from the score.

One input to know: num_clusters. Default 3 is right for "what's the overall scheme?" Crank it to 6–8 and you're analyzing a fuller palette instead of a postcard of the image - but more clusters also means more chances to land on a weak match.

Where it's actually useful

• Style consistency across frames. If every frame of a sequence classifies as the same harmony type, your grade is holding together.
• Checking a stylized render against the mood you asked for - a "warm cinematic" prompt that comes back tetradic and chaotic tells you the palette fought you.
• Auditing a palette before it ships into a product shot or a series where color language matters.

The trap is taking the label as proof of quality. A flat, boring frame of two near-identical hues will happily call itself "analogous." Use it as a diagnostic lens, not an A/B test.

Install

Same pack, same recipe - Manager (search "Image Analysis") or:

cd ComfyUI/custom_nodes
git clone https://github.com/ThatGlennD/ComfyUI-Image-Analysis-Tools
cd ComfyUI-Image-Analysis-Tools
pip install -r requirements.txt

Restart ComfyUI. This is the one node in the pack that genuinely needs scikit-learn (K-means), and it imports it at module load - if scikit-learn is missing, the whole pack silently fails to register, not just this node. Windows portable users: python_embeded\python.exe -m pip install scikit-learn.

Common gotchas

• Pack won't load / nodes missing: almost always the scikit-learn import. Fix that first.
• comfy_api import error: needs a current ComfyUI; update before troubleshooting anything else.
• First frame only: batches analyze frame 0. Video frames go through one at a time.
• All-zero or "No clear harmony" scores: normal for images with few dominant hues. Try dropping num_clusters to 2 or 3, or feeding it a downscaled crop of the actual subject instead of the whole busy frame.

If you pair it with the Color Temperature Estimator in the same pack, you get both halves of "what's this image's color story" - the warmth, and the structure.