About gdal3.js

Convert raster and vector geospatial data to various formats and coordinate systems entirely in the browser.

b

Published by

README.md

gdal3.js - Gdal compiled to JavaScript

gdal3.js is a port of Gdal applications (gdal_translate, ogr2ogr, gdal_rasterize, gdalwarp, gdaltransform) to Webassembly. It allows you to convert raster and vector geospatial data to various formats and coordinate systems.

gdal3.js uses emscripten to compile Gdal, proj, geos, spatialite, sqlite, geotiff, tiff, webp, expat, zlib and iconv to webassembly.

If you are building a native application in JavaScript (using Electron for instance), or are working in node.js, you will likely prefer to use a native binding of Gdal to JavaScript. A native binding will be faster because it will run native code.

gdal3.js GUI

gdal3.js GUI is a web application that provides a gui to gdal_translate, ogr2ogr and gdal_rasterize applications to be used online. Uses gdal3.js in the background. It runs on the browser and files are converted on the client side.

https://gdal3.js.org

Update 09 Sep 2025

Dear gdal3.js community

Excited to announce that https://cpp.js.org has appeared in React Universe Conf by CallStack

gdal3.js is migrating to cpp.js architecture.

Open issues will be resolved and the project will be maintained.

Supported Formats

Raster

Read & Write \ AAIGrid, ADRG, ARG, BLX, BMP, BT, BYN, CALS, CTable2, DTED, EHdr, ELAS, ENVI, ERS, FIT, GIF, GPKG, GRIB, GS7BG, GSAG, GSBG, GTX, GTiff, HF2, HFA, ILWIS, ISCE, ISIS2, ISIS3, JPEG, KMLSUPEROVERLAY, KRO, LAN, LCP, Leveller, MBTiles, MEM, MFF, MFF2, MRF, NITF, NTv2, NWT_GRD, OpenFileGDB, PAux, PCIDSK, PCRaster, PDS4, PNG, PNM, R, RMF, ROI_PAC, RRASTER, RST, Rasterlite, SAGA, SGI, SIGDEM, SRTMHGT, Terragen, USGSDEM, VICAR, VRT, WEBP, WMTS, XPM, XYZ, ZMap, Zarr

Read Only \ ACE2, AIG, AirSAR, BIGGIF, BSB, CAD, CEOS, COASP, COSAR, CPG, CTG, DERIVED, DIMAP, DIPEx, DOQ1, DOQ2, ECRGTOC, EIR, ESAT, ESRIC, FAST, GFF, GRASSASCIIGrid, GSC, GXF, GenBin, IRIS, ISG, JAXAPALSAR, JDEM, L1B, LOSLAS, MAP, MSGN, NDF, NGSGEOID, NOAA_B, NSIDCbin, NWT_GRC, OZI, PDS, PRF, RIK, RPFTOC, RS2, SAFE, SAR_CEOS, SDTS, SENTINEL2, SNODAS, SRP, STACIT, STACTA, TGA, TIL, TSX

Write Only \ COG, PDF

Vector

Read & Write \ CSV, DGN, DXF, ESRI Shapefile, FlatGeobuf, GML, GPKG, GPX, GeoJSON, GeoJSONSeq, GeoRSS, Geoconcept, JML, JSONFG, KML, MBTiles, MVT, MapInfo File, MapML, Memory, ODS, OGR_GMT, OpenFileGDB, PCIDSK, PDS4, PMTiles, S57, SQLite, Selafin, VDV, VICAR, WAsP, XLSX

Read Only \ AVCBin, AVCE00, CAD, EDIGEO, ESRIJSON, GTFS, Idrisi, LVBAG, OGR_PDS, OGR_SDTS, OGR_VRT, OSM, SVG, SXF, TIGER, TopoJSON, UK .NTF, VFK

Write Only \ PDF, PGDUMP

Guide

Installation

Script (CDN) \ Note: It doesn't work with web worker.

<script type="text/javascript"
    src="https://cdn.jsdelivr.net/npm/[email protected]/dist/package/gdal3.js"
    integrity="sha384-yW4c2Jx7lsREjJg58+ZI5U6gAso2bRAPw3LdzPWm7z8+rMJ24R7AS+EFyXDPxgYM"
    crossorigin="anonymous"
></script>

initGdalJs({ path: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/package', useWorker: false }).then((Gdal) => {});

Example: https://github.com/bugra9/gdal3.js/tree/master/apps/example-browser

Script (Local)

<script type="text/javascript" src="gdal3.js"></script>

initGdalJs().then((Gdal) => {});

Example: https://github.com/bugra9/gdal3.js/tree/master/apps/example-browser-worker

ES Module

<script type="module">
    import 'gdal3.js'

    initGdalJs().then((Gdal) => {});
</script>

Example: https://github.com/bugra9/gdal3.js/tree/master/apps/example-module-browser-worker \ Example: https://github.com/bugra9/gdal3.js/tree/master/apps/example-module-browser

Builder such as Webpack (Vue, React, Angular, ...)

pnpm add gdal3.js
# or
yarn add gdal3.js
# or
npm install gdal3.js

import initGdalJs from 'gdal3.js';

initGdalJs({ path: 'static' }).then((Gdal) => {});

plugins: [
    new CopyWebpackPlugin({
        patterns: [
            { from: '../node_modules/gdal3.js/dist/package/gdal3WebAssembly.wasm', to: 'static' },
            { from: '../node_modules/gdal3.js/dist/package/gdal3WebAssembly.data', to: 'static' }
        ]
    })
]

Full working example: https://github.com/bugra9/gdal3.js/blob/master/apps/app-gui/src/App.vue

Vite + Vue3

pnpm add gdal3.js
# or
yarn add gdal3.js
# or
npm install gdal3.js

<script setup>
import { ref } from 'vue'
import workerUrl from 'gdal3.js/dist/package/gdal3.js?url'
import dataUrl from 'gdal3.js/dist/package/gdal3WebAssembly.data?url'
import wasmUrl from 'gdal3.js/dist/package/gdal3WebAssembly.wasm?url'
import initGdalJs from 'gdal3.js';

const paths = {
  wasm: wasmUrl,
  data: dataUrl,
  js: workerUrl,
};

const count = ref(0);
initGdalJs({paths}).then((Gdal) => {
    count.value = Object.keys(Gdal.drivers.raster).length + Object.keys(Gdal.drivers.vector).length;
});
</script>

<template>
  <div>Number of drivers: {{ count }}</div>
</template>

Node

pnpm add gdal3.js
# or
yarn add gdal3.js
# or
npm install gdal3.js

const initGdalJs = require('gdal3.js/node');

initGdalJs().then((Gdal) => {});

Example: https://github.com/bugra9/gdal3.js/blob/master/apps/example-node/index.js

Basic Usage

const Gdal = await initGdalJs();

const files = ['a.mbtiles', 'b.tif']; // [Vector, Raster]
const result = await Gdal.open(files); // https://gdal3.js.org/docs/module-f_open.html
const mbTilesDataset = result.datasets[0];
const tifDataset = result.datasets[1];


/* ======== Dataset Info ======== */
// https://gdal3.js.org/docs/module-f_getInfo.html
const mbTilesDatasetInfo = await Gdal.getInfo(mbTilesDataset); // Vector
const tifDatasetInfo = await Gdal.getInfo(tifDataset); // Raster


/* ======== Vector translate (mbtiles -> geojson) ======== */
const options = [ // https://gdal.org/programs/ogr2ogr.html#description
    '-f', 'GeoJSON',
    '-t_srs', 'EPSG:4326'
];
const output = await Gdal.ogr2ogr(mbTilesDataset, options); // https://gdal3.js.org/docs/module-a_ogr2ogr.html
const bytes = await Gdal.getFileBytes(output); // https://gdal3.js.org/docs/module-f_getFileBytes.html


/* ======== Raster translate (tif -> png) ======== */
const options = [ // https://gdal.org/programs/gdal_translate.html#description
    '-of', 'PNG'
];
const output = await Gdal.gdal_translate(tifDataset, options); // https://gdal3.js.org/docs/module-a_gdal_translate.html
const bytes = await Gdal.getFileBytes(output); // https://gdal3.js.org/docs/module-f_getFileBytes.html


/* ======== Rasterize (mbtiles -> tif) ======== */
const options = [ // https://gdal.org/programs/gdal_rasterize.html#description
    '-of', 'GTiff',
    '-co', 'alpha=yes'
];
const output = await Gdal.gdal_rasterize(mbTilesDataset, options); // https://gdal3.js.org/docs/module-a_gdal_rasterize.html
const bytes = await Gdal.getFileBytes(output); // https://gdal3.js.org/docs/module-f_getFileBytes.html


/* ======== Warp (reprojection) ======== */
const options = [ // https://gdal.org/programs/gdalwarp.html#description
    '-of', 'GTiff',
    '-t_srs', 'EPSG:4326'
];
const output = await Gdal.gdalwarp(tifDataset, options); // https://gdal3.js.org/docs/module-a_gdalwarp.html
const bytes = await Gdal.getFileBytes(output); // https://gdal3.js.org/docs/module-f_getFileBytes.html


// Close all datasets. // https://gdal3.js.org/docs/module-f_close.html
Gdal.close(mbTilesDataset);
Gdal.close(tifDataset);


/* ======== Transform (Coordinate) ======== */
const coords = [
    [27.143757, 38.4247972],
];
const options = [ // https://gdal.org/programs/gdaltransform.html#description
    '-s_srs', 'EPSG:4326',
    '-t_srs', 'EPSG:3857',
    '-output_xy',
];
const newCoords = await Gdal.gdaltransform(coords, options); // https://gdal3.js.org/docs/module-a_gdaltransform.html
console.log(newCoords); // [ [ 3021629.2074563554, 4639610.441991095 ] ]

API References

https://gdal3.js.org/docs

Examples

Full working example with worker and Vue.js -> Code, Live
Browser with Worker -> Code, Live
Browser without Worker -> Code, Live
Browser with Worker (Module) -> Code, Live
Browser without Worker (Module) -> Code, Live
Node.js -> Code

Development

Compiling

Install the EMSDK, as described here
Install Sqlite3. (#31)
Run pnpm install
Run pnpm run build

License

GNU Lesser General Public License v2.1 or later

See LICENSE to see the full text.

Compiled with

Inspired by

gdal3.js