kubakub scene measure

A projector doesn't care about your image. It cares about distance and angle. Point one at a facade and the parts near it and square-on get blasted, the parts 30 m away and turned away are dim, and every sill and ledge sits there at 40% of the brightness of the wall next to it - because the light hits it at a grazing angle. You can't see any of that in your content file. kubakub scene measure tells you, per pixel and per region, in real units.

This is the analytics node of the 3D half, and it's the one you run right after kubakub scene render when something downstream looks wrong. It takes the scene and answers questions with numbers: how far is the projector from each surface, how square-on is the hit, how big is one matrix pixel on the stone, how bright does this patch end up relative to a typical square-on wall, how far does the facade stick out from the main plane.

The inputs you set

viewer_x_m, viewer_distance_m and eye_height_m place the audience: metres along the wall from the projector frame's centre, metres out from the main wall, and eye height. Defaults put someone 15 m out at standing height, which is a reasonable front row.

map chooses which measurement the colour map output shows: brightness, distance to the projector, incidence angle, mm per matrix pixel, or offset from the main wall. brightness is the one to look at first - it's cos(incidence) / distance², normalised so 1.0 is a typical square-on facade. Watch the window reveals and the undersides of cornices come out as dark bands. That's not a bug in the render; that's your projection.

grazing_deg (default 60) is the threshold for tagging. Any region hit at a steeper angle than this gets tagged grazing, which you can then select in a region plan with tag:grazing and treat differently - admit it's going to be dim, or push the content there harder.

Optionally connect regions at the projection view's size (for example from kubakub regions from id renders with the clay as matrix) and they come back with the measurements attached, plus the grazing tag.

Outputs, and what they're for

• regions - your regions with a scene entry each (distance, offset, incidence, mm per px, brightness, area, viewer distance) and the grazing tag. Straight into the region plan and the sampler. Note: if you didn't connect regions, this output is empty. Leave it dangling rather than puzzling over it.
• viewer - a viewpoint built from the projector frame on the wall (real facade width and bottom edge) plus your audience spot. Wire it into viewer on kubakub scene preview, kubakub scene relight, kubakub pieces render and the audience-viewpoint node, and every node agrees on where the audience is standing instead of you retyping three numbers in four places.
• map - the chosen measurement as a colour map. Screenshot material for a client deck.
• raw - the same measurement as a plain grey mask: 0 = the lowest value in the range, 1 = the highest, and 0 outside the building. The report tells you what 0 and 1 mean in real units (metres, degrees, mm). That's the output that makes the numbers usable rather than just readable - feed it as a mask into brightness compensation, or use it as a driver for how much detail you push into the far half of the wall.
• table - tab-separated, per region: distance, offset, incidence, mm per px, brightness, area, viewer distance.
• report - projector frame on the wall in metres, median measurements, where the viewer is, and the map's colour range.

On the pack's test facade (33 m out, camera at ground level) the frame lands at 33.35 × 22.51 m, works out to about 11 mm per matrix pixel, with incidence running from 3° to 83°. Those are the numbers people are surprised by: 11 mm per pixel at 3200 px wide, which is why the whole pack takes pixel size seriously and why kubakub mesh to relief field and kubakub mosaic grid from camera both exist to keep that ratio honest.

Install

It's part of the pack, but it can't run without the 3D path working, so:

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

You need Blender 4.x installed for kubakub scene render upstream (this node itself is numpy - the geometry comes from the scene render's cached passes). If Blender isn't found, scene render is where you'll see it, not here.

Traps

The measurement is only as real as the model. If your .fbx came out of Cinema 4D in centimetres, unit_scale on scene render has to fix it first - scene render's report warns when a model is under 2 m or over 2 km, and if you ignore that warning every number here is off by a factor of 100 and looks superficially plausible.

Also: grazing is a tag on the region, not a fix. Tagging a sill grazing doesn't make it brighter. Take the tag through to the plan - a rule that puts higher-contrast content on grazing regions, or simply that keeps flat pattern there instead of fine detail, is what turns the measurement into a decision.