Data sources

Cloud Optimized GeoTIFF

Read raster data directly from a Cloud Optimized GeoTIFF on static storage. HTTP range requests retrieve the parts needed for the visible map area. The three maps below show RGB imagery, elevation data and classified raster values, each with its configuration.

Imagery from a URL

An RGB orthophoto over Catalonia. The layer definition is nothing but a URL: bounds and zoom range come from the file's own header.

Try it: open the network tab and pan the map. Requests retrieve small byte ranges from the 50 MB file. Cached tiles can be reused.

cog-imagery.map0.json

{
  "$schema": "https://map0.net/schema/v1.json",
  "version": 1,
  "meta": {
    "title": "COG imagery",
    "description": "An RGB orthophoto loaded directly from static storage."
  },
  "map": { "center": [1.83369, 41.5937], "zoom": 14 },
  "basemaps": [
    {
      "id": "gris",
      "title": "ICGC Grey",
      "type": "style",
      "url": "https://geoserveis.icgc.cat/contextmaps/icgc_mapa_base_gris.json",
      "attribution": "© Institut Cartogràfic i Geològic de Catalunya",
      "default": true
    },
    { "id": "none", "title": "None", "type": "empty" }
  ],
  "layers": [
    {
      "id": "ortho-cog",
      "type": "cog",
      "title": "Orthophoto (RGB COG)",
      "url": "https://labs.geomatico.es/maplibre-cog-protocol/data/image.tif",
      "attribution": "Orthophoto © ICGC · demo data © Geomatico",
      "metadata": {
        "url": "https://github.com/geomatico/maplibre-cog-protocol",
        "title": "maplibre-cog-protocol sample data"
      }
    }
  ],
  "controls": { "home": true },
  "i18n": { "locale": "en" }
}

Two views of one elevation model

The same 3 MB elevation file (BEV 25 m terrain model, Großglockner region) drives two layers: hillshade renders relief shading, color maps the elevation band onto a hypsometric ramp. The legend derives its class swatches from the ramp automatically.

Try it: hide either layer to view the other on its own. The hillshade layer draws shadows and highlights, with transparent flat areas. Its opacity slider controls the shading intensity.

cog-terrain.map0.json

{
  "$schema": "https://map0.net/schema/v1.json",
  "version": 1,
  "meta": {
    "title": "COG terrain",
    "description": "One DEM file, two renderings: hillshade and a hypsometric color ramp."
  },
  "map": { "bounds": [12.45, 46.95, 13.05, 47.3] },
  "basemaps": [
    {
      "id": "grau",
      "title": "basemap.at Grey",
      "type": "raster",
      "url": "https://mapsneu.wien.gv.at/basemap/bmapgrau/normal/google3857/{z}/{y}/{x}.png",
      "attribution": "© basemap.at",
      "default": true
    },
    { "id": "none", "title": "None", "type": "empty" }
  ],
  "layers": [
    {
      "id": "dgm",
      "type": "cog",
      "title": "Hillshade (BEV DGM 25 m)",
      "url": "/data/bev-dgm25-grossglockner-3857.tif",
      "hillshade": { "exaggeration": 0.6 },
      "attribution": "Geländemodell © BEV, data.bev.gv.at (CC BY 4.0)",
      "metadata": {
        "url": "https://data.bev.gv.at/geonetwork/srv/ger/catalog.search#/metadata/6a853c17-8960-44a4-81fb-18e0549a1c80",
        "title": "Digitales Geländehöhenmodell – Höhenraster 25m, Stichtag 31.12.2022 (BEV)"
      }
    },
    {
      "id": "dgm-elevation",
      "type": "cog",
      "title": "Elevation (CartoEarth ramp)",
      "url": "/data/bev-dgm25-grossglockner-3857.tif",
      "color": { "scheme": "CartoEarth", "min": 800, "max": 3800 },
      "opacity": 0.7,
      "attribution": "Geländemodell © BEV, data.bev.gv.at (CC BY 4.0)"
    }
  ],
  "controls": { "legend": { "open": true }, "home": true },
  "i18n": { "locale": "en" }
}

