reszta poprawek

2026-08-09 09:47:34 +02:00
parent 966dd3f209
commit a0c9d7947b
439 changed files with 112891 additions and 0 deletions
@@ -0,0 +1,91 @@
+# 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.
+
+```ts
+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.