4.7 KiB
Map element data sources
Choose the source independently for every story element. A single map can—and often should—mix provider vectors with custom geodata.
Decision rule
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 vector mode
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.
Custom geodata 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:
- the feature is not in the provider dataset;
- the story uses a proposed route, planned tunnel, historical boundary, disputed interpretation, or non-public dataset;
- provider geometry was editorially corrected;
- motion must travel through the geometry in a verified order;
- a complete off-screen boundary matters and a viewport query would silently crop it.
Hybrid mode
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.