geotimelapse 0.1.0

package/src/geo-timelapse.tsx

@@ -0,0 +1,204 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { MapBoundsProvider } from './bounds.js';
+import { DAY_SECONDS, TimelapseClockProvider, useTimelapseClock } from './clock.js';
+import Counter from './counter.js';
+import { useAdaptiveTrailFrames, useFps, useFrameHistory, useMinuteActivity } from './hooks.js';
+import TimelapseMap from './map.js';
+import PlayerBar from './player-bar.js';
+import SettingsMenu from './settings-menu.js';
+import type { GeoTimelapseProps, MapBounds } from './types.js';
+
+const defaultFormat = (value: number) => Math.round(value).toLocaleString('en-US');
+
+function Stage({
+  source,
+  mapboxAccessToken,
+  initialBounds,
+  tuning,
+  dateLabel,
+  timeZoneLabel,
+  formatValue = defaultFormat,
+  formatCount = defaultFormat,
+}: GeoTimelapseProps) {
+  const clock = useTimelapseClock();
+  const stageRef = useRef<HTMLDivElement>(null);
+  const [fullscreen, setFullscreen] = useState(false);
+  const [loop, setLoop] = useState(true);
+  const [scoped, setScoped] = useState(true);
+  const [progress, setProgress] = useState<{ loadedBytes: number; totalBytes: number } | null>(null);
+  const [ready, setReady] = useState(false);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  // Bumped after every completed re-scope so readers re-query the source.
+  const [scopeVersion, setScopeVersion] = useState(0);
+  // Mouse-idle state: the settings gear and the cursor itself fade out so
+  // nothing overlays a TV-screen replay; any mouse move brings them back.
+  const [uiVisible, setUiVisible] = useState(true);
+  const [bounds, setBounds] = useState<MapBounds | null>(null);
+
+  const frames = useFrameHistory(source, ready);
+  const trailFrames = useAdaptiveTrailFrames();
+  const fps = useFps();
+  const activity = useMinuteActivity(source, ready, scopeVersion);
+
+  const onBoundsChange = useCallback((next: MapBounds) => {
+    setBounds((prev) =>
+      prev &&
+      prev.west === next.west &&
+      prev.south === next.south &&
+      prev.east === next.east &&
+      prev.north === next.north
+        ? prev
+        : next,
+    );
+  }, []);
+
+  // Load the day once, then start the replay. A swapped source re-gates every
+  // reader until its own load resolves.
+  useEffect(() => {
+    let disposed = false;
+    // Re-gating must track the source swap itself, not a render.
+    // oxlint-disable-next-line react/set-state-in-effect
+    setReady(false);
+    setProgress(null);
+    setLoadError(null);
+    source
+      .load((loadedBytes, totalBytes) => {
+        if (!disposed) setProgress({ loadedBytes, totalBytes });
+      })
+      .then(() => {
+        if (disposed) return;
+        setReady(true);
+        clock.play();
+      })
+      .catch((error: unknown) => {
+        if (!disposed) setLoadError(error instanceof Error ? error.message : String(error));
+      });
+    return () => {
+      disposed = true;
+    };
+  }, [source, clock]);
+
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout>;
+    const show = () => {
+      setUiVisible(true);
+      clearTimeout(timer);
+      timer = setTimeout(() => setUiVisible(false), 5000);
+    };
+    show();
+    window.addEventListener('pointermove', show);
+    return () => {
+      clearTimeout(timer);
+      window.removeEventListener('pointermove', show);
+    };
+  }, []);
+
+  useEffect(() => {
+    const onChange = () => setFullscreen(document.fullscreenElement === stageRef.current);
+    document.addEventListener('fullscreenchange', onChange);
+    return () => document.removeEventListener('fullscreenchange', onChange);
+  }, []);
+
+  // Unscoping goes back to the whole world, once per toggle.
+  useEffect(() => {
+    if (!ready || scoped) return;
+    let disposed = false;
+    void source.setScope(null).then(() => {
+      if (!disposed) setScopeVersion((version) => version + 1);
+    });
+    return () => {
+      disposed = true;
+    };
+  }, [source, scoped, ready]);
+
+  // Re-scope the aggregates once the viewport settles.
+  useEffect(() => {
+    if (!ready || !scoped || !bounds) return;
+    let disposed = false;
+    const handle = setTimeout(
+      () =>
+        void source.setScope(bounds).then(() => {
+          if (!disposed) setScopeVersion((version) => version + 1);
+        }),
+      400,
+    );
+    return () => {
+      disposed = true;
+      clearTimeout(handle);
+    };
+  }, [source, bounds, scoped, ready]);
+
+  // The clock pauses at the end of the day; loop restarts it (play() rewinds).
+  useEffect(() => {
+    if (!loop) return;
+    return clock.subscribe(() => {
+      if (!clock.isPlaying() && clock.getDaySeconds() >= DAY_SECONDS) clock.play();
+    });
+  }, [loop, clock]);
+
+  const toggleFullscreen = () => {
+    if (document.fullscreenElement) void document.exitFullscreen();
+    else void stageRef.current?.requestFullscreen();
+  };
+
+  return (
+    <div
+      ref={stageRef}
+      className={[
+        'relative h-full w-full overflow-hidden bg-black',
+        /* important beats the inline cursor deck.gl sets on its canvas */
+        uiVisible ? '' : 'cursor-none! **:cursor-none!',
+      ].join(' ')}
+    >
+      <TimelapseMap
+        frames={frames.slice(0, trailFrames)}
+        mapboxAccessToken={mapboxAccessToken}
+        initialBounds={initialBounds}
+        tuning={tuning}
+        onBoundsChange={onBoundsChange}
+      />
+      <MapBoundsProvider value={bounds}>
+        <SettingsMenu
+          visible={uiVisible}
+          fullscreen={fullscreen}
+          onToggleFullscreen={toggleFullscreen}
+          loop={loop}
+          onToggleLoop={() => setLoop((value) => !value)}
+          scoped={scoped}
+          onToggleScoped={() => setScoped((value) => !value)}
+          frame={frames[0]}
+          fps={fps}
+          trailFrames={trailFrames}
+        />
+        <Counter
+          source={source}
+          ready={ready}
+          error={loadError}
+          progress={progress}
+          scopeVersion={scopeVersion}
+          dateLabel={dateLabel}
+          timeZoneLabel={timeZoneLabel}
+          formatValue={formatValue}
+          formatCount={formatCount}
+        />
+      </MapBoundsProvider>
+      <PlayerBar activity={activity} />
+    </div>
+  );
+}
+
+/**
+ * A full-day replay of geolocated events: dark glowing map, waveform seek
+ * bar, running totals, and a TV mode (autoplay, loop, self-hiding UI).
+ * Fills its parent — give the wrapping element an explicit size.
+ */
+export function GeoTimelapse(props: GeoTimelapseProps) {
+  return (
+    <TimelapseClockProvider>
+      <Stage {...props} />
+    </TimelapseClockProvider>
+  );
+}

