---
name: kartograf
description: Use when creating, revising or reviewing browser map animations with Kartograf — declarative scenes, routes, travelers, camera choreography, timelines, transitions and post-processing on MapLibre. Covers the CDN-only API, config validation, supported geometry types and common failure modes.
---

# Kartograf

Kartograf is a CDN-only map-animation engine for MapLibre GL JS. You describe a
story as JSON and the engine animates routes, travelers, camera moves,
timelines, labels, choropleths and effects in the browser.

Use this skill when the task is to **produce or fix a Kartograf story**. For
film-level editorial direction, storyboards and acceptance reviews, use the
separate `kartograf-animation` skill when it is available.

## Load order

MapLibre must exist before Kartograf, and the Kartograf constructor needs the
map instance after the style has loaded.

```html
<link href="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css" rel="stylesheet">
<script src="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js"></script>
<script src="https://cdn.kartograf.cc/kartograf/0.5.7/kartograf.min.js"></script>
```

```js
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [29, 41],
  zoom: 5
});

map.on('load', async () => {
  const kartograf = new Kartograf({ mapInstance: map, libraryRef: maplibregl });
  const story = kartograf.createStory(config);
  await story.play();
});
```

- Use a **pinned version** for production; `latest` is for experiments.
- Always pass `libraryRef: maplibregl` or load MapLibre as `window.maplibregl`.
  Without it, markers and popups throw a clear error.
- `createStory()` stops and clears the previous player automatically.

## Validate before rendering

```js
const { valid, errors, warnings } = kartograf.validateStory(config);
if (!valid) console.error(errors); // [{ path: 'scenes[0].features[0].geometry.type', message }]
```

`Kartograf.validateStory(config)` is also available as a static method. The
JSON Schema is published at
`https://kartograf.cc/schema/story.schema.json`.

`createStory()` logs validation errors automatically. Unknown geometry types
also log the supported type list. Do not ignore these messages.

## Minimal valid story

```js
{
  title: 'Istanbul to Ankara',
  scenes: [{
    id: 'route',
    camera: { zoomLevel: 7, pitch: 25, duration: 2000 },
    transition: { delay: 1 },
    features: [{
      geometry: {
        type: 'LinePointString',
        coordinates: [[28.978, 41.008], [32.86, 39.933]]
      },
      marker: { type: 'PULSING', popup: { title: 'Ankara' } },
      line: { color: '#c9a87c', width: 4, animate: true }
    }]
  }]
}
```

## Core rules

- `scenes` is required and non-empty. Each scene has `features`.
- Camera lives on the **scene**, not on the feature. Canonical fields:
  `zoomLevel`, `pitch`, `bearing`, `duration`, `shouldFly`, `shouldRotate`,
  `orbit`, `shouldShowInSequence`, `focusedItemIndexes`, `sequence`.
- Friendly aliases are accepted: `zoom` → `zoomLevel`, `fly` → `shouldFly`,
  `rotate` → `shouldRotate`, `focused` → `focusedItemIndexes`.
- Lines fit their buffered bounds; points fly to their coordinates.
- `transition: { type: 'fade' | 'crossfade' | 'blur', duration, delay }`.
- Narration: `meta: { audioUrl, sync: { scenes: { '1': { at: 3.2 } } } }`.
- Call `story.enableControls()` for the built-in prev / play-pause / next bar.
- `story.play(startIndex?)`, `stop()`, `next()`, `prev()`, `getProgress()`,
  `getCurrentScene()`, `getTimeline()`.
- Give a scene `duration` (seconds) when it will be rendered deterministically.
  `kartograf.getTimeline(config)` returns `{ duration, fps, estimated, scenes }`
  with each scene's `start`, `end`, `duration` and `explicit` flag.
- `player.renderAt(seconds)` renders one deterministic frame. Camera is applied
  instantly; first-phase layer support is `Point`, `LineString`,
  `LinePointString` and `Polygon`. Other types are reported in
  `result.unsupported`; use real-time capture for those.
- Events: `sceneStart`, `sceneEnd`, `complete`, `stopped`, `audioError` on
  `story.story`.
- Branching: `story.story.addBranch(fromId, condition, toId)`.

## Geometry types

Standard: `Point`, `LineString`, `Polygon`, `MultiPoint`, `MultiLineString`,
`MultiPolygon`, `GeometryCollection`.

Custom: `LineArc`, `MultiLineArc`, `LinePointString`, `MultiLinePointString`,
`Timeline`, `Circle`, `Extrusion`, `Donut`, `FlowLine`, `Cluster`, `IconPoint`,
`Heatmap`, `Arc`, `Label`, `Choropleth`, `Gradient`, `Fog`, `Mask`.

Use `LinePointString` when a line should draw while a marker travels along it.
Use `LineArc` for a two-point curve. Use `Timeline` only with a real GeoJSON URL.

## Effects

```js
kartograf.postProcess({ bloom: 0.35, bloomThreshold: 0.6, vignette: 0.4 });
kartograf.postProcess({ focusBlur: 12 });
kartograf.postProcess(null);
```

## Limitations

- Browser-only. Deterministic `renderAt` / `--timeline` covers `Point`,
  `LineString`, `LinePointString` and `Polygon`; other types use the real-time
  capture script. Camera sequences and audio are not frame-accurate yet.
- Needs a real browser and a loaded MapLibre style. Some styles/tiles need keys.
- Audio autoplay may be blocked. Listen for `audioError` and provide a play
  button.
- The map style and external data URLs must allow CORS.
- Bundle is about 809 KiB minified; 3D models and large GeoJSON add to that.

## References

- [Story API](references/api.md)
- [Geometry types](references/geometry-types.md)
- [Recipes](references/recipes.md)
- [Troubleshooting](references/troubleshooting.md)

## Examples

- Live quickstart: https://kartograf.cc/quickstart
- Examples: https://kartograf.cc/quickstart
- Docs: https://kartograf.cc/docs
- Schema: https://kartograf.cc/schema/story.schema.json

Use `scripts/validate-story.mjs <file.json>` to validate a story against the
public bundle. Validate every story before handing it to a user.
