How to Add Support for COG (Cloud Optimized Geotiffs) Rasters in GeoLibre

GeoLibre treats raster data through a source‑kind abstraction where COG is already a first‑class type ("cog"), enabling detection via regex patterns, optional client‑side conversion through WASM, and dual rendering engines (in‑browser WASM tiler or external Titiler).

GeoLibre is an open-source geospatial visualization library that streamlines working with diverse raster formats. To add support for COG (Cloud Optimized Geotiffs) rasters, developers interact with three architectural layers documented in the opengeos/GeoLibre repository: detection and classification, optional conversion, and rendering engine selection.

Detection and Classification Layer

GeoLibre identifies COG files through a source‑kind abstraction that maps file extensions and URLs to internal type identifiers.

File Pattern Matching

In packages/plugins/src/plugins/remote-file-formats.ts, a regular expression maps *.tif and *.tiff extensions to the "cog" kind. This regex acts as the first gate, allowing the system to recognize potential COG sources before any data loading occurs.

UI Integration

The isAddable("cog") function, utilized in both packages/plugins/src/plugins/maplibre-source-coop.ts (for the Source Coop panel) and packages/plugins/src/plugins/maplibre-raster.ts, determines whether the interface should present the "Add COG" option to users. When a user drags and drops a file or enters a URL, the classifyKey utility processes the input through the detection logic, and isAddable validates the resulting kind against available handlers.

Client-Side Conversion Layer

When users supply plain (striped) GeoTIFFs instead of pre-tiled COGs, GeoLibre can convert them internally without server-side dependencies.

The WASM-based converter in packages/processing/src/cog-convert.ts exposes three critical functions: initCogWasm to bootstrap the WebAssembly module, isTiledGeoTiff to inspect existing tiling, and convertGeoTiffToCog to perform the transformation. This pipeline runs entirely in the browser, avoiding any Python sidecar requirements.

The conversion accepts parameters such as compression algorithms defined in COG_WASM_COMPRESSIONS, allowing developers to specify codecs like 'deflate' during the tiling process.

Rendering Engine Selection

GeoLibre supports two distinct engines for streaming COG tiles, selected automatically or via user preference.

Engine Selection Logic

The packages/plugins/src/plugins/raster-layer-sync.ts file contains the decision logic that chooses between cog-tiler-wasm and titiler based on the runtime environment (desktop versus web) and user preferences. Meanwhile, packages/plugins/src/plugins/maplibre-raster.ts sets the default engine and manages UI updates when users manually switch between rendering options.

WASM Tiler vs. Titiler

WASM Tiler: The cog-tiler-wasm engine reads COG bytes client-side and serves MapLibre-compatible raster tiles directly in the browser, ideal for offline workflows or sensitive data that cannot leave the client.

Titiler: For remote COGs, packages/plugins/src/plugins/openaerialmap-api.ts provides buildTitilerTemplate, which constructs {z}/{x}/{y} URL templates pointing to external Titiler endpoints. This approach proxies the remote COG through a dedicated tile server, reducing client-side processing for large archives.

Complete Implementation Workflow

When integrating COG support into a GeoLibre application, the following flow executes:

1. URL Classification: The system passes the input through classifyKey and validates with isAddable("cog"), triggering the "Add COG" UI option.
2. Engine Selection: raster-layer-sync evaluates the runtime context to choose between the WASM tiler or Titiler backend.
3. Tile Fetching:
   • If using WASM, cog-tiler-wasm processes the COG bytes locally.
   • If using Titiler, buildTitilerTemplate generates the appropriate tile URL pattern.

If the source is a non-tiled GeoTIFF, the UI can invoke convertGeoTiffToCog from the processing package to generate a proper COG before adding it to the map.

Practical Code Examples

Detecting COG URLs

To determine if a user-provided URL represents a COG-ready source:

import { classifyKey, isAddable } from '@geolibre/plugins';

const url = 'https://example.com/elevation.tif';
const kind = classifyKey(url);               // → "cog"

if (isAddable(kind)) {
  // show the "Add COG" option
}

Converting Plain GeoTIFFs Client-Side

When the source is a striped GeoTIFF, convert it before adding to the map:

import { initCogWasm, convertGeoTiffToCog } from '@geolibre/processing';

await initCogWasm();                         // ensure WASM module is loaded
const rawBytes = await fetch(url).then(r => r.arrayBuffer());
const cogBytes = await convertGeoTiffToCog(new Uint8Array(rawBytes), {
  compression: 'deflate',                    // one of COG_WASM_COMPRESSIONS
});

await appRef.addCogLayer('DEM', cogBytes);   // add the newly created COG

Building Titiler Tile URLs

For remote COGs served via external tile servers:

import { buildTitilerTemplate } from '@geolibre/plugins';

const cogUrl = 'https://s3.amazonaws.com/data/area.tif';
const tileUrl = buildTitilerTemplate(cogUrl);
// → https://titiler.example.com/cog/tiles/WebMercatorQuad/{z}/{x}/{y}?url=...

Key Source Files

Understanding these specific files is essential for extending or debugging COG functionality in GeoLibre:

• packages/plugins/src/plugins/remote-file-formats.ts: Contains regex patterns mapping .tif/.tiff to the "cog" source kind.
• packages/processing/src/cog-convert.ts: Houses the WASM conversion pipeline including initCogWasm, convertGeoTiffToCog, and isTiledGeoTiff.
• packages/plugins/src/plugins/raster-layer-sync.ts: Implements engine selection logic between WASM and Titiler.
• packages/plugins/src/plugins/maplibre-raster.ts: Manages UI integration, default engine settings, and engine switching.
• packages/plugins/src/plugins/openaerialmap-api.ts: Provides Titiler URL construction utilities.
• packages/plugins/src/plugins/maplibre-source-coop.ts: Handles adding remote COG assets from the Source Coop panel.

Summary

• GeoLibre uses a source‑kind abstraction where COG is type "cog", detected via regex in remote-file-formats.ts.
• Optional conversion from striped GeoTIFF to COG runs client-side via WASM in cog-convert.ts.
• Dual rendering engines support both local WASM tiling and remote Titiler proxies, selected in raster-layer-sync.ts.
• Key integration points include isAddable("cog") for UI gating and buildTitilerTemplate for external tile URL generation.

Frequently Asked Questions

How does GeoLibre detect if a file is a COG?

GeoLibre uses the classifyKey function combined with regex patterns in packages/plugins/src/plugins/remote-file-formats.ts to map .tif and .tiff extensions to the "cog" source kind. The isAddable("cog") check then confirms the system can handle this specific format before exposing UI controls.

Can GeoLibre convert regular GeoTIFFs to COG format?

Yes. The packages/processing/src/cog-convert.ts module provides convertGeoTiffToCog, a WASM-based utility that converts striped GeoTIFFs to tiled COGs entirely within the browser. This eliminates the need for server-side Python processing or external conversion tools.

What is the difference between the WASM tiler and Titiler options?

The WASM tiler (cog-tiler-wasm) processes COG data client-side, suitable for offline use or data privacy requirements. Titiler is an external service that generates map tiles from remote COG URLs, offloading processing but requiring network access. GeoLibre selects between them automatically in raster-layer-sync.ts based on the runtime environment.

Where is the engine selection logic located?

Engine selection occurs in packages/plugins/src/plugins/raster-layer-sync.ts, which evaluates whether to use the in-browser WASM tiler or an external Titiler endpoint. Default preferences and UI switching logic are further managed in packages/plugins/src/plugins/maplibre-raster.ts.

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