Offline Map Component

App Creator Version: 2.1 (switch to 2.0)

The Offline Map component allows you to show a map in your app that does not require any internet connection. The map is typically of a small area to reduce app size. The component supports simple route finding, and Bluetooth Beacons for “you are here” indication without GPS or Wifi. You can also add Points of Interest to the map.

The major changes between 2.0 and 2.1 include multi-level maps and turn-by-turn directions.

Map Display Tiles

The map to be displayed is provided as a set of tile images, generated by a map tiling tool.

  • If you want to start with images such as floorplans for your maps, we suggest using Map Tiler. This allows you to take your images, position them with latitude and longitude, changing the shape if necessary, and then produce a set of tiles. For more information, see our Map Creation Guide.
  • If you want to start from raw map data such as Open Street Maps, then you can use a tool such as Maperitive. Using Maperitive you can change the way the map appears including the features and level of detail shown.

Either way, once you have a set of tile images, the offline map view component will then display the map, allowing the user to zoom and pan the map.

The only limit on size of the map is the amount of data needed for tile images, which must all be included into your app. This is defined mainly by the size of the area you want, but also by the amount of detail – if the map is rendered with less information (e.g. leaving out walkways) then the images will be smaller.

Place the map tiles and matching tiles.json file into your project’s folder, under the maps folder.

You can reduce the size of map tiles produced by Maperitive by post-processing the image files with a tool such as PNGQuant. This compresses the images without losing much quality on typical map tiles. On our typical examples this saves over 75% of the map tile size, ie. the results are only 1/4 of the size of direct Maperitive output.

Multi-level Support

The offline map component supports having multiple levels or floors of maps. Each level has it’s own set of tiles. This is displayed over the base or common set of tiles, if any. It is not required to have more than one level.

To define the list of levels that is available, create a text file named levels.txt in the your map folder (make sure the name is all lower-case). Each line should contain the name of one level, top down, for example:

Once you’ve created this file, reload the project to load the levels.

Within your map folder, you can then provide tiles for each level in a sub folder named the same as the level. In the sub-folder there should be zoom levels, the same as the base tiles.

Tiles for each level are not required; you can just display the base tiles for a level. For example, in the above case, there could be sub folders named 3, 2, 1 and B; the “G” tiles are built-in to the base tiles.

You can then use the Set Map Level action to change levels; beacons will be able to switch to a different level by putting a value in the Level column of the feed; POIs can be filtered to particular levels; and route finding and turn-by-turn directions will provide information on the changes in levels involved in going from point to point.

User Location Methods

The map can show the user’s location in three different ways, allowing flexibility for different situations. In order of priority they are:

  • Manual location: You can tell the map where the user is manually. This allows using methods such as codes or names on signs to identify the location.
  • Bluetooth Low-Energy (BLE) Beacon: Beacons can work in situations where other signals are not available. See below for details.
  • GPS/System location: This uses the device’s native location abilities. Mobile phones combine GPS, Wifi and Cellular signals, and accelerometer information, to provide location in various situations. The accuracy of these methods varies. These capabilities are dependent on the device.

This means that a manual location will always override whatever else may be present; and a nearby beacon will override any GPS location that is present (even if it is accurate).

Each type of location can have a different indicator image, and will be displayed with a circle indicating the accuracy of the location.

Note: The only location method available on desktop PC/Mac is Manual. However, for testing purposes you can fake a beacon being close using the “Fake Beacon Close” action. This should not be considered identical to real beacon behaviours.

Location Using Beacons

The offline map can use Bluetooth beacons to locate the user on the map. Once a beacon is “close” (typically a few meters) then it will be shown on the map as the user location. If more than one beacon is “close”, then the closest one will be shown.

We recommend beacons from Kontakt.io. For more information on beacons, see our beacon installation guide.

The beacons are listed in a Feed in the Umajin Dashboard, selected by the Point Data Feed property. This feed must have (at least) the following columns:

  • BeaconID: the 8 digit ID of the beacon
  • Latitude: latitude of the beacon
  • Longitude: longitude of the beacon

If you have a multi-level map then you will normally also need a level column:

  • Level (optional): the level that the beacon is on (e.g. G)

You can have other columns for information you want to display or make decisions on.

Route Finding

If you also want to find routes between points, then you also need to supply a set of “raw” map data in Open Street Maps XML format (.OSM file). The locations (nodes) and paths (ways) in this data will be read in and a route can be found between two points using this map data.

The route finding is currently simple. It assumes all paths are the same, ie. it doesn’t distinguish between walking, cycling, driving, and public transport. For this reason it is best suited to single-purpose routes such as a set of walkways.

