Choosing images that forge well

The Studio accepts any image, but the effect is not neutral to its subject. The picture spends most of the scroll as scattered noise, and what it looks like on the way to assembled is decided by the image you feed in. Ten minutes choosing the right source beats an hour of flag tuning. Here is what actually matters.

Silhouette beats detail

Mid-assembly, the viewer sees colour masses, not edges. Images with a strong figure–ground relationship — a subject that reads as a shape against a distinct background — start to be recognisable early, which is what makes the landing feel inevitable rather than sudden. A busy scene where every region has similar luminance stays illegible until the last moment and then pops, which can also be the effect you want; just choose it on purpose. Portraits, products on clean backgrounds, skylines, and logos all carry a silhouette. Dense foliage, crowds, and texture-only shots mostly don't.

Contrast is doing the storytelling

The scattered field inherits the image's palette. High internal contrast — a bright subject on a dark ground, or the reverse — makes the chaos phase visibly "about" something. This matters double on themed pages, where the page's entire colour system is extracted from the image: a low-contrast, muddy source yields a low-contrast palette for the studio to fight with. The WCAG floors (body text 4.5:1, accent 3:1) are enforced by construction regardless, but a source with real tonal range gives the palette room to be handsome rather than merely legal.

Resolution: enough, then stop

With the default full-image faces, the landed frame samples the source texture directly, so sharpness comes from the file, not the grid. A source around 1500–2500 px on the long edge lands crisp on any screen the effect sensibly targets; beyond that you are paying payload for pixels the mosaic cannot show. Local files are embedded as base64 — self-contained but sized accordingly — and --optimize re-encodes the embed at what the mosaic can actually sample. It earns its keep on sources far larger than the grid needs — with a already-modest source and the default faces it often has nothing to remove and changes nothing. URLs are referenced live instead: small output, but the image must stay hosted and CORS-readable.

Full-image faces or flat?

• --faces image (the default): photographs, art, anything that should land sharp. Grid rows then only decide how many cubes fly in — spectacle, not sharpness — and rows beyond ~256 rarely earn their cost.
• --faces flat: each tile is averaged to one colour, and the chunky mosaic is the look. Logos, icons, pixel-art. Detail tops out at exactly the grid, so pair it with enough --rows to carry the shape.

Transparent backgrounds are a feature

Fully transparent source pixels drop their cubes entirely, whichever faces you use — a logo on a transparent PNG assembles as the logo's own shape, not a rectangle containing it (--alpha sets the cutoff). Pair with --bg transparent when the effect should sit over your page's own styling.

Keep the budget honest

Before forging, size the grid with a dry run: node cli.mjs photo.jpg --rows 144 --emit json reports the instance count and its tier — ok up to 60,000 instances anywhere, amber to 200,000 on desktops, red beyond only for audiences whose GPUs you know. The whole grid draws in one call whatever you pick, but fill-rate on modest phones is real; the tiers are the boundary the studio has already measured for you.

Then look

Whatever the theory says, verify by looking: --probe 0,0.5,1 writes headless screenshots at scattered, mid-chaos, and landed. The mid-chaos frame is the honest one — it is where a weak silhouette shows up and where text over the effect fails first. The fastest loop of all is the Studio: drop the candidate image, scrub the preview, and you will know in seconds whether the source is right before you commit to a page around it.