kubakub project settings

Projection mapping has one property that pure image generation doesn't: the output has a size in the real world. 3840 pixels is 40 metres. Which means the things you'd normally never think about - how many millimetres of stone one pixel covers, how high the bottom edge sits above the pavement, where the audience stands - are actual parameters of the show, and every downstream node wants them.

kubakub project settings is where you type them once. It's the least glamorous node in the pack and probably the one that saves the most time.

What it holds

name is the project name - export folders and filenames use it, and it's sanitised so a stray slash doesn't ruin your evening. preset picks the matrix size (uhd 3840x2160 by default, or custom and then you set width and height yourself). Connect a matrix image to the optional input and its size wins over everything - which is the right behaviour when you've just been handed the festival's template PNG and don't want to read numbers off it.

fps is the show's frame rate and accepts decimals, so 29.97 works.

Then the physical setup:

• facade_width_m - the real width of the whole matrix on the building. This is the number that turns your render into architecture. Get it wrong and every metre-based effect in the pack is wrong too: the wave speed in pieces falloff, the throw distance in projector, the millimetre size of your pixels.
• bottom_m - how high the bottom edge of the matrix sits above the ground people stand on. Zero is a wall that starts at the pavement.
• viewer_x_m - audience position along the facade from its left edge; -1 means centre. eye_height_m is 1.7 by default (a standing adult, and yes, that's the number to change if the show plays to a seated or a standing crowd). distance_m is how far back they are.

The outputs, and the one that matters

width, height, fps and name are the four you link everywhere - into scene render or the walkthrough's size, into an export node's fps, into the video sampler or keyframe clips, into frame in frame's viewer. viewer is a KUBA_VIEWER: the audience spot as a single object, identical to what kubakub audience viewpoint and kubakub scene measure produce. Connect it to scene preview, scene relight or pieces render and the camera you set here is used everywhere, instead of you retyping three numbers in four nodes and getting them subtly different.

facade_width_m comes back out so it can be chained. And mm_per_px is the number to actually look at: facade width in millimetres divided by matrix width in pixels. It's a one-line sanity check on whether your content will read. At 40 m across a 3840-pixel matrix you're at roughly 10 mm per pixel; the ornate window detail you built at two pixels wide is two centimetres of stone, and nobody in the crowd will ever see it. report gives you the same thing as text: size, fps, millimetres per pixel, and where the audience ended up.

Install

Manager → search kubakub nodes → install → restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/kubakubkub/ComfyUI_KubaNodes
python -m pip install -r ComfyUI_KubaNodes/requirements.txt

Registry users can also comfy node install comfyui-kubanodes. The pip line only adds OpenCV, and this node belongs to the project group, which needs nothing else - no Blender, no models. It's one of the nodes that works on a plain ComfyUI.

Practical notes

This node is a settings object, not a computation. Nothing renders here, so it costs nothing to change and re-queue. Which is the argument for actually using it: the alternative is five nodes each holding their own copy of "40 metres", three of which you updated.

Fill it in before the 3D, not after. If your facade is 40 m and you discover that at the end, every projector distance, throw ratio and metre-per-second speed you tuned is off by a factor you'll have to redo. The pack's 3D sample model is in metres precisely so this all lines up.

A connected matrix overriding your preset confuses people once. If width and height don't seem to do anything, there's an image on the matrix input. That's intentional - the template decides.

A last piece of context that's worth knowing if you're new to this corner: projection mapping with diffusion models isn't hypothetical. The well-documented example is a 2023 show in Kortrijk that used SDXL plus ControlNet to make 200 final images from 1500 generated ones, four projectors, MadMapper for the mapping. The AI was never the interesting part - the mapping was. That's the gap this pack is aimed at, and this node is where you declare the physical facts of it.