SpatioTemporalTileset

The SpatioTemporalTileset class manages the lifecycle, loading, and caching of spatiotemporal tiles. It is the "brain" behind the SpatioTemporalLayer, determining which tiles to load based on the current viewport and time window — and, since the player-buffering work, the readiness oracle a PlaybackGovernor gates playback on.

It is inspired by deck.gl's Tileset2D (the class behind TileLayer), extended for the temporal dimension: tile selection, request scheduling, prefetch, and the buffer model all reason about (z, x, y, t) addresses.

Installation#

import { SpatioTemporalTileset } from '@poopdeck.gl/core';

Usage#

Typically used internally by SpatioTemporalLayer (and @poopdeck.gl/maplibre's STTBaseLayer), but can be used independently for custom implementations.

import { SpatioTemporalTileset } from '@poopdeck.gl/core';
import { makeTilesetCallbacks } from '@poopdeck.gl/core/tileset-adapter';

const tileset = new SpatioTemporalTileset({
  ...makeTilesetCallbacks(archive, metadata),
  maxRequests: 24,
  onTileLoad: (tile) => console.log('Loaded', tile),
});

// Update every frame or viewport change
tileset.update(
  {
    bounds: currentBounds,
    zoom: currentZoom,
    time: Date.now(),
    timeWindow: 86400000,
  },
  false,
);

const visibleTiles = tileset.getVisibleTiles();

makeTilesetCallbacks(archive, metadata?) wires the whole archive-backed fetch bundle — getAvailableTiles, getTileData, getTileDataBatch (with every batch hook forwarded), getTileByteSize, estimateFetchBytes, getThroughput, setSchedulerWeight, setMaxConcurrentRequests, and getAvailableSummaryTiles when metadata.summaryTier is present. Callers add the layout/lifecycle fields themselves. The tables below document what it fills in.

Constructor Options#

Required Callbacks#

Optional Data Callbacks#

Tile Loading Options#

Refinement Options#

Prefetch Options#

Prefetch dispatches in small, time-ordered, byte-budgeted SLICES (~1 s of measured throughput, clamped to 1–16 MiB; 4 MiB before the estimator has a sample) — the streaming-video segment model. One slice is in flight at a time; every slice boundary is a fresh chance for priority work to dispatch first. The prefetch direction has hysteresis (3 consecutive opposite-sign frames before flipping), and the prefetch working set is capped at half the tile-count cache budget so the runway stays resident instead of thrashing the LRU.

Tier dispatch#

Temporal-LOD dispatch is now wired into the tileset, but only via the opt-in Scrub-LOD scrubLod.temporal axis (default off, and only when the archive was built with --temporal-lod). The underlying reader API — STTArchive.pickTemporalLodForZoom, getTileIdsInBoundsForTemporalLod, and getTilesInBoundsForTemporalLod — is also exposed directly, so an app that wants coarser temporal tiers outside the scrub path can select the LOD level and request those tiles itself.

Which tier that axis picks is temporalTierPolicy: 'zoom-threshold' (default) snaps to the coarsest declared level whose maxZoomLevel covers the requested zoom, knowing nothing about the window; 'cost-argmin' prices every addressable tier and takes the cheapest under bytes + tiles × requestOverheadBytes (ties to the COARSER tier). 'cost-argmin' requires both oracles — estimateSelectionCost (wire STTArchive.estimateSelectionCost: exact compressed bytes for a bounds × zoom × window × tier query, read off resident directory entries with zero network) and getRequestOverheadBytes (wire STTArchive.effectiveCoalesceGap: the bytes-equivalent price of ONE request, the same exchange rate the range coalescer fuses on) — and falls back to the zoom threshold whenever either is unwired or any tier prices with unknownTiles > 0.

Scrub-LOD (motion tier)#

Opt-in, default off. While the user drags the timeline, tile SELECTION may degrade to a cheaper preview tier; the readiness/buffer APIs (getBufferedRunway / getBufferedRanges / estimateCost) and the prefetch planner keep measuring/warming the FINE base tier, so a playback gate on scrub release re-arms against full detail — never the coarse preview.

ScrubLodOptions has two independent axes, both default OFF; an absent/empty object is byte-identical to today (the kill switch):

Callbacks#

Methods#

update(viewport, skipDebounce?): number#

Updates the tileset with a new viewport state. Returns a frameNumber which increments whenever the set of visible tiles changes.

• viewport: Object containing { bounds, zoom, time, timeWindow }, plus an optional tileCells — the frustum-quadtree CUT for this camera, a mixed-zoom antichain of (z, x, y) cells. It is capability-gated on getAvailableTilesForCells and can only NARROW which cells are fetched: bounds/zoom are still required alongside it and still drive the coverage index, prefetch planner and every readiness estimate, and anything about the cut that cannot be vouched for (not an array, empty, a non-integer or out-of-world address) drops it back to the AABB path, a strict superset.
• skipDebounce: If true, loads tiles immediately (useful for time-only updates).

bounds is repaired in core by normalizeViewportBounds (exported from @poopdeck.gl/core) before selection: latitude is swapped if inverted and then clamped to ±MAX_MERCATOR_LAT — not ±90, because latToTileY returns NaN in the sliver just inside a pole and a NaN row bound enumerates ZERO tiles; minLon > maxLon is kept as the antimeridian-crossing encoding only while the implied span is under MAX_SEAM_SPAN_DEG (350°), above which it is read as an inversion and swapped; and a ≥360° span collapses to [-180, 180]. A box with any non-finite component is REJECTED — the previous viewport is kept, the previous frameNumber is returned, and one console warning is emitted, because that is a camera→bounds derivation bug in the calling renderer. Producers should call normalizeViewportBounds / boundsFromCorners themselves rather than lean on this backstop: two screen corners only bound the ground quad at bearing 0.

update() also runs speed-aware seek detection: a time jump beyond max(timeWindow, |speed| × 1 s) is treated as a seek and flushes the prefetch runway (a continuous fast playback's per-update step is NOT misread as a seek).

getVisibleTiles(): Tile[]#

Returns the loaded tiles for the current selection. Parent-fallback tiles are included only while at least one of their child cells at the primary zoom is still uncovered.

setAnimationState(playing, speed)#

Inform the tileset about animation playback state for prefetch sizing and direction. The PlaybackGovernor also asserts this while a gate holds the clock frozen, so prefetch keeps reaching ahead during buffering.

setInteractive(interactive: boolean): void / isInteractive: boolean (getter)#

Set/read the interactive (motion) bit — the PlaybackGovernor toggles it true on beginScrub and false on endScrub, driving the preview tier while the timeline is scrubbed. With no Scrub-LOD axis enabled (the default) this is STORED STATE ONLY — no selection change, no fetch, byte-identical behavior (the kill switch). With an axis enabled, the transition re-runs selection immediately: true serves the degraded motion tier; false restores the fine settle tier without waiting for the next clock tick.

isLoaded: boolean (getter)#

True when the current selection has SETTLED: nothing queued, no needed tile in flight. Mirrors upstream Tileset2D.isLoaded semantics including its error stance — a failed/cancelled tile counts as settled. Prefetch/overview lookahead never blocks this.

selectionVersion: number (getter)#

Monotonic needed-set version: bumps exactly when a selection pass changes WHICH tiles the viewport×window needs — never on tile arrival. Pair with isLoaded to derive once-per-settle viewport-load events.

getCacheStats()#

Returns a TilesetCacheStats, in four groups:

• Cache — hits, misses, hitRate, tileCount, cacheBytes, pinnedCount, pinnedBytes. A hit is a needed tile already decoded in memory. Pinned (overview-storyboard) tiles are excluded from the maxCacheSize test, so tileCount − pinnedCount is what the count cap governs.
• Eviction — evictions, runwayEvictions (evictions that reached INTO the protected playhead window — the thrash signal), evictionsByTier ({ b: far behind the playhead, c: distant speculation ahead, d: the near-playhead protected window }; tier A is recoverable as evictions - (b + c + d)), bytesEvicted, overLimitEvictionsScheduled.
• Network & churn — requests, bytesRequested (the coalesced range plan when estimateFetchBytes is wired, else the directory sum), bytesUseful (compressed directory bytes actually delivered — the bytesRequested / bytesUseful ratio IS read amplification), and refetches (deliveries of a key that had been loaded and then evicted; a healthy session keeps this at zero).
• Queues — activeRequests, priorityQueueLength, prefetchQueueLength, prefetchPressureScale (the prefetch policy's speculation scale, 1 = full horizon), selectionPasses, coverageRebuilds.

getPrefetchDirection(): 1 | -1 / getAnimationSpeed(): number#

The committed prefetch direction (with flip hysteresis) and the most recent estimated animation speed (sim-ms per real-ms).

cancelSupersededRequests(neededTileKeys): number#

Aborts in-flight work the current selection no longer needs. Tier-aware: prefetch-tier requests are EXEMPT (being ahead of the window is their normal operating condition), and a priority-tier batch is aborted only when EVERY member has left the needed set (a seek landed elsewhere).

clear() / finalize()#

clear() cancels all active requests (latching them so late deliveries can't corrupt the counters) and clears the cache; a pending overview preload settles with reason 'disabled'. finalize() additionally stops all timers — call it on unmount.

Buffer model (player buffering)#

These APIs are what the PlaybackGovernor consumes — the tileset structurally satisfies the governor's BufferSource contract. All of them are pure directory + cache math (zero network): the coverage index — every needed tile id and its directory byte length at the primary zoom for the current viewport, across the FULL dataset time range, grouped by temporal bucket — is built once per spatial viewport change (lazily, on first buffer-API use or when onBufferChange is wired), and loaded status is resolved live against the tile registry.

getBufferedRunway(time, direction, horizonSimMs?): BufferedRunway#

How much contiguous sim-time ahead of time in direction is fully loaded — "can the clock advance into [t, t+Δ] without rendering a partial frame?". Returns:

interface BufferedRunway {
  simMs: number; // contiguous loaded span (stops at the first bucket with a missing tile)
  bytesPending: number; // directory byte sum of needed-but-not-loaded tiles in the horizon
  // (in-flight counts as not loaded; 0 when getTileByteSize is unwired)
  horizonSimMs: number; // how far the probe looked
  complete: boolean; // reached the horizon — or the dataset edge — with nothing missing
  blockedPermanently?: boolean; // (with complete: false) the runway ends at a tile the
  // archive refused PERMANENTLY (403/404/410) — nothing further can arrive, so the
  // governor folds it as complete. Never set alongside complete: true; such a tile's
  // bytes are excluded from bytesPending for the same reason.
}

The default horizon is max(4 × timeWindow, |animationSpeed| × 10 s), at least one temporal bucket. Cheap and synchronous; safe to call several times per second. Reports an empty, incomplete runway until the coverage index is built.

isInert(): boolean#

true once finalize() has run. One-way — a finalized tileset is never revived. A PlaybackGovernor must DROP an inert source rather than wait on it: clear() empties the tile registry but leaves the coverage index standing, so a finalized tileset reports every bucket missing and would pin a REQUIRED gate at runway 0 forever, freezing the clock.

getBufferedRanges(opts?): Array<{ start, end }>#

Merged, ascending sim-time ranges that are fully loaded for the current viewport at the primary zoom across the FULL dataset time range — the data behind a scrubber's "buffered" bar. Capped at maxRanges (default 64). Cheap enough to poll at ~1 Hz.

estimateCost(range): { bytes, tiles, unknown? }#

Exact cost of making range fully buffered: the directory byte sum (and count) of intersecting tiles that are NOT loaded. Byte-exact lookahead a video player cannot do — STT can because the directory knows every tile's length in advance. unknown: true when the coverage index has not been built — the result is 0/0 but unknowable, so treat it as "cannot predict", never as "nothing missing".

estimateTimeToReadyMs(range): number | null#

Honest ETA: estimateCost(range).bytes / measured throughput. Returns null when getThroughput is unwired, when it has no signal yet, or while the coverage index is still being built (estimateCost().unknown) — callers should show an indeterminate state, not a fake number.

flushPrefetch(): void#

Drop ALL pending prefetch work: clears the prefetch queue, aborts in-flight prefetch-tier requests (priority-tier requests untouched), and resets the runway bookkeeping so the next pass re-plans from the new play-head position. Called automatically on seeks, spatial viewport changes, and committed direction flips; safe to call manually.

preloadOverviewTier(opts?): Promise<OverviewPreloadResult>#

Eagerly load and PIN the coarsest tiles (zooms minZoom..maxZoom, default 0..1) across the full dataset time range and world bounds — the storyboard/thumbnail-strip analog. Budget-gated TWICE from directory math before any fetch: first on COUNT — more candidates than maxTiles (default 0.25 × maxCacheSize) resolves 'over-count', and that is the gate that binds on hourly-bucket archives spanning years — then on BYTES (default budgetBytes 20 MiB, priced on the coalesced range plan when estimateFetchBytes is wired and the directory sum otherwise), resolving 'over-budget'. Either rejection fetches nothing. Fetches ride the LOWEST request tier (dispatched only when priority is idle); pinned headers are exempt from LRU eviction, flushPrefetch(), and supersession. Idempotent — repeat calls return the original attempt's promise. Pinned tiles deliberately do NOT count toward the primary-zoom readiness APIs above.

interface OverviewPreloadResult {
  loaded: boolean;
  bytes: number; // directory byte sum of candidates (reported even on rejection)
  plannedBytes?: number; // the coalesced range plan — present, and what the byte
  // gate decided on, only when estimateFetchBytes is wired
  tiles: number;
  reason?: 'over-count' | 'over-budget' | 'no-tiles' | 'disabled' | 'error';
}

Source#

packages/core/src/spatiotemporal-tileset.ts