package/src/glow-layer.test.ts

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { buildGlowLayers, DEFAULT_GLOW_TUNING } from './glow-layer.js';
+import type { FrameBids } from './hooks.js';
+
+function frame(key: number): FrameBids {
+  return { key, positions: new Float32Array([0, 0]), radii: new Float32Array([1]), count: 1, queryMs: 0 };
+}
+
+const fillAlpha = (layer: ReturnType<typeof buildGlowLayers>[number]) =>
+  (layer.props.getFillColor as unknown as number[])[3];
+
+test('layer ids are stable ring-buffer slots', () => {
+  const layers = buildGlowLayers([frame(14), frame(13), frame(12)]);
+  assert.deepEqual(
+    layers.map((layer) => layer.id),
+    ['glow-2', 'glow-1', 'glow-0'],
+  );
+});
+
+test('radii taper with age from the flash down to the ghost floor', () => {
+  const frames = Array.from({ length: DEFAULT_GLOW_TUNING.trailFrames }, (_, age) => frame(23 - age));
+  const scales = buildGlowLayers(frames).map((layer) => layer.props.radiusScale);
+  assert.equal(scales[0], DEFAULT_GLOW_TUNING.flashRadius);
+  assert.equal(scales[1], DEFAULT_GLOW_TUNING.ghostMaxRadius);
+  assert.equal(scales.at(-1), DEFAULT_GLOW_TUNING.ghostMinRadius);
+  for (let age = 2; age < scales.length; age++) assert.ok(scales[age] < scales[age - 1]);
+});
+
+test('the pixel floor tapers with the same ratio as the radius', () => {
+  const layers = buildGlowLayers([frame(1), frame(0)]);
+  const { minRadiusPx, flashRadius, ghostMaxRadius } = DEFAULT_GLOW_TUNING;
+  assert.equal(layers[0].props.radiusMinPixels, minRadiusPx);
+  assert.equal(layers[1].props.radiusMinPixels, (minRadiusPx * ghostMaxRadius) / flashRadius);
+});
+
+test('ghosts fade geometrically in the fill alpha', () => {
+  const frames = Array.from({ length: 3 }, (_, age) => frame(2 - age));
+  const alphas = buildGlowLayers(frames).map(fillAlpha);
+  assert.equal(alphas[0], DEFAULT_GLOW_TUNING.pointAlpha);
+  assert.equal(alphas[1], Math.round(DEFAULT_GLOW_TUNING.pointAlpha * 0.8));
+  assert.equal(alphas[2], Math.round(DEFAULT_GLOW_TUNING.pointAlpha * 0.8 ** 2));
+});
+
+test('tuning overrides reach the layers', () => {
+  const [layer] = buildGlowLayers([frame(0)], { ...DEFAULT_GLOW_TUNING, pointAlpha: 50, maxRadiusPx: 42 });
+  assert.equal(fillAlpha(layer), 50);
+  assert.equal(layer.props.radiusMaxPixels, 42);
+  assert.equal(layer.props.radiusUnits, 'meters');
+});

