How the Time Slider in GeoLibre Handles Time-Series Raster Data

GeoLibre’s Time Slider leverages the maplibre-gl-time-slider library to instantiate a TimeSliderControl that filters raster tiles by timestamp, synchronizing the UI dock with temporal map layers while enabling pixel-level time-series queries.

The Time Slider in GeoLibre (opengeos/GeoLibre) provides a comprehensive interface for visualizing temporal datasets within the open-source geospatial framework. Built on top of the maplibre-gl-time-slider library and exposed through the maplibre-time-slider plugin, this system bridges React-based UI controls with MapLibre GL JS rendering capabilities. When working with time-series raster sources such as Cloud-Optimized GeoTIFFs, WMS-Time layers, or temporal XYZ tiles, the slider manages state synchronization, theme consistency, and pixel-level data extraction across the timeline.

Core Plugin Architecture and Control Initialization

The entry point for temporal functionality resides in packages/plugins/src/plugins/maplibre-time-slider.ts. Upon activation, the plugin instantiates a TimeSliderControl and registers it as a map control at a configurable position—defaulting to bottom-left according to the source configuration.

During initialization, the plugin evaluates stored configurations. If no prior state exists, it constructs a fresh control with sensible defaults: a timeline spanning 1984-01-01 to 2013-01-01 with yearly granularity. This default range provides immediate context for common remote sensing datasets while remaining fully customizable through the control's API.

Theme Synchronization and UI Consistency

GeoLibre maintains visual coherence between the Time Slider dock and the application's global theme. A MutationObserver monitors the document class list for dark/light mode transitions, automatically updating the control's appearance whenever the theme changes. This ensures the timeline widget renders appropriately whether the user operates in dark mode or light mode without manual style overrides.

Store-Layer Mirroring and Source Identification

To isolate temporal layers from static geospatial data, GeoLibre marks every time-slider source with the constant TIME_SLIDER_SOURCE_KIND = "time-slider". The plugin watches the GeoLibre store and reconciles these specially marked layers with underlying MapLibre adapters defined in temporal-layers.ts.

This architecture allows the system to prune or rebuild temporal layers independently of other store data. When a raster source containing temporal metadata—such as a COG with a time band or a WMS-Time endpoint—is added, the plugin creates a corresponding store layer that mirrors the map's state while preserving the source's temporal characteristics.

Temporal Binding and Raster Filtering

The time-slider-binding.ts file handles the mathematical conversion between calendar dates and map filters. It implements two critical functions:

• pickGranularity: Analyzes the source's temporal metadata to determine the appropriate time step (daily, monthly, yearly)
• buildTimeFilter: Constructs a MapLibre filter expression that restricts raster tile requests to the currently selected timestamp

For vector sources, the binding supports "selector" time bindings that filter features based on temporal attributes. For raster sources, this mechanism ensures that only tiles corresponding to the active date range render on the map, optimizing bandwidth and visual clarity.

Pixel Time-Series Analysis and Identification

Two companion plugins extend the Time Slider's capabilities beyond simple visualization:

• time-slider-pixel-series.ts: Queries pixel values across the entire timeline to generate charts showing spectral or data evolution
• time-slider-pixel-identify.ts: Implements the "Identify" tool, returning precise pixel values for the selected timestamp

These components resolve source URLs through resolveUrl and, for mosaic sources, load manifests via loadMosaic to retrieve per-band values for each timestamp. This enables users to click any point on a temporal raster and observe how that specific pixel's value changes over decades or seasons.

Configuration Persistence and State Management

When users deactivate the Time Slider plugin, the current configuration—including timeline bounds, playback speed, and active sources—is captured via timeSliderControl.getConfig() and stored in savedConfig. Upon reactivation, the plugin restores this exact state, preserving user context across application sessions without requiring manual reconfiguration of date ranges or data sources.

Code Examples

Activating the Time Slider Plugin

