Dynamical Systems Orchestration

Persistent homology as a significance filter

Rather than detecting blobs by thresholding intensity or filtering by area — both of which conflate size with significance — persistence measures how prominent a blob is relative to its local surroundings across a continuous range of intensity thresholds. The H0 persistence diagram treats the greyscale image as a scalar function: as a threshold sweeps from high to low intensity, connected components 'born' at blob peaks 'die' when they merge with a brighter neighbour. A blob's persistence is the intensity gap between its peak and the saddle point where it merges. The input is inverted (255.0 - small) so OpenCV's 'bright = foreground' becomes 'low value = foreground' matching GUDHI's sublevel-set sweep; downscaling to ~320×240 keeps CubicalComplex under ~40 ms on an M-series Mac. A sublevel-set branch deduplication pass removes same-branch sub-features using the elder rule.

Flow-advected mask identity

Farneback dense optical flow estimates a displacement vector at every pixel between consecutive frames. Each track owns a binary mask initialised at birth from the blob's detection contour. Every frame the mask is remapped forward using the inverse-warp of the flow field. Every REFINE_INTERVAL = 5 frames the mask is 50/50 blended with the current detection contour, counteracting accumulated flow drift. A blob that briefly becomes semi-transparent and disappears from the persistence diagram does not fire a death event — the mask continues to exist and be advected forward.

Wasserstein-inspired topological matching

When multiple advected masks overlap a single detection, the system resolves the ambiguity using distance in the persistence diagram's birth–death plane rather than pixel space: cost = 0.75·topo_dist + 0.15·pixel_dist + 0.10·hue_cost. This is not full Wasserstein optimal transport — rather, a Wasserstein-inspired cost that prioritises topological feature space over ambient pixel space. Two blobs at similar positions but different thermal states are distinguished correctly where naïve position-based Hungarian would assign them arbitrarily.

Physics-informed buoyancy Kalman

The constant-velocity Kalman model assumes blobs move at fixed velocity between frames. Lava lamp blobs do not: they decelerate to near zero at the top and bottom as buoyancy force reverses, and accelerate through the middle column. The v3.x Kalman adds a fifth state variable ay (vertical acceleration), governed by mean-reverting dynamics and initialised with a directional prior (+0.15 rising, −0.15 falling, 0 turning).

Measurement noise adapts based on y-position. Within 12% of the lamp top/bottom, noise is 2.0 — the filter trusts its physics model more than the noisy detection. In mid-column it is 0.05 — detection dominates. This produces accurate predictions at the physically most important moments: turning points where identity ambiguity is highest.

The zombie voice pool

The zombie pool addresses the failure mode where a turning blob fires death → birth in rapid succession and the release tail of the dead voice stacks against the attack of the new voice — producing the ~9-second phantom polyphony that plagued v3.0 turning events.

Lifecycle. On on_blob_death, a BLOB_ONLY voice's slot transitions to ZOMBIE. The SC node stays alive (gate=1) but its amp is multiplied by 0.35, audibly softening without triggering release. Before spawning a fresh voice for any new blob, the BindingManager asks the VoiceManager to scan zombies for a match within ~15% of lamp height whose persistence is within a factor of 3×. The closest match wins: its slot transitions back to BLOB_ONLY, morphing seamlessly toward the new target values. Zombies older than zombie_window = 4 s release normally.

v4.0 integration. The zombie pool is now a sub-state of the slot lifecycle rather than a side-table. A HYBRID voice whose player has been active within blob_recent_play_window = 5 s detaches to KEYBOARD_ONLY instead of zombifying — the player keeps the voice; the blob bind drops.

Voice-slot architecture v4.0

v4.0's central new abstraction. A Voice is no longer implicitly a 1:1 image of a blob — it is a slot in a fixed pool, holding full synth state, a routing matrix, and a lifecycle state that is independent of any given blob's existence. The state determines what events the slot accepts:

IDLE accepts only spawn_for_blob or create_empty. BLOB_ONLY runs the routing matrix and forwards no keyboard input. KEYBOARD_ONLY accepts notes and edits but ignores blob updates. HYBRID accepts both — the player's notes set base values, the routing matrix adds modulation on top. ZOMBIE is a transient state with a timer. Each slot's SynthState tracks both editable base values and smoothed current/target values for every continuous output parameter; first-order lag on the SC side ensures parameter changes never click.

MPE routing matrix v4.0

Every Voice carries a list of Routing(src, dst, depth, curve) tuples. Sources read blob CV features each frame — y_norm, x_norm, vy, persistence, area, mean_hue, elongation, orientation, age. Destinations write directly to synth parameters — pitch, cutoff, res, amp, pan, wave_pos, attack, release. Curves are pre-tabulated lookup arrays (LIN, LOG, EXP, SCURVE, SQRT) — cheap to evaluate and trivial for the user to extend.

Default routings on BLOB_ONLY voices reproduce v3.2 behaviour: y_norm → pitch (depth +24 semitones, LIN), persistence → amp (SQRT), vy → wave_pos and area → wave_pos (kinematic + geometric), elongation → res (depth +0.6), orientation → pan (depth +1.0), plus an EventRoute firing direction_change → attack/release preset. The mean_hue → wave_pos mapping was removed in v3.2 because camera-firmware variations made blob hue an unreliable continuous source; Source.MEAN_HUE remains available for explicit wiring.

The \mpeVoice SynthDef v4.0

One \mpeVoice instance runs per active voice slot. The oscillator is VOsc reading across 16 contiguous wavetable buffers (4 banks × 4 wavetables, allocated with Buffer.allocConsecutive): bank 0 = analogue shapes (saw / square / pulse / triangle), bank 1 = harmonic-series sweeps, bank 2 = formants (ah / eh / ih / oh), bank 3 = metallic / bell partials. The filter section uses parallel RLPF / BPF / RHPF crossfaded via SelectX.ar on the fmode parameter, giving a continuous LP↔BP↔HP morph. Full ADSR envelope drives amplitude; .lag smoothing on every continuous parameter (50 ms typical, 100 ms on amp, 1 s on attack/release) matches Python's first-order smoothing so cross-frame changes never click.

Controller abstraction v4.0

All player input is funnelled through a Controller protocol that emits ControllerEvent dataclasses. The VoiceManager and BindingManager only see ControllerEvents; they do not know whether the source is a keyboard, an external MIDI controller, an OSC stream from a tablet, or a future voice-to-MIDI bridge. The Phase 1 KeyboardController and Phase 2 MIDIController are interchangeable adapters.

Why this is worth the small upfront cost: the temptation in Phase 1 is to wire pygame keys directly to VoiceManager methods. That works, but Phase 2 then becomes a refactor instead of an add. A 60-line Controller protocol now makes Phase 2 a ~100-line MIDIController plus a small JSON learn-map file. The same protocol can later host a Push 3 adapter, a TouchOSC layout, or a tablet UI without disturbing anything downstream of it.