diff --git a/README.md b/README.md index 5514e3d..14ed54d 100644 --- a/README.md +++ b/README.md @@ -223,6 +223,13 @@ window, the second differences first derivatives over several frames and still r its own noise. Whichever brakes harder wins, so a thick window is unaffected and a thin one gets a stop it would otherwise never have seen. +**A corner is not a stop, and telling them apart needs the other axis.** Along the heading the hand was +going, a corner takes its speed away faster than any stop does — so braking, which is deliberately believed +on thin evidence and acted on at once, fires on a hand that has not slowed by a pixel per second. What +separates them is where the bend points: a hand coming to a stop pushes straight back along its path, and a +hand turning pushes sideways. Through a right angle at speed, a hundredth of the bend pointed back along the +path and the rest of it across. + **Most of the overshoot was never in the fit — it was the ramp behind it.** A first-order lag trails its target by its own time constant times how fast that target is moving, and coming off a flick the target falls faster than at any other time. That lag is a known quantity rather than something to be differentiated out of @@ -234,6 +241,13 @@ The rest is mostly about not believing noise: - **Below a crawl there is no lead at all.** Whole mouse counts are all a slow hand produces, and a fit over four of them is mostly quantisation. +- **What a count is worth is measured, not assumed.** Every noise floor is written in units of one count, and + a count is one pixel only on a mouse at ordinary sensitivity — a low-DPI one steps four, and so does + anything the OS or a device pixel ratio scales on the way through. Assumed, that put every floor four times + too low on such a device: it swung the guess 28° of heading a frame on a dead straight path and led a crawl + it should have refused. The deltas are the only thing that knows, and every delta is a whole number of + counts — so the grid they sit on is their greatest common divisor, which is the one reading of it that does + not mistake a coarse device for a fast hand. - **The parabola is believed only as far as the bend stands above the noise floor** — how hard a path of whole counts appears to bend when it is dead straight — and slides back to the straight line as that margin closes. Sample count is the wrong question: it counts the samples that carried motion, so a fast @@ -250,21 +264,69 @@ The rest is mostly about not believing noise: grew a fifth on it, which is the one frame the eye gets before freshness starts discounting it. - **A hitch is not a change of refresh interval**, and the age of the newest sample is averaged rather than taken raw — a few milliseconds of horizon is pixels of lead on a hand doing nothing new. +- **The turn is believed on its own evidence, and on several readings of it.** It used to be gated by how far + the parabola was believed as well — a worse measurement of the same thing, which sits near a half on a + window holding four samples. Two half-open gates left the arc bending at a quarter of the rate the hand was + turning, and a lead that lags the heading on a circle points outwards: the guess orbited 20px outside a + 120px circle. Averaging the readings before judging them is more evidence rather than a lower bar — a hand + going round turns the same way on every frame and quantisation flips sign — and a reading that contradicts + a turn already believed is taken at once, because a hand can start going round the other way. +- **Nor further ahead than the path turns a quarter circle over.** Past that the answer is mostly the turn + rate — the noisiest thing in the fit — and the chord being asked for has stopped growing with the horizon + and started coming back towards the hand, so a wobble in the rate moves the guess around the circle rather + than along it. Unbounded, a hand stirring a small circle came apart as `leadFrames` went up: at three + refreshes of lead the guess sat 58px off a 25px circle. Bounded, it reads the same at one refresh and at + four. - **The guess is never led past its own reversal.** A quick shake turns round before the horizon is out, and at the moment it is fastest there is no acceleration to give the turn away. ## The rig -`example/` is a cursor-to-photon rig: markers chase the OS cursor so a slow-motion recording can measure the +`example/` is a cursor-to-photon rig: markers chase the OS pointer so a slow-motion recording can measure the gap to it. That is the only way to see presentation latency — no clock inside the page can observe it. ```bash bun i && bun dev ``` -The red square is the reported position, the green circle is the prediction, and the OS cursor is the truth -(the compositor draws it, so it is never late). `?compare=1` shows two leads at once; `?nocursor=1`, -`?noreported=1` and `?nopredicted=1` strip the frame down to what you want to read. +The red square is the reported position, the green circle is the prediction, and the white dot is the truth: +it is the OS pointer wearing a cursor image, so the compositor still draws it and it is still never late — an +arrow is simply a poor shape to judge a circle against, being pointed rather than centred on the position it +means. `?compare=1` shows two leads at once; `?nocursor=1`, `?noreported=1` and `?nopredicted=1` strip the +frame down to what you want to read. + +## Changing the prediction + +The rig above is the only way to see presentation latency, and it needs a hand, a camera and an afternoon. +Everything else is measured off a replay instead, so the fit can be changed and judged without one: + +```bash +bun test # 30 shapes × 9 devices, against floors that were measured +bun run bench # the same runs, printed as numbers +bun run bench circle --all # one family of shapes, on every device +bun run bench --save before.json +bun run bench --diff before.json # what your change actually moved, marked ↓ better ↑ worse +``` + +A hand moves along a known path, a modelled device reports it in whole counts at its own rate and with its +own clock wander, a frame loop reads the lead back out, and the run is scored against where the hand really +is when each frame reaches the screen. Both ends are modelled because both ends matter: a wired mouse and one +on a radio are different problems, and so are 60Hz and 144Hz. + +The shapes are in `library/src/__tests__/harness.ts` — steady drags from a crawl to a whip, flicks stopping +in anywhere from 40ms to 400ms, circles, figure eights, spirals, corners taken sharp and round, shakes, +zigzags, target acquisition, tremor, and stops and starts between all of them. Add one there and the +scoreboard picks it up; the shapes suite will then fail until it is given a floor, which is the point. + +What is scored, per run: how far past the hand the guess ever sat and how far behind, how much the picture +moved against the hand or moved at all while the hand was still, how far the guess jumped in a frame, and the +error against the error of not guessing at all. Overshooting and falling short are never added together — +lead that was never needed has to be handed back, and handing it back walks the view backwards under the +hand, where lead that was never taken is only the lateness the library exists to remove. + +Every figure in a test was read off that rig and given about a quarter more room. **Improve one and tighten +it in the same change**, or the floor stops being a floor. Most changes trade one column for another; the +`--diff` output is there so the trade is visible rather than discovered later on somebody's desk. ## License diff --git a/example/pages/index.tsx b/example/pages/index.tsx index 5fab9fb..1533993 100644 --- a/example/pages/index.tsx +++ b/example/pages/index.tsx @@ -10,8 +10,9 @@ import { import Head from 'next/head' -// Cursor-to-photon rig. Markers chase the OS cursor so a slow-motion recording can measure the gap to it, -// which is the only way to see presentation latency — no clock inside the page can observe it. +// Cursor-to-photon rig. Markers chase the OS pointer — drawn here as a white dot, see CURSOR_DOT_RADIUS — +// so a slow-motion recording can measure the gap to it, which is the only way to see presentation latency: +// no clock inside the page can observe it. // // Getting the input position is not the problem: the frame asked for at one refresh is presented one to // four refreshes later, and the hand has moved by then. Prediction is the only thing that closes that, and @@ -73,6 +74,30 @@ const COMPARE_COLOURS: [number, number, number][] = [ ] const RING_RADII = [11, 16] +// The OS pointer, re-skinned as a white dot a little inside the green ring's radius. +// +// It is still the OS pointer: a cursor image is handed to the window server and drawn by the compositor at +// the true position, exactly as the arrow was, so it stays the one thing in the frame that is never late. +// Drawing a dot into the canvas instead would draw it at the *reported* position, which is the red square — +// the lag this page exists to show would vanish along with the reference for it. +// +// An arrow is a bad shape to judge alignment against: it is not centred on the position it means, so the +// eye compares a corner to a circle and the answer depends on which way the arrow points. A dot centred on +// the hotspot is the same shape as the markers chasing it, and a slow-motion frame reads as the dot being +// inside the ring, on its edge, or outside it. Smaller than the ring so that the two never touch when they +// agree, which is what makes the gap between them readable at all. +const CURSOR_DOT_RADIUS = 8 +const cursorDot = () => { + const size = CURSOR_DOT_RADIUS * 2 + 4 + const centre = size / 2 + const svg = + `` + // Falls back to the ordinary arrow rather than to nothing: a rig with no pointer at all is worse than one + // with the wrong pointer, and `none` is what the hide button is for. + return `url("data:image/svg+xml,${encodeURIComponent(svg)}") ${centre} ${centre}, default` +} + // Number(null) is 0, so an absent parameter has to be checked for rather than converted — otherwise every // default silently reads as zero. const numberParam = (params: URLSearchParams, key: string, fallback: number) => { @@ -398,7 +423,10 @@ const Rig = ({ compare, measure, leadFrames, capPx, hideCursor, hideReported, hi }, [compare, measure, leadFrames, capPx, hideReported, hidePredicted]) return ( -
- Move the pointer around. The red square is where the browser says it is; the green circle is where hyperpointer - thinks it will be by the time this frame reaches the screen. They should sit on top of each other when the hand - is still, and the circle should sit on the OS cursor while it moves. + Move the pointer around. The white dot is the OS pointer, drawn by the compositor and never late; the red square + is where the browser says it is; the green circle is where hyperpointer thinks it will be by the time this frame + reaches the screen. All three should sit on top of each other when the hand is still, and the circle should stay + around the dot while it moves.
{measure && capture && ( diff --git a/library/src/__tests__/harness.ts b/library/src/__tests__/harness.ts new file mode 100644 index 0000000..33d702b --- /dev/null +++ b/library/src/__tests__/harness.ts @@ -0,0 +1,959 @@ +// The rig the guess is judged on, written down once so every test is judging the same thing: a hand moving +// along a known path, a device reporting that motion the way real hardware does, a frame loop reading the +// lead back out, and the handful of numbers that say whether the guess was worth having. +// +// The point of keeping it here rather than in any one test file is that the prediction is tuned from these +// numbers. A change to the fit moves all of them at once, and the only way to tell an improvement from a +// trade is to see the whole board — so the same replay feeds the assertions and `bun run bench`, and a +// scenario added here is scored by both. +// +// Everything is deterministic: the clock wander comes from a seeded generator, so a figure measured today is +// the figure measured on the next machine. Any number in a test file was read off this rig and given room. + +import { createPointerPredictor, DEFAULT_DECAY_MS, DEFAULT_LEAD_FRAMES, DEFAULT_MAX_LEAD_PX } from '../predictor.js' +import { createLeadRatchet } from '../ratchet.js' + +export const FRAME = 16.7 +/** What the newest sample's age measures at at 60Hz, per the example rig. */ +export const AGE = 13 +export const LEAD_FRAMES = DEFAULT_LEAD_FRAMES + +/** Refresh intervals worth replaying at. The lead is a count of refreshes, so each of these is a different + * horizon in milliseconds off the same hand. */ +export const HZ_30 = 1000 / 30 +export const HZ_60 = 1000 / 60 +export const HZ_120 = 1000 / 120 +export const HZ_144 = 1000 / 144 + +export type Vec = { x: number; y: number } +/** Where the hand is at a given moment, in pointer pixels. Continuous — the quantisation is the device's + * job, and modelling it here would hide the thing most likely to wreck a second derivative. */ +export type Path = (t: number) => Vec + +/** How a device reports: how often, how many at a time, how much its clock wanders, and how coarse a step + * one of its counts is worth. */ +export type Device = { + name: string + periodMs: number + burst: number + jitterMs: number + /** Pointer pixels per count. A high-DPI mouse at default sensitivity moves about a pixel per count; a low + * one moves several, and a fit over four of those is looking at a staircase rather than a path. */ + countPx: number +} + +const device = (name: string, periodMs: number, burst: number, jitterMs: number, countPx = 1): Device => ({ + name, + periodMs, + burst, + jitterMs, + countPx, +}) + +export const WIRED = device('wired', 1, 1, 0.1) +export const TRACKPAD = device('trackpad', 11, 1, 0.4) +/** A mouse on a radio: reports in clumps, and says nothing at all for a third of frames while moving. */ +export const BLUETOOTH = device('bluetooth', 8, 3, 2.5) +/** Slower still, and the one whose gaps most resemble a hand that has stopped. */ +export const SLOW_RADIO = device('slow radio', 16, 2, 3) +/** The default of every mouse that is not a gaming one: one report per 8ms, which is two per frame. */ +export const USB_125 = device('125Hz mouse', 8, 1, 0.5) +export const USB_500 = device('500Hz mouse', 2, 1, 0.2) +/** Eight reports per millisecond, so the window is full and every sample carries almost no motion — the + * case where a second derivative is being asked of nothing but quantisation. */ +export const USB_8K = device('8KHz mouse', 0.125, 1, 0.05) +/** Coarse counts: four pixels a step, which is what a low-DPI mouse reports. The path arrives as a + * staircase, and every noise floor in the fit is written in units of one count. */ +export const COARSE = device('low-DPI mouse', 8, 1, 0.5, 4) +/** Counts finer than a pixel, which is what a page at a device pixel ratio of two reports. The floors were + * tuned at a pixel and are held there rather than followed down: a device quieter than they assume costs a + * little sensitivity, and one noisier than they assume is the bug this is the other side of. */ +export const FINE = device('half-pixel mouse', 4, 1, 0.3, 0.5) +/** The sparsest thing that still calls itself a pointer: less than one report a frame, so most frames see + * nothing and the window holds two or three samples. */ +export const SPARSE = device('sparse', 25, 1, 4) + +/** The four the shipped figures are quoted against. */ +export const DEVICES: readonly Device[] = [WIRED, TRACKPAD, BLUETOOTH, SLOW_RADIO] +/** Every device, including the awkward ones that exist to be survived rather than to be fast. */ +export const ALL_DEVICES: readonly Device[] = [ + WIRED, + USB_8K, + USB_500, + USB_125, + TRACKPAD, + BLUETOOTH, + SLOW_RADIO, + COARSE, + FINE, + SPARSE, +] + +export type ReplayOptions = { + path: Path + device: Device + durationMs: number + /** Stalls one frame in this many to three times its length, as a real one does. 0 for none. */ + hitchEvery?: number + frameMs?: number + leadFrames?: number + decayMs?: number + maxLeadPx?: number + /** When scoring starts, so the window filling up is not read as steady-state behaviour. */ + scoreAfterMs?: number + /** How long before the frame the browser stops handing events over. A couple of milliseconds is an + * ordinary machine; a busy main thread, a compositor under load or a device driver having a bad day make + * it tens, and every one of them goes into the horizon as time the guess has to cover. */ + deliveryLagMs?: number + /** How many refreshes after a frame is drawn it reaches the screen — what the guess is scored against. + * Defaults to `leadFrames`, which is the assumption the lead is set from. */ + presentFrames?: number + seed?: number + /** Every frame as it happens, for the properties that are about each frame rather than about the run: a + * lead that is finite, inside the cap, and pointing somewhere the samples support. Scored frames only are + * not enough for those — a guess that goes wrong while the window is filling has still gone wrong. */ + onFrame?: (frame: { + /** Frame index from 1, and the clock reading it was drawn at. */ + index: number + frameAt: number + lead: { x: number; y: number; live: number } + /** Where the hand truly is, where the device has said it is, and what the screen would show. */ + hand: Vec + reported: Vec + shown: Vec + /** What the hand did since the previous frame. Zero while it is still. */ + handStep: Vec + }) => void +} + +export type Metrics = { + /** Frames scored, so a figure averaged over them can be read for what it is. */ + frames: number + /** Frame-to-frame move of the lead. On a hand doing nothing new every bit of it is jitter, and jitter on + * a camera is nauseating, so the worst one matters more than the average. */ + worstStep: number + meanStep: number + /** A step that is itself a change of step: the lead changing speed, which is what the eye reads as + * shaking rather than as motion. */ + worstJerk: number + /** How much the size of the guess jumps in one frame, and how much its heading jumps against the hand's. + * On a curving path most of `worstStep` is the lead legitimately swinging round with the hand — it is + * 10px a frame on an ordinary circle and none of it is jitter — so these two are what steadiness means + * anywhere except a straight line. Degrees for the second. */ + worstSizeStep: number + worstTurnStep: number + /** RMS distance from where the hand really is when this frame reaches the screen. */ + error: number + /** The same, for a caller that does not guess at all. The only thing `error` means anything against. */ + errorWithout: number + /** error / errorWithout. Under 1 is worth having; over 1 is worse than nothing. */ + gain: number + /** Mean signed distance along the way the hand is going: positive is systematically ahead of the hand, + * negative is systematically behind it. Which side of zero the errors sit on, rather than how big. */ + bias: number + /** Furthest past the hand the guess ever sat, along the way the hand is going. Lead that was never needed + * has to be handed back, and handing it back walks the view backwards under the hand. */ + worstOvershoot: number + /** Furthest behind the hand it ever sat: the lateness the library exists to remove. Scored apart from + * overshoot because the two are not the same mistake. */ + worstLate: number + /** Total on-screen travel against the way the hand is moving at that moment, over the whole run. Measured + * against what the hand did between these two frames rather than against a fixed direction, so a hand + * that genuinely turns round is not scored as the picture fighting it. Overshoot being handed back and + * jitter both land here, and this is the one artefact a camera cannot hide. */ + backwards: number + /** The worst of that in a single frame — one visible kick rather than a slow drift back. */ + worstBackwards: number + /** On-screen travel over frames where the hand is not moving at all: motion nobody asked for, in either + * direction. A guess still holding lead when the hand stops has to give every pixel of it back, and this + * is what that costs. */ + phantom: number + /** How unevenly the picture moves, in pixels: the worst frame's difference between how far the picture + * travelled and how far it should have. A hand at a constant speed makes a picture that moves the same + * distance every frame, and the eye reads any departure from that as a jump — which is not the same + * question as how far the guess is from the truth, and not the same question as how much the lead moved. + * A lead that jumps about to cancel a device reporting in clumps is doing its job. + * + * Two of them, because there are two ways to spend a lead and they judge it differently. The first is a + * caller with a true position to add the lead to. The second is a locked pointer, which has none and can + * only ever be pushed further along — `createLeadRatchet`, and the shape most of this library's callers + * are. A guess can be smooth for one and not the other. */ + worstJump: number + worstRatchetJump: number + worstLead: number + meanLead: number + /** How far the guessed position sits from the origin, averaged. Only means something on a circle, where + * it is the radius the guess draws against the radius the hand drew. */ + meanRadius: number + /** What a caller applying only the growth accumulates. Jitter is rectified into rotation there: every + * upward wobble is kept and none of the downward ones give it back. */ + kept: number + /** Frames the predictor called dead while the hand was in fact moving. A stop seen late is overshoot; a + * stop seen where there is none is the lead dropping out under a moving hand. */ + falseDeadFrames: number +} + +/** What a caller applying only the growth of the lead would keep from this frame: an axis moving further + * out in the direction it already pointed, and nothing given back when it comes in again. */ +const growth = (value: number, applied: number) => + value * applied >= 0 && Math.abs(value) > Math.abs(applied) ? value - applied : 0 + +/** An angle difference brought back into a half turn either side, so a swing past pi is read as the small + * turn it is rather than as a nearly whole one. */ +const wrapped = (angle: number) => { + let value = angle + while (value > Math.PI) value -= 2 * Math.PI + while (value < -Math.PI) value += 2 * Math.PI + return value +} + +/** + * One run of a hand along `path`, reported by `device`, read by a frame loop, scored against where the hand + * really is when each frame reaches the screen. + */ +export const replay = (options: ReplayOptions): Metrics => { + const { + path, + device: dev, + durationMs, + hitchEvery = 0, + frameMs = FRAME, + leadFrames = LEAD_FRAMES, + decayMs = DEFAULT_DECAY_MS, + maxLeadPx = DEFAULT_MAX_LEAD_PX, + scoreAfterMs = 600, + presentFrames = leadFrames, + deliveryLagMs = 2, + seed = 20260808, + onFrame, + } = options + + const predictor = createPointerPredictor() + const ratchet = createLeadRatchet() + let rndState = seed + const rnd = () => (rndState = (rndState * 1103515245 + 12345) & 0x7fffffff) / 0x7fffffff + + // Whole counts, and a count is not always a pixel. + const countPx = dev.countPx + const quantise = (value: number) => Math.trunc(value / countPx) * countPx + + let reportedX = 0 + let reportedY = 0 + let integratedX = 0 + let integratedY = 0 + let frameAt = 0 + let prevFrameAt = 0 + let nextReport = 0 + let previous: Vec | null = null + let previousStep: Vec | null = null + let previousShown: Vec | null = null + let keptX = 0 + let keptY = 0 + let appliedX = 0 + let appliedY = 0 + let worstStep = 0 + let stepSum = 0 + let worstJerk = 0 + let worstSizeStep = 0 + let worstTurnStep = 0 + let previousRelativeAngle: number | null = null + let previousHandAngle: number | null = null + let phantom = 0 + let worstJump = 0 + let worstRatchetJump = 0 + let previousTruth: Vec | null = null + let previousReported: Vec | null = null + let ratchetX = 0 + let ratchetY = 0 + let previousRatchetX = 0 + let previousRatchetY = 0 + let worstLead = 0 + let leadSum = 0 + let worstOvershoot = 0 + let worstLate = 0 + let backwards = 0 + let worstBackwards = 0 + let biasSum = 0 + let radialSum = 0 + let withSum = 0 + let withoutSum = 0 + let falseDeadFrames = 0 + let scored = 0 + + let frameIndex = 0 + while (frameAt <= durationMs) { + frameIndex++ + frameAt += frameMs * (hitchEvery > 0 && frameIndex % hitchEvery === 0 ? 3 : 1) + // Events are held until shortly before the callback, and arrive a burst at a time. + while (nextReport <= frameAt - deliveryLagMs) { + for (let b = 0; b < dev.burst; b++) { + const t = nextReport - (dev.burst - 1 - b) * dev.periodMs + (rnd() - 0.5) * dev.jitterMs + if (t <= 0) continue + const at = path(t) + const dx = quantise(at.x) - reportedX + const dy = quantise(at.y) - reportedY + if (dx !== 0 || dy !== 0) { + predictor.push(t, dx, dy) + reportedX += dx + reportedY += dy + integratedX += dx + integratedY += dy + } + } + nextReport += dev.periodMs * dev.burst + } + + // What the hand itself did over this frame, which is what everything on screen is judged against. Read + // before the frame clock moves on, since that is what it is a difference against. + const from = path(prevFrameAt) + const to = path(frameAt) + const handX = to.x - from.x + const handY = to.y - from.y + const handStep = Math.hypot(handX, handY) + const moving = handStep > 0.02 * (frameAt - prevFrameAt) + + const lead = predictor.update({ + nowMs: frameAt, + deltaMs: frameAt - prevFrameAt, + leadFrames, + decayMs, + maxLeadPx, + }) + prevFrameAt = frameAt + + keptX += growth(lead.x, appliedX) + keptY += growth(lead.y, appliedY) + appliedX = lead.x + appliedY = lead.y + + // Once the window is full of the motion rather than of starting up. + if (frameAt > scoreAfterMs) { + const step = previous ? Math.hypot(lead.x - previous.x, lead.y - previous.y) : 0 + if (previous) { + worstStep = Math.max(worstStep, step) + stepSum += step + const stepVec = { x: lead.x - previous.x, y: lead.y - previous.y } + if (previousStep) { + worstJerk = Math.max(worstJerk, Math.hypot(stepVec.x - previousStep.x, stepVec.y - previousStep.y)) + } + previousStep = stepVec + worstSizeStep = Math.max( + worstSizeStep, + Math.abs(Math.hypot(lead.x, lead.y) - Math.hypot(previous.x, previous.y)), + ) + } + // Where the guess points against where the hand is going. A lead swinging round with a turning hand + // holds this still; a lead being shaken about by noise does not. Below a pixel there is no heading to + // read and the size step has it covered, and a hand that has itself turned by a quarter turn between + // two frames is asking a question about the reversal rather than about steadiness. + const handAngle = Math.atan2(handY, handX) + const handTurned = previousHandAngle === null ? 0 : Math.abs(wrapped(handAngle - previousHandAngle)) + previousHandAngle = moving ? handAngle : null + if (moving && handTurned < Math.PI / 4 && Math.hypot(lead.x, lead.y) > 1) { + const relative = Math.atan2(lead.y, lead.x) - handAngle + if (previousRelativeAngle !== null) { + const turned = wrapped(relative - previousRelativeAngle) + worstTurnStep = Math.max(worstTurnStep, Math.abs((turned * 180) / Math.PI)) + } + previousRelativeAngle = relative + } else { + previousRelativeAngle = null + } + const truth = path(frameAt + presentFrames * frameMs) + + // How far past the hand the guess sits, along the way the hand is going. Overshooting and falling + // short are not the same error and are not worth scoring as one: lead that was never there has to + // be handed back, and handing it back is a reversal on screen, where falling short is only the + // lateness this whole thing exists to remove. + const ahead = path(frameAt + presentFrames * frameMs + 1) + const behind = path(frameAt + presentFrames * frameMs - 1) + const towardsX = ahead.x - behind.x + const towardsY = ahead.y - behind.y + const towards = Math.hypot(towardsX, towardsY) + const shownX = integratedX + lead.x + const shownY = integratedY + lead.y + if (towards > 1e-9) { + const past = ((shownX - truth.x) * towardsX + (shownY - truth.y) * towardsY) / towards + worstOvershoot = Math.max(worstOvershoot, past) + worstLate = Math.max(worstLate, -past) + biasSum += past + // The hand is demonstrably moving here, so a dead reading is the predictor losing a moving hand + // rather than noticing a stopped one. + if (moving && lead.live === 0) falseDeadFrames++ + } + // What the screen does against what the hand does over the same frame. A picture moving the other way + // is the guess handing something back, whether it was overshoot or noise; a picture moving at all + // while the hand is still is motion nobody asked for. + if (previousShown) { + const movedX = shownX - previousShown.x + const movedY = shownY - previousShown.y + if (moving) { + const along = (movedX * handX + movedY * handY) / handStep + if (along < 0) { + backwards -= along + worstBackwards = Math.max(worstBackwards, -along) + } + } else { + phantom += Math.hypot(movedX, movedY) + } + } + // How far the picture moved this frame against how far it should have. Both cameras are fed the same + // guess; they differ in what they are allowed to do with it. + const grew = ratchet.step(lead) + ratchetX += reportedX - (previousReported?.x ?? reportedX) + grew.x + ratchetY += reportedY - (previousReported?.y ?? reportedY) + grew.y + if (previousTruth && previousShown && previousReported) { + const wanted = Math.hypot(truth.x - previousTruth.x, truth.y - previousTruth.y) + worstJump = Math.max( + worstJump, + Math.abs(Math.hypot(shownX - previousShown.x, shownY - previousShown.y) - wanted), + ) + worstRatchetJump = Math.max( + worstRatchetJump, + Math.abs(Math.hypot(ratchetX - previousRatchetX, ratchetY - previousRatchetY) - wanted), + ) + } + previousRatchetX = ratchetX + previousRatchetY = ratchetY + previousTruth = truth + previousReported = { x: reportedX, y: reportedY } + withSum += (shownX - truth.x) ** 2 + (shownY - truth.y) ** 2 + withoutSum += (integratedX - truth.x) ** 2 + (integratedY - truth.y) ** 2 + radialSum += Math.hypot(shownX, shownY) + const magnitude = Math.hypot(lead.x, lead.y) + worstLead = Math.max(worstLead, magnitude) + leadSum += magnitude + previousShown = { x: shownX, y: shownY } + scored++ + } + previous = { x: lead.x, y: lead.y } + onFrame?.({ + index: frameIndex, + frameAt, + lead: { x: lead.x, y: lead.y, live: lead.live }, + hand: to, + reported: { x: reportedX, y: reportedY }, + shown: { x: integratedX + lead.x, y: integratedY + lead.y }, + handStep: { x: handX, y: handY }, + }) + } + + const frames = Math.max(1, scored) + const error = Math.sqrt(withSum / frames) + const errorWithout = Math.sqrt(withoutSum / frames) + return { + frames: scored, + worstStep, + meanStep: stepSum / frames, + worstJerk, + worstSizeStep, + worstTurnStep, + error, + errorWithout, + gain: errorWithout > 1e-9 ? error / errorWithout : error > 1e-9 ? Infinity : 0, + bias: biasSum / frames, + worstOvershoot, + worstLate, + backwards, + worstBackwards, + phantom, + worstJump, + worstRatchetJump, + worstLead, + meanLead: leadSum / frames, + meanRadius: radialSum / frames, + kept: Math.hypot(keptX, keptY), + falseDeadFrames, + } +} + +/** The worst reading of every number across a set of devices, which is what a floor has to hold at. */ +export const worstAcross = (devices: readonly Device[], options: Omit