cv2.trace

The trace of a matrix is the sum of its main diagonal, which sounds like a trivia answer and is actually one of the cheapest sanity checks in linear algebra. Trace equals the sum of the eigenvalues - so for a covariance or Hessian, trace divided by the dimension is the mean eigenvalue, i.e. how much total "energy" the matrix has, in one number. For a rotation matrix, the trace has to land in [-1, 3], and a trace of 3 means identity. For a homography, a wildly wrong trace tells you the fit went sideways before you spend an hour feeding it into a warp.

cv2.trace gives you that number. It's a diagnostic node in a pack of mostly-doers, and the diagnostic nodes are worth having when you're debugging a matrix pipeline.

One of roughly 470 auto-generated raw cv2.* wrappers in ComfyUI CV (bmad4ever/comfyui_cv) - uncurated, LLM-generated, per the author's own warning.

Inputs and outputs

mtx is NPARRAY-only, and the tooltip says the thing that matters: "a data array (points / matrix), NOT an image - only an NPARRAY link is accepted here". So no IMAGE socket, no MASK, no automatic conversion. Produce the matrix with Parse Matrix (paste a table), CV Matrix Multiply, CV Eye, CV Pose To Matrix, CV Camera Matrix, a decomposition, or anything else in the pack's array half.

The single output is called trace, and its type is a STRING holding a cv2 Scalar in the pack's literal spelling, "(c0, c1, c2, c3)" - one value per channel, matching what every colour and borderValue input accepts. For a single-channel matrix, the first component is your trace and the rest are zeros.

That string type is the node's main limitation and it's deliberate: a Scalar is up to four numbers, so handing it to a numeric socket would be lying about the shape. To actually read it, wire it into Inspect CV Data, or use a text show node. To use the value in arithmetic, get it as numbers with CV Array To Numbers on the matrix itself, or compute the diagonal sum in the array nodes - this one is for looking, not for math.

What it's good for

Three checks I'd actually run:

Is this rotation valid? Trace of a real rotation matrix is 1 + 2·cos(θ), so it lives between -1 and 3. Anything outside that range means the matrix isn't a rotation - usually a scale got mixed in somewhere, or a decomposition returned the triangular factor and got read as the rotation (a confusion the pack's own matrix-decomposition workflow calls out by name, because OpenCV's RQDecomp3x3 names its upper-triangular factor R).

How much energy is in this covariance? Decompose with cv2.SVDecomp and you'd read the eigenvalues directly; use the trace and you get their sum for free without the decomposition.

Did this fit blow up? A homography or essential matrix recovered from bad correspondences tends to have an absurd trace. One node, one number, and you know whether the rest of the graph is worth running.

Installing the pack

cd ComfyUI/custom_nodes
git clone https://github.com/bmad4ever/comfyui_cv
cd comfyui_cv && pip install "opencv-contrib-python-headless~=5.0.0.93"

Manager → search ComfyUI CV → install → restart also works. Python ≥ 3.12 and a ComfyUI with the V3 node API, or these nodes don't exist in your install. The OpenCV wheel must be contrib: all four distributions share one site-packages/cv2, so installing plain opencv-python over the contrib build empties the contrib submodules - tools/repair_opencv_contrib.py --check then --apply is the repair path. Curated against 5.0.0.93, and support isn't promised.

Watch out for

Trying to link an IMAGE into mtx - it's an array socket by design. Expecting a FLOAT out: it's a Scalar literal string, and if you need the number in a comparison you have to get it as numbers elsewhere. And remembering that for a multi-channel array cv2 returns a per-channel Scalar, so a 3-channel trace gives you three values and reading only the first one is your choice, not the node's.