kubakub frame guide (old)

What it's for

This is the original "make the windows into openings" node, and its own display name says (old). It lives in the pack's lab group for a reason.

What it does is still worth understanding, because the idea is the good part: give a region a depth in metres, and it stops being a flat mask and becomes a frame seen from where the audience stands. Positive depth is a room or world behind the frame - the facade hides everything outside the opening, and a window's mullions stay in front of it. Negative depth is a "parasite" sticking out of the facade toward the viewer. The node draws the side walls (shaded) and the back or front faces in that perspective and hands you the masks and the quads.

If you're starting now, use kubakub frame in frame instead. Same core idea, but it also does media corner-pinning, a shared world behind the facade, parasite shadows, and it emits plan entries and a generate mask so the region sampler knows what to paint. This node gives you the guide and the masks and stops there. It's kept for workflows that already use it.

How it works

Depth comes from a small text field, depth_rules, not from a per-region setting in a plan:

'<name wildcard> = metres', 'group:<g> = m', 'tag:<t> = m'

Later lines win, so you can set a default for the whole facade and then override specific floors. default_depth_m (0) catches regions no rule names - and 0 means "not a frame", so an unset facade produces nothing rather than nonsense. Negative metres put the piece in front of the wall.

Two more behaviours worth knowing:

• dim (0.55) darkens the matrix outside the frames. That's for looking - a quick previz where the openings read clearly. Set it to 0 when the guide is the input to a generation, because you want the facade to stay exactly as it is and only the new geometry to be added.
• window_hull (on) treats a multi-pane window as one opening so the gaps between panes - the mullions - stay in front. Off, only the largest part of a region becomes the frame.

Inputs and outputs

• regions - the facade partition, same size as the viewer's matrix.
• viewer - from kubakub audience viewpoint. Required in practice: without a viewpoint you have no perspective to draw.
• depth_rules - the rules above, empty by default.
• default_depth_m, dim, window_hull.
• matrix (optional) - the background of the guide, dimmed by dim.

Outputs: guide (the dimmed matrix with frames drawn as the viewer sees them), area (pixels generation may change - the opening for rooms, frame plus walls plus front face for parasites), back (back faces of rooms and front faces of parasites), walls (side walls), frames_json (per frame: depth, scale, outline, and the back_quad corner pin), and report (the frames with their depth and scale).

That back_quad is the useful plumbing if you're placing media yourself: it's the shape your image has to be warped into to sit flat on the back wall.

Install

Manager → kubakub nodes → install → restart. Manual:

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

ComfyUI 0.37.0 or newer; opencv-python-headless is the only package it adds (keep an existing OpenCV build if you have one). It's in the lab group of the node menu, so it's one of the ones a kubakub.ini with lab = off will hide - and a hidden node shows up as missing in any workflow that uses it, with the console line telling you what was hidden.

Common issues

• You can't find it in the menu. Search kubakub frame guide, or check kubakub.ini - the lab group is the first thing people switch off.
• "It's marked old, is it dead?" Not dead, superseded. It still runs; it just doesn't get the newer work (media, world, shadows, plan entries).
• The generated result kept the dimmed background. dim was left at 0.55 when the guide was fed to a generation. Set it to 0 for that use.
• Nothing got a frame. default_depth_m is 0 and your depth_rules don't match the region names. Copy the names out of regions_json - guessing at naming is the usual cause.