Kaleidoscope Shader: Build a Symmetry Lens

A kaleidoscope shader is a coordinate lens: it folds one source domain into mirrored angular sectors before sampling color. This tutorial builds that fold in WGSL, makes seams inspectable, directs the source window, bounds motion, provides a still fallback, and archives the result as a repeatable edition.

Kaleidoscope shader geometry is a fold

Start in normalized coordinates centered on the frame. Correct the x-axis for aspect ratio so a circle remains circular, then convert each point to radius and angle. This polar coordinate folding divides the full turn by the chosen sector count, wraps the angle into one sector, and mirrors it around the sector midpoint.

That sequence creates dihedral symmetry: rotation repeats the sector, while reflection mirrors it. The kaleidoscope shader does not duplicate pixels in screen space; it sends many output coordinates back to one source wedge. This mental model makes composition easier because every visible repetition can be traced to a sampling location.

Render the folded angle and radius as grayscale diagnostics before using a texture. Straight radial bands reveal origin placement, aspect mistakes, discontinuities, and sector orientation. Label sector count and phase on the canvas. A beautiful source image can hide broken geometry, while a plain ramp makes every mathematical seam obvious.

Write the smallest WGSL lens first

Pass resolution, sector count, phase, zoom, and source transform through a typed uniform buffer. In the fragment stage, derive centered UV coordinates, apply aspect correction, calculate atan2, fold the angle, reconstruct a unit vector, and map it back into source UV. Keep every constant named and guard division by zero at the center.

The WGSL specification defines shader semantics, WebGPU defines the pipeline and resources, and the MDN WebGPU guide provides practical browser context. These sources establish implementation behavior; the visual rhythm remains an authored decision.

Use the executable JavaScript fold as a CPU reference. For selected angles and sector counts, compare its output with pixels or a debug buffer from the WGSL fragment shader. The kaleidoscope shader gains a conformance oracle that can catch a sign, wrap, or phase mistake independently from the final image.

The math fixture folds angles into mirrored sectors and proves periodic equivalence for four, six, and nine sectors without requiring a GPU.

Runnable artifact — kaleidoscope-fold.test.mjs

import assert from "node:assert/strict";
const fold=(angle,sectors)=>{const span=Math.PI*2/sectors,local=((angle%span)+span)%span;return Math.min(local,span-local)};
for(const sectors of [4,6,9])for(const angle of [-3.1,-.4,.2,1.7]){assert.ok(Math.abs(fold(angle,sectors)-fold(angle+Math.PI*2/sectors,sectors))<1e-12);assert.ok(fold(angle,sectors)<=Math.PI/sectors)}
console.log("PASS: kaleidoscope fold preserves sector symmetry");

Run node kaleidoscope-fold.test.mjs. Expected receipt: PASS: kaleidoscope fold preserves sector symmetry.

Inspect the sector seam before hiding it

Display sector boundaries as thin diagnostic lines and sample a continuous procedural grid. A correct mirrored boundary should join positions continuously, even when derivatives change direction. Texture filtering, derivative-based effects, and high-frequency sources may still reveal a hairline, so inspect at several zooms and resolutions.

The polar SVG maps a source wedge into a sixfold lens and repeats every label in an HTML legend. It makes the source ownership visible: one triangular domain supplies all six mirrored regions. A procedural lens becomes art-directable when the selected wedge is as deliberate as the symmetry count.

For seam repair, prefer reducing source frequency, moving the source window, using derivative-aware filtering, or blending across a very narrow documented boundary. Large soft masks erase the crisp geometry and can create a different halo. Keep a seam heatmap in the edition receipt so a clean final frame does not conceal how the edge was tested.

Direct the source window as a composition

The source may be a photograph, painted texture, signed-distance pattern, previous shader pass, or live camera with consent. Place it inside a movable, rotatable, and scalable sampling frame. Small changes near the source wedge can reorganize the entire image because every sector reflects the same local structure.

Create contact sheets that vary one parameter at a time: source offset, rotation, zoom, sector count, and phase. Mark selections with the values that produced them. Kaleidoscope shader exploration becomes curation when discarded neighborhoods remain visible and the chosen image has a stated reason, such as a quiet center and denser outer rhythm.

