Skip to content

Latest commit

 

History

History
372 lines (304 loc) · 10.6 KB

GETTING_STARTED.md

File metadata and controls

372 lines (304 loc) · 10.6 KB
Raw

Getting Started

Installation

We start with the assumption that you have both Node.js and npm (node package manager) installed.

You can install the Terra Draw into your project like so:

npm install terra-draw

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.

Script Tag

Some people may want to experiment with using Terra Draw without a build step. To do this you can use the UMD bundle that is put onto npm via a CDN like unpkg. For example if we were using Terra Draw with MapLibre we might do something like this in our <head> tag:

<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
<script src="https://unpkg.com/[email protected]/dist/terra-draw.umd.js"></script>
<link
	href="https://unpkg.com/[email protected]/dist/maplibre-gl.css"
	rel="stylesheet"
/>

Later on in our JavaScript code we can access the global terraDraw like so:

const draw = new terraDraw.TerraDraw({
	adapter: new terraDraw.TerraDrawMapLibreGLAdapter({ map }),
	modes: [new terraDraw.TerraDrawRectangleMode()],
});

Putting this together we can create a simple map with rectangle drawing like so:

<!doctype html>
<html>
	<head>
		<!-- Required Styles & Script -->
		<link
			href="https://unpkg.com/[email protected]/dist/maplibre-gl.css"
			rel="stylesheet"
		/>
		<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
		<script src="https://unpkg.com/[email protected]/dist/terra-draw.umd.js"></script>
	</head>
	<body>
		<!-- Map Container (must have dimensions set!) -->
		<div id="map" style="width: 300px; height: 300px"></div>

		<script>
			// Create MapLibre Map
			var map = new maplibregl.Map({
				container: "map", // Container ID
				style: "https://demotiles.maplibre.org/style.json",
				center: [0, 0], // Starting position [lng, lat]
				zoom: 1, // Starting zoom
			});

			// Create Terra Draw
			const draw = new terraDraw.TerraDraw({
				adapter: new terraDraw.TerraDrawMapLibreGLAdapter({ map }),
				modes: [new terraDraw.TerraDrawRectangleMode()],
			});

			// Start drawing
			draw.start();

			// Set the mode to rectangle
			draw.setMode("rectangle");
		</script>
	</body>
</html>

API Docs

You can find the full autogenerated API docs on the terra draw website.

Common Patterns

A selection of common things you may want to do with Terra Draw is available via the common patterns guide in this folder. If you think something is missing please raise an issue!

Adapters

Terra Draw can be used with a set of different adapters to allow you to use it with your mapping library of choice. Each adapter has slightly different configuration but the API is the same for them all. For a deeper explanation about what adapters are and how to write you own see the development guide.

Leaflet

Here is some simple starter code for using Terra Draw with the popular open source mapping library Leaflet.

We are instructing Leaflet to display within an element with the id of map (i.e. <div id="map"></div>), which must exist within your HTML.

// Import the leaflet mapping library
import * as L from "leaflet";

// Import Terra Draw, we will import the leaflet adapter, select mode and polygon mode
import {
	TerraDraw,
	TerraDrawLeafletAdapter,
	TerraDrawSelectMode,
	TerraDrawPolygonMode,
} from "terra-draw";

// Initialize a new Leaflet map, providing the id of the div to display the map
// Set the initial center (latitude, longitude) and the zoom level
const leafletMap = L.map("map", {
	center: [lat, lng],
	zoom: 4, // starting zoom,
	minZoom: 3,
	maxZoom: 20,
	tapTolerance: 10,
});

// Add a basemap from OpenStreetMap to the Leaflet map
L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
	maxZoom: 19,
	attribution:
		'&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>',
}).addTo(leafletMap);

// Instantiate the TerraDraw API with a Leaflet adapter and custom modes
const draw = new TerraDraw({
	adapter: new TerraDrawLeafletAdapter({
		// The leaflet library object
		lib: leaflet,

		// The leaflet map object we created
		map: leafletMap,

		// The decimal precision of the coordinates created
		coordinatePrecision: 9,
	}),

	// Modes is an object containing all the modes we wish to
	// instantiate Terra Draw with
	modes: [
		new TerraDrawSelectMode({
			flags: {
				// Following flags determine what you can do in
				// select mode for features of a given mode - in this case polygon
				polygon: {
					feature: {
						scaleable: true,
						rotateable: true,
						draggable: true,
						coordinates: {
							midpoints: true,
							draggable: true,
							deletable: true,
						},
					},
				},
			},
		}),
		new TerraDrawPolygonMode({
			allowSelfIntersections: false,
			pointerDistance: 30,
		}),
	],
});

// Start drawing
draw.start();

// Set the mode to polygon
draw.setMode("polygon");