After a route is found (or not) an event fires to allow you to display time/distance information about it. You can also use the action ‘Zoom Map to Fit Route’ to make sure the whole route is visible.

Creating Route Maps Using the Map Editor

If your maps are new ones from floor plans, then you will need to create the route data yourself. You can do this using the Map Editor built into the App Creator. Click the “Edit Map” button underneath the Routing Data File property.

See article: Map Editor

Creating Route Maps Using External Tools

You can also use external tools such as as JOSM to create your route map. You can use Open Street Maps as a reference background, if it has enough detail, or else position your map images using e.g. the PicLayer plugin to JOSM.

Each way you create must be tagged with the ‘highway’ tag, e.g. highway=pedestrian, for the Offline Map component to read it. This tag distinguishes ways that can be routed on, distinct from things like building outlines. To build multi-level maps also requires the nodes to be tagged with the level=X tag.

However, these tools typically have two key limitations:

  • not multi-level aware, and therefore make it difficult to create routes for more than one level.
  • difficult to use custom tile sets; typically requiring setting up a web server with tile set server.

Both these limitations don’t exist with the built-in editor.

Downloading Existing Route Data

If the data is already existing in Open Street Maps, for simple cases this data can be obtained directly from Open Street Maps using it’s “Download XML” function. For larger areas or to give you more control over the data, you can use tools like Overpass Turbo to extract the data.

Points Of Interest (POIs)

The offline map can display points of interest such as businesses, public toilets, bus terminals etc on the map. Each POI displays as a fixed size image, depending on the category; to add a new category requires updating the app.

POIs are listed in the same Point Data Feed as Beacons. For POIs this feed must have the following columns:

  • Title: a name for the point of interest, optionally displayed beside the POI image on the map.
  • Latitude: latitude of the POI
  • Longitude: longitude of the POI
  • Level (optional): the levels on which the POI will display. If blank or not present, the POI will display on all levels. You can specify more than one level by separating them with commas, such as 1, 2, 3
  • Zoom: The zoom level at which the POI becomes visible (1-20). For performance and visual clutter, you should only show a few major POIs such as landmarks at low zoom levels. Most “detailed” POIs such as individual businesses should only be visible at high zoom levels.
  • Category: The type of point of interest as a number or name. This is used to decide which image to use to display the POI – see below.
  • Exits: POIs with a category of “exit” have special behavior: they will always be centered, regardless of POI alignment setting, and they will never display a title.

POI Images

Each POI is displayed with an image, controllable by it’s Category. By default, a standard POI image will be used (default_poi_point.png or default_poi_pin.png, depending on the alignment you’ve chosen). You can change this default image to change all the POI images.

You can also provide an image for a single category by adding a file named categoryXXX.png, where XXX is the category name. Place the image into the images/map folder in your project. Note the case of the filename is important for the image to work on device (both Android and iOS have case-sensitive file systems); for example if you have a category “food” and you create an image named categoryFood.png, it will work on Windows but not on devices.

A POI image may be centered on the POI location, or above it in “pin” style – this is defined by the Image Align property. It will be scaled to the physical size defined by the POI Size property.

Properties for Offline Map Component

