@geomotion/gm

GM is the GeoMotion SDK — a tiny, dependency-free fluent builder that produces an AnimationConfig, the JSON contract the GeoMotion render engine consumes to produce cinematic map animations (Remotion + MapLibre) on real GIS data.

npm install @geomotion/gm

Quick start

import { GM } from '@geomotion/gm'

const config = GM.animation({ title: 'Nairobi → Mombasa', aspect: '9:16', duration: 12 })
  .basemap('dark')
  .view({ center: [38, -2.6], zoom: 6, pitch: 45 })
  .source('route', GM.lineString([[36.82, -1.29], [39.66, -4.05]]))
  .camera([
    GM.key(0, { center: [36.82, -1.29], zoom: 6 }),
    GM.key(1, { center: [39.66, -4.05], zoom: 8 }),
  ], { follow: 'route' })
  .trimPath('route', { glow: true })
  .travelingMarker('route', { icon: 'plane' })
  .title('Nairobi → Mombasa')
  .build()

// POST { base_config: config } to the GeoMotion render API

Concepts

• Coordinates are always [longitude, latitude].
• Timing: every track has a from/to window as a fraction of the clip (0–1), so animations stay in sync at any duration.
• Real data: sources can be live PostGIS layers (GM.postgis) or Google Earth Engine rasters (GM.gee), resolved server-side at render time.

Builder methods

Setup: GM.animation(opts) · .basemap(id|url) (21-map catalog: satellite, dark, light, voyager, esri-topo, osm, ofm-liberty… or a style URL / {z}/{x}/{y} template) · .view({center,zoom,pitch,bearing}) · .source(id, def) · .title(text, opts) · .counter(opts) · .post({grain,vignette,colorGrade,filter,adjust}) · .filter(name) · .terrain(opts) · .sky(on?) · .globe(on?) · .projection('globe') · .compass(opts) · .legend(items, opts) · .build().

Camera

| Method | Purpose | | --- | --- | | .camera(keyframes, {follow}) | Animate across GM.key(t, …) keyframes (one camera/clip). | | .whipPan(a, b, opts) / .quickPan | Fast snap-pan between two places. | | .pan(a, b, opts) | Steady pan. | | .zoomIn(center, opts) / .pushIn | Push down into a point (+tilt). | | .zoomOut(center, opts) / .pullOut | Pull back to reveal context. | | .orbit(center, opts) | Rotate around a pivot (degrees). | | .dollyZoom(center, opts) | Vertigo (zoom vs pitch). | | .flyTo(a, b, opts) | Cinematic hop between two framings. | | .reveal · .spiral · .craneUp · .craneDown · .sCurve · .multiStage | More named moves. | | .cameraSequence([{move, t:[from,to], …}]) | Compose several moves into one continuous shot. |

Every direct move is configurable (zoom, by, pitch, bearing, degrees) and accepts an optional { from, to } time window. The same generators are also available standalone as GM.whipPan(...), GM.orbit(...), etc. (pass to .camera()).

flyTo is a smooth Van Wijk optimal path (zoom-out → pan along the great circle → zoom-in), with the zoom-out depth derived from the jump distance — long flights feel like Google Earth Studio, short hops stay tight.

Continuous camera tours — GM.tour(...)

Compile a continuous multi-stop tour into ONE clip (single scene, no cuts): one camera flies place→place and holds at each stop while that stop's effects play, then flies on. Render once → finish voice-over / sound in Premiere or After Effects. This is the GeoBytes / Altivex map-storytelling look, scripted.

import { GM } from '@geomotion/gm'

const config = GM.tour({
  title: 'AFRICA', aspect: '9:16', basemap: 'satellite', look: 'cinematic',
  intro: { establish: true },          // wide fly-in to the first stop
  outro: { pullOut: true },            // end on a pull-back
  stops: [
    { feature: congoGeo, flag: 'https://flagcdn.com/w1280/cd.png',
      beat: 'orbitReveal', dwell: 6, color: '#ffd166',
      effects: ['boundary', 'flagWave', 'label'], label: 'DR CONGO',
      overlays: [{ kind: 'counter', toValue: 102, suffix: 'M people', font: { family: 'Impact' } }] },
    { feature: kenyaGeo, beat: 'spotlight', dwell: 6,
      effects: ['highlight', 'label'], label: 'KENYA',
      overlays: [{ kind: 'emoji', emoji: '🦁' }] },
    { feature: egyptGeo, flag: 'https://flagcdn.com/w1280/eg.png',
      beat: 'pushIn', dwell: 6, effects: ['boundary', 'flagPaint', 'label'], label: 'EGYPT',
      overlays: [{ kind: 'text', text: 'Gift of the Nile', font: { family: 'Georgia' }, position: 'bottom' }] },
  ],
}).build()

