versatiles-map-animation

Prototype tool for composing camera animations on a VersaTiles map and previewing them in the browser. Long-term goal: feed the same data model into a headless renderer for TV-grade map animations.

Status: prototype. Hosted but not publicly linked. The JSON schema is the durable contract; the editor and renderer talk it.

Features

Camera animation

• Drop keyframes on a timeline that capture the current camera (lng, lat, zoom, pitch, bearing, roll).
• Play back with ease-in-out interpolation between keyframes; shortest-path bearing/roll wrap.
• Per-segment trajectory style: arc (default, smooth great-circle path) or linear.
• Scrub anywhere on the timeline; click a keyframe to jump to its view; drag markers along the track to retime — and past their neighbours to reorder the sequence. Timestamps snap to 1/100 s.
• Timeline zoom & pan: vertical scroll / Ctrl-wheel / pinch zooms; horizontal scroll pans; drag the pan-bar thumb to scroll, drag its edges to zoom; the playhead can be moved past the last keyframe to add a new one there.
• Insert keyframes at the current playhead (compose a shot, then + Add in the Keyframe group).

Map style

• Style: colorful or satellite.
• Toggle place-name / road-shield labels (or, for satellite, the colorful overlay on top).
• Optional 3D terrain (with hillshade).
• Optional atmospheric sky (visible when the camera is pitched).
• Composition aspect ratio: 16:9 (default), 21:9, 4:3, 3:2, 1:1, 4:5, 9:16. Editor preview, embed iframe, and MP4 render all letterbox to the chosen aspect, so the composition stays WYSIWYG across surfaces.

Annotations

• Drop pin / arrow / circle / star / outline / icon markers anywhere on the map.
• Per-annotation editable label, font (187 SDF fonts bundled by the VersaTiles tile server), label position (9-way grid: top-left … bottom-right), label distance, label colour, label size.
• Per-annotation icon, icon colour, icon size, rotation.
• Per-annotation halo colour & width for both label text and the icon outline (auto-flipping default for legibility on any basemap).
• Visibility window with optional fade-in / fade-out tails — set on the timeline by dragging the four-handle bar that appears for the selected annotation.
• Drag annotations directly on the map; reorder them in the sidebar's Markers list by drag-and-drop.
• Per-animation default style — set a template in the sidebar's Default annotation style panel; every marker that doesn't override a field follows the template. Change the template later and every still-thin marker updates automatically. The same template is used as the starting state for newly-pinned markers.

Sharing & rendering

• Share by URL — the entire animation (style, terrain, sky, annotations, per-animation default style, scale, aspect ratio) is encoded into the URL hash with a bit-packed binary codec; any tester with the link sees the same animation.

• Embed in a third-party page via a generated <iframe> snippet (16:9, fluid width). The viewer is served from /view and carries the same URL-hash payload. See embed-demo.html for the iframe in real-page context with a copy-paste snippet.

• Local persistence — the latest animation is mirrored to localStorage, so a reload without a hash restores it.

• Export / import as JSON for archival or hand-off.

• Render to MP4 via the published Docker image (button in the editor copies the command):

  docker run --rm -it --pull always -v "$PWD:/out" \
    ghcr.io/versatiles-org/versatiles-map-animation:latest \
    --hash '<URL-hash payload>' --width 1920 --fps 30 --output animation.mp4
  

Run locally

npm install
npm run dev      # http://localhost:5173

Build a static site

npm run build

Output in build/. Deploy to any static host (GitHub Pages, Cloudflare Pages, etc.). URL-hash state means no server-side support is needed.

Quality checks

npm run check          # format + svelte-check + eslint + vitest
npm run test:coverage  # vitest with v8 coverage

Schema

The same shape ships in the downloadable JSON and (in a more compact bit-packed form) the URL hash. JSON schema version 1:

{
    "version": 1,
    "style": "colorful", // "colorful" | "satellite"
    "labels": true, // place names (colorful) or overlay (satellite)
    "terrain": false,
    "sky": false,
    "annotationScale": 1, // global multiplier on per-annotation iconSize/labelSize
    "aspectRatio": "16:9", // "16:9" | "21:9" | "4:3" | "3:2" | "1:1" | "4:5" | "9:16"
    "keyframes": [
        {
            "t": 0.0, // seconds, snapped to 1/100 s in the editor
            "lng": 13.405,
            "lat": 52.52,
            "zoom": 10,
            "pitch": 0, // 0..90
            "bearing": 0, // -180..180
            "roll": 0, // -180..180
            "path": "arc" // optional: "arc" | "linear" — trajectory to this keyframe
        }
    ],
    "annotations": [
        // Only `lng`, `lat`, and `label` are required. Every style field is
        // optional; the renderer fills missing ones from `defaultAnnotation`
        // below, then from the hardcoded baseline (`symbol-marker`, red, etc.).
        {
            "lng": 13.405,
            "lat": 52.52,
            "label": "Berlin",
            "icon": "symbol-marker", // optional; legacy "color" key also accepted for iconColor
            "iconColor": "#cc0000", // optional
            "iconSize": 1, // optional
            "iconHaloColor": "#ffffff", // optional
            "iconHaloWidth": 0, // optional
            "labelColor": "#111111", // optional
            "labelSize": 1, // optional
            "labelFont": "noto_sans_bold", // optional; see ANNOTATION_LABEL_FONTS in src/lib/types.ts
            "labelPosition": "bottom", // optional: top-left … bottom-right
            "labelDistance": 1.5, // optional: em from the geo point
            "labelHaloColor": "#ffffff", // optional: explicit override (else auto-flip for legibility)
            "labelHaloWidth": 1.5, // optional
            "rotation": 0, // optional, degrees clockwise (mainly for arrow icons)
            "visibleFrom": 0, // optional: hide before this time
            "visibleUntil": 5, // optional: hide at/after this time
            "fadeIn": 0.5, // optional: seconds; ramp 0→1 before visibleFrom
            "fadeOut": 0.5 // optional: seconds; ramp 1→0 after visibleUntil
        }
    ],
    // Per-animation style template. Any annotation that omits a field below
    // inherits it from here. Position/content/time fields (lng/lat/label/
    // rotation/visibleFrom/visibleUntil/fadeIn/fadeOut) are never inherited
    // — those are per-annotation by definition.
    "defaultAnnotation": {
        "icon": "symbol-arrow1",
        "iconColor": "#ffffff",
        "iconHaloColor": "#000000",
        "iconHaloWidth": 1,
        "labelColor": "#ffffff",
        "labelHaloColor": "#000000",
        "labelHaloWidth": 1,
        "labelFont": "noto_sans_bold",
        "labelPosition": "top",
        "labelDistance": 1.8
    }
}

version is the JSON-format compat marker; new optional fields are added without bumping it. Files written before a feature was added still load — every additional field is optional and falls back to a sensible default.

The URL hash uses a separate compact binary format (single tag, V1). New optional features extend an in-struct options mask without bumping the format tag, so simple animations stay short and adding a feature doesn't invalidate previously-shared links. The format tag bumps to V2 only on a genuinely-breaking change — see the rule documented at the top of src/lib/url_state/animation_codec.ts.

License

MIT — see LICENSE.