Kartograf / Field notes

A guide to maps in motion.

Start with a place, build a scene, and bring it to life. The Story API, geometry types, and configuration reference live here.

01

Introduction

Kartograf is a geospatial animation and storytelling library built on MapLibre GL JS. It extends standard GeoJSON with custom geometry types — such as animated line-point paths, bezier arcs, and time-series timelines.

Kartograf exposes a clean declarative Story API (createStory → play). Define scenes with camera settings, GeoJSON features, and transition delays — Kartograf normalizes the config into its internal rendering pipeline automatically.

02

Installation

Kartograf is CDN-only: there is no npm package and no build step. Load MapLibre first, then the Kartograf bundle.

Pin the version in production. latest always follows the newest release; use a versioned URL for reproducible deployments. The manifest at https://cdn.kartograf.cc/kartograf/info.json lists the current version and available files.
<!-- latest -->
<script src="https://cdn.kartograf.cc/kartograf/latest/kartograf.min.js"></script>

<!-- pinned (example) -->
<script src="https://cdn.kartograf.cc/kartograf/0.5.7/kartograf.min.js"></script>

MapLibre GL JS is also loaded via CDN:

<script src="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js"></script>
<link href="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css" rel="stylesheet" />

Dependencies bundled in the CDN build:

For agents: the JSON Schema lives at https://kartograf.cc/schema/story.schema.json, a compact reference at https://kartograf.cc/llms.txt, and the agent skill at https://kartograf.cc/skills/kartograf/SKILL.md. Validate a story with kartograf.validateStory(config) before playing it.
03

Basic Setup

Initialize a MapLibre map, then create a Kartograf instance bound to it:

// Kartograf & MapLibre loaded via <script> tags
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [35, 39],
  zoom: 5,
});

map.on('load', () => {
  const kartograf = new Kartograf({
    mapInstance: map,
  });

  // Ready to load data
});

The constructor takes a single options object:

OptionTypeRequiredDescription
mapInstancemaplibregl.MapYesMapLibre GL map instance with loaded style
libraryRefanyNoMapLibre namespace used for markers and popups. Defaults to window.maplibregl; pass it explicitly if MapLibre is loaded under another name.

Scene Transitions

Transitions are configured at the scene level via transition:

FieldTypeDefaultDescription
transition.delaynumber0Seconds to wait after the scene finishes before advancing to the next scene
transition.typestring—fade, crossfade or blur. Fades to the story background before the scene and back after it; blur uses the post-processing focus pull.
transition.durationnumber0.5Transition duration in seconds (blur defaults to 1)
04

Feature Properties

Features in a scene use a clean shorthand syntax. Kartograf normalizes this into the internal format automatically.

Scene Configuration

FieldTypeRequiredDescription
idstringNoScene identifier (used for branching)
cameraobjectNoCamera behavior for this scene's features
featuresarrayYesArray of features (declarative or GeoJSON)
staggernumberNoMilliseconds delay between each feature reveal. First feature appears immediately; subsequent features cascade.
durationnumberNoScene duration in seconds for the deterministic timeline/renderer. Falls back to meta.duration, then a 5s default marked as estimated.
transitionobjectNo{ delay: number } — seconds after scene ends
metaobjectNo{ audioUrl: string, duration?: number, sync?: object } — narration and optional duration fallback

StoryPlayer

Created by kartograf.createStory(config). Manages playback.

MethodReturnsDescription
play(startIndex?)PromisePlay from the first scene (or an optional zero-based scene index). Resolves when all scenes complete or playback is stopped.
stop()voidStop playback immediately and emit stopped.
next()PromiseStop the current run and play from the next scene.
prev()PromiseStop the current run and play from the previous scene.
enableControls(container?)voidInject the built-in prev / play-pause / next bar into the map container.
getProgress()number0–1 progress ratio. Returns 1 after a completed run.
getCurrentScene()Scene|nullCurrently playing scene.
getTimeline(options?)TimelineDeterministic scene timeline: { duration, fps, estimated, scenes[] }. Uses scene.duration.
renderAt(seconds)objectRender one deterministic frame. Applies camera instantly and draws supported layers at scene-local progress. Returns { scene, sceneIndex, sceneElapsed, progress, timeline, unsupported }.

Events on the Story

Attach listeners via story.story.on(event, handler):

story.story.on('sceneStart', (scene) => { /* ... */ });
story.story.on('sceneEnd', (scene) => { /* ... */ });
story.story.on('complete', () => { /* finished naturally */ });
story.story.on('stopped', () => { /* player.stop() was called */ });
06

Geometry Types

Kartograf supports 25 geometry types: 7 standard GeoJSON and 18 custom patch types. The factory routes each type to the appropriate Layer class.

Point

Standard

Single location with itemDisplayImage configuration. Supports CIRCLE, PULSING_ANIMATED, STABLE_ANIMATED, and THREED display modes. Camera flies to the point coordinates.

{
  geometry: { type: 'Point', coordinates: [28.978, 41.008] },
  marker: { type: 'PULSING', popup: { title: 'Istanbul' } },
}

LineString

