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

> Learn how to add COG Cloud Optimized Geotiff raster support in GeoLibre. Discover regex detection, WASM conversion, and dual rendering engines for efficient raster data handling.

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

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/plugins/maplibre-source-coop.ts) (for the Source Coop panel) and [`packages/plugins/src/plugins/maplibre-raster.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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:

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

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

```typescript
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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/cog-convert.ts)**: Houses the WASM conversion pipeline including `initCogWasm`, `convertGeoTiffToCog`, and `isTiledGeoTiff`.
- **[`packages/plugins/src/plugins/raster-layer-sync.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/plugins/raster-layer-sync.ts)**: Implements engine selection logic between WASM and Titiler.
- **[`packages/plugins/src/plugins/maplibre-raster.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/plugins/maplibre-raster.ts)**: Manages UI integration, default engine settings, and engine switching.
- **[`packages/plugins/src/plugins/openaerialmap-api.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/plugins/openaerialmap-api.ts)**: Provides Titiler URL construction utilities.
- **[`packages/plugins/src/plugins/maplibre-source-coop.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/remote-file-formats.ts).
- **Optional conversion** from striped GeoTIFF to COG runs client-side via WASM in [`cog-convert.ts`](https://github.com/opengeos/GeoLibre/blob/main/cog-convert.ts).
- **Dual rendering engines** support both local WASM tiling and remote Titiler proxies, selected in [`raster-layer-sync.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/plugins/maplibre-raster.ts).