A wrapper for running GDAL in the browser using gdal-js
npm install loam
Assuming you are using a build system, the main loam
library should integrate into your build the same as any other library might. However, in order to correctly initialize the Emscripten environment for running GDAL, there are other assets that need to be accessible via HTTP request at runtime, but which should not be included in the main application bundle. Specifically, these are:
loam-worker.min.js
: This is the "backend" of the library; it initializes the Web Worker and translates between the Loam "frontend" and GDAL.gdal.js
: This initializes the Emscripten runtime and loads the GDAL WebAssembly.gdal.wasm
: The GDAL binary, compiled to WebAssembly.gdal.data
: Contains configuration files that GDAL expects to find on the host filesystem.
All of these files will be included in the node_modules
folder after running npm install loam
, but it is up to you to integrate them into your development environment and deployment processes.
// Load WebAssembly and data files asynchronously. Will be called automatically by loam.open()
// but it is often helpful for responsiveness to pre-initialize because these files are fairly large. Returns a promise.
loam.initialize();
// Assuming you have a `Blob` object from somewhere. `File` objects also work.
loam.open(blob).then((dataset) => {
dataset.width()
.then((width) => /* do stuff with width */);
Manually set up web worker and initialize Emscripten runtime. This function is called automatically by other functions on loam
. Returns a promise that is resolved when Loam is fully initialized.
Although this function is called automatically by other functions, such as loam.open()
, it is often beneficial for user experience to manually call loam.initialize()
, because it allows pre-fetching Loam's WebAssembly assets (which are several megabytes uncompressed) at a time when the latency required to download them will be least perceptible by the user. For example, loam.initialize()
could be called when the user clicks a button to open a file-selection dialog, allowing the WebAssembly to load in the background while the user selects a file.
This function is safe to call multiple times.
pathPrefix
: The path prefix that Loam should use when downloading its WebAssembly assets. If left undefined, Loam will make a best guess based on the source path of its own<script>
element. If Loam fails to work properly and you see requests resulting in 404s for thegdal.*
assets listed above, then you will need to set this parameter so that Loam requests the correct paths for its WebAssembly assets.
A promise that resolves when Loam is initialized. All of the functions described in this document wait for this promise's resolution when executing, so paying attention to whether this promise has resolved or not is not required. However, it may be helpful to do so in some circumstances, for example, if you want to display a visual indicator that your app is ready.
Creates a new GDAL Dataset.
file
: A Blob or File object that should be opened with GDAL. GDAL is compiled with TIFF, PNG, and JPEG support.
A promise that resolves with an instance of GDALDataset
.
Burns vectors in GeoJSON format into rasters. This is the equivalent of the gdal_rasterize command.
Note: This returns a new GDALDataset
object but does not perform any immediate calculation. Instead, calls to .rasterize()
are evaluated lazily (as with convert()
and warp()
, below). The rasterization operation is only evaluated when necessary in order to access some property of the dataset, such as its size, bytes, or band count. Successive calls to .warp()
and .convert()
can be lazily chained onto datasets produced via loam.rasterize()
.
geojson
: A Javascript object (not a string) in GeoJSON format.args
: An array of strings, each representing a single command-line argument accepted by thegdal_rasterize
command. Thesrc_datasource
anddst_filename
parameters should be omitted; these are handled internally by Loam. Example (assuming you have a properly structured GeoJSON object):loam.rasterize(geojson, ['-burn', '1.0', '-of', 'GTiff', '-ts', '200', '200'])
A promise that resolves to a new GDALDataset
.
Reproject coordinates from one coordinate system to another using PROJ.4.
fromCRS
: A WKT-formatted string representing the source CRS.toCRS
: A WKT-formatted string representing the destination CRS.coords
: An array of [x, y] coordinate pairs.
A promise that resolves with an array of transformed coordinate pairs.
This used to be required in order to avoid memory leaks in earlier versions of Loam, but is currently a no-op. It has been maintained to preserve backwards compatibility, but has no effect other than to display a console warning.
A promise that resolves immediately with an empty list (for historical reasons).
Get the number of bands in the dataset.
A promise which resolves to the number of bands in the dataset.
Get the width of the dataset, in pixels.
A promise which resolves to the width of the dataset, in pixels.
Get the height of the dataset, in pixels.
A promise which resolves to the height of the dataset, in pixels.
Get the coordinate reference system of the dataset, as a WKT-formatted string.
A promise which resolves with a WKT-formatted string representing the dataset's coordinate reference system.
Get the affine transform of the dataset, as a list of six coefficients. This allows converting between pixel coordinates and geographic coordinates. See the GDAL documentation for further details.
A promise which resolves to the affine transform.
Converts raster data between different formats. This is the equivalent of the gdal_translate command.
Note: This returns a new GDALDataset
object but does not perform any immediate calculation. Instead, calls to .convert()
and .warp()
are evaluated lazily. Each successive call to .convert()
or .warp()
is stored in a list of operations on the dataset object. These operations are only evaluated when necessary in order to access some property of the dataset, such as its size, bytes, or band count.
args
: An array of strings, each representing a single command-line argument accepted by thegdal_translate
command. Thesrc_dataset
anddst_dataset
parameters should be omitted; these are handled byGDALDataset
. Example:ds.convert(['-outsize', '200%', '200%'])
A promise that resolves to a new GDALDataset
.
Image reprojection and warping utility. This is the equivalent of the gdalwarp command.
Note: This returns a new GDALDataset
object but does not perform any immediate calculation. Instead, calls to .convert()
and .warp()
are evaluated lazily. Each successive call to .convert()
or .warp()
is stored in a list of operations on the dataset object. These operations are only evaluated when necessary in order to access some property of the dataset, such as its size, bytes, or band count.
args
: An array of strings, each representing a single command-line argument accepted by thegdalwarp
command. Thesrcfile
anddstfile
parameters should be omitted; these are handled byGDALDataset
. Example:ds.warp(['-s_srs', 'EPSG:3857', '-t_srs', 'EPSG:4326'])
A promise that resolves to a new GDALDataset
.
Utility for rendering and computing DEM metrics. This is the equivalent of the gdaldem command.
Note: This returns a new GDALDataset
object but does not perform any immediate calculation. Instead, calls to .render()
are evaluated lazily (as with convert()
and warp()
, above). The render operation is only evaluated when necessary in order to access some property of the dataset, such as its size, bytes, or band count. Successive calls to .warp()
and .convert()
can be lazily chained onto datasets produced by .render()
, and vice-versa.
mode
: One of ['hillshade', 'slope','aspect', 'color-relief', 'TRI', 'TPI', 'roughness']. See thegdaldem documentation
for an explanation of the function of each mode.args
: An array of strings, each representing a single command-line argument accepted by thegdaldem
command. Theinputdem
andoutput_xxx_map
parameters should be omitted; these are handled byGDALDataset
. Example:ds.render('hillshade', ['-of', 'PNG'])
colors
: If (and only if)mode
is equal to 'color-relief', an array of strings representing lines in the color text file. Example:ds.render('color-relief', ['-of', 'PNG'], ['993.0 255 0 0'])
. See thegdaldem documentation
for an explanation of the text file syntax.
A promise that resolves to a new GDALDataset
.
After cloning,
yarn install
yarn dev
and in another sessionyarn test:watch
Built assets are placed in lib
.
Contributions are welcomed! Please feel free to work on any of the open issues or open an issue describing the changes you'd like to make. All contributions will be licensed under the Apache License, as per the GitHub Terms of Service.