kubakub mask field

What it's for

A mask is on-or-off. A building isn't. You want a wave to set off at one corner of the facade and arrive at the other end two seconds later, window by window - and for that, every pixel needs a position along the path, not a binary.

That's what this node produces. It turns your regions into a grey ramp: black where the move starts, white where it ends. Feed the ramp to kubakub mask animate and a reveal, a band or rings run along it. The docs put it well - this is the vector field, that node is the thing travelling on it.

It also stands alone. As a soft mask it's a better feather than a blur, because the gradient follows the architecture rather than the image: it's 0 on the edge of a window and 1 at its deepest point, so an iris-opening window is a real visual rather than a blurred blob. Or export it and use it as a time-offset map in After Effects, Houdini or TouchDesigner - the same trick escapes ComfyUI happily.

How it works

Five field types, and picking the right one is 90% of using this node:

• edge distance - black on the edge of a region, white at its deepest point. A reveal along it closes from the outline to the middle (invert to grow outward from the middle). This is the one that makes windows look like they're filling up.
• direction - black to white along angle, 0 = left to right, 90 = top to bottom, 180 = right to left. A wipe.
• radial - black at a centre you place with centre_x/centre_y, white furthest out. An iris.
• region order - one flat grey per region, sequenced by order: left, right, top, bottom, centre (middle out), outside (inward), size (biggest first), random. This is the "one more window per beat" machine when it's driven by a beat curve.
• noise - soft random greys, every grey used about equally often. A dissolve that looks hand-made.

per decides whether the ramp is local or global. each region gives every region its own black-to-white run, so all windows open simultaneously. all together makes one ramp across the whole facade, which is what turns the same reveal into a single wipe. per has no effect on region order and noise, which are already discrete or random.

select filters by name in the region plan's syntax: W_F1_*, group:Windows, tag:front, comma for or, space for and, ! for not. Same syntax the region plan and the samplers use, so one vocabulary across the pack.

Inputs and outputs

• regions - from any kubakub regions node. Connect nothing at all (and no mask) and it uses the windows of the sample facade, so you can play with it before you own a facade.
• mask (optional) - regions from a mask batch instead, one region per mask, or per separate shape with split_shapes (on by default).
• select, field, per, angle, order, centre_x/centre_y, noise_px, seed, invert - the shape of the ramp, as above.

Outputs: field - the 0-1 ramp inside the regions, 0 outside, also drawn on the node; mask - 1 on the regions the field covers, which is the one you wire into mask animate's mask input; report - region count, size, and what it fell back to when you connected nothing.

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+, OpenCV as the only added dependency (keep yours if you have one). No models needed - this is pure array work. It arrived in pack version 0.3.0 along with mask animate, and needs no new packages.

Common issues

• The reveal runs the wrong way. invert. Both field and animate have their own; changing one may be all you need.
• All the windows behave identically when you wanted a sweep. That's per: switch to all together for one ramp across the building.
• select matched nothing. The report says so. It's almost always a name that isn't in your region table - check regions_json rather than guessing at the naming.
• The ramp is too abrupt inside a window. Blend it: the field output is a mask, so Blur or a soft combine before mask animate widens the transition without changing where the move starts and ends.