Aliasing and the sampling theorem: why wagon wheels turn backward on film

// game.js: a wheel with eight spokes, filmed by a camera. Set the wheel's speed and the camera's frame rate,
// and compare the wheel on film with its true motion and the brightness of one spot with the camera's samples.
// The notebook writes the constants and the sawtooth (speed on film against true speed) into #data.
"use strict";

const DATA = JSON.parse(document.getElementById("data").textContent);
const N = DATA.n_spokes;
const STEPS_PER_REV = Math.round(1 / DATA.speed_step);         // 20 slider steps per rev/s
const MAX_STEPS = Math.round(DATA.speed_max * STEPS_PER_REV);
const WINDOW = DATA.window_s;                                   // the sine panel shows the last 0.5 s

// ---- the state: everything that changes, in one object
const DEFAULTS = {speedSteps: Math.round(DATA.start.speed * STEPS_PER_REV), fps: DATA.fps_steps.indexOf(DATA.start.fps), showTrue: false};
const state = {...DEFAULTS, running: true, t: 0, turns: 0, filmTurns: 0, frameTime: 0, blur: 0};
const speed = (s) => s.speedSteps / STEPS_PER_REV;             // rev/s; a count of steps, so a tie is exact
const fps = (s) => DATA.fps_steps[s.fps];

// The speed on film: the step per frame in spoke spacings, rounded to the nearest whole spoke; the eye sees the rest.
function apparentSpeed(r, fs) {
  const x = N * r / fs;                                         // the step per frame, in spoke spacings
  return r - fs / N * Math.floor(x + 0.5);                      // floor(x + 0.5): a half goes up, as in the notebook
}
const isTie = (r, fs) => (N * r / fs) % 1 === 0.5;

// One tick: the true wheel turns on; the camera holds the wheel as it was at its last frame, k / fs.
function tick(dt) {
  const r = speed(state), fs = fps(state);
  state.t += dt;
  state.turns += r * dt;
  const k = Math.floor(state.t * fs);                           // the frame on film
  state.frameTime = k / fs;
  state.filmTurns = state.turns - r * (state.t - state.frameTime);
  state.blur = dt;                                              // the true wheel is smeared over the last refresh
}
// the true angle in turns at an earlier time tp, at the current speed
const turnsAt = (tp) => state.turns - speed(state) * (state.t - tp);

// ---- drawing
const $ = (id) => document.getElementById(id);
const canvas = $("scene"), strip = $("strip");
let dpr = 1;

function fit(c) {
  const box = c.getBoundingClientRect();
  c.width = Math.round(box.width * dpr);
  c.height = Math.round(box.height * dpr);
}
function layout() {
  dpr = window.devicePixelRatio || 1;
  fit(canvas);
  fit(strip);
  render();
}

function colors() {
  const css = getComputedStyle(document.documentElement);
  return Object.fromEntries(["bg", "fg", "ink", "accent", "second", "muted", "pale"].map((k) => [k, css.getPropertyValue(`--${k}`).trim()]));
}

function spokes(ctx, cx, cy, R, turns) {
  ctx.beginPath();
  for (let i = 0; i < N; i++) {
    const a = 2 * Math.PI * (turns + i / N) - Math.PI / 2;      // clockwise on screen: the wheel rolls to the right
    ctx.moveTo(cx + 0.12 * R * Math.cos(a), cy + 0.12 * R * Math.sin(a));
    ctx.lineTo(cx + R * Math.cos(a), cy + R * Math.sin(a));
  }
  ctx.stroke();
}

// The wheel in a frame of film: sprocket holes above and below, the ground, the true wheel faintly behind.
function drawWheel(ctx, c, box) {
  const pad = 6, hole = Math.max(5, Math.min(box.w, box.h) / 28);
  ctx.strokeStyle = c.muted; ctx.fillStyle = c.muted; ctx.lineWidth = 1.5;
  ctx.strokeRect(box.x + pad, box.y + pad, box.w - 2 * pad, box.h - 2 * pad);
  for (let x = box.x + pad + hole; x < box.x + box.w - pad - hole; x += 2.2 * hole) {
    for (const y of [box.y + pad + 0.6 * hole, box.y + box.h - pad - 1.6 * hole]) ctx.fillRect(x, y, hole, hole);
  }
  const inner = {x: box.x + pad, y: box.y + pad + 2.4 * hole, w: box.w - 2 * pad, h: box.h - 2 * pad - 4.8 * hole};
  const R = 0.4 * Math.min(inner.w, inner.h), cx = inner.x + inner.w / 2, cy = inner.y + inner.h / 2 - 0.04 * R;
  const lw = Math.max(2, R / 28);
  ctx.beginPath(); ctx.moveTo(inner.x + 0.1 * inner.w, cy + R + lw); ctx.lineTo(inner.x + 0.9 * inner.w, cy + R + lw); ctx.stroke();  // ground
  ctx.beginPath(); ctx.moveTo(cx, cy - R - 0.22 * R); ctx.lineTo(cx, cy - R - 0.08 * R); ctx.stroke();                              // fixed tick
  if (state.showTrue) {                                          // a few faint copies over the last refresh, as the eye blurs it
    const copies = 6, r = speed(state);
    ctx.strokeStyle = c.second; ctx.lineWidth = lw; ctx.globalAlpha = 0.5 / Math.sqrt(copies);
    for (let j = 0; j < copies; j++) spokes(ctx, cx, cy, 0.97 * R, state.turns - r * state.blur * j / (copies - 1 || 1));
    ctx.globalAlpha = 1;
  }
  ctx.strokeStyle = c.ink; ctx.lineWidth = lw;
  spokes(ctx, cx, cy, R, state.filmTurns);
  ctx.lineWidth = 1.6 * lw;
  ctx.beginPath(); ctx.arc(cx, cy, R, 0, 2 * Math.PI); ctx.stroke();                                                              // rim
  ctx.fillStyle = c.ink;
  ctx.beginPath(); ctx.arc(cx, cy, 0.12 * R, 0, 2 * Math.PI); ctx.fill();                                                         // hub
  ctx.fillStyle = c.muted; ctx.strokeStyle = c.bg; ctx.lineWidth = 2;
  ctx.beginPath(); ctx.arc(cx, cy - R, Math.max(5, R / 14), 0, 2 * Math.PI); ctx.fill(); ctx.stroke();                            // the spot
}