Classifying values with colours

Use color.classes to assign colours to exact pixel values or value ranges. This example uses a binary sealed-surfaces raster for Austria, stored in a 1.3 GB file. Each class receives a labelled legend entry. Values outside the defined classes are transparent.

Try it: the unsealed class uses an eight-digit hex colour. The last two digits control opacity, allowing the basemap to show through. Remove the class to hide those pixels completely.

cog-classes.map0.json

{
  "$schema": "https://map0.net/schema/v1.json",
  "version": 1,
  "meta": {
    "title": "COG classification",
    "description": "A binary raster styled by exact pixel values with hand-picked colors."
  },
  "map": { "bounds": [14.38, 48.01, 14.47, 48.08] },
  "basemaps": [
    {
      "id": "grau",
      "title": "basemap.at Grey",
      "type": "raster",
      "url": "https://mapsneu.wien.gv.at/basemap/bmapgrau/normal/google3857/{z}/{y}/{x}.png",
      "attribution": "© basemap.at",
      "default": true
    },
    { "id": "none", "title": "None", "type": "empty" }
  ],
  "layers": [
    {
      "id": "versiegelung",
      "type": "cog",
      "title": "Sealed surfaces 2022",
      "url": "https://map0.s3.fr-par.scw.cloud/data/VER_2022_AT_3857.tif",
      "color": {
        "classes": [
          { "value": 0, "color": "#67a9cf40", "label": "unsealed (0)" },
          { "value": 1, "color": "#c22f2f", "label": "sealed (1)" }
        ]
      },
      "attribution": "Versiegelung 2022 © ÖROK-Monitoring, Bearbeitung: Umweltbundesamt (CC BY 4.0)",
      "metadata": {
        "url": "https://www.data.gv.at/datasets/90c7dd9b-32eb-4521-9489-d31f0d673ae6",
        "title": "ÖROK-Monitoring Versiegelung 2022 (Stand Berechnungsjahr 2025)"
      }
    }
  ],
  "controls": { "legend": { "open": true }, "home": true },
  "i18n": { "locale": "en" }
}

What these demos show

A cog layer needs a URL; extent and zoom range are read from the file header
color maps a single band onto a named ramp (ColorBrewer/CARTOColors), discrete classes or continuous
color.classes instead styles exact values or from–to ranges directly, with hand-picked colors and labels
hillshade renders a single-band DEM as relief shading (exaggeration, light direction, colors)
The legend panel derives its entries from the color ramp or the classes automatically
The decoder (geotiff.js, ~150 KB) loads when a COG layer is used

Colour ramp names follow Brewer<Name><classes>, such as BrewerSpectral9, or Carto<Name>, such as CartoEarth. See the colour scheme examples. An unsupported name puts the layer into an error state.

Class ranges include from and exclude to. The class with the highest to also includes that upper bound. Exact values take precedence over ranges. The same file cannot use classes and a colour ramp or hillshade at the same time on one page, because the colour function is associated with the COG URL.

EPSG:3857 required. This adapter reads Web Mercator COGs. Prepare files in other coordinate systems with gdalwarp -t_srs EPSG:3857 and gdal_translate -of COG. Nodata pixels are transparent; when no nodata value is declared, zero is treated as transparent.

When to reach for COG

COG is useful for publishing orthophotos, elevation models or other raster data as individual files. Host the file on storage that supports HTTP range requests and CORS. The browser can then read the required parts as the view changes. A tiled service such as WMTS is another option for serving raster data.

The adapter uses @geomatico/maplibre-cog-protocol for imagery, colour ramps and hillshading. The terrain example uses the BEV 25 m elevation model, transformed to EPSG:3857 and clipped to a smaller area. The original dataset uses EPSG:31287.