CV Split Tuple

CV Tuple packs components into one composite value so they can travel down a single wire. CV Split Tuple is the reverse: one composite in, four components out, so the number inside can drive a plain INT or FLOAT socket.

That's the whole job, and it's the kind of job the KB's plumbing doc files under "these nodes exist to fight repetition and illegibility". A size, a point, a box - each is one concept, and each is several numbers. This node is the boundary where the concept becomes numbers again.

What it takes

tuple - the composite value. Two types are accepted and both matter:

• CV_TUPLE - anything from CV Tuple, or any cv2 node's point or size output.
• BOUNDING_BOX - a cv2 Rect, which reads as x, y, width, height.

That second one is worth pausing on. It means a detection box can drive four normal sockets directly - width into a maths node, y into a crop offset - without a conversion dance. Box data in this ecosystem is core-typed (the same BOUNDING_BOX a PrimitiveBoundingBox emits), so being able to unpack it here makes the CV pack a participant in the core crop/paste plumbing rather than a silo.

dtype - int truncates, float preserves fractions. Same choice as CV Split Point, same consequence: right for pixel indices, wrong-but-survivable for subpixel work.

What comes out

Four outputs and a count:

• a, b, c, d - first through fourth components, typed *.
• count - how many components the value actually carried.

And the rule that makes it safe: components past the value's own length come out as 0. Feed it a two-component point and you get a, b populated, c = 0, d = 0, count = 2. No error, no crash, and count tells you whether the zeros are "the value was short" or "the value really was zero". Use that flag if the distinction matters - it usually does, because a 0 width silently reaching a crop node is a much more annoying bug than an exception would have been.

Why this shape, and where it goes

Sizes and points are the pack's lingua franca. A cv2 call returns a Size, an (N,4) detection table has rows, a bounding box has four numbers - all of it is "several numbers that mean one thing", and all of it eventually needs to be individual numbers to drive a widget-converted socket, a Math Expression, a loop bound, or a crop.

Two practical destinations. First, arithmetic: unpack a size, feed b and a into something that computes an aspect ratio, use the result to branch. Second, probing: a and b from a box or point feed CV Select Component At Point's x and y, with dtype = float if the source was subpixel.

The KB's plumbing doc's point applies here too - the value-in-a-widget versus value-on-a-wire distinction. Anything you unpack into a socket now has one authoritative source in the graph instead of four numbers maintained by hand. That's less about features and more about whether your graph survives being edited next month.

Install

ComfyUI Manager → ComfyUI CV → install → restart. Manual:

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

Python ≥ 3.12, recent ComfyUI on the V3 node API. Nothing to download; it's a data-plumbing node from image/CV/low-level.

Common issues

• c and d are always 0. Your value is two-component. Check count; if you expected four, the packing node upstream took a different shape than you assumed.
• Fractions disappeared. dtype is on int. Switch to float.
• A point needs only x and y. CV Split Point is the two-output version and it also accepts the older "(30, 12)" string form of a point output.
• Contrib nodes missing after installing an unrelated pack. Non-contrib OpenCV wheel overwriting the contrib one in the shared site-packages/cv2. python tools/repair_opencv_contrib.py --check, then --apply.