bubblechambersimart/README.md

# Bubble Chamber

A seeded, parametric generator of imaginary particle-physics plates — the
black-and-white "bubble chamber" photographs of mid-century high-energy physics —
built for large-format art print. One seed → one fully-determined image, rendered
either as a worn photographic plate or as clean, layered vector for print.

![a generated plate](output/iterations/01_archival-mono.svg)

## How the images are generated

Everything derives deterministically from a **seed** string: the seed is hashed
(`cyrb53`) to seed a chain of salted PRNGs (`mulberry32`) that drive a small
physics model, so the same seed always yields the same plate. Charged particles
are launched from interaction **vertices** and integrated step-by-step through a
uniform magnetic field — curving with radius `r = p/(qB)` and bleeding momentum to
a simplified Bethe–Bloch energy loss, so slow particles tighten into inward
spirals. The velocity **β** is tracked along every path and sets both how densely
**bubbles** nucleate (`∝ 1/β²`) and how fat they are. Low-energy electrons
knocked loose along the way (**δ-rays**) are drawn as tight logarithmic spirals;
neutral particles leave **V-decays**; stiff **cosmic rays** and gentle
**sweepers** cross the frame; a pressure **shock disk**, faint **chamber-optics**
lines, and **emulsion damage** (scratches, dust, water rings, stains) complete the
scene. This pure geometric description — the **scene model** — is renderer-agnostic
and handed to independent renderers: a **photographic raster** compositor that
layers soft blooming bubbles, halation, film grain, tonal mottle, vignette and
plate damage for the worn-archival look; and a **vector renderer** that emits the
identical geometry as **layered SVG** and **CMYK PDF (with OCG layers)** for the
print shop. Because the seed fixes every choice, an inspiration thumbnail and its
print master are the same image at different sizes.

## Colour, palettes & effects

Black-and-white is the default; colour is an optional, seeded **palette** layer
(`src/render/palette.js`) applied over the same geometry. Shipped feels:

- **mono** (B&W), **charge** (duotone by charge sign), **β** (velocity → spectral)
- **kind** (one hue per particle type), **kindlife** / **kindrise** (type sets the
  hue, lifecycle sets the *intensity* — fading to, or rising toward, the death)
- **lifecycle** (hue across birth→death), **psychedelic** (hue cycling along trails)
- **cyanotype** (a full chemistry — blueprint ground + pale ink), **magentarise**
  (a restrained magenta-family example with a burnt-orange disk)

Orthogonal global controls: **paper tone** (cream/sepia/selenium/cool/olive/neutral
toners + brightness + gas-glow), **saturation**, **hue shift**, **depth/exposure**
(per-trail opacity, size & defocus from chamber depth + event age), **bubble edge
softness**, **iridescent disk** (spectral sunburst), and **chromatic halo** (a
hue-shifted aura around trails). Adding a new "feel" is one entry in the registry.

## Quick start

```bash
# interactive: open the single self-contained file in a browser
open bubble_chamber.html            # type a seed, hit "Derive all params from seed", tweak sliders

# dev build (modular src/ → portable single file)
node build.mjs

# browse random plates, pick by seed, render print masters
tools/inspire.sh 24 600             # → output/inspiration/index.html
tools/render.sh  LAMBDA-2648        # → output/masters/  (SVG + CMYK PDF + hi-res PNG)
node tools/render-svg.mjs --seed LAMBDA-2648 out.svg 6000 diskSoften=1.5
```

## Project layout

- `src/` — modular source: `scene/` (the deterministic model), `render/` (canvas /
  svg / pdf), `ui/`, `rng.js`, `main.js`.
- `bubble_chamber.html` — built, portable single-file app (live sliders + export).
- `tools/` — headless render helpers, the inspiration randomizer, CLI renderers.
- `output/` — `inspiration/` contact sheets, `iterations*/` curated SVG sets (with
  browsable `index.html`), and `masters/` print files. Raster PNGs and print
  masters are **git-ignored** (large and fully reproducible from their seeds).
- **[DESIGN.md](DESIGN.md)** — architecture & physics decisions.
- **[PRINT.md](PRINT.md)** — large-format strategy (vector + texture layers, SVG/PDF layers, sizes/DPI).
- **[roadmap.md](roadmap.md)** — where the project is going, artistically and technically.

## Aesthetic

Faithful black-and-white photographic-positive by default (dark ink on milky
paper), with a "negative plate" variant and an optional colour-palette layer.
Vector-first for print; the seed/hash makes any preview reproducible at any
resolution.