Technique 01 — Cesium Flyover

A helicopter glide through real terrain

Google-Earth-grade 3D mountains — quantized-mesh terrain draped in satellite imagery — with a camera that flows along a river, banks into the bends, and never jitters. For the beat where the viewer needs to feel the landscape: a canyon, a gorge, a coastline, a route.

Engine CesiumJS Terrain + imagery MapTiler Render harness Remotion Output MP4, any resolution

Actual output — Yarlung Tsangpo Great Bend, 24-second glide Compressed preview · full render is 1080p+

/ Fit

What it's for

Reach for it when

The story needs a cinematic reveal of a real place — fly through a canyon, over a mountain range, along a border or supply route.
You want true 3D geometry with sharp ridgelines, not a flat map tilted back.
The shot must be reproducible: re-render after a script change and get the identical move.

Not the tool for

Flat "where is this?" maps, choropleths, or data overlays — switch to the 2D Map Animation.
Street-level or city photorealism (that's a 3D-tiles job, a paid tier above this stack).

/ Architecture

Three parts, one job each

Neither engine can do this alone — Cesium won't render reliably headless by itself, and Remotion has no 3D globe. Stacked, they cover each other exactly.

Draws the world

CesiumJS

A true free camera in a 3D globe that renders to the horizon. Loaded from CDN at runtime, driven one frame at a time — its default render loop is switched off.

Feeds the world

MapTiler

Quantized-mesh terrain (real 3D geometry, crisp silhouettes) plus satellite imagery draped on top. One API key covers both — no separate Cesium ion account.

Runs the clock

Remotion

Steps the timeline frame by frame and holds each frame until every terrain tile is loaded before capturing it. Deterministic in, deterministic out.

/ Pipeline

From a line on a map to a finished shot

Prepare the camera path

Start from a river or route centerline (OpenStreetMap). The prep script clips a window, resamples it to even spacing, smooths it into continuously flowing curves, and dampens the swerve toward a straight chord — one knob controls how much the camera weaves.

Fly the path

Each frame, the camera walks the path by distance and aims at a real point further along it. That far aim is what makes the heading turn gently with the terrain — and the rate of turn drives a subtle roll, so the camera banks into bends like a helicopter.

Render

One headless Chrome, one frame at a time: npx remotion render … --gl=angle. Every frame waits for tilesLoaded before capture, so there are no half-loaded tiles in the final video — ever.

/ Live demo

The camera path, interactive

This is the actual path algorithm running in your browser, top-down. The thin cyan line is the raw river; the amber line is the smoothed, dampened camera path; the marker aims at a point ahead of itself and banks with the turn. Drag the sliders.

Swerve45%

Look-ahead2.0 km

Speed1.0×

Swerve at 0% flies dead straight; 100% follows every meander. The proven water-wars values: swerve 45%, look-ahead 1.5 km, 13 km travelled over 24 s (≈0.54 km/s — slower reads calmer, and renders faster because tiles stay cached).

/ Tuning

Every feel decision is one number

You want	Turn this	Proven value
Slower, more peaceful	Composition duration (speed = distance ÷ seconds)	24 s for 13 km
More / less swerve	`DAMP` in the path script	0.45
Higher / lower camera	`ALT_START` / `ALT_END` (absolute, in metres)	4600 → 4300 m
More horizon in frame	`PITCH_FROM_NADIR`	76°
Stronger / gentler bank	`MAX_BANK` / `BANK_GAIN`	±7.5° / 0.6
More dramatic relief	`verticalExaggeration`	1.1

The gotcha this skill exists to spare you

Cesium's globe silently refuses to draw in a plain headless browser — WebGL works, the sky renders, but the terrain produces zero draw commands. The fix that works: render through Remotion, disable Cesium's own render loop, drive every frame with viewer.render() (never scene.render()), and gate each frame on tilesLoaded. The skill's troubleshooting file maps every failure symptom to its fix.

/ Contents

What ships in the skill

SKILL.mdthe entry point — when to use it, architecture, quick start

assets/CesiumFlythrough.tsxthe runnable Remotion component

assets/example-Root.tsxminimal composition scaffold (duration = speed knob)

assets/sample-river.geojsonan OSM gorge centerline — works out of the box

assets/cesium-path.jsonthe pre-generated camera path for the sample

scripts/prep-cesium-path.mjscamera-path generator (dependency-free Node)

references/architecture.mdfull camera math + proven feel values

references/troubleshooting.mdevery symptom → its fix

/ Quick start

Four steps to a first render

# 1 — copy the component + scaffold into a Remotion project
cp assets/CesiumFlythrough.tsx  your-project/src/components/
cp assets/example-Root.tsx      your-project/src/Root.tsx

# 2 — generate a camera path (runs against the shipped sample as-is)
node scripts/prep-cesium-path.mjs                # or: … my-river.geojson src/geo/cesium-path.json

# 3 — set the key (must be an UNRESTRICTED MapTiler key; domain-locked keys 403 headless)
echo "REMOTION_MAPTILER_KEY=…" > .env

# 4 — validate one still, then render
npx remotion still  src/index.ts CesiumFlyover out.png --frame=360 --gl=angle --timeout=180000
npx remotion render src/index.ts CesiumFlyover out.mp4 --gl=angle --concurrency=1 --timeout=180000

Technique 02 — Map Explainer

A river draws itself across the map

A flat, editorial explainer beat: a river or route traces on with a white-hot electric head, and each country lights up the moment the water reaches it — border draws, fill blooms, label rises. For "where is this?", "what's the path?", and "who is upstream of whom?"

Basemap MapTiler dataviz-dark Geometry GeoJSON layers Labels React overlay Render harness Remotion

Actual output — Yarlung Tsangpo → Brahmaputra, Tibet to the delta Compressed preview · full render is 1080p+

/ Fit

What it's for

Reach for it when

The viewer needs to place the story: where the river runs, which countries it crosses, in what order.
Regions should light up in a meaningful sequence — upstream before downstream, cause before consequence.
Labels must be typographically yours (real fonts, real animation), not map-engine text.

Not the tool for

3D terrain reveals — switch to the 3D Terrain Flythrough.
Non-geographic data viz (charts and ledgers have their own patterns).

/ Architecture

Three layers, one job each

The map draws the geography, Remotion runs the clock, and the labels live in React where typography is fully in your control.

Draws the map

MapTiler SDK

The dataviz-dark basemap, stripped of its own labels and inner admin borders, plus GeoJSON layers for the river, fills, and borders — all in one WebGL canvas.

Runs the clock

Remotion

Per frame: update the layers imperatively, then hold the frame until the map reports idle before capture. No transitions, no guesswork — pure functions of the frame number.

Sets the type

React HTML overlay

Country labels are positioned <div>s in Space Grotesk, projected from map coordinates to screen pixels every frame. Any font, any entrance, pixel-exact.

/ Pipeline

From raw geodata to a finished beat

Bake the geography

The prep script reads a clean river line plus one polygon per country and computes, for each country: when the river enters it (its trigger), where its label sits (the most-interior point of the story region — centroids drift to the edges), and which single border segment to draw (the longest visible one, so no confusing second border).

Strip the basemap

On load, every basemap label and inner admin border is removed. What remains is quiet context — country outlines and terrain shading — so your geography is the only thing talking.

Reveal the river

The line draws on by arc length, led by a white-hot electric head — the last few percent of the drawn line rendered in its own bright, glowing layers — which fades out as the river reaches the sea.

Light the countries

As the head crosses into each country: its border draws over a constant 2.5 s, its fill blooms in with a slight overshoot, its label rises. Constant durations matter — a long border must never flash by just because the river is fast there.

/ Live demo

The choreography, interactive

The same sequencing logic, running in your browser on abstract geography: the river draws with its electric head, and each region triggers the moment the head enters it — computed live with the same point-in-polygon test the real prep script uses.

Pace1.0×

Border → fill → label, each a fixed-length phase since trigger. In the water-wars render the real entry points were: China at 0%, India at 56%, Bangladesh at 90% of the river's length.

/ Tuning

Every feel decision is one number

You want	Turn this	Proven value
River colour / glow	`COLORS` in `tokens.ts`	icy core, electric-blue glow
Bigger / smaller electric head	head length + widths	3% of the line
Border draw time	`BORDER_S` (constant per country)	2.5 s
Fill bloom strength	opacity overshoot curve	×1.25, settling to ×1
Label position	story-region bbox + nudge, in the prep script	per country
When a country lights up	its entry point — recomputed from the geometry	0 / 0.56 / 0.90
Overall pace	river draw window; the beat length follows	8 s draw → 12 s beat

The contract that prevents silent failures

Each country's lowercase key must be identical in three places: the prep script's country list, the component's draw order, and the palette tokens (one light + one dark shade per country). A mismatched key doesn't error — the country simply never appears. The skill documents this four-file contract explicitly.

/ Contents

What ships in the skill

SKILL.mdthe entry point — when to use it, architecture, quick start

assets/RiverReveal.tsxthe main runnable Remotion component

assets/CountryLabel.tsxreusable Space Grotesk label with accent rule

assets/tokens.tspalette + durations, one import for both components

assets/example-Root.tsxminimal composition scaffold

assets/sample-data/pre-baked river + country metadata — renders without prep

scripts/prep-geo.mjsgeo pipeline: triggers, label anchors, border segments

references/architecture.md + geo-prep.mdtiming model, electric head, basemap stripping

/ Quick start

Four steps to a first render

# 1 — copy the components + tokens into a Remotion project
cp assets/{RiverReveal,CountryLabel}.tsx  your-project/src/components/
cp assets/tokens.ts                       your-project/src/theme/
cp assets/example-Root.tsx                your-project/src/Root.tsx

# 2 — use the shipped sample data, or bake your own river + countries
cp assets/sample-data/*.json  your-project/src/geo/   # or: node scripts/prep-geo.mjs

# 3 — set the key + fonts (google-fonts version-matched to your remotion)
echo "REMOTION_MAPTILER_KEY=…" > .env
npm i @maptiler/sdk @turf/turf @remotion/google-fonts

# 4 — render (--gl=angle is mandatory: the map is WebGL)
npx remotion render src/index.ts MapExplainer out.mp4 --gl=angle --timeout=120000