cv2.compareHist

What it's for

cv2.compareHist takes two histograms and returns one number describing how similar they are. That's a colour- or tone-similarity metric with no model attached: "did the palette drift between these two shots?", "have these two frames broken away from each other?", "is this batch colour-consistent with the reference?"

The catch that stops most people is that histograms are not images. This node's sockets accept NPARRAY only - the author's tooltip says it outright: "A data array (points / matrix), NOT an image - only an NPARRAY link is accepted here." So this node sits in the middle of a small data pipeline, not on the IMAGE wire. It's a raw wrapper from ComfyUI CV (bmad4ever/comfyui_cv), category image/CV/low-level/cv2 C.

How it works, and the one thing to get right

A histogram is a vector of bin counts. compareHist applies a distance/divergence measure between two equal-length vectors and hands back the scalar in a FLOAT output named float.

The score only means something once you know the direction. This is the trap. The methods are not all "bigger = more similar":

| Method | Identical histograms give | Read it as | | --- | --- | --- | | HISTCMP_CORREL | 1.0 | higher = more similar | | HISTCMP_INTERSECT | maximal (unbounded) | higher = more overlap | | HISTCMP_BHATTACHARYYA | 0.0 | lower = more similar | | HISTCMP_CHISQR / HISTCMP_CHISQR_ALT | 0.0 | lower = more similar | | HISTCMP_KL_DIV | 0.0 | lower = more similar |

Set a threshold on Chi-square while thinking "score goes up" and you will select precisely the frames you meant to reject. Pick one method, note its direction, and stick to it.

Inputs and outputs that matter

Three required inputs, one output:

• H1 - first histogram, NPARRAY.
• H2 - second histogram, same size as H1. Different bin counts is not an error you get told about nicely - match them yourself.
• method - the measure, defaulting to HISTCMP_CORREL.
• float - the score. Wire it to a display/note node, compare it with a PrimitiveFloat, or use it as the branch condition in a logic chain. It's a plain FLOAT, so anything that takes a number will take it.

Get the histograms from the curated CV Histogram node in this same pack (calcHist with named channels and ranges) - that's the intended upstream neighbour, and it's the difference between "this works" and "how do I even make a histogram in ComfyUI". CV Back Project is the same family if you want the back-projected mask instead of a scalar.

Installing the pack

Manager → search ComfyUI CV, or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/bmad4ever/comfyui_cv

Restart. Requirements: Python ≥ 3.12, a ComfyUI built on the V3 node API, and opencv-contrib-python-headless~=5.0.0.93.

Where people get burned

• Feeding it images. The socket type makes this hard to do by accident, which is good - an IMAGE wire simply won't connect. If your histogram-looking thing is actually a greyscale image, it needs to go through CV Histogram first.
• Comparing histograms built with different settings. Same bins, same channel subset, same value range, or the number is noise. A 32-bin and a 256-bin histogram are not comparable even when they look alike.
• Flat histograms and HISTCMP_CORREL. Correlation divides by the variance, and a constant vector has none. Expect a NaN rather than a helpful error. If a frame is a solid colour, handle it before it reaches this node.
• Nobody has done this for you. The pack - like the operation itself - has essentially no community footprint: a corpus search for the pack name returns nothing, and this kind of utility node never generates threads, only silent use. The README's own caveats apply and are worth reading once: LLM-assisted code, self-declared overfitting risk, no planned updates, "not recommended for production" without independent review. The one failure that hits hard is at install time - the cv2 namespace is shared by all OpenCV wheels, so a plain opencv-python install over your contrib build empties the contrib submodules. tools/repair_opencv_contrib.py --check in the repo diagnoses it.