// The brightness of the marked spot over the last WINDOW seconds of film, modeled as sin(2π N turns):
// the true sine, the camera's samples as dots, and the slow sine that runs through the dots.
function drawSine(ctx, c, box) {
  const r = speed(state), fs = fps(state), f = N * r, fa = N * apparentSpeed(r, fs);
  const font = Math.max(14, Math.min(16, box.h / 9)), pad = 8;
  const top = box.y + pad + 1.4 * font, bottom = box.y + box.h - pad - 1.3 * font;
  const left = box.x + pad, width = box.w - 2 * pad, mid = (top + bottom) / 2, amp = (bottom - top) / 2 * 0.9;
  const t1 = state.frameTime, t0 = t1 - WINDOW;
  const X = (tp) => left + (tp - t0) / WINDOW * width, Y = (b) => mid - amp * b;
  const brightness = (tp) => Math.sin(2 * Math.PI * N * turnsAt(tp));
  // the slow sine: the true phase minus a whole number of turns per sample, so it meets every dot
  const seen = (tp) => Math.sin(2 * Math.PI * N * turnsAt(tp) - 2 * Math.PI * (f - fa) * tp);
  ctx.strokeStyle = c.muted; ctx.lineWidth = 1;
  ctx.beginPath(); ctx.moveTo(left, mid); ctx.lineTo(left + width, mid); ctx.stroke();
  const curve = (g, color, lw) => {
    const n = Math.max(2, Math.round(width));
    ctx.strokeStyle = color; ctx.lineWidth = lw;
    ctx.beginPath();
    for (let i = 0; i <= n; i++) {
      const tp = t0 + WINDOW * i / n;
      if (i) ctx.lineTo(X(tp), Y(g(tp))); else ctx.moveTo(X(tp), Y(g(tp)));
    }
    ctx.stroke();
  };
  if (state.showTrue) curve(brightness, c.second, 1.2);
  curve(seen, c.accent, 2.2);
  ctx.fillStyle = c.ink;
  for (let k = Math.ceil(t0 * fs - 1e-9); k <= Math.round(t1 * fs); k++) {
    ctx.beginPath(); ctx.arc(X(k / fs), Y(brightness(k / fs)), 4, 0, 2 * Math.PI); ctx.fill();
  }
  ctx.font = `${font}px system-ui, sans-serif`; ctx.textBaseline = "top";
  ctx.textAlign = "left"; ctx.fillStyle = c.second;
  ctx.fillText(`true ${f.toFixed(1)} Hz`, left, box.y + pad);
  ctx.textAlign = "right"; ctx.fillStyle = c.accent;
  ctx.fillText(`seen ${Math.abs(fa).toFixed(1)} Hz`, left + width, box.y + pad);
  ctx.textAlign = "left"; ctx.textBaseline = "bottom"; ctx.fillStyle = c.muted;
  ctx.fillText(`spot's brightness, last ${WINDOW} s`, left, box.y + box.h - 2);
}

// The strip under the slider: the speed on film against the true speed for this frame rate, on the slider's scale.
function drawStrip(c) {
  const ctx = strip.getContext("2d");
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
  const W = strip.width / dpr, H = strip.height / dpr, inset = 11;   // the slider's thumb stops short of the ends
  ctx.clearRect(0, 0, W, H);
  const fs = fps(state), top = fs / (2 * N), values = DATA.sawtooth[String(fs)];
  const X = (i) => inset + i / MAX_STEPS * (W - 2 * inset), Y = (v) => H / 2 - v / top * (H / 2 - 4);
  ctx.strokeStyle = c.muted; ctx.lineWidth = 1;
  ctx.beginPath(); ctx.moveTo(X(0), Y(0)); ctx.lineTo(X(MAX_STEPS), Y(0)); ctx.stroke();      // zero on film
  ctx.strokeStyle = c.accent; ctx.lineWidth = 1.8;
  ctx.beginPath();
  values.forEach((v, i) => {                                    // lift the pen at every jump of the sawtooth
    if (i && Math.abs(v - values[i - 1]) < top) ctx.lineTo(X(i), Y(v)); else ctx.moveTo(X(i), Y(v));
  });
  ctx.stroke();
  ctx.fillStyle = c.accent;
  ctx.beginPath(); ctx.arc(X(state.speedSteps), Y(values[state.speedSteps]), 5, 0, 2 * Math.PI); ctx.fill();
}