// Activate the Time Slider plugin (usually done automatically on app start)
import { maplibreTimeSliderPlugin } from "@geolibre/plugins";
app.activatePlugin?.(maplibreTimeSliderPlugin.id);

Adding a Temporal COG Layer

// Add a COG raster with a temporal axis to the slider dock
await app.addLayer({
  id: "landsat-annual",
  type: "raster",
  sourceKind: "time-slider",
  source: {
    type: "cog",
    url: "https://example.com/landsat/annual.tif",
    // The COG must contain a temporal axis (e.g., a "time" band)
  },
});

Accessing the Active Control Programmatically

// Retrieve the active control to read the current timeline programmatically
import { getActiveTimeSliderControl } from "@geolibre/plugins";
const ctrl = getActiveTimeSliderControl();
if (ctrl) {
  const { startDate, endDate, currentDate } = ctrl.getConfig();
  console.log(`Showing ${currentDate} of ${startDate}–${endDate}`);
}

Implementing Pixel Time-Series Charts

// Use the Pixel Time-Series chart for a raster layer
import { PixelTimeSeriesControl } from "apps/geolibre-desktop/src/components/layout/PixelTimeSeriesControl";
<PixelTimeSeriesControl layerId="landsat-annual" />

Summary

• The Time Slider in GeoLibre operates through the maplibre-time-slider plugin, which wraps the maplibre-gl-time-slider library to provide temporal controls.
• Core functionality resides in packages/plugins/src/plugins/maplibre-time-slider.ts, where the plugin creates a TimeSliderControl, manages theme synchronization via MutationObserver, and handles activation/deactivation cycles.
• Temporal layers are marked with TIME_SLIDER_SOURCE_KIND = "time-slider" to enable isolated store-layer mirroring and management through temporal-layers.ts.
• The time-slider-binding.ts module parses temporal metadata and constructs MapLibre filters via buildTimeFilter and pickGranularity to restrict raster tiles to active timestamps.
• Pixel time-series analysis is enabled through companion plugins that resolve URLs, load mosaic manifests, and query values across the timeline for charting and identification tools.
• Configuration persistence ensures that timeline settings, speed, and source selections survive plugin deactivation and reactivation.

Frequently Asked Questions

How does GeoLibre identify which layers should be controlled by the Time Slider?

GeoLibre uses the constant TIME_SLIDER_SOURCE_KIND = "time-slider" to flag layers originating from temporal sources. The plugin watches the store for layers bearing this marker and reconciles them with MapLibre adapters without affecting other geospatial data. This approach allows the Time Slider to manage temporal raster and vector layers independently while maintaining clean separation from static base maps or overlay layers.

What raster formats support time-series visualization in GeoLibre?

The Time Slider supports any raster source that exposes temporal metadata, including Cloud-Optimized GeoTIFFs (COGs) with time bands, XYZ/WMTS tile layers with temporal parameters, WMS-Time endpoints, and time-filtered GeoJSON sources. The time-slider-binding.ts module parses each source's temporal axis to determine appropriate granularity and constructs the necessary MapLibre filters to request time-specific tiles.

How does the Time Slider maintain visual consistency with the application's theme?

A MutationObserver registered in packages/plugins/src/plugins/maplibre-time-slider.ts monitors the document's class list for dark or light mode changes. When the theme switches, the observer automatically updates the TimeSliderControl styling to match the current application theme, ensuring the timeline dock remains visually integrated whether the user interface displays in dark mode or light mode.

Can users analyze specific pixel values across different time steps?

Yes, through the time-slider-pixel-series.ts and time-slider-pixel-identify.ts plugins. These components utilize the active TimeSliderControl to resolve source URLs and load mosaic manifests, retrieving per-band pixel values for each timestamp. This enables the "Pixel Time Series" chart and "Identify" tool to display how individual pixel values evolve across the timeline, supporting change detection and temporal analysis workflows.

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