Skip to content

feat: animated raster layers (GeoTIFF frame stacks + video overlays), play/pause only - #23

Merged
TommySquared merged 1 commit into
mainfrom
feat/frame-stack-video
Nov 19, 2026
Merged

TommySquared merged 1 commit into
mainfrom
feat/frame-stack-video

Conversation

@TommySquared

Copy link
Copy Markdown
Collaborator

Adds two animated raster layer types: a frame stack (one GeoTIFF per frame, played at a fixed frame rate) and a video overlay (a pre-encoded WebM/MP4 placed by its corners with MapLibre's video source). Both have play/pause only: no timeline, no scrubbing, and no shared map clock.

Events

add_geotiff_frames

  • urls (2–240 GeoTIFFs), colormap, and a required fixed vmin/vmax.
  • Optional fps (clamped to 0.25–30), labels (one per frame), loop, autoplay, nodata, alpha, band.
  • Every frame goes through the existing single-band render path. All frames must share the same bounds and pixel size, or the event is rejected and no asset is created.
  • Asset type geotiff_frames. Frame 0 is also written as {id}.png, so thumbnails and existing raster handling keep working.

add_video

  • urls (1–3, in browser preference order, e.g. WebM with alpha, then MP4), bounds in EPSG:4326, optional poster_url, loop, autoplay, alpha.
  • Downloads have a size cap ([video] max_file_size_mb, default 100). The container type is checked from magic bytes, and only WebM/Matroska and MP4 are accepted.
  • east may exceed 180 for overlays crossing the antimeridian. MapLibre rejects an image/video box whose centre is past 180°, so the client draws such boxes shifted by −360°, which is the same place on the globe.
  • Asset type geotiff_video.

Both events are in Z_EVENTS and appear in the contract's CHANGE_EVENTS. source_url keeps its query string.

Persistence and client

  • New assets.animation JSON column (additive migration), returned on GET /assets and in the session snapshot. Restore handles both types before the generic geotiff_ branch.
  • Frame stack: the frames are preloaded as blob URLs, then swapped on one image source with updateImage.
  • Video: one video source.
  • Control: a small play/pause pill per animated layer, with i/N · label for frame stacks.
    • It's shown only while its layer is visible and removed on delete.
    • Play state is per viewer and not persisted. Playback pauses while the tab is hidden.
    • It appears in every UI mode, including ui=none. That's accepted for now, but ui=none was meant to show no UI at all, so this should be revisited with the other chrome that has crept into that mode.
  • Screenshots: ?animate=0 holds frame 0 with no control. The screenshot service uses it and waits for the animations to be ready.
  • Files router: serves video/webm and video/mp4. Range requests return 206, which Safari needs.

SDK and MCP

  • MapSession.add_geotiff_frames(...) and MapSession.add_video(...). _send_event takes an optional timeout: 60 s or more for frames, 300 s for video.
  • One consolidated MCP tool, add_animation(kind="frames" | "video", ...).
  • Docs updated: README, docs/llm-context.md, docs/mcp-integration.md, puppeteer skills.

Testing

  • tests/test_animation.py: 43 tests covering validation, mismatched grids, cleanup on error, payloads, the snapshot, Range, bounds past 180°, and the MCP tool.
  • tests/test_animation_browser.py: headless Chromium. Frames advance, pause and resume; the VP9-alpha video plays; hide/show and delete; restore after reload; ?animate=0; the canvas stays untainted.
  • Full suite: the same 2 failures as on main before this change (test_mcp_phase0 MCP lifespan, and test_screenshot_loopback, which fails only in a full run).
  • Also run end to end from a consumer app, with real 0.25° SST anomaly frames in EPSG:3832 plus a VP9-alpha video across the Pacific.

Not covered

  • H.264 MP4 playback and Safari weren't browser-tested; Chromium played the WebM only.
  • Re-attaching a video after a vector-basemap setStyle is untested (needs a MapTiler key).
  • Deleting an asset doesn't delete its PNGs or videos, same as existing GeoTIFFs.
  • Anything that waits on map.loaded() or idle will wait forever while a video plays. ?animate=0 is the documented workaround.
  • The existing seam at ±180° on antimeridian-crossing GeoTIFFs also affects frame stacks; it's being handled separately.

🤖 Generated with Claude Code

…pause only

Two generic layer types for animations, deliberately without a timeline or
shared clock: viewers get play/pause, and play state stays in each viewer.

- add_geotiff_frames: 2..240 single-band GeoTIFFs rendered through the
  existing singleband path with one fixed vmin/vmax (required), concurrently
  (4 at a time). Every frame must land on frame 1's grid, else the request
  fails naming the frame and leaves nothing behind. Frames are stored as
  {asset_id}-{i}.png, frame 0 also as {asset_id}.png. fps clamped to
  0.25..30; optional per-frame labels shown beside the play button.
- add_video: 1..3 WebM/MP4 encodings, downloaded with a size cap
  ([video] max_file_size_mb, default 100), sniffed by magic bytes, stored
  as {asset_id}-{i}.webm|.mp4, optional PNG/JPEG poster as {asset_id}.png.
  Bounds may cross the antimeridian (east > 180, kept as given).
- Both store a server-owned assets.animation JSON (served URLs, fps, labels,
  loop, autoplay, bounds), returned by GET /assets and the session snapshot,
  so reloads rebuild them. asset_type geotiff_frames / geotiff_video, so
  they stack and read as rasters.
- Viewer: frames preload as blob URLs and advance with updateImage; video
  uses MapLibre's video source (boxes centred past 180 drawn on the western
  world copy, which MapLibre requires). Compact bottom-left play/pause rows;
  hidden with the layer, removed on delete, timers paused while the page is
  hidden. ?animate=0 (and the headless screenshot service) holds every
  animation on its first frame, so screenshots are stable. WS screenshots
  no longer wait for an 'idle' that never fires while a video plays.
- Files route serves video/webm and video/mp4 with Range support.
- SDK add_geotiff_frames / add_video; MCP add_animation tool; docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@TommySquared
TommySquared merged commit b6e884c into main Nov 19, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant