gdal3.js
DOCS · RECIPES & EXAMPLES

Recipes & examples

Paste-ready snippets for the jobs people actually come here for. All of them assume an initialised module; see Quick start for the boot lines.

In every snippet, Gdal comes from the header import and Module is the initCppJs() return. The /opfs/ paths are browser OPFS; on Node and React Native use host paths.

Convert a vector file (+ reproject)

ogr2ogr equivalent
const ds   = await Gdal.openEx("/opfs/cities.geojson");
const opts = await Module.toVector("VectorString", [
  "-f", "GPKG",
  "-t_srs", "EPSG:3857",
]);
const out = await ds.vectorTranslate("/opfs/cities.gpkg", opts);
await out.close(); await ds.close();

Read the result back

browser: read OPFS output
// the conversion above wrote /opfs/cities.gpkg
const dir  = await navigator.storage.getDirectory();
const fh   = await dir.getFileHandle("cities.gpkg");
const blob = await fh.getFile();   // download, upload, or display

Multi-file outputs (a Shapefile is .shp + .shx + .dbf) come back via ds.getFileList(). On Node and React Native the outputs are real files on the host filesystem. The VFS guide has the full tour.

Reproject a raster (gdalwarp)

warp
const src  = await Gdal.openEx("/opfs/dem.tif");
const opts = await Module.toVector("VectorString", ["-t_srs", "EPSG:4326", "-r", "bilinear"]);
const out  = await Gdal.warp("/opfs/dem-4326.tif", null,
  await Module.toVector("VectorDataset", [src]), opts);   // sources as a typed vector
await out.close(); await src.close();

Inspect metadata (gdalinfo / ogrinfo)

info as JSON
const ds   = await Gdal.openEx("/opfs/input.tif");
const json = JSON.parse(await ds.info(await Module.toVector("VectorString", ["-json"])));
console.log(json.bands?.length, json.coordinateSystem?.wkt);

// vector side: ds.vectorInfo(opts), and ds.multiDimInfo(opts) for multidim data

Mosaic several rasters with a VRT

buildvrt + translate
const a = await Gdal.openEx("/opfs/tile-a.tif");
const b = await Gdal.openEx("/opfs/tile-b.tif");

const vrt = await Gdal.buildVRT("/vsimem/mosaic.vrt",
  await Module.toVector("VectorDataset", [a, b]),   // sources as a typed vector
  await Module.toVector("VectorString", []),        // source names (optional)
  await Module.toVector("VectorString", []));       // build options

const out = await vrt.translate("/opfs/mosaic.tif",
  await Module.toVector("VectorString", ["-of", "COG"]));
await out.close(); await vrt.close(); await a.close(); await b.close();

Hillshade a DEM (gdaldem)

demProcessing
const dem = await Gdal.openEx("/opfs/dem.tif");
const out = await dem.demProcessing(
  "/opfs/hillshade.tif",
  "hillshade",          // also: slope, aspect, color-relief, TRI, TPI, roughness
  "",                   // color file (color-relief only)
  await Module.toVector("VectorString", ["-z", "1.5"]),
);
await out.close(); await dem.close();

Open a zipped shapefile directly

/vsizip/
const ds = await Gdal.openEx("/vsizip//opfs/districts.zip");
// convert as usual; collect multi-file outputs with ds.getFileList()

Georeference an image with GCPs

gdal_translate -gcp equivalent
const opts = await Module.toVector("VectorString", [
  "-a_srs", "EPSG:4326",
  "-gcp", "0", "0", "28.85", "41.12",        // pixel, line, lon, lat
  "-gcp", "4000", "0", "29.15", "41.12",
  "-gcp", "4000", "3000", "29.15", "40.95",
  "-gcp", "0", "3000", "28.85", "40.95",
]);
const img = await Gdal.openEx("/opfs/scan.png");
const out = await img.translate("/opfs/scan-georef.tif", opts);
await out.close(); await img.close();
// programmatic alternative: the GCP class + Gdal.gcpsToGeoTransform + ds.setGCPs

Complete apps to read