Wayfinding

Mappedin SDK version 6 is currently in an alpha state while Mappedin perfects a new design. Breaking changes may occur, which will be posted in the v6 release notes.

Wayfinding is the process of navigating through environments using spatial cues and instructions to efficiently reach a destination. The Mappedin SDK provides the tools needed to guide users from one location to another. It allows drawing a path between points on the map as well as creation of textual turn-by-turn directions for navigation.

Getting Directions

Directions form the core of wayfinding. Mappedin has pathfinding capabilities that allow it to generate directions from one target to another. These directions are used for drawing paths and providing the user with textual turn-by-turn directions.

Generate directions by calling MapView.getDirections() and pass in targets for the origin and destination. These targets are wrapped in a TNavigationTarget, which can contain a Space, MapObject, Coordinate, Door, PointOfInterest or Connection.

MapView.getDirections() can accept a single TNavigationTarget or an array of them for the origin and destination. If an array is used, the Mappedin SDK will choose the targets that are closest to each other. An example of where this could be used is when a user asks for directions to a washroom. There may be many Spaces labelled Washroom. The app can pass all washroom spaces to getDirections and receive directions to the nearest one.

The following CodeSandbox demonstrates drawing directions on the map. It also includes a toggle to change between Path, which draws a path and navigation, which uses the Navigation class to draw a path and departure and arrival icons.

Drawing Navigation

When a user needs to get from point A to point B, drawing a path on the map helps them to navigate to their destination. It can help them to visualize the route they'll need to take, like a good treasure map.

Navigation is a helper class to display wayfinding easily on the map. Functionality of Navigation could be replicated by drawing the paths using IPaths and adding well designed tooltips at connection points.

Note that the MapView class includes the Navigation class and exposes it as MapView.Navigation. Use MapView.Navigation to utilize Navigation's methods.

Navigation.draw() allows for easily drawing multiple components that make up a wayfinding illustration. It shows a human figure to mark the start point, a path with animated directional arrows, pulses in the direction of travel and a pin to mark the destination. Each of these components can be customized to match an app's style.

The following sample uses the default navigation settings to navigate from the Cafeteria to the Gymnasium.

Copy
// Get the spaces for the first and second spaces to navigate to and from.
const firstSpace = mapData.getByType('space').find(s => s.name === 'Cafeteria');
const secondSpace = mapData.getByType('space').find(s => s.name === 'Gymnasium');

// Ensure that the spaces exist.
if (firstSpace && secondSpace) {
	const directions = mapView.getDirections(firstSpace, secondSpace);

	if (directions) {
		// Add a path from the first space to the second space.
		mapView.Navigation.draw(directions);
	}
}

Navigating From a Click Event

A navigation start or end point may originate from a user clicking on the map. It is possible to create a start and or end point using the click event and accessing its TEvents payload. The code shown below uses the click position as a starting point to create directions. nearRadius and farRadius are described in the Path Styles section later in this guide.

Copy
mapView.on('click', async event => {
	const clickedLocation = event.coordinate;
	const destination = mapData.getByType('space').find(s => s.name === 'Gymnasium');

	// If the destination is found, navigate to it.
	if (destination) {
		//Ensure that directions could be generated (user clicked on a navigable space).
		const directions = mapView.getDirections(clickedLocation, destination);

		if (directions) {
			// Navigate from the clicked location to the gymnasium.
			mapView.Navigation.draw(directions, {
				pathOptions: {
					nearRadius: 1,
					farRadius: 1,
				},
			});
		}
	}
});

Multi-Floor Wayfinding

Using Navigation, no additional work is needed to provide wayfinding between floors. Whenever a user needs to switch a floor, an interactive tooltip with an icon indicating the type of Connection (such as an elevator or stairs) will be drawn. By clicking or tapping the tooltip, the map view switches to the destination floor.

The following CodeSandbox gives an example of multi floor navigation.

Wayfinding Using Accessible Routes

When requesting directions, it is important to consider the needs of the user. Users with mobility restrictions may require a route that avoids stairs and escalators and instead uses ramps or elevators.

The getDirections method accepts TGetDirectionsOptions, which allows specifying whether an accessible route should be returned. By default, the shortest available route is chosen. The following code demonstrates how to request directions that make use of accessible routes.

Copy
const directions = await map.getDirections(space1, space2, {accessible: true});

Drawing a Path

While Navigation provides a complete start and end navigation illustration, it may be desired to draw just the path. This can be done using IPaths.

Note that the MapView class implements the IPaths interface and exposes it as MapView.Paths. Use MapView.Paths to utilize IPaths methods.

