kubakub mosaic illusion

Most "mosaic" filters blur an image and stamp a grid on top. The result looks like what it is: a picture with a grid over it. kubakub mosaic illusion does the real thing - it cuts a photo of actual material into tiles and then picks or shades each tile so that a target picture emerges when you step back. Up close it's stone. From the street it's a face. That's the whole trick, and it's the reason this one lives in the pack's lab group rather than in post-processing: it's a physical illusion for projection work, not a filter.

The two inputs

texture is the material photo - stone, bricks, glazed tiles - and it sets the output size. A batch gives you one mosaic per material image, which is how you test three stone samples in one queue.

target is the picture hidden in the mosaic. Only its brightness matters, which is the key constraint: you're not transferring colour, you're steering each tile's value along the material's own range. If your target only reads in colour, desaturate it yourself and check it still works before you queue.

mode is the important choice

mode has four settings, and they are genuinely different tools, not strengths of one thing:

• select is the mosaicist's method, and the default. It builds a palette from the texture itself and, for each cell, picks the tile whose value the target needs. Nothing is tinted, nothing is invented - every cell is a real piece of the material. palette_size (default 12) is how many colours are on the tray, dither breaks the banding at the edges of the hidden shape, and level_radius (default 6 tiles) shifts a whole neighbourhood's level so more of the original pattern survives. This is the mode you use when the material has to look untouched.
• multiply darkens and brightens the tiles towards the target. Uniform and forgiving, and it works with any texture.
• mix blends each tile toward the target's grey.
• lift only brightens - the one to use with a dark material where you can't go down any further.

strength (default 0.55) is the readability of the hidden picture: 0 is material only, 1 is the target plainly readable. The tooltip is worth noting because it's a workflow, not just a parameter - animate it to move the resolving distance. Ramping strength over frames is how the picture appears as the audience walks closer, which is a much better effect than a static mosaic.

quantise_texture (on by default) flattens each tile to one colour. Turn it off when the texture is already a tiled photo - otherwise you flatten it twice and it goes muddy.

tile_px is the tile size in pixels; with adaptive on it becomes the largest tile. And that's the pair to take seriously: with adaptive, a quadtree splits cells where the motif has detail and leaves them big where it's flat, controlled by min_tile_px, detail (how much the motif must change before a cell splits) and max_depth. On a real facade the adaptive grid is what makes the motif read at a low tile count.

The craft knobs

The defaults here are geometry. mortar (0 = none) and mortar_value draw the joints on the real cell outlines, so they work with either grid type. edge_noise and edge_scale roughen the tile outlines - 0.10 to 0.20 with a small edge_scale looks hand-cut, chipped; a large edge_scale is wobbly, like old render. jitter randomly shifts each tile's target value so the picture looks less mechanical. seed ties all of it down: same seed, same mosaic.

On the target side, target_fit (cover / contain / stretch), target_autocrop (trims a dark border so a cutout fills the frame), target_autolevels (stretches levels to full black-to-white so a flat photo still reads), target_blur (default 6; soften so the image emerges instead of stamping a silhouette), target_invert and contrast are the prep. Autolevels and blur are doing real work - turn them off and your first attempts will look like a silhouette pasted onto bricks.

Outputs: image (the mosaic), tile_values (the grey value each tile was asked for - the target as the tiles see it, which is how you debug "why doesn't the face read"), and grid (white tiles, black borders). Look at tile_values when the result disappoints; it tells you instantly whether the target had enough contrast to survive quantisation.

Install

Part of the pack:

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

No model, no Blender, no extra dependency - this one is torch tensors all the way down, so it runs on CPU as happily as on GPU.

Two things to know before you spend an evening on it

Get the tile size from the building, not from the screen. kubakub mosaic grid from camera exists exactly for this: give it the real facade width, the real width of one stone and your render width, and it hands back the tile_px that makes the grid land on actual material. Eyeballing it gives you a grid that's 40% too fine and a mosaic that reads as texture, not as mosaic.

Palette size sets the ceiling on the illusion. In select mode you're quantising to the material's own values, so 8 colours on a light stone gives you 8 levels for the whole picture. That's plenty for a strong graphic and nowhere near enough for a photograph. Use tile_values to find out which one you've got - and reach for a darker material or a higher contrast before you reach for more tiles.