Terra Draw adds a number of geographical Feature drawing tools to popular mapping libraries. There are few key concepts that allow it to stay strongly decoupled and as library-agnostic as possible, let's walk through them.
The Store is the heart of the library and is responsible for managing the state of all Features that are added to the map. The Store is created when Terra Draw is instantiated:
// Create a Terra Draw instance and assign it to a variable called `draw`
const draw = new TerraDraw({ adapter, modes });Important
Throughout the documentation we will use the variable name draw to refer to the Terra Draw instance.
Features are added to the Store when interacting with the Map using a number of available drawing Modes (such as TerraDrawRectangleMode or TerraDrawPolygonMode).
The Store is exposed via the getSnapshot method, which returns an Array of all given Feature geometries in the Store:
// Get an Array of all Features in the Store
const features = draw.getSnapshot();See the Store section to find out more about the store and getting data in and out of Terra Draw.
Adapters are thin wrappers that contain map library specific logic, for creating and updating layers rendered by the mapping library.
For example if you are using MapLibre you would use the TerraDrawMapLibreGLAdapter Adapter, for Leaflet you would use the TerraDrawLeafletAdapter Adapter:
// Create an Adapter for Leaflet
const adapter = new TerraDrawLeafletAdapter({ map, lib });Important
Each Adapter must be instantiated with both map and lib properties.
See the Adapters section for more information.
Modes represent the logic for a specific drawing tool, for example there are TerraDrawRectangleMode, TerrDrawPolygonMode and TerraDrawLineStringMode Modes which allow you to draw rectangles, polygons and lines on the map respectively.
The TerraDrawSelectMode allows for the selection and manipulation of features on the Map, while the TerraDrawRenderMode is used to render uneditable features, for example contextual data.
Modes are instantiated like so:
const polygonMode = new TerraDrawPolygonMode();
const rectangleMode = new TerraDrawRectangleMode();
const renderMode = new TerraDrawRenderMode({
modeName: "auniquename",
});See the Modes section for more information.
Terra Draw can be added to your site either via the <script> tag, or using a package manager like NPM.
Important
We start with the assumption that you have both Node.js and npm installed.
You can install the Terra Draw into your project like so:
npm install terra-drawWarning
Be aware Terra Draw is currently in alpha, the initial API is still being finalised.
It is strongly advised to pin your installation to a specific version i.e. not using carat, asterix or tilde for versions but giving a version explicitly in your package.json.
"terra-draw": "0.0.1-alpha.50"Once terra-draw is out of alpha this suggestion will be removed as we will aim to move to semantic versioning.
View the NPM package page for more information.
Once installed via NPM you can use Terra Draw in your project like so:
// Import Terra Draw
import {
TerraDraw,
TerraDrawMapLibreGLAdapter,
TerraDrawRectangleMode,
} from "terra-draw";
// Import MapLibreGL
import { MapLibreGL as lib } from "maplibre-gl";
// Create MapLibre Map, targetting <div id="map">
const map = new MapLibreGL.Map({ container: "map" });
// Create Terra Draw
const draw = new TerraDraw({
// Using the MapLibre Adapter
adapter: new TerraDrawMapLibreGLAdapter({ map, lib }),
// Add the Rectangle Mode
modes: [new TerraDrawRectangleMode()],
});
// Start drawing
draw.start();
draw.setMode("rectangle");To use Terra Draw without a build step, you can load the UMD (Universal Module Definition) bundle directly from a CDN (Content Delivery Network) like unpkg.
For example if we were using Terra Draw with MapLibre we might do something like this in our <head> tag:
<!-- MapLibre -->
<script src="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.js"></script>
<link
href="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.css"
rel="stylesheet"
/>
<!-- Terra Draw -->
<script src="https://unpkg.com/terra-draw@0.0.1-alpha.50/dist/terra-draw.umd.js"></script>Later on in our JavaScript code we can access terraDraw globally like so:
// Create Terra Draw instance
const draw = new terraDraw.TerraDraw({
// Using the MapLibre Adapter
adapter: new terraDraw.TerraDrawMapLibreGLAdapter({ map, lib }),
// Add the Rectangle Mode
modes: [new terraDraw.TerraDrawRectangleMode()],
});Putting these concepts together we can create a simple map with freehand drawing enabled like so:
<!doctype html>
<html>
<head>
<!-- Required Styles & Script -->
<link
rel="stylesheet"
href="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.css"
/>
<script src="https://unpkg.com/maplibre-gl@3.6.2/dist/maplibre-gl.js"></script>
<script src="https://unpkg.com/terra-draw@0.0.1-alpha.50/dist/terra-draw.umd.js"></script>
</head>
<body>
<!-- Map Container (must have dimensions set!) -->
<div id="map" style="height:420px;"></div>
<script>
// Create MapLibre Map, targetting <div id="map">
// See https://maplibre.org/maplibre-gl-js/docs/
var map = new maplibregl.Map({
container: "map",
style: "https://demotiles.maplibre.org/style.json",
center: [-4.49049, 54.189649], // [lng, lat]
zoom: 5,
});
// Create Terra Draw
const draw = new terraDraw.TerraDraw({
adapter: new terraDraw.TerraDrawMapLibreGLAdapter({
map: map,
lib: maplibregl,
}),
modes: [new terraDraw.TerraDrawFreehandMode()],
});
// Start drawing
draw.start();
// Set the mode to rectangle
draw.setMode("freehand");
</script>
</body>
</html>You can find the full autogenerated API docs on the terra draw website.
There are a few other working examples that you can use as points of reference for creating a new app using Terra Draw:
- Development Example - showcases all of Terra Draw Modes and Adapters. It is meant for local development but can also be used as a guide of how to use Terra Draw with each Adapter without any framework.
- Terra Draw Website - Acts as a full working implementation of how to use Terra Draw. In this case it is used with popular framework Preact (has very similar API to React). It's Open Source too!
Guides