Paths can be drawn from one coordinate to another using IPaths.add(). If using just two coordinates, the path will be drawn straight between the two points. This may work for some scenarios, but in most cases an app will need to show the user their walking path, going through doors and avoiding walls and other objects. Such a path of coordinates can be created by calling the MapView.getDirections() method, passing in a start and end TNavigationTarget. Note that a Space requires an entrance to be used as a target.

The width of the path is set using the nearRadius and farRadius parameters. These values are in meters. nearRadius is the path width used at the lowest zoom level closest to the ground and farRadius is used at the highest zoom level. Additional path styles are outlined later in this guide in the Path Styles section.

Copy
// Get the directions between two spaces.
const directions = mapView.getDirections(startSpace, endSpace);
// Draw a path using the directions' coordinates array to show the route.
path = mapView.Paths.add(directions.coordinates, {
    nearRadius: 0.5,
    farRadius: 0.5,
});

The following CodeSandbox draws a path from one location to another. Click on a room to set the departure point, then click another room to set the destination. When a path is shown, clicking anywhere will remove it.

Removing Paths

There are two methods that can be used to remove paths. IPaths.remove() accepts a path to remove and is used to remove a single path. To remove all paths, IPaths.removeAll() can be used.

Copy
// Remove a single path.
mapView.Paths.remove(path);

Copy
// Remove all paths
mapView.Paths.removeAll()

Path Styles

The Mappedin SDK offers many options to customise how paths appear to the user. Path animations, color, width and many more options can be set using TAddPathOptions, which is shown below.

Copy
TAddPathOptions: {
    adjustedAltitude?: boolean;
    animateArrowsOnPath?: boolean;
    animateDrawing?: boolean;
    color?: string;
    displayArrowsOnPath?: boolean;
    drawDuration?: number;
    farRadius?: number;
    farZoom?: number;
    interactive?: boolean;
    maxAdjustedAltitude?: number;
    minAdjustedAltitude?: number;
    nearRadius?: number;
    nearZoom?: number;
    pulseColor?: string;
    pulseIterations?: number;
    pulsePauseDuration?: number;
    showPulse?: boolean;
}

TAddPathOptions

• adjustedAltitude - Boolean to set whether to vertically adjust the path to the tallest point.
• animateArrowsOnPath - Boolean to set whether animated arrows should be drawn on the path.
• animateDrawing - Boolean to set whether to animate the drawing of the path in the direction of travel.
• color - Path color
• displayArrowsOnPath - Boolean to set whether to show arrows on the path.
• drawDuration - Duration of path drawing in milliseconds if animateDrawing is enabled.
• farRadius - Radius of path at furthest zoom, in metres.
• farZoom - Zoom level where the path size is farRadius.
• interactive - Whether the path should be clickable.
• maxAdjustedAltitude - The maximum altitude of the path in meters.
• minAdjustedAltitude - The minimum altitude of the path in meters.
• nearRadius - Radius of path at nearest zoom, in metres.
• nearZoom - Zoom level in meters where the path size is nearRadius.
• pulseColor - Colour of path pulse.
• pulseIterations - Number of iterations to pulse to indicate direction.
• pulsePauseDuration - The number of milliseconds to wait before starting the next pulse after the current pulse travels the entirety of the path.
• showPulse - Boolean whether to show an animated pulse indicating the direction of travel.

Turn-by-Turn Directions

Turn-by-Turn directions are a set of text instructions describing the route the user needs to take. An example is "Turn right and go 10 meters". These could be shown to the user in a list to give them an overview with all steps they need to take, or the current instruction could be displayed along with a map showing the next leg of their journey.

The code sample assembles these actions together and:

• Gets directions between the start and end Space.
• Draws a path using the directions' coordinates.
• Creates a Marker with textual turn-by-turn instructions for each leg in the journey. Rerfer to the Markers guide for more information on using Markers.

Copy
// Get directions from the first space to the second space.
const directions = mapView.getDirections(firstSpace, secondSpace);

// Add a path from the first space to the second space.
mapView.Paths.add(directions.coordinates);

// Add markers for each direction instruction.
directions.instructions.forEach((instruction: TDirectionInstruction) => {
	const markerTemplate = `
		<div class="marker">
			<p>${instruction.action.type} ${instruction.action.bearing ?? ''} and go ${Math.round(instruction.distance)} meters.</p>
		</div>`;

	mapView.Markers.add(instruction.coordinate, markerTemplate, {
		rank: 4,
	});
});