Standard

Path with optional progressive draw animation. Camera fits bounds to the line with configurable buffer.

{
  geometry: {
    type: 'LineString',
    coordinates: [[28.978, 41.008], [32.860, 39.933]],
  },
  line: { color: '#c9a87c', width: 3, animate: true },
}

Polygon

Standard

Filled area with semi-transparent red fill. Camera fits to bounds. No marker or line config — display is purely geometric.

{
  geometry: {
    type: 'Polygon',
    coordinates: [[[32.8, 39.8], [32.9, 39.9], [32.7, 39.9], [32.8, 39.8]]],
  },
}

MultiPoint

Standard

Multiple points, each with independent marker configuration. The markers array maps 1:1 to coordinates by position. Each point can have a different display type and popup. Supports 3D models per point.

{
  geometry: {
    type: 'MultiPoint',
    coordinates: [
      [28.978, 41.008],
      [32.860, 39.933],
    ],
  },
  markers: [
    { type: 'PULSING', popup: { title: 'Istanbul' } },
    { type: 'CIRCLE' },
  ],
}

MultiLineString

Standard

Multiple lines, each with independent styling via the lines array. Each line can have different color, width, animate settings. Animates all lines simultaneously in lockstep.

{
  geometry: {
    type: 'MultiLineString',
    coordinates: [
      [[28.978, 41.008], [30.520, 39.800]],
      [[32.860, 39.933], [27.138, 38.423]],
    ],
  },
  lines: [
    { color: '#c9a87c', width: 3, animate: true },
    { color: '#88c0d0', width: 2, animate: true },
  ],
}

MultiPolygon

Standard

Multiple polygons rendered as fills. Each polygon is drawn with a semi-transparent red fill. No per-polygon styling — all share the same paint properties.

{
  geometry: {
    type: 'MultiPolygon',
    coordinates: [
      [[[32.8, 39.8], [32.9, 39.9], [32.7, 39.9], [32.8, 39.8]]],
      [[[33.0, 40.0], [33.2, 40.2], [33.0, 40.0]]],
    ],
  },
}

LinePointString Custom

The signature Kartograf type. A LineString that draws progressively while a point marker moves along the path tip simultaneously. Internally, this is a cross-breed — the geometry type is LinePointString, which the parser converts to LineString with itemType: "LinePointString". The factory then routes it to LinePointLayer instead of LineLayer.

Both marker and line configs are applied. The point can be a pulsing dot, static marker, or THREED 3D model. The line can have its own styling independent of the point.