package/src/glow-layer.ts

@@ -0,0 +1,166 @@
+import { ScatterplotLayer } from 'deck.gl';
+
+import type { FrameBids } from './hooks.js';
+
+// ScatterplotLayer with the disc fill replaced by a point light: a ~1px core
+// plus an inverse-square halo. Rendered additively (see GLOW_PARAMETERS), so
+// stacked points accumulate into a bloom that reveals density.
+const fs = /* glsl */ `\
+#version 300 es
+#define SHADER_NAME glow-layer-fragment-shader
+
+precision highp float;
+
+in vec4 vFillColor;
+in vec2 unitPosition;
+in float outerRadiusPixels;
+in float vSqrtWeight;
+in float vSoftRadiusPixels;
+
+out vec4 fragColor;
+
+void main(void) {
+  geometry.uv = unitPosition;
+
+  float distPixels = length(unitPosition) * outerRadiusPixels;
+  float core = smoothstep(1.4, 0.3, distPixels);
+  // Gaussian halo: a soft, wide shoulder instead of a spiky falloff, with a
+  // per-point amplitude low enough that white needs hundreds of stacked
+  // points — that slow additive build-up is what reads as glow. Its sigma
+  // follows the soft-capped radius so heavy stacks stay distinguishable.
+  float sigma = vSoftRadiusPixels * 0.35;
+  // Aggregation collapsed stacked points into one draw; sqrt(weight) raises
+  // the halo AMPLITUDE rather than the summed profile, so heavy stacks keep a
+  // gaussian gradient instead of clipping into a flat disc. The exponential
+  // shoulder (film-exposure response) approaches 1 without ever clipping, so
+  // intensity keeps discriminating stack sizes. Weight 1 is near-identical.
+  float gain = 1.0 - exp(-vSqrtWeight * 0.035);
+  float halo = gain * exp(-distPixels * distPixels / (2.0 * sigma * sigma));
+  // The core reads pure white; the halo carries the fill color's tint.
+  vec3 color = mix(vFillColor.rgb, vec3(1.0), core);
+  fragColor = vec4(color, vFillColor.a * min(core + halo, 1.0));
+
+  DECKGL_FILTER_COLOR(fragColor, geometry);
+}
+`;
+
+export default class GlowLayer<DataT> extends ScatterplotLayer<DataT> {
+  static layerName = 'GlowLayer';
+
+  getShaders() {
+    return {
+      ...super.getShaders(),
+      fs,
+      // The radius attribute carries sqrt(weight); hand it to the fragment
+      // stage, along with a soft-capped radius: instead of the hard clamp at
+      // radiusMaxPixels, tanh approaches it asymptotically so ever-heavier
+      // stacks keep growing (less and less) instead of all looking alike.
+      inject: {
+        'vs:#decl': 'out float vSqrtWeight;\nout float vSoftRadiusPixels;',
+        'vs:#main-end': `\
+vSqrtWeight = instanceRadius;
+float rawRadiusPixels = project_size_to_pixel(scatterplot.radiusScale * instanceRadius, scatterplot.radiusUnits);
+vSoftRadiusPixels = max(
+  scatterplot.radiusMaxPixels * tanh(rawRadiusPixels / scatterplot.radiusMaxPixels),
+  scatterplot.radiusMinPixels
+);`,
+      },
+    };
+  }
+}
+
+// Additive blending: overlapping halos sum toward white instead of occluding.
+export const GLOW_PARAMETERS = {
+  blendColorOperation: 'add',
+  blendColorSrcFactor: 'src-alpha',
+  blendColorDstFactor: 'one',
+  blendAlphaOperation: 'add',
+  blendAlphaSrcFactor: 'one',
+  blendAlphaDstFactor: 'one',
+} as const;
+
+/**
+ * The visual knobs of the glow trail. Radii are ground distances in meters so
+ * the on-screen density — and therefore the additive glow intensity — stays
+ * invariant across zoom levels.
+ */
+export interface GlowTuning {
+  /** Master per-point transparency, 0-255: density does the brightening. */
+  pointAlpha: number;
+  /** Halo tint; the shader keeps the point core pure white. */
+  haloTint: [number, number, number];
+  /** Radius of the freshest frame's points, in meters (per unit of weight). */
+  flashRadius: number;
+  /** Ghost radii taper linearly from this down to ghostMinRadius, in meters. */
+  ghostMaxRadius: number;
+  ghostMinRadius: number;
+  /** Floor in pixels so isolated points survive deep zoom-outs. Applies to
+   *  the freshest frame; ghosts get it scaled down with their age taper. */
+  minRadiusPx: number;
+  /** Asymptote of the rendered radius, in pixels: the halo tends toward it
+   *  (tanh) as stacks grow, without ever flattening against a hard clamp. */
+  maxRadiusPx: number;
+  /** How many past frames stay visible as fading ghosts. */
+  trailFrames: number;
+}
+
+// Defaults calibrated on the glow-lab bench (apps/website /lab/glow); the
+// ghost radii keep the 2/3 and 1/15 taper ratios of the flash radius.
+export const DEFAULT_GLOW_TUNING: GlowTuning = {
+  pointAlpha: 115,
+  haloTint: [190, 222, 255],
+  flashRadius: 80_000,
+  ghostMaxRadius: 53_000,
+  ghostMinRadius: 5_000,
+  minRadiusPx: 12,
+  maxRadiusPx: 80,
+  trailFrames: 12,
+};
+
+function radiusForAge(age: number, tuning: GlowTuning): number {
+  if (age === 0) return tuning.flashRadius;
+  const taper = (age - 1) / Math.max(tuning.trailFrames - 2, 1);
+  return tuning.ghostMaxRadius - (tuning.ghostMaxRadius - tuning.ghostMinRadius) * taper;
+}
+
+// Ghosts fade geometrically with age. Applied in the fill color, not the
+// layer opacity — deck gamma-corrects opacity (^1/2.2), which would keep the
+// oldest ghost at ~32% instead of ~9%.
+const GHOST_FADE = 0.8;
+
+function alphaForFrame(age: number, tuning: GlowTuning): number {
+  return Math.round(tuning.pointAlpha * GHOST_FADE ** age);
+}
+
+/**
+ * One layer per remembered frame, fading and tightening with age into a ghost
+ * trail. The layer id is the frame's ring-buffer slot: a slot's data only
+ * changes when its frame rotates out, so per tick a single layer re-uploads
+ * attributes. Pure: same frames + tuning, same layers.
+ */
+export function buildGlowLayers(frames: FrameBids[], tuning: GlowTuning = DEFAULT_GLOW_TUNING): GlowLayer<unknown>[] {
+  return frames.map(
+    (frame, age) =>
+      new GlowLayer({
+        id: `glow-${frame.key % tuning.trailFrames}`,
+        data: {
+          length: frame.count,
+          attributes: {
+            // sqrt(weight) radii: point AREA stays linear in the weight.
+            getPosition: { value: frame.positions, size: 2 },
+            getRadius: { value: frame.radii, size: 1 },
+          },
+        },
+        getFillColor: [...tuning.haloTint, alphaForFrame(age, tuning)],
+        // Fill-rate is the frame budget: cost grows with the quad area (r²),
+        // so ghost frames shrink with age — the glow cools as it fades. The
+        // pixel floor tapers along, or it would resurrect every ghost.
+        radiusScale: radiusForAge(age, tuning),
+        radiusMinPixels: (tuning.minRadiusPx * radiusForAge(age, tuning)) / tuning.flashRadius,
+        radiusMaxPixels: tuning.maxRadiusPx,
+        radiusUnits: 'meters',
+        stroked: false,
+        parameters: GLOW_PARAMETERS,
+      }),
+  );
+}

