Offline Map

The Offline Map component allows you to show a map in your Project that does not require any internet connection. The map is typically of a small area to reduce project 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.

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 Project. 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:

3
2
1
G
B

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 Cloud, 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.

Note: if using a custom Javascript feed for POIs and Beacons, you must make sure that the first row of your feed includes all the columns for both POIs and Beacons (with blank values for the columns you don’t need). This is required to identify all the possible columns.

Note: beacon signals can come and go briefly, for example when people move past. To reduce the effect of this you can set a “linger time” for the last location to stay visible for a little while.

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 Umajin Editor. Click the “Edit Map” button underneath the Routing Data File property.

See article: Map Editor

Creating Route Maps Using External Tools

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 Project.

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.
Max_Zoom: the zoom level after which the POI dissappears again. This can be useful to turn off “area”-type POIs as you zoom in to more detail. Added in Editor 3.2
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.

Note:if using a custom Javascript feed for POIs and Beacons, you must make sure that the first row of your feed includes all the columns for both POIs and Beacons (with blank values for the columns you don’t need). This is required to identify all the possible columns.

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

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 an Offline Map Component thats size will be maintained 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.
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.

Map Points Data

Feed ID	Click the Folder icon to select the numbered feed from the feed Picker. You will have already entered these feeds into the Feed Picker.
Data URL	Type in the website or select a URL that has already been loaded into the Umajin Cloud.
Custom feed parameters	Not enabled unless you have created a Custom Feed using JavaScript. It will allow you to set the parameters of that Custom Feed.

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.
Linger Time (s)	The time that the last known location will stay visible if the beacon or GPS signal disappears. This can help when beacons are prone to disappearing briefly, for example in obstructed locations.
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 occur 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 Moved

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. In addition, the variables [is_top] and [is_bottom] will be set to the text “true” if the level is the top or bottom level of the map respectively.

On Location Changed

Occurs whenever the user’s location changes. You can use the variables [Latitude], [Longitude] and [Level] 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 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 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 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.

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.

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.
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.