Google Maps API

Here is some starter code for using Terra Draw with the Google Maps API. It assumes you are going instantiate your map in a div with and id of map, which is assumed to exist within your HTML.

// Import the google maps api loader
import { Loader } from "@googlemaps/js-api-loader";

// Import Terra Draw, we will import the leaflet adapter, select mode and polygon mode
import {
	TerraDraw,
	TerraDrawLeafletAdapter,
	TerraDrawSelectMode,
	TerraDrawPolygonMode,
} from "terra-draw";

const loader = new Loader({
	apiKey: "INSERT_YOUR_API_KEY_HERE", // You need to provide your own API key here
	version: "weekly",
});

// We need to await the google maps api
loader.load().then((google) => {
	// Create the map
	const map = new google.maps.Map(document.getElementById("map"), {
		disableDefaultUI: true,
		center: { lat: this.lat, lng: this.lng },
		zoom: this.zoom,

		//Setting clickableIcons to false is used to disable the default behavior of the
		// Google Maps API, which is to allow users to interact with clickable icons on the
		// map, such as points of interest (POIs) or other interactive map elements.
		clickableIcons: false,
	});

	// When using Google Maps, it's important to wrap the creation of custom overlays or other // map-related initializations inside the 'projection_changed' event listener to ensure
	// that the map's projection is fully loaded before your code runs.
	map.addListener("projection_changed", () => {
		const draw = new TerraDraw({
			adapter: new TerraDrawGoogleMapsAdapter({
				lib: google.maps,
				map,
				coordinatePrecision: 9,
			}),
			modes: [
				new TerraDrawSelectMode({
					flags: {
						// Following flags determine what you can do in
						// select mode for features of a given mode - in this case polygon
						polygon: {
							feature: {
								scaleable: true,
								rotateable: true,
								draggable: true,
								coordinates: {
									midpoints: true,
									draggable: true,
									deletable: true,
								},
							},
						},
					},
				}),
				new TerraDrawPolygonMode({
					allowSelfIntersections: false,
					pointerDistance: 30,
				}),
			],
		});

		// Start drawing
		draw.start();

		// Set the mode to polygon
		draw.setMode("polygon");
	});
});

OpenLayers

Coming soon - please see development folder for example for now.

MapboxGL JS

Coming soon - please see development folder for example for now.

MapLibreGL JS

Here is some starter code for using Terra Draw with the MapLibreGL JS. It assumes you are going instantiate your map in a div with and id of map, which is assumed to exist within your HTML.

// Import the MapLibre mapping library
import MapLibreGL from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";

// Import Terra Draw, we will import the MapLibre adapter, select mode and polygon mode
import {
	TerraDraw,
	TerraDrawMapLibreGLAdapter,
	TerraDrawSelectMode,
	TerraDrawPolygonMode,
} from "terra-draw";

// Initialize a new MapLibre map, providing the id of the div to display the map
// Set the initial center (longitude, latitude) and the zoom level
const mapLibreMap = new MapLibreGL.Map({
	container: "map",
	style: {
		version: 8,
		sources: {
			"osm-tiles": {
				type: "raster",
				tiles: ["https://tile.openstreetmap.org/{z}/{x}/{y}.png"],
				tileSize: 256,
				attribution:
					'&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>',
			},
		},
		layers: [
			{
				id: "osm-tiles",
				type: "raster",
				source: "osm-tiles",
			},
		],
	},
	center: [lng, lat],
	zoom: 4,
	minZoom: 3,
	maxZoom: 20,
});

// Instantiate the TerraDraw API with a MapLibre adapter and custom modes
const draw = new TerraDraw({
	adapter: new TerraDrawMapLibreGLAdapter({
		// The MapLibre library object
		lib: MapLibreGL,

		// The MapLibre map object we created
		map: mapLibreMap,

		// The decimal precision of the coordinates created
		coordinatePrecision: 9,
	}),

	// Modes is an object containing all the modes we wish to
	// instantiate Terra Draw with
	modes: [
		new TerraDrawSelectMode({
			flags: {
				// Following flags determine what you can do in
				// select mode for features of a given mode - in this case polygon
				polygon: {
					feature: {
						scaleable: true,
						rotateable: true,
						draggable: true,
						coordinates: {
							midpoints: true,
							draggable: true,
							deletable: true,
						},
					},
				},
			},
		}),
		new TerraDrawPolygonMode({
			allowSelfIntersections: false,
			pointerDistance: 30,
		}),
	],
});

// Start drawing
draw.start();

// Set the mode to polygon
draw.setMode("polygon");

Other Examples

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

The development folder features an example of using Terra Draw with all the 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 frame work.

Full Example

The Terra Draw official website is open source 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).