General
Name When components are placed on a page they appear highlighted blue in the scene tree and can be renamed by double clicking in this panel and typing the new name. Components can also be set to be visible/invisible on the page, using the ‘eye’ icon on this panel.
Position and Size Sets position and size. As long as measurements are maintained as percentages it deals automatically with dynamic layout and resizing for different devices and orientations. You can use millimeters to control aspects of size like width or height in order to create a group that will be well positioned across devices.
Map
Map Tiles Definition Select the location of the map tile images, by selecting the tiles.json file. Tile images should be in numbered folders.
Point Data Feed Select the Feed you have created in the dashboard to define the beacons and Points of Interest.
Routing Data File Select the .OSM file containing the data to be used for finding routes on the map.
Display Center Crosshair Places a centred cross hair over the map so you can be sure where the map is centred.
Limit Display to Map Boundary When set, the map can not be scrolled outside the bounds as defined by the tiles.json file. When unset the map can be scrolled outside these bounds; this can be helpful to allow display of routes or locations near the edge of the map.
Location
Use System (GPS) Location Whether the location from GPS/wifi/cellular should be displayed on the map at all.
If Accuracy (m) How accurate the system (GPS) location must be before it will be displayed and used by the map. This prevents a giant blue circle being displayed when the GPS is present but very inaccurate. Note that in some situations, the device can think that it’s GPS location is accurate but still be wrong.
System (GPS) Image The image used to display System (GPS) location, if enabled.
Beacon Image The image used to display a location that is detected using BLE beacons.
Manual Image The image used to display a location set using the Set Manual Location on Map action.
Above Image An additional image displayed when the user’s location is above the currently displayed level.
Below Image An additional image displayed when the user’s location is below the currently displayed level.
Direction Indicator This image is placed over top of the location image, and rotated to match the compass heading of the phone. This allows you to show an arrow or similar indicating the direction the phone is pointing. Not all devices have compass sensors. If the device doesn’t have a compass sensor or the image is not set, nothing will be displayed.
Size (mm) The various location images will be scaled to this physical size, allowing them to adjust to different device resolutions.
Markers
Size (mm) When markers are set, their images will be scaled to this physical size, allowing them to adjust to different device resolutions.
Beacons
Signal Select the minimum signal level to consider the beacon “close” enough to define location.
Unvisited Image This image is displayed if the beacon is not showing a close image, and has not been visited before.
Visited Image This image is displayed if the beacon is not showing a close image, and has been visited before. A beacon is considered “visited” if it has been the closest close beacon at some point.
Route Finding
Line Color Defines the color of the line drawn to show a route, once found.
Opacity The opacity (transparency) of the route line.
Line Width The width in pixels of the route line.
Route Finding Diagnostics
Display Route Map Draws the data used for route finding over top of the tiles. This allows you to visually confirm the correct data is available.
Show Nodes Checked for Routing After trying to find a route, this will show a marker at every node (point) on the route map that was checked in the search. This allows you to find gaps in paths, by looking for nodes that are not marked when it seems they should be.
Points of Interest
Image Align Selects if the POI image will be positioned with the location at the bottom center (in the style of a pin in the map) or centered on the location.
Title Whether a text title will be displayed next to each POI.
Size (mm) Defines the width to display POI images, in millimetres.
Point of Interest Titles
This set of style settings controls the appearance of the titles shown for Points of Interest, if enabled (above).

Events

The following events can occurr from the Offline Map component.

On Press Occurs when the user taps or clicks on a normal area of the map (that isn’t a POI). [Latitude], [Longitude] and [Level] variables are available.
On Long Press Occurs when the user holds down a button or finger on the map. [Latitude], [Longitude] and [Level] variables are available.
On Map Move Occurs whenever the centre position of the map changes to a new latitude/longitude. You can use the variables [Latitude], [Longitude], [Level] and [Zoom] in your actions.
On Location Changed Occurs whenever the user’s location changes. You can use the variables [Latitude], [Longitude], [Level] and [Zoom] in your actions.
On Location Unknown Occurs whenever the user’s location is lost (ie. changes from known to unknown). This can occur when there is no GPS (or GPS is disabled) and no beacon nearby or manual location set.
On Beacon Close Occurs when a beacon is “Close” (as defined by the Close signal strength threshold), and is the nearest beacon. See below for information on using this event.
On No Beacon Close Occurs when there are no close beacons (there may still be beacons at “far” distance, ie. less than Close signal strength).
On No Route Found After trying to add a route to the map, if a path couldn’t be found, this event will fire. The variable [route_message] contains a description of the problem. Some possible reasons for failure include:

  • The user’s location is unknown (and no starting location was specified)
  • Start or end location is outside the map bounds
  • Couldn’t find a path between start and end. This can occur when there are isolated segments within the route map.
  • No route map loaded, or the route map is empty.
On Route Found After adding a route to the map, this event will fire. You can use two variables: [time_to_destination] gives you a description of time and distance such as “15 minutes (550m)”; [total_minutes] will give you a number with the total number of minutes
On Point Of Interest Click This occurs when the user clicks on a Point Of Interest (without moving their finger around). See below for information on using this event.
On Route Waypoint Reached

The main event for turn-by-turn directions. Occurs when a point along the route is reached that requires instructions, e.g. an intersection, elevator or corner. In addition this can fire for special circumstances such as Bluetooth being turned off when using beacons.

The following variables are available to show the instruction:

[direction] A simple name for the direction. You can use this to pick an image representing the direction. Possible direction names are:

