How spatiotemporal tiles work

The directory: 52 bytes per leaf up front, ~1 byte per tile inside

One object holds every tile address in the archive, and it has to stay small enough to fetch cold. Two mechanisms do that: a root page that rules whole leaves out before they're downloaded, and a body that exploits how little consecutive tile keys differ.

Above: it prunes before anything is fetched

The root page carries one 52-byte descriptor per leaf — zoom range, geo bbox and time span. Only leaves overlapping the query are downloaded.

Deeper: laying the space-time cube down in a line

A blob's address has three axes — (x, y) on the map plus a time bucket — but a pack is one flat byte string. --blob-ordering chooses the space-filling walk that linearizes the cube. Pick a walk, then play a real map+time gesture and watch which bytes it touches: the walk decides how many range reads the gesture costs.

--blob-ordering auto — the default — reads the archive's occupied space-vs-time extent and picks: time-deep datasets (a buoy's four-year track over a few cells) get spatial, because playback wants each cell's whole timeline in one pull; balanced or space-heavy datasets (a day of global flights) get the hilbert3 generalist. To decide from measurement instead of shape, build with --blob-ordering measured or audit an existing archive with stt-optimize order-audit, which simulates the range-read cost of each walk over the real directory. Either way the directory index keeps its own (zoom, hilbert(x,y), t) sort — the knob permutes bytes inside packs, never keys.

Deeper still: the same walk on real archives

The cube above is idealized — every cell full. Real archives are sparse and lopsided, and that shape is exactly what --blob-ordering auto reads to pick a walk. Switch datasets and watch the winner flip: a buoy's multi-year track over a few cells wants spatial; a day of flights wants the 3D-Hilbert generalist. Density is sampled from each archive's directory.

Packs — dedup by content, fetch by range

The governor buffers sim-time like a video player buffers seconds

The governor is a small state machine — it degrades before it freezes

The governor never touches the network itself — it sees the loader only through a small BufferSource seam (getBufferedRunway, estimateCost, flushPrefetch, setAnimationState), which is why @poopdeck.gl/playback stays zero-dependency and renderer-agnostic.

Per frame, the GPU alpha-gates every feature — buffers never rebuild

Per-feature (and per-vertex) times upload once as attributes. Each frame updates a handful of uniforms and the vertex shader gates alpha; fully hidden vertices collapse to a degenerate position so they cost no fragments. Times are relativized against a per-tile offset before upload, keeping f32 attributes millisecond-accurate (relative windows cap at 2²⁴ ms ≈ 4.6 h). The identical gate math runs as deck.gl GLSL, MapLibre GLSL and Three TSL.

Deeper: four looks, one mechanism — alpha as a function of age

Dashed line = the playhead. Switching modes changes a uniform, not the data — the same buffers render as a sliding window, a comet trail, a vessel wake or an accumulating record. A separate injection can also map age to height, turning any dataset into a space-time cube.

The control loop — two packages, one seam

In deck.gl apps the controller rides deck's own frame loop (useDeckClock mirrors it onto context.userData.stt), so STT layers stay cached layer instances that simply redraw. MapLibre, Three and Cesium bridge their render loops the same way.

Deeper: many datasets, one playhead

The governor folds health over the required set only — combined runway is the minimum, completeness is the AND. The shared scheduler then splits the connection budget by deficit round robin (the lidar's weight 4 earns 4× the bandwidth) and orders requests earliest-deadline-first, where a request's deadline is its distance from the playhead.

The pipeline gains a build-time analyst

stt-optimize wraps the tiler with a loop that runs entirely at build time — nothing here touches the serve path. analyze picks the zoom range and temporal bucket and runs the advisors; --auto folds the safe ones in (bare, it only fills zoom + bucket; --auto encode also applies the non-lossy byte levers); then inspect, diff and doctor turn the manual tuning passes this project kept re-running by hand into commands CI can gate on (diff --fail-on-growth, doctor --strict).

Measure, don't guess — every projection is a real encode

Instead of a size formula, the analyzer keeps a deterministic stride sample of real geometries and property values and pushes it through the production encoder plus zstd, then attributes cost by re-encoding each column alone. That is where a projection like −36% sample encode (measured) comes from — and how the doctor knows a near-incompressible id column, not the geometry, is eating the archive.

From analysis to advice — with a no-thinning firewall

five analyzers profile the source; four advisors turn that profile into flag recommendations, each carrying a measured projection and a confidence grade.

This split is the project's no-thinning principle made mechanical: a build never silently throws data away to hit a size target. Quantization and per-tile budgets can shrink an archive a lot — so they stay a deliberate, per-dataset choice, and the default build is byte-identical whether or not you ran the analyzer.

The doctor — severity-ranked findings on the built tileset

Each rule keys off numbers already measured for this tileset — directory stats and per-column costs from inspect — and cites them in its message; the doctor never re-encodes, so every delta is labelled (estimated from measured column costs). Run it with --strict and a fresh smell fails the build.

Deeper: the archive describes how to style itself

Every non-streaming build already bakes the cheap signals into manifest.json — the dominant layer kind and a suggested playback duration — so a client can open a strange archive and pick a clock with no config. --style-hints adds the expensive part: a full per-property profile with percentiles and a suggested colour domain.

"style_hints": {
  "version": 1,
  "layer_hint": "trips",              // always baked
  "suggested_playback_seconds": 45,   // always baked
  "properties": [                     // --style-hints only
    { "name": "speed_kmh", "min": 0, "p50": 14.2, "p95": 31.6,
      "p97": 34.0, "p99": 41.8, "max": 58, "suggested_domain": [0, 34] },
    { "name": "route_id", "cardinality": 214 }
  ]
}

The domain clamps at p97, not max — one outlier must not dim the whole ramp. Values are sampled at a deterministic stride (capped per property), so the block is byte-identical across rebuilds of the same input, safe to content-address alongside everything else.

Who renders what — the capability matrix

● native · ↳ falls back to a simpler kind · — unsupported. Generated from each backend's BackendDescriptor — the full, regenerated table lives in the spec.