# Sorting Ballet — `sorting-ballet@1.0.0`

A row of rainbow bars sorts itself as a dance, every swap a hop, then un-sorts again. Loops perfectly.

A row of rainbow bars that sorts itself as a dance. A sorting algorithm (insertion, bubble, selection or quick sort) runs on a shuffled row; every swap is two bars hopping past each other in an arc, one over and one under. When the row is in order a wave of lift runs along it, then the same dance is played backwards until the row is shuffled again. Choose the number of bars, the algorithm, where the rainbow starts, how high the bars hop, the seed that shuffles the row, the backdrop colour and whether the camera sways.

- Kind: object; status: published; digest sha256:5668a5f8b9783a9fc8ccdf9f9b9fdd938f69964a30d036d230460e38e283d065
- Role: Object (3D, three.js): the favourite algorithm visualisation, as a satisfying studio loop.
- Implementation: three; entry `src/sorting-ballet.js`
- Files: https://aipixelwizard.com/registry/sorting-ballet/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/sorting-ballet.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/sorting-ballet/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/sorting-ballet/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — Renderer, geometry and shader materials.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createSortingBallet({ bars?, algorithm?, hue?, hop?, seed? }) => { group, swaps, setProgress(progress), dispose() }` — The row of instanced bars (about 15 wide) resting on y = 0; `swaps` is the number of swaps the algorithm needs; needs an environment map.
- `sortingSwaps(values, algorithm?) => [slotA, slotB][]` — The list of swaps that sorts a row of numbers with the chosen algorithm.

## Parameters
- `bars` (integer 12–48, default 24) — Bars
- `algorithm` (select one of insertion | bubble | selection | quick, default "insertion") — Algorithm
- `hue` (number 0–1, default 0) — Rainbow start
- `hop` (number 0.4–2, default 1) — Hop height
- `seed` (integer 1–999, default 9) — Seed
- `background` (color, default "#1a1d2a") — Backdrop
- `orbit` (boolean, default true) — Camera sway

## Composition
- Inputs: Time within the loop; the bars, algorithm, rainbow start, hop height, seed, backdrop and camera sway.
- Outputs: A full frame rendered in 3D with a studio environment.
- Coordinates: The bars stand on y = 0, about 15 wide and up to 4.8 tall; swapping bars hop in an arc and slide ±0.9 in depth to pass each other.
- Lighting: A warm key light with a shadow map, a floor and the studio environment.
- Timing: setProgress(progress) replays the swaps up to the current moment (at most a few hundred); frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- Bubble sort needs the most swaps; the dance runs at a steady rate of swaps per second, so more bars make a faster dance.

## Output and loop
- 1080×1080, 30 fps, 20 s, procedural
- Seamless loop: yes — The sort runs forward over the first half of the loop, the row holds in order for a moment with a wave of lift, and the same swaps are played backwards over the second half, so the row is back to its shuffled start at the last frame.
- Verified 2026-10-06 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (WebGL 2 via SwiftShader (software)); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create a WebGLRenderer with a studio environment and a shadow-casting light, add createSortingBallet().group and call row.setProgress(progress) each frame.

Existing project: Copy src/sorting-ballet.js; add the group to your scene with an environment map.

Reuse ideas:
- CS explainer: Insertion, 24 bars.
- Fast and busy: Bubble, many bars.
- Calm: Selection, big hops.

## Limitations
- The dance speed depends on the number of swaps: bubble sort with many bars is very fast.
- Only swaps are shown, not the comparisons.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Adapted from the owner's threejs-sketches/data-information/sorting-ballet (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original studio object: precomputed swap lists for four algorithms replayed at a steady rate with hopping bars, a lift wave when sorted and the same dance in reverse on an exact loop.