Fly-over plugin

A camera that flies a route: it aims at the junctions ahead, frames them, keeps clear of the terrain, and parks the followed position, marked with an arrow, where you want it on screen.

npm install @tomtom-org/maps-sdk maplibre-gl @tomtom-org/maps-sdk-plugin-flyover

@tomtom-org/maps-sdk and maplibre-gl are peer dependencies.

import { calculateRoute } from '@tomtom-org/maps-sdk/services';
import { RouteFlyover } from '@tomtom-org/maps-sdk-plugin-flyover';

const routes = await calculateRoute({ locations, guidance: { type: 'coded' } });
const flyover = new RouteFlyover(map, {
    route: routes.features[0],
    camera: { speedKMH: 300, pitch: 76 },
    onProgress: ({ traveledDistanceInMeters }) => showProgress(traveledDistanceInMeters),
});

flyover.start();

MapLibre caps the pitch at 60° by default: a flight tilted further needs mapLibre: { maxPitch: 85 } on the map.

Use cases

• Preview a drive before it is driven: a scenic route, a delivery round, a race stage.
• Present a corridor (roadworks, a new line, an itinerary) without authoring a camera path.
• Show a long route in a short loop: the flight wraps at the destination and never lands.

What it needs from the route

• The line and its progress, which a calculated route carries by default.
• Guidance, optionally: ask for guidance: { type: 'coded' } to unlock the instruction aim and the instructions zoom. Without it, the aim falls back to its fallbackMetersAhead and the zoom to a fixed level.

The camera

Every field has a default and can be changed mid-flight with setCamera(); getCamera() returns the camera in use, defaults included.

Aim: what the camera looks at

The camera points ahead of itself, so it turns into a bend before reaching it.

• { mode: 'instruction', fallbackMetersAhead }: the next guidance instruction, the junction it is heading for. The default.
• { mode: 'distance', metersAhead }: a fixed distance down the road.
• { mode: 'points', pointsAhead }: a number of route vertices, which are denser through bends, so the aim shortens where the road turns.

Zoom: how high it rides

• { mode: 'instructions', instructionsAhead }: fits the road up to the Nth junction ahead (one at least) in view, so hairpins pull back and straights close in. The default.
• { mode: 'speed' }: lifts with the ground speed, one zoom level per doubling.
• { mode: 'fixed', zoom }: one zoom.

The two automatic modes keep between zoom 11 and 15. In every mode the camera pulls back further where terrain would block its view of the road.

Anchor: where the position sits on screen

A level map is a plan, so the position belongs in the middle; a tilted one shows mostly what lies ahead, so the position belongs low. Absent an anchor, it slides down with the pitch to two thirds at 60°, so a top-down pass needs no mode of its own.

import { anchorForPitch } from '@tomtom-org/maps-sdk-plugin-flyover';

flyover.setCamera({ anchor: { x: 0.5, y: 0.67 } }); // fractions of the viewport
const anchor = anchorForPitch(76); // what a pitch would choose: { x: 0.5, y: 0.667 }

• It holds over terrain at any pitch and zoom: the camera looks at the road on the ground.
• A changed anchor is eased onto, not jumped to.
• It is applied as viewport padding, kept 5% clear of the edges; remove() restores the padding the map had.

The marker

An arrow lies on the road at the followed position, facing along it. Restyle it, replace it or hide it with marker, and change it mid-flight with setMarker(), which replaces the whole marker setting.

// The arrow, recoloured with the SDK's SVG icon options.
new RouteFlyover(map, { route, marker: { image: { type: 'arrow', fillColor: '#e2231a', outlineColor: 'white' } } });

// An image of your own, drawn pointing up: a URL, raw SVG markup, a data URI or a loaded <img>.
flyover.setMarker({ image: { type: 'custom', image: '/icons/car-top-down.png' }, size: 56 });

flyover.setMarker({ visible: false });

• Drawn by the map, in a custom layer restored after style changes: MapEffects, depth of field included, and captures take it along.
• Placed as each frame is drawn, on the terrain under its route point, so it never trails the camera the way a symbol layer, updated through a worker, would.
• Not themed: a map theme's accent recolours the route, not the arrow. Pass fillColor: map.mapColors.accent to match a themed route.
• Mercator projection only, and a custom image on another origin needs CORS, since it becomes a WebGL texture.

Terrain

• Clearance: where a ridge behind the road would block the view, the camera zooms out along the same line of sight until it is 200 m above the ground. Pitch and anchor stay put.
• Altitude: while running, the flight sets the altitude of the point it looks at, the ground under the road, eased so the camera doesn't step as elevation tiles load. start() turns MapLibre's centre clamping off for that and stop() restores your setting, so a paused map behaves as usual.
• No terrain: TerrainModule raises it. Without it there is nothing to clear, and the camera looks at sea level.

Smoothness, and what it costs

• Critically damped springs move the heading, zoom, pitch, anchor and altitude: no overshoot, no kick when a target changes, and a start ramps the speed up. Each step is solved exactly, so a flight looks the same at 30, 60 or 120 fps.
• The heading is decided five times a second. Changes under 2.5°, which come from the line's sampling rather than the road, are ignored; real turns are capped at 22°/s.
• Expensive work runs on that tick: the route lookups, the framing and the terrain queries. Per frame the flight only steps its springs and moves the camera, so cost doesn't grow with the refresh rate.

Controlling the flight

flyover.start();              // or resume, ramping up to speed
flyover.stop();               // freeze where it is
flyover.seek(0.5);            // jump to half way along, clamped to 0..1
flyover.setRoute(nextRoute);  // fly a different route, from its start
flyover.setCamera({ pitch: 45 });
flyover.running;              // whether the flight is advancing
flyover.remove();             // stop, take the marker off, and restore your padding

• onProgress reports the distance and time travelled on the five-times-a-second tick, and on every seek.
• The camera is the flight's while it runs: a jumpTo or easeTo of yours fights it, so stop() first.
• Until the flight first places the camera (start() or seek()), the page keeps the view, so a whole route can be shown before anyone flies it.

API reference

For complete documentation see the RouteFlyover API Reference and anchorForPitch.

Related guides and examples

• Route fly-over playground - Every camera setting on one panel, with a depth of field holding the road ahead in focus
• Depth of field - The lens that keeps the road ahead sharp
• Terrain - The relief the camera clears