@openverb/geostory

The Future of Spatial Storytelling

A portable, format-agnostic language for spatial narratives built on top of OpenVerb. Define your story declaratively, and let the renderer handle the camera.

npm i @openverb/geostory GitHub Repository

Cinematic QGIS Rendering

Our GS Studio QGIS plugin is the first canonical implementation of the GeoStory format, transforming declarative .ov documents into fully-voiced, cinematic geographic documentaries.

Declarative Geographic Authority

A valid GeoStory is playable from its declarative data alone. Authoring tools commit geocoding results and bounds directly to the file, enabling seamless playback across platforms without requiring external dependencies.

Top-level registries for basemaps, places, and audio
Scenes compile into atomic OpenVerb actions

How GeoStory Works

Unlike traditional map animations that rely on manual keyframes, GeoStory is completely declarative. It revolves around one core invariant: A valid story must be playable from its declarative data alone.

A Complete Example

Places, basemaps, and audio are defined in top-level registries to keep scenes lightweight. Scenes act as spatial macros, abstracting away complex camera math and transitions.

# A complete OpenVerb GeoStory (.ov)
name: sf-redevelopment
version: 1.0.0
profile: geostory

story:
  title: "San Francisco Transbay Redevelopment"
  author: "GeoStory Team"

basemaps:
  - id: bm_streets
    name: "CartoDB Positron"
    type: xyz
    url: "https://basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png"
    max_zoom: 20

places:
  - id: pl_transbay
    as_written: "Transbay, San Francisco"
    resolved:
      point: [-122.3948, 37.7887]
      bounds: [[-122.4005, 37.7845], [-122.3890, 37.7925]]

scenes:
  - id: sc_01_terminal
    sequence: 1
    place_id: pl_transbay
    basemap: bm_streets
    transition: cut
    content:
      caption: "The Transbay Terminal, 1939 to 2010."
      narration: >-
        For seventy years this corner of downtown San Francisco was organised
        around a bus terminal.

  - id: sc_02_transit_center
    sequence: 2
    place_id: pl_transbay
    basemap: bm_streets
    transition: fly
    camera:
      mode: 3d
      center: [-122.3968, 37.7897]
      zoom: 17
      pitch: 55
      bearing: 20
    content:
      caption: "The new Salesforce Transit Center."
      narration: >-
        The new transit center opened in August 2018. Below it sits an empty
        train box, built for rail service that has not yet been funded.

Top-Level Registries

Notice how basemaps and places are defined at the root. Authoring tools commit geocoding results directly to the file, so players never have to hit an external geocoding API.

Scene Macros

When a renderer processes a scene, it expands it into atomic OpenVerb actions (like geostory.basemap.set or geostory.camera.fly_to), calculating proper framing automatically based on the resolved bounds.