package/src/hooks.ts

@@ -0,0 +1,167 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { useTimelapseClock } from './clock.js';
+import type { GeoTimelapseSource } from './types.js';
+
+// One clock tick of replayed time (480x speed, 24 ticks/s).
+const DEFAULT_WINDOW_S = 20;
+// Widened-window cap when ticks were skipped (slow queries, render lag).
+// Kept tight: giant catch-up frames feed the lag they compensate for.
+const MAX_WINDOW_S = 3 * DEFAULT_WINDOW_S;
+
+export interface FrameBids {
+  /** Monotonic frame number, also the identity of the frame's layer slot. */
+  key: number;
+  /** Interleaved [lon, lat] pairs, one per distinct location, ready for a binary deck.gl attribute. */
+  positions: Float32Array;
+  /** Per-location sqrt(weight): scaling the radius by it keeps the point AREA linear in the weight. */
+  radii: Float32Array;
+  /** Distinct locations in the frame (the instance count). */
+  count: number;
+  queryMs: number;
+}
+
+/** How many past frames stay visible as fading ghost trails. */
+export const FRAME_HISTORY = 12;
+
+/**
+ * The last FRAME_HISTORY frames of events, newest first. Each frame holds
+ * the window since the frame before it; a seek resets the history.
+ */
+export function useFrameHistory(source: GeoTimelapseSource, ready: boolean): FrameBids[] {
+  const clock = useTimelapseClock();
+  const [frames, setFrames] = useState<FrameBids[]>([]);
+
+  useEffect(() => {
+    if (!ready) return;
+    let disposed = false;
+    let inFlight = false;
+    let lastQueried = -1;
+    let lastEpoch = -1;
+    let frameKey = 0;
+
+    const query = async () => {
+      const daySeconds = Math.floor(clock.getDaySeconds());
+      const epoch = clock.getEpoch();
+      if (inFlight || (daySeconds === lastQueried && epoch === lastEpoch)) return;
+      inFlight = true;
+      try {
+        const started = performance.now();
+        // A time jump (seek, restart) starts the trail over; mere lag only
+        // widens the window, capped, so skipped ticks don't drop events.
+        const jumped = epoch !== lastEpoch || lastQueried < 0 || daySeconds <= lastQueried;
+        const span = jumped ? DEFAULT_WINDOW_S : Math.min(daySeconds - lastQueried, MAX_WINDOW_S);
+        lastQueried = daySeconds;
+        lastEpoch = epoch;
+        const result = await source.frame(daySeconds - span, daySeconds);
+        if (disposed) return;
+        const radii = new Float32Array(result.count);
+        for (let i = 0; i < result.count; i++) radii[i] = Math.sqrt(result.weights[i]);
+        const frame: FrameBids = {
+          key: frameKey++,
+          positions: result.positions,
+          radii,
+          count: result.count,
+          queryMs: Math.round(performance.now() - started),
+        };
+        // Ghost trails only make sense over contiguous playback.
+        setFrames((history) => (jumped ? [frame] : [frame, ...history.slice(0, FRAME_HISTORY - 1)]));
+      } finally {
+        inFlight = false;
+      }
+    };
+
+    void query();
+    const unsubscribe = clock.subscribe(() => void query());
+    return () => {
+      disposed = true;
+      unsubscribe();
+    };
+    // ready re-arms the reader once the source has loaded.
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies
+  }, [clock, source, ready]);
+
+  return frames;
+}
+
+/** Event count for each minute of the replayed day, within the current scope. */
+export function useMinuteActivity(
+  source: GeoTimelapseSource,
+  ready: boolean,
+  scopeVersion: number,
+): Float32Array | null {
+  const [activity, setActivity] = useState<Float32Array | null>(null);
+
+  useEffect(() => {
+    if (!ready) return;
+    let disposed = false;
+    void source.activity().then((counts) => {
+      if (!disposed) setActivity(counts);
+    });
+    return () => {
+      disposed = true;
+    };
+    // ready and scopeVersion re-run the effect so a (re)loaded source is re-read.
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies
+  }, [source, ready, scopeVersion]);
+
+  return activity;
+}
+
+/**
+ * Trail length that adapts to the achieved frame rate: under 24 fps ghosts
+ * are shed one per second, above 58 fps they come back, up to FRAME_HISTORY.
+ * (58, not 60: a 60 Hz display — the TV target — never reads past 60.) The
+ * 1s sampling window doubles as a cooldown so the count settles instead of
+ * oscillating across the wide 24-58 dead band.
+ */
+export function useAdaptiveTrailFrames(): number {
+  const [count, setCount] = useState(FRAME_HISTORY);
+
+  useEffect(() => {
+    let rafId = 0;
+    let ticks = 0;
+    let windowStart = performance.now();
+    const loop = (now: number) => {
+      ticks += 1;
+      if (now - windowStart >= 1000) {
+        const fps = (ticks * 1000) / (now - windowStart);
+        if (fps < 24) setCount((current) => Math.max(current - 1, 2));
+        else if (fps > 58) setCount((current) => Math.min(current + 1, FRAME_HISTORY));
+        ticks = 0;
+        windowStart = now;
+      }
+      rafId = requestAnimationFrame(loop);
+    };
+    rafId = requestAnimationFrame(loop);
+    return () => cancelAnimationFrame(rafId);
+  }, []);
+
+  return count;
+}
+
+/** Rendered frames per second, sampled twice a second. */
+export function useFps(): number {
+  const [fps, setFps] = useState(0);
+
+  useEffect(() => {
+    let rafId = 0;
+    let count = 0;
+    let windowStart = performance.now();
+    const loop = (now: number) => {
+      count += 1;
+      if (now - windowStart >= 500) {
+        setFps(Math.round((count * 1000) / (now - windowStart)));
+        count = 0;
+        windowStart = now;
+      }
+      rafId = requestAnimationFrame(loop);
+    };
+    rafId = requestAnimationFrame(loop);
+    return () => cancelAnimationFrame(rafId);
+  }, []);
+
+  return fps;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { GeoTimelapse } from './geo-timelapse.js';
+export { buildGlowLayers, DEFAULT_GLOW_TUNING, default as GlowLayer, GLOW_PARAMETERS } from './glow-layer.js';
+export type { GlowTuning } from './glow-layer.js';
+export type { FrameBids } from './hooks.js';
+export type { FramePoints, GeoTimelapseProps, GeoTimelapseSource, MapBounds, Totals } from './types.js';