cv2.eigen

Eigen decomposition, as a node. It takes a square symmetric matrix and hands back its eigenvalues and eigenvectors. If that sounds like a detour from images, here's the image-flavoured version: build the 2×2 covariance matrix of a set of points, decompose it, and the eigenvector with the largest eigenvalue is the principal axis of those points. That's the direction they're stretched in - the thing fitEllipse gives you as an angle, but available for any point set and justified by the data rather than fit to an outline.

What it needs

src is a NPARRAY - a matrix, not an image, and the tooltip says so. It must be CV_32FC1 or CV_64FC1, square, and symmetric. Get the type wrong and OpenCV asserts; get the symmetry wrong and it silently uses one triangle of your matrix, so a mistyped covariance matrix doesn't error, it just gives you a wrong answer. That's the failure mode to watch.

Three outputs:

• retval, a boolean - OpenCV's own return value for the call. Branch on it before you build anything on the numbers.
• eigenvalues - a column vector in descending order. I checked it on a symmetric 2×2: the larger eigenvalue comes first, every time.
• eigenvectors - a matrix whose rows are the eigenvectors, in the same order.

Getting a matrix in and the answer out

The pack has the plumbing for this, which is most of the reason the node is usable at all from a graph UI. Parse Matrix turns delimited text into a 2-D array. CV Scalar builds a constant vector. CV Points gives you a point array, and cv2_calcCovarMatrix (a raw wrapper too) turns a sample set into covariances. Then CV Array To Text prints the result as a table, or Preview CV Array shows it as an image if that's less confusing than numbers.

As a concrete chain: points → cv2.calcCovarMatrix → its covariance output → cv2.eigen → the eigenvalues tell you the spread along each axis, the top eigenvector tells you which way they're orientated. Add atan2 on the eigenvector components and you have the principal angle, computed rather than fitted.

Honest expectations

This is a maths accessory in an image pack, and you should treat it as one. It's not a fast path to anything visual on its own - nothing about a diffusion pipeline needs it - but the class of problems it solves ("what are this data's axes", "which direction matters most", "is this configuration stable") comes up the moment you start measuring geometry instead of looking at pixels. The pack has similar corners: cv2.SVDecomp, the moments nodes, the ellipse fits. Between them they're the measurement layer.

Two ordering notes worth memorising, because they're the kind of detail that produces a plausible-looking wrong result: eigenvalues are descending, and eigenvectors are rows, not columns. Most textbook presentations use the other convention for at least one of those.

Installing the pack

One of ~470 auto-generated raw cv2.* wrappers in bmad4ever/comfyui_cv, a GPL-3.0 fork of Gerold Meisinger's opencv-comfyui with a curated node layer on top. Manager: search ComfyUI CV. Or:

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

Then restart. Python ≥ 3.12 and a recent ComfyUI on the V3 node API; the only dependency is opencv-contrib-python-headless~=5.0.0.93. Keep the contrib build - all four OpenCV distributions share one site-packages/cv2 and the last installed wins, so a later plain opencv-python silently removes the contrib submodules and their nodes. tools/repair_opencv_contrib.py --check / --apply is the pack's own repair tool.

Common issues

(-215:Assertion failed) type == CV_32F || type == CV_64F. Integer matrix. Cast to float32 or float64 first - this one I checked, and uint8 fails immediately.

Nonsense eigenvalues. Your matrix isn't symmetric, and OpenCV used one triangle without complaining. Symmetrise it (average the matrix with its transpose) or use cv2.eigenNonSymmetric.

Shapes look rotated. Eigenvectors are rows. If you expected columns, transpose.

Empty output. The matrix workflow upstream failed - check Preview CV Array on the input before you debug this node.