The Toolbox

Why this page exists

Every engine on this project fights the same two enemies: noisy landmarks and a browser that punishes wasted work. The answers turned out to be reusable. These six techniques are the project's real infrastructure; each engine is a different arrangement of them. For each one: what it is, why it won against the usual alternatives, and where it runs.

One-Euro filtering, per channel

A tracked point jitters even when you hold still. Smooth it hard and it lags when you move. The One-Euro filter solves this with one idea: the filter's cutoff frequency follows the signal's speed. Slow signal, heavy smoothing. Fast signal, almost none.

Why it won. A Kalman filter needs a motion model and a tuning matrix; a fixed low-pass lags; a moving average lags and blurs. One-Euro was designed for exactly this class of problem (interactive human input), has two parameters, and costs almost nothing per channel. We run separate instances for position, scale, and angle, tuned independently, because those channels have different noise and different tolerance for lag.

Where it runs. Earring anchors (per ear), ring channels, the tracker demo in Research Note 001.

Adaptive smoothing with velocity lead

The necklace needed something stronger than a filter: perfectly still at rest, yet zero visible trailing on movement. Those two goals fight. The answer is double-exponential smoothing whose blend follows measured speed, plus a prediction term fed by the raw signal's velocity rather than the smoothed one, so the prediction wakes up the instant real motion starts.

Why it won. The academic comparison point is a Kalman filter; double-exponential smoothing tracks it closely at a fraction of the cost and with almost nothing to tune. The velocity lead is the part most stacks miss: predict from the smoothed signal and your prediction inherits the smoothing lag. Predicting from held raw velocity is what killed the "trails at onset, then catches up" feel. Measured on the necklace: zero jitter at rest, 33 ms to respond.

Where it runs. The necklace hook engine, detailed on the necklace page.

Hysteresis latches

Any threshold on a noisy signal flickers when the signal hovers at the boundary. Show the earring at 10 degrees, hide at 10 degrees, and a head held at 10 degrees strobes. The fix is two thresholds with a gap: enter at 14, exit at 8. Inside the gap, the current state simply holds.

Why it won. The usual alternative is debouncing (wait N frames before switching), which adds a fixed delay to every legitimate change. Hysteresis adds no delay at all when the signal moves decisively; it only refuses to oscillate. Where a hold is genuinely safer we use one deliberately, like the ring's 10-frame handedness hold, but visibility and orientation decisions run on thresholds with gaps.

Where it runs. Earring frontal-hide (14°/8°), ring front/back/edge-on latch, necklace lock entry and exit.

Worker-side inference with a watchdog

Pose and face models are heavy. Run them on the main thread and every inference janks the render loop. The necklace engine moves inference into a Web Worker, and because workers can stall silently (a WASM init that never returns, a device that throttles), a six-second watchdog falls back to main-thread inference rather than freezing the product.

Why it won. The alternatives are running inference inline (jank on every frame), WebGPU-only paths (not everywhere yet), or trusting the worker (a silent stall becomes a frozen product). Worker plus watchdog degrades gracefully on the worst device instead of failing on it.

Where it runs. Necklace and chain tracking.

Band-only pixel reads

Reading pixels back from a canvas is one of the most expensive things a browser page can do; it forces the GPU and CPU to synchronize. The necklace compositor never reads the full frame. It computes the narrow band the necklace actually occupies and reads only that.

Why it won. The naive full-frame readback caps frame rate on exactly the phones customers use. Cutting the read to the jewellery's band shrinks the cost by roughly the ratio of band to frame, which is most of it. The same discipline caps detection input at 480 px on the long edge: the models do not need more pixels to find a shoulder line.

Where it runs. Necklace compositing and detection sizing.

Capped pixel-ratio rendering

A 3× device-pixel-ratio phone asks for more than twice the pixels of a 2× phone for a quality difference nobody can see in a live camera view. Every canvas in the project clamps its backing-store ratio (2 on mobile, 3 on desktop) before allocating.

Why it won. The alternative is honoring the device ratio and paying for it in memory, fill rate, and on the worst devices, crashes. The ring engine's out-of-memory forensics made this rule a hard default everywhere.

Where it runs. Every engine's canvases.

The pattern behind the toolbox

Each technique earns its place the same way: measure the failure, pick the cheapest mechanism that removes it, and make the mechanism boring. Nothing here is exotic; the value is that all six run together, tuned per channel, on every engine.