{
  geometry: {
    type: 'LinePointString',
    coordinates: [[28.978, 41.008], [30.520, 39.800], [32.860, 39.933],
  },
  marker: { type: 'PULSING', popup: { title: 'Traveler' } },
  line: { color: '#c9a87c', width: 3, animate: true },
}

MultiLinePointString Custom

Multiple lines with simultaneous point animation. Each line draws while its corresponding point moves along the path tip. Uses both markers and lines arrays. The point markers update their positions frame by frame, and 3D models move in real-time.

{
  geometry: {
    type: 'MultiLinePointString',
    coordinates: [
      [[28.978, 41.008], [30.520, 39.800]],
      [[32.860, 39.933], [27.138, 38.423]],
    ],
  },
  markers: [
    { type: 'PULSING', popup: { title: 'Convoy A' } },
    { type: 'CIRCLE' },
  ],
  lines: [
    { color: '#c9a87c', width: 3, animate: true },
    { color: '#88c0d0', width: 2, animate: true },
  ],
}

LineArc Custom

Takes exactly two coordinates (start and end) and generates a smooth quadratic bezier curve between them using Turf.js. The arc's control point is calculated as a perpendicular offset from the midpoint. Internally, the parser converts LineArc to LineString with computed bezier coordinates and routes it to LineLayer — there is no dedicated LineArcLayer.

{
  geometry: {
    type: 'LineArc',
    coordinates: [[28.978, 41.008], [51.390, 35.689]],
  },
  line: { color: '#88c0d0', width: 3, animate: true },
}

Algorithm: turf.midpoint(start, end) → perpendicular offset by distance/4 → turf.bezierSpline([start, control, end]) → resulting bezier coordinates.

MultiLineArc Custom

Multiple arc pairs. Each pair [start, end] is independently converted to a bezier curve. The result is rendered as a MultiLineString and routed to MultiLineLayer — there is no dedicated MultiLineArcLayer.

{
  geometry: {
    type: 'MultiLineArc',
    coordinates: [
      [[28.978, 41.008], [32.860, 39.933]],
      [[27.138, 38.423], [30.520, 39.800]],
    ],
  },
  lines: [
    { color: '#c9a87c', width: 3, animate: true },
    { color: '#88c0d0', width: 2, animate: true },
  ],
}

Timeline Custom

Time-series data visualization within a bounding polygon. Fetches external GeoJSON data and iterates through date or numeric values, rendering points frame by frame. The initialQuery is used for the first frame; subsequent frames use query with CURRV and PREVV keywords substituted at runtime.

{
  geometry: {
    type: 'Timeline',
    coordinates: [[[26, 42], [45, 42], [45, 35], [26, 35], [26, 42]]],
  },
  timeline: {
    url: 'https://api.example.com/events.geojson',
    start: '1200-01-01',
    end: '1453-05-29',
    step: 30,
    qualifier: 'DATE',
    fps: 120,
    paint: { color: '#c9a87c', radius: 5, opacity: 0.7 },
    initialQuery: "['all',['==','$type','Point'],['==','date',CURRV]]",
    query: "['all',['==','$type','Point'],['>=','date',PREVV],['<','date',CURRV]]",
  },
}

Reserved keywords for queries:

KeywordReplaced With
CURRVCurrent iteration value (date or number)
PREVVPrevious iteration value

GeometryCollection Custom

Mixed geometry types in a single feature. Supports sequential display with per-sub-geometry display configs inlined directly in each geometry object. The destructGeometryCollection function destructures the GC into individual Feature objects, propagating parent properties to each sub-feature with itemLocalIndex for filtering.

Key behaviors:

{
  geometry: {
    type: 'GeometryCollection',
    geometries: [
      {
        type: 'Point',
        coordinates: [28.978, 41.008],
        // Inline config for this sub-geometry:
        marker: { type: 'PULSING', popup: { title: 'Start' } },
      },
      {
        type: 'LineString',
        coordinates: [[28.978, 41.008], [32.860, 39.933]],
        line: { color: '#c9a87c', width: 3, animate: true },
      },
      {
        type: 'LinePointString',
        coordinates: [[32.860, 39.933], [27.138, 38.423]],
        marker: { type: 'CIRCLE' },
        line: { color: '#8fbcbb', width: 2, animate: true },
      },
    ],
  },
  sequence: true,
  delayDurationInSecond: 2,
  focusedItemIndexes: [0, 2],
}

Circle New

Custom

Generates a polygon approximation of a circle from a center point and radius using Turf.js. Supports sweep, pulse, and breathe animations.

{
  geometry: { type: 'Circle', coordinates: [28.978, 41.008] },
  circle: { radius: 50, unit: 'km', color: '#c9a87c', opacity: 0.4, animate: 'sweep', speed: 1 },
}

Extrusion New

Custom

3D polygon extrusion using MapLibre's fill-extrusion paint type. Supports rise (grow height), wave (oscillate), and color sweep animations.

{
  geometry: { type: 'Extrusion', coordinates: [[[bounds...]]] },
  extrusion: { height: 200, color: '#c9a87c', opacity: 0.7, base: 0, animate: 'rise', speed: 1 },
}

Donut New

Custom

Two concentric circles producing a ring polygon with a hole. Supports sweep (inner radius grows) and pulse (thickness oscillates) animations.

{
  geometry: { type: 'Donut', coordinates: [28.978, 41.008] },
  donut: { innerRadius: 10, outerRadius: 50, unit: 'km', color: '#c9a87c', opacity: 0.5, animate: 'sweep', speed: 1 },
}

FlowLine New

Custom

Line with animated particles flowing continuously along the path. Two modes: particles (flowing dots) and stream (moving dash pattern). Supports glow and progressive draw animation before the flow begins.

{
  geometry: { type: 'FlowLine', coordinates: [[lng, lat], ...] },
  flow: {
    type: 'particles',
    color: '#c9a87c',
    width: 3,
    particleCount: 20,
    speed: 0.5,
    size: 4,
    animationDuration: 3000,
    glow: { color: '#c9a87c', width: 8, opacity: 0.3, blur: 4 },
  },
}

Cluster New

Custom

MapLibre-native point clustering with automatic cluster counts. Supports explode animation for interactive pulsing cluster/point radii.

{
  geometry: { type: 'Cluster', coordinates: [[lng, lat], ...] },
  cluster: { radius: 50, maxZoom: 14, color: '#c9a87c', animate: 'explode', speed: 1 },
}

IconPoint New

Custom

Image-based point marker using an external image URL. The image is rendered inside a CSS shape mask — choose square, circle, or octagon. Supports optional border. Uses an HTML marker element instead of a MapLibre symbol layer for full CSS control.

Note: Standalone IconPoint does not support popups or bounce animation. To use an image marker with a popup, set marker: { type: "ICON_POINT", iconPointConfig: { ... } } on a Point or LinePointString instead.
{
  geometry: { type: 'IconPoint', coordinates: [28.978, 41.008] },
  iconPoint: {
    imageUrl: 'https://example.com/icon.jpg',
    shape: 'circle',
    size: 48,
    border: { color: '#ffffff', width: 2 },
  },
}

Heatmap New

Custom

Density heatmap from point data using MapLibre's native heatmap layer type. Configurable radius, intensity, weight, and color stops. Supports pulse animation that oscillates intensity.

{
  geometry: { type: 'Heatmap', coordinates: [[lng, lat], ...] },
  heatmap: {
    radius: 30,
    intensity: 0.6,
    weight: 1,
    colorStops: [
      [0, 'rgba(33,102,172,0)'],
      [1, 'rgb(178,24,43)']
    ],
    animate: 'pulse',
  },
}

Arc New

Custom

Great-circle curved line between two coordinates using @turf/greatCircle. Renders a smooth flight-path arc. Supports sweep animation (line grows from origin to destination) and optional particles flowing along the arc.

{
  geometry: { type: 'Arc', coordinates: [[28.978, 41.008], [51.390, 35.689]] },
  arc: {
    color: '#88c0d0',
    width: 3,
    npoints: 100,
    animate: 'sweep',
    particles: true,
    particleCount: 15,
  },
}

Label New

Custom

Text label placed on the map via MapLibre's symbol layer with text-field. Configurable font, size, color, halo, offset, and anchor. Works on Point geometry.

{
  geometry: { type: 'Label', coordinates: [28.978, 41.008] },
  label: {
    text: 'Istanbul',
    size: 18,
    color: '#c9a87c',
    haloColor: '#111d2b',
    haloWidth: 2,
  },
}

Choropleth New

Custom

Data-driven polygon fills using MapLibre step expressions. Maps numeric property values to colors using configurable stops with animated color transitions.

{
  geometry: { type: 'Polygon', coordinates: [[[28.8, 40.9], ...]] },
  choropleth: {
    property: 'population',
    value: 75,
    stops: [[0, '#1b2838'], [50, '#c9a87c'], [100, '#f4f1ea']],
    animate: true,
  },
}

Works with: Polygon, MultiPolygon geometries. The value field supplies the data point for synthetic features; real GeoJSON datasets carry values in their properties natively.

Gradient Fill New

Custom

Canvas-generated gradient texture applied as a MapLibre fill-pattern. Supports radial and linear gradient types with configurable color stops.

{
  geometry: { type: 'Polygon', coordinates: [[[28.9, 41.0], ...]] },
  gradient: {
    type: 'radial',
    stops: ['#c9a87c', '#1b2838', '#88c0d0'],
  },
}

Works with: Polygon, MultiPolygon. The gradient texture stretches to fit the polygon bounds. Use type: 'linear' for diagonal gradient fill.

Fog of War New

Custom

World-covering dark overlay with geographic clear-zone holes. Added as an additive layer in StoryPlayer — does not replace the main feature render.

{
  geometry: { type: 'Point', coordinates: [28.978, 41.008] },
  marker: { type: 'PULSING' },
  fog: {
    color: '#0a0a14',
    opacity: 0.85,
    clearZones: [{ center: [28.978, 41.008], radius: 30 }],
    animate: { duration: 3000 },
  },
}

Additive overlay: Declare fog on any feature alongside its normal styling. The fog renders above the basemap with circular holes cut out at the specified geographic centers.

Mask Reveal New

Custom

Circular mask reveal that expands from a geographic center using CSS radial-gradient. Configurable feather for soft edges. Added as an additive overlay.

{
  geometry: { type: 'Point', coordinates: [28.978, 41.008] },
  marker: { type: 'PULSING' },
  mask: {
    type: 'circle',
    center: [28.978, 41.008],
    animate: { from: 0, to: 500, duration: 3000 },
    feather: 20,
  },
}

Screen-space effect: The mask center tracks the geographic point as the camera moves. When animation completes, the overlay is removed. Use feather: 0 for hard edges.

07

Feature Config Reference

Detailed reference for all declarative configuration fields. These are the clean-format keys that the normalizer maps to internal GeoJSON properties.

Marker

Controls how point-based geometries appear. Used by Point, LinePointString, and as entries in the markers array.

FieldTypeDefaultDescription
typestring"PULSING"PULSING, STABLE, CIRCLE, THREED, ICON_POINT
popup.titlestring—Popup header
popup.contentstring—Popup body
popup.imagestring—Popup background image URL
popup.sizenumber—Popup image container size in px
model.urlstring—GLTF model URL (requires type: "THREED")
model.sizenumber1Model scale factor
model.anglenumber0Initial rotation in degrees
bouncebooleanfalseAnimate the marker bouncing up and down (currently disabled in code)
iconPointConfigobject—When type: "ICON_POINT", pass { imageUrl, shape, size, border }

Display type mapping: PULSING → PULSING_ANIMATED, STABLE → STABLE_ANIMATED, CIRCLE → CIRCLE, THREED → THREED, ICON_POINT → ICON_POINT.

Line

Controls how line-based geometries render and animate. Used by LineString, LineArc, LinePointString, and as entries in lines.

FieldTypeDefaultDescription
colorstring"#0f115e"Hex color
widthnumber3Stroke width in pixels
opacitynumber1Stroke opacity (0–1)
blurnumber0Gaussian blur radius
animatebooleantrueProgressive line draw animation
durationnumber3000Animation duration in milliseconds (time-based, independent of line length)
dashedbooleanfalseEnable dashed stroke
dashArraynumber[][2, 2]Dash pattern [on, off]
ghostbooleanfalseShow a dashed preview line ahead of the drawing animation
ghostColorstring"#ffffff"Color of the ghost path line
ghostWidthnumber2Width of the ghost path line
particlesobject—Particle flow config: { count: 15, speed: 0.5, size: 3, color: '#c9a87c' }
glowobject—Glow trail behind the line: { width: 3, color: '#c9a87c', opacity: 0.3, blur: 3 }

FlowLine

Controls the FlowLine layer behavior. Used by FlowLine geometry type.

FieldTypeDefaultDescription
typestring"particles"particles (flowing dots) or stream (moving dash pattern)
colorstring"#c9a87c"Line and particle color
widthnumber3Line width in pixels
sizenumber4Particle radius in pixels
particleCountnumber20Number of flowing particles
speednumber0.5Animation speed multiplier
animationDurationnumber3000Progressive draw duration in ms before flow begins
glowobject—Glow behind the line: { width: 8, color, opacity: 0.3, blur: 4 }

IconPoint Config

Controls the image-based point marker.

FieldTypeDefaultDescription
imageUrlstring—URL of the image to display
shapestring"circle"circle, square, or octagon
sizenumber32Marker size in pixels
border.colorstring"transparent"Border color
border.widthnumber0Border width in pixels

Note: The bounce property is documented but not currently implemented for standalone IconPoint or marker-based ICON_POINT.

Heatmap Config

Controls the Heatmap layer behavior.

FieldTypeDefaultDescription
radiusnumber30Heatmap blur radius in pixels
intensitynumber0.5Heatmap intensity multiplier (0–1)
weightnumber1Per-point weight for density
opacitynumber0.8Heatmap opacity
colorStopsarray—Array of [stop, color] pairs for heatmap gradient
animatestring—pulse — oscillate intensity
speednumber1Animation speed multiplier

Arc Config

Controls the Arc layer behavior.

FieldTypeDefaultDescription
colorstring"#c9a87c"Arc line color
widthnumber2Arc line width
opacitynumber0.8Arc line opacity
npointsnumber100Number of points on the great-circle arc
animatestring—sweep — grow arc from origin
speednumber1Animation speed multiplier
particlesbooleanfalseEnable particle flow after sweep
particleCountnumber15Number of flowing particles
sizenumber3Particle size in pixels

Label Config

Controls the text label layer.

FieldTypeDefaultDescription
textstring—Label text content
colorstring"#333333"Text color
sizenumber12Font size in pixels
opacitynumber1Text opacity
fontarray["Open Sans Regular","Arial Unicode MS Regular"]Font family stack
haloColorstring"#ffffff"Text halo/outline color
haloWidthnumber1Text halo width
offsetarray[0, 0]Text offset [x, y] in ems
anchorstring"center"Text anchor: center, left, right, etc.

Choropleth

Data-driven polygon coloring using step expressions. Used on Polygon/MultiPolygon features.

FieldTypeDefaultDescription
propertystring"value"Name of the feature property to read
valuenumber—Data value for synthetic features (real GeoJSON carries values in properties natively)
stopsarray—Array of [threshold, color] pairs for the step expression
defaultColorstring"#1b2838"Fallback color when property is missing or null
animatebooleanfalseAnimate color transition from default to target colors over 2s

Gradient Fill

Canvas-based gradient texture applied via MapLibre fill-pattern. Used on Polygon/MultiPolygon features.

FieldTypeDefaultDescription
typestring"radial"radial or linear gradient type
stopsstring[]["#c9a87c","#1b2838"]Array of hex colors evenly distributed across the gradient
center[number, number]—Optional radial gradient center [lng, lat]

Fog of War

World-covering dark overlay with clear-zone holes. Additive overlay — declared on any feature alongside its normal styling.

FieldTypeDefaultDescription
colorstring"#0a0a14"Fog fill color
opacitynumber0.85Fog opacity (0–1)
clearZonesobject[][]Array of { center: [lng,lat], radius: km } clear zones cut as polygon holes
animate.durationnumber—Fade-in duration in ms (fades opacity from 0 to target)

Mask Reveal

Circular mask reveal expanding from a geographic center. Screen-space CSS effect — additive overlay. The center tracks the geographic point during camera movement.

FieldTypeDefaultDescription
typestring"circle"Mask shape (circle supported)
center[number, number]—Geographic center [lng, lat] of the mask reveal
animate.fromnumber—Starting mask radius in screen pixels
animate.tonumber—Ending mask radius in screen pixels
animate.durationnumber2000Animation duration in ms
feathernumber0Soft edge width in pixels (0 = hard edge)

Polygon

Controls polygon-specific display and animation behaviors.

FieldTypeDefaultDescription
breathebooleanfalseOscillate fill opacity between 0.2 and 0.8
progressiveFillbooleanfalseGrow polygon from centroid to full size
speednumber1Animation speed multiplier

Circle

Controls the Circle layer behavior. Used by Circle geometry type.

FieldTypeDefaultDescription
radiusnumber50Circle radius
unitstring"kilometers"Radius unit (kilometers, miles, etc.)
colorstring"#c9a87c"Fill color
opacitynumber0.4Fill opacity
animatestring—sweep, pulse, breathe
speednumber1Animation speed multiplier

Extrusion

Controls the Extrusion layer behavior. Used by Extrusion geometry type.

FieldTypeDefaultDescription
heightnumber200Extrusion height in meters
colorstring"#c9a87c"Extrusion color
opacitynumber0.7Extrusion opacity
basenumber0Base height in meters
animatestring—rise, wave, color
speednumber1Animation speed multiplier

Donut

Controls the Donut layer behavior. Used by Donut geometry type.

FieldTypeDefaultDescription
innerRadiusnumber10Inner ring radius
outerRadiusnumber50Outer ring radius
unitstring"kilometers"Radius unit
colorstring"#c9a87c"Fill color
opacitynumber0.5Fill opacity
animatestring—sweep, pulse, breathe
speednumber1Animation speed multiplier

Cluster

Controls the Cluster layer behavior. Used by Cluster geometry type.

FieldTypeDefaultDescription
radiusnumber50Cluster radius in pixels
maxZoomnumber14Maximum zoom level for clustering
colorstring"#c9a87c"Cluster color
animatestring—explode
speednumber1Animation speed multiplier

Buffer

Controls camera bounds padding. Higher values = more zoomed out. A buffer of 25 km is applied if not specified. The buffer is computed using @turf/buffer and the resulting bounding box is passed to map.fitBounds.

DeclarativeInternalDescription
buffer: 15itemBufferSize: [{ index: 0, buffer: 15 }]Buffer in kilometers

Timeline Config

DeclarativeInternalDescription
urlurlGeoJSON endpoint URL
startstartValueStart date "2024-01-01" or number 0
endendValueEnd date or number
stepstepSizeIncrement per frame (days for DATE, number for NUMBER)
qualifierqualifier"DATE" or "NUMBER"
displayTypedisplayType"CIRCLE" or "ANIMATED_POINT"
fpsfpsFrame rate in ms (lower = faster)
paintpaintStyle: { color, radius, opacity }
initialQueryinitialQueryFilter for the first frame
queryqueryFilter for subsequent frames. Keywords: CURRV, PREVV

Image Overlay

Raster image overlaid on the map with 0.7 opacity. Four-corner coordinate system (top-left, top-right, bottom-right, bottom-left).

DeclarativeInternalDescription
overlay.urlmapOverlayImage[].imageUrlImage URL
overlay.coordinatesmapOverlayImage[].coordinatesFour-corner lon/lat array
{
  geometry: { type: 'Polygon', coordinates: [bounds] },
  overlay: {
    url: 'https://example.com/map.jpg',
    coordinates: [
      [29.03, 42.92],
      [50.01, 42.92],
      [50.01, 33.01],
      [29.03, 33.01],
    ],
  },
}

Video Overlay

Video overlaid on the map using four-corner coordinate bounding. Supports autoplay, looping, fade-in/fade-out, and seeking.

DeclarativeInternalDescription
overlay.typetypeSet to "video" for video overlay
overlay.urlimageUrlVideo URL (MP4/WebM)
overlay.coordinatescoordinatesFour-corner lon/lat array
overlay.mutedmutedStart muted
overlay.looploopLoop playback
overlay.playplayAutoplay on add
overlay.fadeInfadeInFade-in duration in ms
overlay.fadeOutfadeOutFade-out duration in ms
overlay.seekseekInitial seek time in seconds
overlay.durationdurationMaximum playback duration in ms
{
  geometry: { type: 'Polygon', coordinates: [bounds] },
  overlay: {
    type: 'video',
    url: 'https://example.com/video.mp4',
    coordinates: [
      [29.03, 42.92],
      [50.01, 42.92],
      [50.01, 33.01],
      [29.03, 33.01],
    ],
    muted: true,
    loop: true,
    play: true,
    fadeIn: 500,
  },
}

Camera Options

Camera is configured at the scene level via scene.camera.

FieldTypeDefaultDescription
zoomLevelnumbermap defaultTarget zoom level
pitchnumber0Camera pitch (0–60)
bearingnumber0Camera rotation (0–360)
durationnumber3000flyTo / fitBounds duration in milliseconds
shouldRotatebooleanfalseEnable continuous map rotation (0.1° per 10ms)
orbitboolean / numberfalseAuto-orbit camera around the scene center. true = 30s full rotation, or specify seconds: orbit: 60.
For compatibility, zoom, fly, rotate and focused are accepted and mapped to zoomLevel, shouldFly, shouldRotate and focusedItemIndexes. Prefer the canonical names in new code.

GeometryCollection-only camera options:

FieldTypeDefaultDescription
shouldShowInSequencebooleantrueIf false, the sub-geometry renders but the camera does not move.
focusedItemIndexesnumber[]—Array of sub-item indexes that trigger camera movement. Others render silently.
delayDurationInSecondnumber0Seconds to wait before advancing to the next sub-item in a sequence.

Camera behavior per geometry:

Camera Sequence New

Multi-stage camera choreography defined via scene.camera.sequence — an array of timed actions. Runs independently of feature-driven camera, after all features finish rendering.

ActionParamsDescription
flyTot, target, zoom, pitch?, bearing?, duration, easing?Animate camera to a new center with optional pitch/bearing
fitBoundst, bbox, pitch?, bearing?, durationFit camera to a bounding box
orbitt, angle?, durationOrbit camera by specified degrees (default 360)
rotateTot, bearing, duration, easing?Rotate camera to a specific bearing
waitt, durationPause at current position
shaket, intensity?, durationCamera shake with configurable intensity and decay
{
  camera: {
    sequence: [
      { t: 0, action: 'flyTo', target: [28.978, 41.008], zoom: 10, duration: 3000, easing: 'easeOut' },
      { t: 3, action: 'orbit', angle: 180, duration: 4000 },
      { t: 8, action: 'flyTo', target: [32.860, 39.933], zoom: 12, pitch: 60, duration: 4000, easing: 'easeInOutCubic' },
    ],
  },
}

Each action has a t (start time in seconds from feature render completion). Actions are sorted by t and scheduled independently. Overlapping actions (e.g., orbit + flyTo at the same t) may conflict — stagger them.

Easing Curves New

28 easing functions available for camera animations. Pass the name string to any camera action that accepts easing.

CategoryAvailable Functions
Linearlinear
QuadeaseInQuad, easeOutQuad, easeInOutQuad
CubiceaseIn (alias), easeOut (alias), easeInOut (alias), easeInCubic, easeOutCubic, easeInOutCubic
QuarteaseInQuart, easeOutQuart, easeInOutQuart
QuinteaseInQuint, easeOutQuint, easeInOutQuint
SineeaseInSine, easeOutSine, easeInOutSine
ExpoeaseInExpo, easeOutExpo, easeInOutExpo
CirceaseInCirc, easeOutCirc, easeInOutCirc
BackeaseInBack, easeOutBack, easeInOutBack
ElasticeaseInElastic, easeOutElastic
BounceeaseOutBounce
Spring{ type: 'spring', stiffness: 0.3, damping: 0.7 }
Custom{ type: 'cubicBezier', values: [x1, y1, x2, y2] }

Usage: Set easing: 'easeOutCubic' on any camera action. For spring physics, pass easing: { type: 'spring', stiffness: 0.3, damping: 0.7 }. For custom beziers, easing: { type: 'cubicBezier', values: [0.42, 0, 0.58, 1] }.

08

Branching

Stories can have non-linear paths. Branches are evaluated when a scene ends. If the condition passes, playback jumps to the target scene instead of continuing sequentially.

MethodArgumentsDescription
story.story.addBranch(fromId, condition, toId)string, Function|Object, stringAdd a branch rule. condition can be a function (sceneData) → boolean or an object { key, value } for property matching.
// Condition as function
story.story.addBranch(
  'crossroads',
  (sceneData) => sceneData.sceneIndex === 0,
  'northern_route'
);

// Condition as key-value match
story.story.addBranch(
  'northern_route',
  { key: 'completed', value: true },
  'finale'
);
09

Plugin System

Extend Kartograf with custom geometry types by implementing the Layer interface and registering it:

// CDN: Kartograf.Layer is the base classspan>
const { Layer } = Kartograf;

class HeatmapLayer extends Layer {
  // Called to add sources and layers to the map
  add() {
    const { map, element, index, state, camera } = this;
    // Camera is handled automatically by the caller
  }

  // Called to clean up
  remove() {
    // Remove sources, layers, markers
  }

  // Optional: per-frame animation
  animate() {
    // Return when animation is complete
  }
}

kartograf.registerLayerType('Heatmap', HeatmapLayer);

After registration, use the type name in your geometry:

{
  geometry: { type: 'Heatmap', coordinates: [...] },
  // Your custom config fields
}

Layer class interface:

MethodRequiredDescription
constructor(map, element, index, state, camera)—Called by the factory. Store references.
add()YesAdd sources, layers, markers. Camera is handled before this is called.
remove()YesRemove all sources and layers this layer added.
animate()NoStart any animation. Fire ITEM_ANIMATION_FINISHED when done.
10

Events Reference

Kartograf fires custom events on the map instance. Listen to them to synchronize external UI, control navigation, or track state.

Event NameSourceFired When
ITEM_IN_ANIMATIONmapA feature animation starts (line draw, point move, camera flight). Sets state.isMapFlyToInProgress = true.
ITEM_ANIMATION_FINISHEDmapAnimation completes. Fires state.mapIsReadyForNextItemDraw() which advances the SequenceRunner.
map.on('ITEM_IN_ANIMATION', () => {
  // Disable UI, show loading
});

map.on('ITEM_ANIMATION_FINISHED', () => {
  // Re-enable UI, advance navigation
});

Animation Manager API:

// CDN: getAnimationManager is on the Kartograf global
const { getAnimationManager } = Kartograf;

const manager = getAnimationManager();
manager.getActiveAnimations();   // string[] of active IDs
manager.cancelAllAnimations();   // stop everything
manager.getStats();              // debug info
11

Post-processing

Kartograf can render the map through a WebGL post-processing pass. Effects are applied live and stay active until they are changed or disabled.

EffectRangeDescription
bloom0–1Additive bloom on bright pixels
bloomThreshold0–1Brightness threshold for bloom (default 0.5)
vignette0–2Radial edge darkening
focusBlurpixelsFull-image blur, used by transition.type: 'blur'
// Apply effects
kartograf.postProcess({
  bloom: 0.35,
  bloomThreshold: 0.6,
  vignette: 0.4,
});

// Reset / disable the pass
kartograf.postProcess(null);
Advanced: kartograf._postProcessor.loadLUT(image, size) loads a packed 3D LUT and kartograf._postProcessor.lut(size) activates color grading. reset() clears every effect.
12

Audio & Sync

Narration is configured per scene with meta.audioUrl. Audio starts when the scene starts and stops when the scene ends or playback stops.

{
  id: 'departure',
  meta: {
    audioUrl: '/audio/departure.mp3',
    sync: {
      // after this scene finishes, wait until the audio reaches 3.2s
      // before starting scene index 1
      scenes: { 1: { at: 3.2 } },
    },
  },
}

Browsers may block autoplay until the user interacts with the page. Pair narration with story.enableControls() or your own play button. If playback fails, the player emits audioError on the story.

13

Instance API

Everything is reached through the Kartograf instance created after the map loads.

MethodReturnsDescription
createStory(config)StoryPlayerBuild a player. Stops and clears the previous story automatically.
loadStory(config)PromiseCreate and immediately play a story.
validateStory(config)object{ valid, errors, warnings } with exact field paths. Also available as Kartograf.validateStory(config).
supportedGeometryTypes()string[]List of the 25 built-in geometry types.
getTimeline(config, options?)TimelineScene start/end/duration table for deterministic rendering. Also available as Kartograf.getTimeline(config).
getMap()MapLibre MapThe map instance passed to the constructor.
perf(enabled)voidToggle the animation performance overlay.
registerLayerType(name, Class)voidRegister a custom layer class for a new geometry type.
destroy()voidStop playback and remove layers, sources, listeners and injected CSS.
const result = kartograf.validateStory(storyConfig);
if (!result.valid) {
  console.error(result.errors); // [{ path: 'scenes[0].features[0].geometry.type', message: '...' }]
}

await kartograf.loadStory(storyConfig);
14

Error Handling

Validate before you play

kartograf.validateStory(config) returns every problem with a field path, so a bad config fails loudly instead of rendering nothing. createStory() also logs validation errors to the console automatically.

const { valid, errors, warnings } = kartograf.validateStory(config);
// errors:   [{ path: 'scenes[0].features[0].geometry.type', message: 'Unknown geometry type "LnieString". Supported: ...' }]
// warnings: unknown keys that will be ignored

Common errors and their causes

ErrorCauseSolution
Kartograf: mapInstance is requiredNo mapInstance passed to constructorPass a valid MapLibre GL map instance after the style has loaded
Kartograf: mapInstance must be a valid MapLibre GL map instanceThe object has no addSource methodPass the real maplibregl.Map instance
Kartograf: invalid story configValidation found one or more errorsRead the errors[].path and fix that field, or call validateStory() first
Kartograf: unknown geometry type "X"The type is not one of the 25 built-ins and is not registeredUse a supported type or call registerLayerType()
Layer.add() not implemented for XA custom layer class does not implement add()Implement add(), remove() and optionally animate()

Graceful degradation

15

Performance

Best practice: Always call kartograf.destroy() when removing a Kartograf instance (e.g., in framework beforeUnmount / useEffect cleanup). This prevents event listener leaks and orphaned animation frames.
16

Rendering frames

The repository includes a headless capture CLI. It opens the story in Chrome, captures PNG frames at a requested rate, and can encode an MP4 with ffmpeg.

// real-time capture
npm run build
node scripts/render-story.mjs examples/story-route.json \
  --out outputs/demo --fps 24 --video

// frame-stepped: uses scene.duration + player.renderAt(t)
node scripts/render-story.mjs examples/story-route.json \
  --timeline --out outputs/demo --fps 30 --video

// one deterministic frame
node scripts/render-story.mjs examples/story-route.json \
  --at 4.5 --out outputs/frame
Deterministic layer support (first phase): Point, LineString, LinePointString and Polygon (including progressive fill). Other layer types are reported in unsupported and should use the real-time capture path until their renderAt hook is implemented. Camera sequences and audio are not yet frame-accurate.
Real-time capture, not deterministic rendering. The script screenshots a live browser session. A frame-accurate seek(t) / renderAt(t) engine API is still planned. Chrome/Chromium and ffmpeg are required.

Timeline contract

Give each scene a duration and read the deterministic timeline before rendering:

const timeline = kartograf.getTimeline(config);
// { duration: 12, fps: 30, estimated: false, scenes: [
//   { id: 'istanbul', start: 0, end: 3, duration: 3, explicit: true },
//   { id: 'route', start: 3, end: 7, duration: 4, explicit: true }
// ] }
const clip = kartograf.getTimeline(config, { fps: 30, defaultSceneDuration: 5 });

scene.duration is in seconds. If it is omitted, meta.duration is used, then the default duration; timeline.estimated becomes true in that case.