start The user has reached the first point on the route.
forward User should continue forward – can re-occur with updated [distance]
left User should turn left
right User should turn right
back Does not normally occur
destination Does not normally occur
up User should travel up in an elevator, to [target_level]
down User should travel down in an elevator, to [target_level]
dogleg_left Path turns left then back to straight in a short distance
dogleg_right Path turns right then back to straight in a short distance
sharp_left Path turns sharply left (more than 90 degrees)
sharp_right Path turns sharply right
location_unknown Location is unknown and have not yet reached any point on the route
bluetooth_disabled Bluetooth is disabled (only occurs if beacons are in use)
before_route Location is known, but have not yet reached any point on the route

 

[instruction] Text describing the instruction to the user, such as “Take the left turn”.
[choice] Whether this is a choice of directions at this point: true or false. This can be false for example when a corridor just turns to the left without any intersection with other corridors.
[distance] The distance in metres AFTER this point, to the next one
[target_level] If there is a change in level at elevators or stairs, this gives the name of the level the route goes to next.

If you want to customise the text used in the instructions, Javascript can be used.

On Off Route Occurs when the user has reached a point that is not on the route.
On Destination Reached Occurs when the user has reached the final point on the route. Note that navigation does not automatically stop; use the Stop Navigation action to in this event if required.

Using Beacon and POI Events

When using Beacon and POI events, you can use the “Set Feed Items Index” action, with Set Mode = “Data bound index” option, to set a Feed Item View to the index of the beacon or POI, and therefore display some details about it.

All the data from the beacon row in the feedlist are available as variables, including the mandatory “Latitude”, “Longitude”, and “BeaconID”.

If you want different behaviour depending on which beacon is close, then you can use a column in the beacon feed to define it. The “Condition” action can be used to change which actions fire.

Actions

The following actions are useful in conjunction with the offline map component

Set Map Centre Location

Positions the map to be centred on the specified latitude and longitude and on the specified level.

Note that if latitude, longitude and level are blank then the map will be centered on the current user location (if known), same as the “Center Map on User Location” action.

Set Map Level Changes the level (floor) of the map that is being viewed. Options allow you to set a specific floor or go up or down. This may have no effect if already at top or bottom, or you specify a level that doesn’t exist in levels.txt.
Set Map Zoom Level Zooms the map to a specified level. Note that the map tiles will only support a certain range.
Set Manual Location on Map Sets the map to show a fixed location that you supply. The image is changed to that set by the Manual Image property.
Clear Manual Location on Map Clears a manually set user location. The map will go back to showing location by beacons, GPS etc as applicable.
Fake Beacon Close This makes the map behave as if a specified Beacon ID is nearby. This helps you test beacon behaviours, especially on the desktop when designing the app.
Condition This action allows you to set a simple “IF” condition, controlling if further actions occur. This can be useful in conjunction with beacon events.
Add Map Route by Latitude/Longitude Finds a route between two (latitude, longitude) points. It will first find the nearest points on a path on the route map, and then find a route between the two points. To find a route from the user’s current location, leave the start latitude and longitude blank.
Zoom Map to Fit Route Zooms and pans the map to show the current route in a defined area. To define the area, create any component such as a rectangle and make it invisible or behind the map. This allows you select the area of the screen which is used to show the route.
Zoom Map to Fit Points Zooms and pans the map to fit two specified coordinates in a defined area. To define the area, create any component such as a rectangle and make it invisible or behind the map.
Start Map Navigation

Starts turn-by-turn directions for the current route. While navigating, the events On Route Waypoint Reached, On Off Route, and On Destination Reached will fire. The following special messages can be given as directions:

Bluetooth Disabled Message: If Bluetooth is off and beacons are being used.
Location Unknown Message: If location is unknown before starting the route. (Once the user has reached the route, this message is not triggered if location becomes unknown, so that the last direction can be left showing).
Before Route Message: When location is known, but has not yet reached the route.

Stop Map Navigation Stops turn-by-turn directions.
Update Map Directions Triggers the current direction again. This can be useful to update the display when something else may have changed.
Center Map on User Location This moves the map so that the user’s current location is centered. If the “Lock” option is checked, then the map will move as the user moves, to keep itself centered on their location.
If system/GPS location is available, that is used. Otherwise, if beacons are being used and one is nearby, then the strongest (closest) beacon is used. A manually set user location will override either of these.
Clear Map Route Clears the currently displayed route
Add Map Marker Places a named map marker at a latitude and longitude.  This marker will remain on the map until cleared. If there is an existing marker with the same name it will be replaced.
Clear Map Marker Clears a map marker with the given name.
Clear All Map Markers Clears all map markers.
Switch Map GPS On/Off Allows you to control whether the map will use GPS (system) location while running. This can be useful to switch between indoor and outdoor operation.
Set Map Diagnostics Turns display of diagnostics on the map on and off.