Add a COG raster source

A Cloud Optimized GeoTIFF (COG) is one image file laid out so the browser can read just the tiles it draws. A .tif URL on a raster source is all it takes: maplibre-yaml reads the file with the COG protocol, so there is no tile server and no page JavaScript. Here one COG is the imagery, and a second holds elevation, which shades the hills and lifts the map into 3D.

Edit this map in the playground

The complete document

# Cloud Optimized GeoTIFFs — YAML only. A .tif file name is the only
# hint: imagery on a raster source, elevation on a raster-dem source (it
# drives the hillshade layer and the 3D terrain). fitTo frames the imagery
# file's own extent.
# Synthetic, public-domain data (a fictional island).
type: map
id: add-a-cog-raster-source
config:
  center: [10.2, 42.15]
  zoom: 9
  pitch: 50
  mapStyle: "https://tiles.openfreemap.org/styles/positron"
  fitTo: { source: imagery, padding: 20 }
legend:
  title: The island
sources:
  imagery:
    type: raster
    url: /gallery-assets/cloud-native/imagery.cog.tif
  elevation:
    type: raster-dem
    url: /gallery-assets/cloud-native/elevation.cog.tif
terrain:
  source: elevation
  exaggeration: 1.5
layers:
  - id: imagery
    type: raster
    source: imagery
    legend: { label: Imagery, color: "#789c5c", shape: square }
  - id: hills
    type: hillshade
    source: elevation
    paint: { hillshade-exaggeration: 0.5 }
    legend: { label: Hillshade, color: "#7f7f7f", shape: square }

What to notice

type: raster stays the MapLibre source type; the .tif file name tells maplibre-yaml to read it as a COG. For a URL without the extension, add format: cog.
type: raster-dem reads the same kind of file as elevation: it feeds the hillshade layer and terrain:. No encoding: or tileSize: is needed; maplibre-yaml sets what the COG reader produces.
fitTo frames the imagery file’s own extent, read from the file.
COGs must be in Web Mercator (EPSG:3857). A file in another projection is refused with the gdalwarp command that converts it.
The files are read with HTTP range requests, so they need a host that supports them (GitHub Pages, Netlify, S3, R2; not python -m http.server).
Data: synthetic and public domain (a fictional island), generated by scripts/fixtures/cog.py.

More: Cloud Optimized GeoTIFF (COG) — single-band colour ramps, making a COG with GDAL, sizes, hosting, and what the map says when a file can’t be read.

Use this map

Save the document as a .yaml file in your site and load it with <ml-map src="map.yaml"> on an HTML page, or with the <Map> component in Astro. To use it without maplibre-yaml, export it to a style.json with mlym emit.