CV 3D Object Transform

Here's a specific, ugly problem in augmented-reality-style ComfyUI graphs. You have a 3-D model, and you want it in two places at once:

• Rendered over your photo or calibration target, by CV Preview 3D (Calibrated Camera), which takes an object_transform JSON string.
• Tracked, meaning the actual geometry moved into the scene, by CV Transform Points 3D with a 4×4 matrix - and the same placement has to drive CV Rapid Track, PPF, ICP, CV Rasterize Mesh.

Those two lanes live in different coordinate systems. The viewer is Three.js (Y up). OpenCV is Y down. So if you type the numbers in twice, you get a render and a tracker that disagree about where the object is, and the debugging is miserable because both look individually plausible.

This node is one set of numbers, two outputs, conversion handled.

The distinction the node is careful about

space - OpenCV (Y down, Z into the scene) or glTF / Three.js (Y up) - declares which convention your numbers are written in, and it should match CV Mesh From 3D Model's axis_convention. It is not a switch that moves the model. The two spaces are the same scene under a 180° roll about X, so typing y/z with the opposite sign in the other space gives an identical result. Flipping space alone therefore does move the model, but only because you changed the meaning of the numbers you typed - it's a promise, not an action. If you want the model to turn, use model_up and the rotations.

model_up is the action, and it's the dropdown that replaces the rotate_x_deg = -90 people type by hand in AR workflows: leave as the file has it, +Y is up (glTF / most GLB exports), +Z is up (Blender / CAD / OBJ). Note what "up" means here - it's the target plane's normal, OpenCV +Z, since the markers lie in its XY plane, not +Y. A stock +Y-up GLB arrives lying flat across the board, which is exactly why this widget exists. It's applied before your rotate_* values so those stay a free nudge on top.

The rest is a placement: position_x/y/z (same units as the mesh and the camera pose - metres if your calibration is), rotate_x_deg / rotate_y_deg / rotate_z_deg (each ±360, about the mesh origin - use recenter on CV Mesh From 3D Model if you want to spin about the object's own centre), and scale, which reconciles authoring units with the calibration. Rotation order is Rz·Ry·Rx, matching the pack's "CV Transform Points (Scale, Rotate, Translate)" blueprint.

Outputs

• object_transform - the JSON string for CV Preview 3D (Calibrated Camera)'s object_transform input: position, quaternion [x, y, z, w], scale, in Three.js world space. Convert that widget to an input and wire this in; the viewer's gizmo then only previews, because this value wins on the next run.
• matrix - the same placement as a 4×4 float64 model matrix, in the selected space. Feed it to CV Transform Points 3D to move the mesh, annotation anchors, or a cloud exactly as the render moved it.

CV Parse Object Transform is the return leg: read a placement dragged out with the viewer's gizmo back into a 4×4.

Install

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

Manager → ComfyUI CV. Restart and reload. Python ≥ 3.12, V3-API ComfyUI, opencv-contrib-python-headless~=5.0.0.93. No models needed for this node itself - though the workflow around it will want a GLB and a calibration.

Common issues

The render and the tracker disagreeing. Almost always space not matching the mesh's axis_convention. They're a pair; the tooltips say so and it's the one thing to check first.

An object at the right bearing and the wrong depth. A scale mismatch between authoring units and the calibration. A centimetre-authorised model against a metre calibration wants scale = 0.01, and the failure mode is directional rather than obvious.

A model standing on its side. model_up. Blender and CAD exports are usually +Z up; GLB is usually +Y up; a few are authored to stand already and want the default.

A gizmo drag that doesn't stick. By design. Once object_transform is wired from this node, the string wins every run - the gizmo becomes a preview. Use CV Parse Object Transform if you want the drag to become data.