How to Implement the Time Slider Plugin for Temporal Geospatial Data in GeoLibre

The GeoLibre Time Slider plugin enables interactive exploration of temporal datasets by binding a UI dock directly to a layer's time dimension, allowing users to scrub through Zarr or NetCDF time series without rebuilding map layers.

The opengeos/GeoLibre framework provides a built-in Time Slider plugin specifically designed for visualizing temporal geospatial data. This plugin integrates with multi-dimensional Zarr datasets and time-enabled NetCDF files, exposing a UI dock that drives a layer's time property directly. By implementing this plugin according to the core architecture, developers enable end-users to explore time slices interactively while the underlying DuckDB-WASM engine queries temporal data via ST_Read.

How the Time Slider Plugin Works

The plugin operates through a unidirectional data flow that keeps the map renderer synchronized with the temporal state. When a user moves the slider, the system updates the core store, which triggers the MapLibre renderer to fetch and display the appropriate time slice without reconstructing the layer object.

Core Components

• Zarr Layer (addZarrLayer): Loads multi-dimensional datasets and exposes a time dimension that the slider manipulates.
• Time Slider Plugin (packages/plugins/src/plugins/maplibre-time-slider.ts): Registers the <TimeSliderDock> UI component and dispatches { time: n } updates to active layers.
• Plugin Registry (packages/plugins/src/viewer-plugins.ts): Declares the plugin as a built-in viewer plugin, making it available in the Plugins panel for toggle activation.
• Core Store (@geolibre/core): Maintains layer state; receives setLayerTime calls and notifies renderers of temporal changes.
• MapLibre Sync (@geolibre/map): Reacts to store changes and invokes DuckDB-WASM to retrieve specific temporal slices.

Step-by-Step Implementation Guide

Follow these steps to integrate the Time Slider into your GeoLibre application.

1. Register the Plugin

Import and register the plugin in your application's plugin hook to make it available in the interface.

// apps/geolibre-desktop/src/hooks/usePlugins.ts
import { maplibreTimeSlider } from '@geolibre/plugins';

const plugins = [
  maplibreTimeSlider,
  // other plugins...
];

2. Load a Temporal Dataset

Use the addZarrLayer helper to load data with a time dimension. The function automatically detects temporal dimensions but allows explicit configuration.

import { addZarrLayer } from '@geolibre/core';

const layerId = await addZarrLayer({
  url: 'https://example.com/climate-timeseries.zarr',
  temporalDimension: 'time', // Optional: override auto-detection
});

This creates a GeoLibreLayer instance with a mutable time property that the slider controls.

3. Activate the Time Slider UI

Open the Plugins panel via the gear icon, then enable Time Slider. The dock appears on the right side of the map canvas and automatically binds to the active temporal layer.

4. Control Time Programmatically

Use setLayerTime to jump to specific indices programmatically, bypassing the UI when necessary.

import { setLayerTime } from '@geolibre/core';

// Jump to the 42nd time step
await setLayerTime(layerId, 42);

5. Persist State (Optional)

The current time index is automatically tracked in the project state. Call saveProject to write the temporal position to .geolibre.json.

import { saveProject } from '@geolibre/core';

await saveProject(); // Saves current time index with layer configuration

Practical Code Examples

Toggling the Slider UI in React

Create a button component that toggles the plugin visibility using the usePluginToggle hook.

import { usePluginToggle } from '@geolibre/ui';
import { maplibreTimeSlider } from '@geolibre/plugins';

export function TimeSliderToggle() {
  const { enabled, toggle } = usePluginToggle(maplibreTimeSlider);
  
  return (
    <button onClick={toggle}>
      {enabled ? 'Hide' : 'Show'} Time Slider
    </button>
  );
}

Programmatic Time Jump from Analysis Tools

Execute temporal navigation from custom processing workflows without user interaction.

import { getActiveLayerId, setLayerTime } from '@geolibre/core';

async function runTemporalAnalysis() {
  const layerId = await getActiveLayerId();
  const optimalIndex = await computeBestTimeIndex(); // Custom logic
  
  await setLayerTime(layerId, optimalIndex);
}

Auto-Loading Data with Slider Activation

Automatically open the time slider when adding a temporal layer.

import { addZarrLayer, openPlugin } from '@geolibre/core';
import { maplibreTimeSlider } from '@geolibre/plugins';

async function loadAndExplore() {
  const id = await addZarrLayer({ url: '/data/weather.zarr' });
  
  // Automatically open slider dock for the new layer
  await openPlugin(maplibreTimeSlider, { layerId: id });
}

Key Source Files and Implementation Details

The following files define the Time Slider architecture according to the GeoLibre source:

• packages/plugins/src/plugins/maplibre-time-slider.ts: Implements the UI dock (<TimeSliderDock>) and handles the binding between slider events and setLayerTime dispatches.
• packages/plugins/src/viewer-plugins.ts: Declares maplibreTimeSlider in the viewer plugin registry, controlling its availability in the Plugins panel.
• apps/geolibre-desktop/src/hooks/usePlugins.ts: Entry point where built-in plugins are registered for the desktop application.
• docs/plugin-api.md: Documents the plugin interface and store interaction patterns used by the time slider.
• tests/time-slider-binding.test.ts: Contains test suites verifying slider-layer binding, auto-close behavior, and configuration persistence.
• packages/core/src/layers.ts: Defines the core layer object that holds the time property manipulated by the slider.

Summary

• The Time Slider plugin (maplibreTimeSlider) provides a UI dock for exploring temporal datasets without layer reconstruction.
• Temporal data loads via addZarrLayer, which exposes time dimensions for the slider to manipulate.
• Programmatic control is available through setLayerTime, getActiveLayerId, and openPlugin functions.
• The architecture uses a core store pattern where the slider updates state, triggering DuckDB-WASM queries via the MapLibre sync layer.
• State persistence automatically saves the current time index when calling saveProject.

Frequently Asked Questions

Does the Time Slider plugin support NetCDF files?

Yes, the plugin supports any temporal dataset loaded through GeoLibre's data layer API. While Zarr is the primary format mentioned in the implementation, NetCDF files with time dimensions are supported when loaded via compatible layer helpers that expose a time property to the core store.

Can I control the time slider programmatically without displaying the UI dock?

Yes, you can manipulate temporal state directly using setLayerTime from @geolibre/core. This updates the layer's time index and triggers a re-render without requiring the <TimeSliderDock> component to be mounted or visible.

How does the plugin handle large temporal datasets with thousands of time steps?

The plugin delegates temporal slicing to the DuckDB-WASM engine using ST_Read, which performs efficient columnar queries on the source data. Only the active time slice is fetched and rendered, keeping memory usage constant regardless of the total temporal extent.

Where is the current time index stored when saving a project?

The current time index is stored as part of the layer state in the project JSON (.geolibre.json). When you call saveProject, the core store serializes the time property of each layer, allowing projects to reopen at the exact temporal position where they were saved.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}