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.

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

  1. 3
  2. 2
  3. 1
  4. G
  5. 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.

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

General
NameWhen 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 SizeSets 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 DefinitionSelect the location of the map tile images, by selecting the tiles.json file. Tile images
should be in numbered folders.
Routing Data FileSelect the .OSM file containing the data to be used for finding routes on the map.
Display Center CrosshairPlaces a centred cross hair over the map so you can be sure where the map is centred.
Limit Display to Map BoundaryWhen 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 IDClick the Folder icon to select the numbered feed from the feed Picker. You will have
already entered these feeds into the Feed Picker.
Data URLType in the website or select a URL that has already been loaded into the Umajin Cloud.
Custom feed parametersNot 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) LocationWhether 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) ImageThe image used to display System (GPS) location, if enabled.
Beacon ImageThe image used to display a location that is detected using BLE beacons.
Manual ImageThe image used to display a location set using the Set Manual Location on
Map
action.
Above ImageAn additional image displayed when the user’s location is above the currently displayed
level.
Below ImageAn additional image displayed when the user’s location is below the currently displayed
level.
Direction IndicatorThis 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
SignalSelect the minimum signal level to consider the beacon “close” enough to define location.
Unvisited ImageThis image is displayed if the beacon is not showing a close image, and has not been visited
before.
Visited ImageThis 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 ColorDefines the color of the line drawn to show a route, once found.
OpacityThe opacity (transparency) of the route line.
Line WidthThe width in pixels of the route line.
Route Finding Diagnostics
Display Route MapDraws 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 RoutingAfter 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 AlignSelects 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.
TitleWhether 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 PressOccurs 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 PressOccurs when the user holds down a button or finger on the map. [Latitude], [Longitude] and
[Level] variables are available.
On Map MovedOccurs 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 ChangedOccurs whenever the user’s location changes. You can use the variables [Latitude],
[Longitude] and [Level] in your actions.
On Location UnknownOccurs 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 CloseOccurs 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 CloseOccurs when there are no close beacons (there may still be beacons at “far” distance, ie.
less than Close signal strength).
On Route FoundAfter 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 FoundAfter 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 ReachedThe 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:

startThe user has reached the first point on the route.
forwardUser should continue forward – can re-occur with updated
[distance]
leftUser should turn left
rightUser should turn right
backDoes not normally occur
destinationDoes not normally occur
upUser should travel up in an elevator, to [target_level]
downUser should travel down in an elevator, to [target_level]
dogleg_leftPath turns left then back to straight in a short distance
dogleg_rightPath turns right then back to straight in a short distance
sharp_leftPath turns sharply left (more than 90 degrees)
sharp_rightPath turns sharply right
location_unknownLocation is unknown and have not yet reached any point on
the route
bluetooth_disabledBluetooth is disabled (only occurs if beacons are in use)
before_routeLocation 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 RouteOccurs when the user has reached a point that is not on the route.
On Destination ReachedOccurs 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 ClickThis 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 LocationPositions 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 LevelChanges 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 LevelZooms the map to a specified level. Note that the map tiles will only support a certain
range.
Set Manual Location on MapSets 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 MapClears a manually set user location. The map will go back to showing location by beacons,
GPS etc as applicable.
Fake Beacon CloseThis 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/LongitudeFinds 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 RouteZooms 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 PointsZooms 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 NavigationStarts 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 NavigationStops turn-by-turn directions.
Update Map DirectionsTriggers the current direction again. This can be useful to update the display when
something else may have changed.
Center Map on User LocationThis 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 RouteClears the currently displayed route
Add Map MarkerPlaces 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 MarkerClears a map marker with the given name.
Clear All Map MarkersClears all map markers.
Switch Map GPS On/OffAllows 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 DiagnosticsTurns display of diagnostics on the map on and off.