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

> Explore how GeoLibre's Time Slider efficiently manages time-series raster data using maplibre-gl-time-slider. Filter tiles by timestamp and perform pixel-level queries.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-07-31

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/temporal-layers.ts).
- The [`time-slider-binding.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/time-slider-pixel-series.ts)** and **[`time-slider-pixel-identify.ts`](https://github.com/opengeos/GeoLibre/blob/main/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.