Offline Map Component
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.
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.
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.
The beacons are listed in a Feed in the Umajin Dashboard. 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
You can have other columns for information you want to display or make decisions on.
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 from Scratch
If your maps are new ones from floor plans, then you will need to create the route data using a tool such as JOSM.
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.
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 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
- 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.
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. Or, you can 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.
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 a group that will be well positioned across devices.|
|Map Data File||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.|
|Display Center Crosshair||Places a centred cross hair over the map so you can be sure where the map is centred.|
|Use System (GPS) Location||Whether the location from GPS/wifi/cellular should be displayed on the map.|
|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 User Location action.|
|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.|
|Size (mm)||When markers are set, their images will be scaled to this physical size, allowing them to adjust to different device resolutions.|
|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.|
|Routing Data File||Select the .OSM file containing the data to be used for finding routes on the map.|
|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).|
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] and [Longitude] variables are available.|
|On Long Press||Occurs when the user holds down a button or finger on the map. [Latitude] and [Longitude] 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] and [Zoom] in your actions.|
|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:
|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.|
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.
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.|
|Set Map Zoom Level||Zooms the map to a specified level from 1-20. Note that the map tiles will not usually support this full range – pick zoom levels that work for your app.|
|Set User Location on Map||Sets the map to show a fixed location that you supply. The image is changed to that set by the Manually Set Location Image property.|
|Clear Manual User Location on Map||Clears a manually set user location. If the Show current location property is set, then the map will go back to showing location using whatever is the most accurate available (Beacon, GPS, or wifi/cellular as available).|
|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.|
|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.|