Protect source rights and privacy. A mirrored crop can make incidental faces or identifying details less recognizable without actually anonymizing them. Use licensed or authored material, keep attribution, and avoid live camera defaults. When the source is procedural, record its seed and upstream parameters as part of the complete edition.

Shape the center without a singularity

Polar angle has no defined value at radius zero, and a literal reconstruction can produce unstable pixels or an overly sharp pinwheel. Decide what the center should do: remain a small quiet disk, continue a low-frequency field, form a rosette, or reveal the source origin. This is a compositional choice with a numerical boundary.

Use a radius threshold and a smooth transition to a stable center sample when necessary. Verify that the threshold is resolution-independent and does not create a visible ring. The table compares radius zones, sample transformations, and intended roles so center treatment is not buried in an unexplained epsilon.

A kaleidoscope shader often benefits from unequal visual density. Keep the center calmer, let middle radii carry recognizably mirrored forms, and reserve the edge for fine repetition. Map source scale or procedural frequency by radius with bounded curves. The symmetry remains exact while the information budget changes across the frame.

Color sectors without breaking symmetry

Color can follow the source faithfully or receive a sector-aware treatment. If alternating sectors shift hue, disclose that they are no longer pure mirror copies. Use parity, radius, or source luminance as controlled inputs; avoid random variation per fragment because it destroys repeatability and produces temporal noise.

Review the image in grayscale and with a limited palette. Symmetry should remain legible through shape and value, while color establishes emotional temperature. The semantic comparison table makes sector role redundant with labels, and the final artwork needs a meaningful alt description rather than an inventory of every hue.

The kaleidoscope shader can output wide gamut, but keep an sRGB proof and monitor clipping. A saturated reflected edge may become a flat band after conversion. Apply palette mapping after coordinate diagnostics, preserve a neutral debug mode, and save the exact output color space. Color is a final material layer, not evidence that the fold is correct.

Move phase slowly and preserve a still

Animation can rotate the source window, advance sector phase, breathe zoom, or evolve an upstream field. Choose one dominant motion and make it loop on an exact period. Independent motion at every layer produces visual churn that overwhelms the geometric pleasure of reflection.

Honor reduced motion with a deliberately selected still. Provide pause when the shader runs continuously and suspend GPU work when the artwork is offscreen. Keep interaction optional; pointer movement may reveal source ownership, but the default composition must already have a focal hierarchy and must not flash.

Connect neighboring techniques without blending their intents. Domain warping marble shaders bends coordinates organically, quasicrystal shaders use wave interference, seeded randomness stabilizes generative choices, and WebGPU generative art covers the broader delivery system. A dedicated motion proof should also compare first frame, loop midpoint, final frame, and reduced-motion still at the same crop.

Keep the static edition reachable before shader initialization so reduced motion and device failure preserve the same authored center, crop, and palette.

Archive the symmetry lens as an edition

Store WGSL source, pipeline layout, source asset digest and rights, sector count, phase, aspect convention, source transform, center rule, seam method, palette, motion period, reduced-motion frame, device notes, and output digest. Include debug renders for angle, radius, sectors, source UV, and seams.

The release sequence is concise: validate the fold, inspect seams, curate the source window, proof the still, then render the edition. Stop when symmetry differs across resolutions, a seam becomes visible at target size, the source cannot be licensed, reduced motion has no composed frame, or a clean device cannot reproduce the canonical image within declared tolerance.

Revisit the kaleidoscope shader when browser implementations, source material, or rendering targets change. The artistic identity lives in the relationship between a small selected wedge and the full repeated field. Preserving both the code and the selection history makes that relationship legible long after the moving image has stopped.

Kaleidoscope shader editions archive the seam view beside the beauty frame; future changes need both the intended image and its geometric diagnostic.

Archive the symmetry as an edition

A kaleidoscope becomes more than a filter when the fold, source wedge, center, seams, color, and motion each remain editable and documented. The exact symmetry supplies structure; art direction decides what deserves to be repeated. Keep a contact sheet of rejected source windows because it records the visual search space that the final image conceals. That sheet also helps another artist distinguish a mathematical parameter change from a curatorial one, making the edition teachable without reducing it to a preset. The same discipline supports print: render a tiled high-resolution proof, inspect radial seams at physical size, and record color conversion before calling the moving browser frame the master artwork. Preserve one neutral grid render beside every edition so a future palette change cannot hide a damaged fold or displaced origin at any resolution.