kubakub region sampler

Here's the thing nobody tells you about generating a building: a diffusion model is bad at it. Ask Flux or Qwen for "a facade with 40 windows" and you get a painting of a facade, with windows that don't line up, don't match each other, and don't correspond to the actual stonework you're projecting onto. Projection mapping doesn't want a painting of a facade. It wants this facade, with the windows replaced.

kubakub region sampler does that. It takes a plan (from kubakub region plan) and a canvas exactly the size of your regions, and runs the model region by region, pasting each result back into its own mask. Everything outside the regions is untouched - not re-encoded, not gently degraded by a VAE round trip, untouched. That guarantee is the entire product, and it's the same one the Inpaint Crop-and-Stitch pattern won the community over with.

How it actually works, per region

This is worth understanding because it explains the settings:

1. It takes a box around the region plus context_px (64 target pixels by default) so the model can see what it's attached to.
2. That box is scaled uniformly and exactly to roughly region_mp megapixels (1 by default), snapped to whole 16-pixel blocks, and capped at max_upscale (4) for small regions. A 270×310 window box becomes ~864×992. A whole-floor wall gets scaled down. Nothing is stretched, ever - the pack treats non-uniform scaling as a bug.
3. The mask is the region grown by the plan's dilate_px, and the crop's own latent goes in as a reference latent (reference = self in the plan).
4. Flux 2 gets sampled with core's Flux2Scheduler sigmas for the crop size. Denoise works like a normal KSampler.
5. The result is scaled back by the exact inverse, colour matched to the original crop (color_match: none, mean_std, mkl), and pasted with a feather_px soft edge that can never reach outside the mask or the scope.

Then the canvas updates, so later regions see earlier ones. That's what stops a floor of windows looking like it was assembled from forty unrelated images - window 39 was inpainted into an image where windows 1–38 already exist.

The single biggest creative lever is reference in the plan. self (default) keeps the structure that's already there, so Klein behaves like an editor - perfect for materials, weathering, stone repair. none lets the region be freely repainted, which is what you want for turning a dark window into a lit room. And with none, denoise matters enormously; with self, much less.

The inputs you'll actually set

model, clip, vae (Flux 2 Klein 4B or 9B is auto-detected; Qwen Image 2.1 too - adapter on auto does it, and there's a generic path for everything else). plan and image.

Then steps and cfg, both defaulting to 0, which means "use the model's default" - Klein 4 steps at CFG 1, Qwen Image 2.1 at 25. Someone who knows Klein will tell you to try 8 steps and CFG 1.2–1.5 when anatomy or texture starts going wrong; that advice applies here too, per region. sampler_name is euler and scheduler only matters for generic models, because Flux 2 always brings its own schedule.

region_mp is the work resolution per region crop, and it's the main quality/speed dial. max_upscale stops a tiny cornice detail from being blown up 8× into invented nonsense. schedule has two special values worth knowing: qwen21_turbo_5 and pruna_qwen21_8 are the trained step schedules of two Qwen Image 2.1 LoRAs, and with those loaded the node starts partial denoise at the matching step. seed_offset is how you ask for "the same plan, different take" across every region at once.

Two optional inputs earn their keep. only takes the same selector syntax as the plan (group:Windows, W_F1_*, !W_F1_*) and processes just those - how you iterate on one floor instead of the whole building. style is a style image, used by regions whose plan says reference = style.

Outputs and the cache

image is the canvas with every processed region pasted in. changed is a mask of where pixels were actually replaced - wire that into kubakub seam pass so only the new material gets harmonised. report gives you the model, cache usage, timing and one line per region.

The cache is the feature that makes this usable. Results are held in RAM, keyed on the crop pixels, masks, prompt, seed, settings and models. Change one prompt and only that region re-samples - plus any later regions whose crops overlap it, because they saw the old pixels. Default budget is region_cache_mb = 4096 and cond_cache_mb = 2048 in kubakub.ini; 0 turns it off, which you should not do.

Install

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

Manager → kubakub nodes, or comfy node install comfyui-kubanodes. ComfyUI 0.37.0+; OpenCV is the only added package. You need an image model - the sample workflow uses Klein 4B, the smallest option, per the pack's docs/MODELS.md. Any quantisation works: bf16, fp8, int8, NVFP4, GGUF, pick your file in the loader.

Where it goes wrong

The canvas must be exactly the size of the regions. Not roughly. This node never resizes to fit, and a mismatch is the difference between a paste and a smear.

Overlapping regions, one going the wrong way. Regions are processed in plan order (order = largest_first by default), and overlap means the later one wins in its own mask. If your wall region runs after your window regions, it will repaint over them. That's what order is for. And the cache includes the model, so loading a different LoRA strength invalidates everything.