Per stop: beat — the full camera-move catalog: orbitReveal · orbit · spotlight/hold · pushIn · pullOut · dropIn · reveal · spiral · craneUp · craneDown · dollyZoom (vertigo) · whipPan · sCurve · creepPan · multiStage · routeFly (follow a route path) — plus dwell seconds, effects (highlight · boundary · flagWave|flagPaint|flagPour|flagFlat · spotlight · region/fill · label · lowerThird · pulse · radio · pin), and overlays (counter · text · emoji/icon · image). Text & overlays take a per-stop font {family,size}, color, and position. Tour effects auto-fade-out so a stop's outline never lingers as the camera flies on.

Everything is configurable per stop: camera start→end zoom / tilt / rotation (startZoom/endZoom, startPitch/endPitch, startBearing/endBearing — the camera zooms in/out while it holds, single-style parity), ease (easeInOut default = smooth), highlight/stroke style (strokeColor, strokeWidth, glow, glowWidth, dash, fillOpacity, spotlightOpacity, spotlightFeather, spotlightRing), and a big title (titlePosition, titleFont, titleColor, titleTyping).

Spotlight is fully configurable: opacity (push it high so the rest dims right out and the focus pops), feather (0–1 soft edge on the cutout), and ring (a glowing outline on the lit feature). flagFlat paints a static flag (no wobble); flagWave/flagPaint/flagPour animate it.

Captions / lower-third readout: the lowerThird and label effects type out on screen (typewriter, typing — on by default) and auto-fill a lat/long readout (coords, on by default) so you have an on-screen cue and coordinates to time voice-over / SFX. Text and field colours are independent — textColor for the caption text, fieldColor for the side bar (so they never collide). Anchor it with lowerThirdPosition (any of the 9 anchors, adapts to the aspect) and dismiss (seconds) to auto-remove it after the type-out.

Tour-wide film look: look (grade preset), filter (named CSS look — vivid, noir, sepia, warm, cool…), and adjust ({ hue, saturate, brightness, contrast }). All applied identically in the live preview and the MP4 render.

Smoothness & flow: smoothness (0–1, default 0.5) keeps a gentle continuous drift at each stop so the camera never freezes. flow (0–1, default 0.5) is a graph-editor smoothing pass over the whole camera track — it low-pass-filters the path so the stop→stop transitions glide instead of stopping dead at each keyframe (which reads blocky/robotic). flow: 0 plays the exact keyframes; higher = more glide. flyTo between stops is already a Van Wijk optimal path.

Atmosphere, globe & map elements: by default an atmosphere/sky is drawn at the horizon so tilting never exposes the flat map's rectangular edge (pass sky: false to turn it off). Set globe: true to wrap the whole tour onto a 3D globe (MapLibre globe projection). Add a true-north compass (true or { position, color }) that rotates with the camera, and a legend key ({ items: [{ color, label }], position, title }) — all rendered identically in the live preview and the MP4 render. These are also available as builder methods on a plain animation: .sky(on?) · .globe(on?) · .projection('globe') · .compass({position,color}) · .legend(items,{position,title}).

Effects & overlays

.trimPath · .travelingMarker · .arrowLine · .dashedLine · .arc · .boundaryStroke · .regionFill · .spotlight · .zoomToFeature · .highlightFeature · .choropleth · .extrusion3d · .heatmap · .proportionalSymbols · .bars · .geeLayer (reveal a real GEE/XYZ raster — NDVI, land cover, Sentinel-2 — over a window) · .radioWaves · .pulseMarker · .blink · .pinDrop · .flagMarker (circular flag-disc map pins that drop in — the "find-your-team" look) · .flag · .flagFill · .mapLabel · .lowerThird · .photo.

Source factories

GM.lineString, GM.point, GM.polygon, GM.geojson, GM.url, GM.postgis, GM.gee, GM.key.

License

MIT © Lawrence Kimutai