Setting the file. One moment.
Skill 01 · Remotion Best Practices
Subchapter 1.97
remotion-markup/remotion-maps/techniques/maptiler/references/map-data-sources.mdMarkdown5 KBView on GitHub
Choose the source independently for every story element. A single map can—and often should—mix provider vectors with custom geodata.
Use a MapTiler Planet vector layer when the feature already exists there, its attributes support an editorially precise filter, and provider geometry is acceptable for the claim. Use custom GeoJSON when the feature is absent, proposed, historical, disputed, corrected, privately sourced, or needs ordered geometry for a deterministic draw.
| Requirement | MapTiler vector layer | Custom GeoJSON |
|---|---|---|
| Roads, waterways, water, boundaries, land cover, or other standard context | Prefer | Use only when provider data is insufficient |
| Basemap-consistent geometry without a duplicate local dataset | Prefer | No |
| Proposed, historical, classified, corrected, or production-specific element | No | Prefer |
| Fade, colour, width, radius, blur, or fill-opacity animation | Yes | Yes |
| Feature-state highlight when a stable feature ID exists | Yes | Yes |
| Deterministic source-to-end line draw or perimeter draw | Bake first | Prefer |
| Geometry editing, morphing, clipping, or exact sequencing | No | Prefer |
Provider alignment is not proof of correctness. Inspect the attributes and geometry against the editorial source before presenting a provider feature as evidence.
MapTiler Planet is a vector tile source. Add it once, then build story layers with a
source-layer and an exact attribute filter. Read the current MapTiler Planet schema before choosing
layer names or fields.
Common layer categories include waterway, water, transportation, boundary, landcover, and
poi; availability, fields, and zoom ranges vary by schema version.
import {addMapTilerVectorElement, setVectorElementPaint} from "./MapTilerVectorElement";
addMapTilerVectorElement(map, process.env.REMOTION_MAPTILER_KEY!, {
id: "story-river",
sourceLayer: "waterway",
type: "line",
filter: [
"all",
["==", ["get", "class"], "river"],
["==", ["coalesce", ["get", "name_en"], ["get", "name"]], "Yarlung Tsangpo"],
],
layout: {"line-cap": "round", "line-join": "round"},
paint: {
"line-color": "#E8F7FF",
"line-width": 3,
"line-opacity": 0,
},
});
setVectorElementPaint(map, "story-river", {
"line-opacity": reveal,
"line-width": 2 + reveal * 2,
});Animate provider features by changing paint properties from the Remotion frame: opacity, colour, width, blur, fill opacity, circle radius, or symbol opacity. Use feature state only when the source provides stable IDs and the selection remains deterministic across tiles.
Do not treat a tiled line as one ordered path. Vector tiles split features at tile boundaries, so a source-to-mouth or start-to-end draw has no reliable global order. If that motion carries meaning, extract and verify the complete feature, order it once, save it as GeoJSON, and use the custom mode.
Use the bundled ../assets/RiverReveal.tsx and ../scripts/prep-geo.mjs pattern for custom GeoJSON. This mode owns
the exact geometry and can slice it by distance, calculate entry triggers, draw complete borders, and
produce deterministic sequences.
Custom mode is mandatory when:
Use provider vectors for ordinary contextual features and custom GeoJSON for the specific claim. For example: MapTiler waterways and roads as aligned context; a custom proposed tunnel, dam site, disputed boundary, or verified evacuation area as the highlighted evidence.
Keep provider and custom layers visually distinct when they carry different evidentiary weight. Record the source and effective date of every custom layer in the production notes.