function drawScene(c) {
  const ctx = canvas.getContext("2d");
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
  const W = canvas.width / dpr, H = canvas.height / dpr;
  ctx.fillStyle = c.bg;
  ctx.fillRect(0, 0, W, H);
  const wide = W > 1.25 * H;                                    // side by side, or the wheel above the sine panel
  const wheel = wide ? {x: 0, y: 0, w: Math.min(0.5 * W, H * 1.15), h: H} : {x: 0, y: 0, w: W, h: 0.6 * H};
  const sine = wide ? {x: wheel.w + 8, y: 0.1 * H, w: W - wheel.w - 8, h: 0.8 * H} : {x: 0, y: 0.6 * H + 4, w: W, h: 0.4 * H - 4};
  drawWheel(ctx, c, wheel);
  drawSine(ctx, c, sine);
}

const signed = (v) => (v > 0 ? "+" : v < 0 ? "−" : "") + Math.abs(v).toFixed(2);
function render() {
  const c = colors(), r = speed(state), fs = fps(state), ra = apparentSpeed(r, fs);
  drawScene(c);
  drawStrip(c);
  const tie = isTie(r, fs);
  $("film").textContent = `on film ${tie ? "±" + Math.abs(ra).toFixed(2) : signed(ra)} rev/s`;
  $("verdict").textContent = tie ? "either way" : Math.abs(ra) < 1e-9 ? "standing" : ra < 0 ? "backward" : "forward";
  $("true").textContent = `true ${r.toFixed(2)} rev/s`;
  $("speed").value = state.speedSteps;
  $("fps-val").textContent = `${fs} fps`;
  $("slower").disabled = state.speedSteps === 0;
  $("faster").disabled = state.speedSteps === MAX_STEPS;
  $("fewer").disabled = state.fps === 0;
  $("more").disabled = state.fps === DATA.fps_steps.length - 1;
  $("show-true").setAttribute("aria-pressed", state.showTrue);
  $("play").textContent = state.running ? "Pause" : "Play";
}

// ---- controls, keys, and the frame
function set(partial) {
  const p = {...partial};
  if ("speed" in p) { p.speedSteps = Math.round(p.speed * STEPS_PER_REV); delete p.speed; }   // rev/s from outside
  if ("fps" in p) p.fps = DATA.fps_steps.indexOf(p.fps);       // frames per second, kept as an index into the steps
  Object.assign(state, p);
  state.speedSteps = Math.min(MAX_STEPS, Math.max(0, state.speedSteps));
  tick(0);
  render();
}
const nudge = (k) => set({speedSteps: state.speedSteps + k});
const stepFps = (k) => set({fps: DATA.fps_steps[Math.min(DATA.fps_steps.length - 1, Math.max(0, state.fps + k))]});
const actions = {
  slower: () => nudge(-1), faster: () => nudge(1), fewer: () => stepFps(-1), more: () => stepFps(1),
  "show-true": () => set({showTrue: !state.showTrue}), play: () => set({running: !state.running}),
  reset: () => set({...DEFAULTS, fps: DATA.start.fps}),
};
for (const [id, act] of Object.entries(actions)) $(id).addEventListener("click", act);
$("speed").addEventListener("input", (e) => set({speedSteps: Number(e.target.value)}));
const keys = {arrowleft: "slower", arrowright: "faster", "[": "fewer", "]": "more", t: "show-true", " ": "play", r: "reset"};
document.addEventListener("keydown", (e) => {
  const key = keys[e.key.toLowerCase()];
  if (!key || (e.target instanceof HTMLInputElement && e.key.startsWith("Arrow"))) return;   // the slider steps itself
  if (e.target instanceof HTMLButtonElement && e.key === " ") return;
  e.preventDefault();
  actions[key]();
});

let last = null;
function frame(now) {                                           // called by the browser once per screen refresh
  const elapsed = last === null ? 0 : Math.min((now - last) / 1000, 0.05);   // capped: a background tab does not jump
  last = now;
  tick(state.running ? elapsed : 0);
  render();
  requestAnimationFrame(frame);
}

const fitter = new ResizeObserver(layout);                       // refit both canvases whenever the grid moves them
fitter.observe($("view"));
fitter.observe(strip);
$("speed").max = MAX_STEPS;
layout();
requestAnimationFrame(frame);
window.game = {state, set, render};