Skip to main content
Version: 6.0

Outdoor Map

Mappedin SDK version 6 is currently in a beta state while Mappedin perfects new features and APIs. Open the v6 release notes to view the latest changes.
Using Mappedin JS with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.

The outdoor map shown around the Mappedin indoor map can be manipulated to show or hide additional information. It can be used to add GeoJSON based geometry, images, deck.gl layers and more.

The outdoor map is accessed using MapView.Outdoor.map, which returns a maplibregl.Map object. MapLibre GL JS is a TypeScript library that uses WebGL to render interactive maps from vector tiles in a browser. Mappedin JS makes use of it to display the outdoor map.

By providing access to the MapLibre map used to draw the outdoor map, Mappedin JS enables developers to draw on and manipulate the outdoor map. Developers can use most capabilities of MapLibre GL JS with key exceptions being Interactivity and Camera, which are not available.

User touch and click events are handled by Mappedin JS and are not propagated to the outdoor map layer. Camera movement is also handled by Mappedin JS and cannot be manipulated using MapLibre controls.

The remainder of this guide demonstrates a few examples of what is could be achieved with the outdoor map. Please refer to the MapLibre GL JS documentation and MapLibre GL JS Examples for comprehensive instructions and demonstrations of what is possible with MapLibre.

Styles​

Styles can be applied to the outdoor map to change its colours. Mappedin provides five pre-built styles to choose from.

To change the style used by the Outdoor map, pass the URL of the style in the outdoorView object of TShow3DMapOptions as shown below.

const mapView = await show3dMap(document.getElementById('mappedin-map') as HTMLDivElement, mapData, {
	outdoorView: {
		style: 'https://tiles-cdn.mappedin.com/styles/freshmint/style.json',
	},
});

The outdoor style can also be changed at runtime using mapView.Outdoor.setStyle().

mapView.Outdoor.setStyle('https://tiles-cdn.mappedin.com/styles/freshmint/style.json');

Changing the outdoor style does not change the indoor style. Indoor styles are tied to a View specified when loading the map. Refer to the Views guide for more information.

The CodeSandbox below demonstrates changing the Outdoor style while optionally changing the indoor style by changing the view.

Adding Raster or Vector Maps​

Mappedin JS's outdoor map uses a road map to provide users with a reference point and to give them context of the area around buildings. An app may wish to display a different type of map, such as a satellite image or weather patterns.

Mappedin JS allows an app to add additional map sources. Vector, raster and raster-dem sources can be used from providers such as Google, Azure, MapTiler or mapbox.

Satellite Outdoor Map​

The following example demonstrates the use of a raster satellite image source from MapTiler.

The key used in this example is locked for use on developer.mappedin.com and the provided CodeSandbox. To customise this example, create a free MapTiler key at https://www.maptiler.com/

Adding a Raster Source​

The following code snippet adds a raster satellite map from MapTiler. The addLayer method passes mappedin as the name of the layer to draw below. This ensures that the layer is drawn under the indoor map. Remove it if you need to have your source rendered on top of the indoor map.

// Get an instance of the outdoor map.
const outdoorMap = mapView.Outdoor.map!;

// On load of the outdoor map, add a satellite tiles layer
outdoorMap.on('load', () => {
	try {
		// Add a raster tile source for satellite imagery from MapTiler.
		// Get your own free MapTiler key at https://www.maptiler.com/
		outdoorMap.addSource('satelite', {
			type: 'raster',
			tiles: ['https://api.maptiler.com/maps/satellite/{z}/{x}/{y}@2x.jpg?key=<REPLACE_WITH_YOUR_KEY>'],
			tileSize: 512,
			attribution: '© MapTiler © OpenStreetMap contributors',
		});

		// Add a raster layer using the satellite source.
		// Have it show below the mappedin layer, which holds the indoor map.
		outdoorMap.addLayer(
			{
				id: 'satelite',
				type: 'raster',
				source: 'satelite',
				paint: {},
			},
			'mappedin',
		);
	} catch (error) {
		console.error('Error adding tile source or layer:', error);
	}
});

Adding a Vector Source​

The following code snippet adds a contour vector map from MapTiler. The addLayer method passes mappedin as the name of the layer to draw below. This ensures that the layer is drawn under the indoor map. Remove it if you need to have your source rendered on top of the indoor map.

// Get an instance of the outdoor map.
const outdoorMap = mapView.Outdoor.map!;

// On load of the outdoor map, add a satellite tiles layer
outdoorMap.on('load', () => {
	try {
		// Add a vector tile source for satellite imagery from MapTiler.
		// Get your own free MapTiler key at https://www.maptiler.com/
		outdoorMap.addSource('contours', {
			type: 'vector',
			url: 'https://api.maptiler.com/tiles/contours/tiles.json?key=<REPLACE_WITH_YOUR_KEY>',
		});

		// Add a raster layer using the satellite source.
		// Have it show below the mappedin layer, which holds the indoor map.
		outdoorMap.addLayer(
			{
				id: 'terrain-data',
				type: 'line',
				source: 'contours',
				'source-layer': 'contour',
				layout: {
					'line-join': 'round',
					'line-cap': 'round',
				},
				paint: {
					'line-color': '#ff69b4',
					'line-width': 1,
				},
			},
			'mappedin',
		);
	} catch (error) {
		console.error('Error adding tile source or layer:', error);
	}
});

Drawing GeoJSON Geometry on the Outdoor Map​

MapView.Outdoor.map allows drawing GeoJSON based geometry on top of the outdoor map using MapLibre. The following example demonstrates drawing a LineString on the outdoor map that represents an area under construction that should be avoided. Labels are drawn using Mappedin JS.

Using deck.gl​

In addition to using MapLibre methods, deck.gl can also be used to draw on the outdoor map using deck.MapboxOverlay. The next example shows how to take positional information in GeoJSON format that represents the off site positions of shopping carts and displays them on the map using a deck.gl ScatterplotLayer.

Drawing an Image on the Outdoor Map​

Images can be drawn on top of the outdoor map. They are positioned using latitude and longitude coordinates that begin on the top left position and continue clockwise. The example below draws an image of a black parking symbol. The green parking symbol uses an image on a Marker created with Mappedin JS.

Right click on the map and move to rotate it to observe how the image added to the outdoor map remains static while the image added to a Marker rotates with the map to always use the same perspective. The Marker also remains a constant size when the map is zoomed in and out while the image gets smaller and larger.