Dithered Motif Site

dithered-motif-site

Overview

Full pipeline for turning a described subject into an animated, pointer-reactive, Bayer-dithered dot-field background: source image/video prompt -> frame extraction -> canvas dither engine -> looping -> pointer interaction -> page composition. Sourced from a working Higgsfield/Renaissance-oil-painting implementation; the prompt style and the algorithm below are proven together, but every stage generalizes to other visual styles as long as the subject rule in Step 1 is respected.

The one rule everything else depends on: the subject must be made of many small discrete elements (sparks, ash, tracery, a flock, a crowd, crops in a field, repeated architecture). A solid object — one face, one animal, one smooth mass — turns into an illegible grey blob when dithered, because the dot field has no internal structure to latch onto. If the source is a solid object, change the source; don't fight the dither settings.

Pipeline

1. Image prompt (Higgsfield nano_banana_pro) — see references/image-prompts.md. Generate via the generate_image MCP tool if available, or hand the user the filled prompt to paste manually.
2. Video prompt (Higgsfield seedance_2_0, image-to-video) — see references/video-prompts.md. Locked-off camera language is non-negotiable; a drifting subject cannot be fixed downstream.
3. Frame extraction (ffmpeg) — see references/frame-extraction.md.
4. Dither engine — see references/dither-engine.md for the full algorithm/parameter spec and references/dither-engine.ts for a reference TypeScript canvas implementation to adapt directly into the target repo (React/Next.js <canvas> component or vanilla).
5. Looping — crossfade-the-wrap for non-cyclic motifs (the common case); scored-seam matching only for genuinely cyclic subjects. Covered in references/dither-engine.md.
6. Pointer interaction — displace sampling coordinates, not drawn output. Covered in references/dither-engine.md.
7. Page composition — full-bleed canvas, legibility solution (scrim / blend-mode / backing panel), canvas background = page ground color so empty cells read as background, not white. Covered in references/dither-engine.md.

Load-bearing gotchas (do not skip)

• Pin auto-levels for the whole sequence. Compute the 2nd/98th percentile luma levels once, reuse for every frame. Recomputing per frame makes dot density visibly pulse — this is the single easiest thing to get wrong.
• Invert is about the SOURCE, not the page theme. Dark subject on light background -> invert so dots land on the subject. Light subject on dark background -> don't invert. This is independent of whether the page itself is light or dark mode.
• Crop before scale if the source has a painted/generated border baked in (common with AI image models) — otherwise it dithers into a hard rectangle sitting mid-page.
• Airiness = cell size vs dot fill, not dot count. If the result looks heavy and flat, raise pixelSize and lower dotScale together — do not just add more dots.
• Most natural motifs have no true loop point. Don't hunt for a seam that doesn't exist; crossfade the wrap instead (see reference doc for the short-sequence edge case).
• Avoid radial ripple for pointer interaction on natural motifs — it reads as a lens artifact sitting on top of the image, not something happening to the subject. Match interaction shape to subject shape instead (directional lean / rotational twist / gentle scatter).
• mix-blend-mode: multiply for text legibility only works on light grounds. On dark grounds use a scrim or backing panel instead.

Sanity checklist before shipping (from source material)

• Dot density constant across the whole loop — if it pulses, auto-levels aren't pinned.
• No visible jump at the wrap — if there is, lengthen the crossfade.
• Headline readable at every point in the animation, not just one screenshot.
• Subject still reads as itself at the chosen pixelSize — coarser is more striking but there's a point where it dissolves.
• Looks right on a narrow viewport where the canvas is much smaller relative to pixelSize — small canvases usually need a finer grid.

References

• references/image-prompts.md — Higgsfield nano_banana_pro prompt patterns and three worked examples (molten forge sparks, cathedral rose window, falling ash over a lost city).
• references/video-prompts.md — Higgsfield seedance_2_0 image-to-video settings and prompt patterns, worked examples matching the image prompts.
• references/frame-extraction.md — ffmpeg commands for frame rate, crop, and background-noise flattening.
• references/dither-engine.md — full algorithm spec: buffer downscale, luma conversion, auto-levels, invert, floor clamp, 8x8 Bayer quantization, batched cell drawing, parameter table, color approaches (sampled / duotone / blended), looping, pointer interaction, page composition.
• references/dither-engine.ts — reference TypeScript canvas implementation of the engine above, meant to be adapted (not copy-pasted verbatim) into the target app's component structure.