The map object shows a map of the world. The map data is provided by any map server that delivers maps in a tile format where each map tile is an image of 256 x 256 pixels with Mercator projection. OpenStreetMap.org is one of the Internet services that delivers free maps in this format.
The map uses WGS84 as a geographical coordinate system, which is the same coordinate system that is used by the Global Positioning System - GPS. Coordinates used by the map are specified as longitude and latitude in decimal form.
The map can either be set to follow the GPS position provided by a GPS receiver, or to show the location of a specified coordinate. The zoom level of the map is a parameter that can be statically set or controlled by the timeline system. This allows for dynamic control over the scale of the map.
The map can display markers at given locations. These markers can be used for marking way points or points of interest etc. The location of the markers, and their properties, are retrieved from a data source that provides marker data in a specified database table format. Since the data, such as the location of the marker, is provided by a data source, the markers can dynamically update their location and data while a map is shown. This can be used to show the location of other moving objects in the world that have reported their position to the database.
- FollowGPS - Setting this parameter to True will make the map always center on the current GPS position received from a GPS receiver connected to the system. If this parameter is False, the map is instead centered on the position specified by the Longitude and Latitude parameters.
- Latitude - Specifies the latitude coordinate to center the map on. This parameter is only valid if the FollowGPS parameter is set to False.
- Longitude - Specifies the longitude coordinate to center the map on. This parameter is only valid if the FollowGPS parameter is set to False.
- Provider - This is the provider of the map data in the form of a URL. An example of a map data provider is OpenStreetMap.org which provides one of its tile sets through the URL "http://tile.openstreetmap.org". Please be aware of the Tile usage policy for OpenStreetMap.org before you start using that tile set.
- ZoomLevel - The zooming level that the map is displayed in. This is a value between 0 and 18. A low value means that more of the world is shown than with a higher value.
- MarkerDataSource - This parameter is used to create a connection to a data source item from which markers can be retrieved. The data item that provides the marker information can provide data fields as shown in Table 17.1, “Marker data fields”. The only required fields are the longitude and the latitude fields, the other ones are optional. Leaving out a field in either the query in the data item or from the data itself means that that field's feature is not used by the marker.
Table 17.1. Marker data fields
Field Name Data Type Purpose longitude double The longitude coordinate where to place the marker. latitude double The latitude coordinate where to place the marker. category string A category string that is used for giving the marker an icon on the map. The mapping between categories and icon images is done with the CategoryImages property. name string A text that is displayed on the marker. at_distance double Distance, in meter, when another GPS position is considered to be at the same location as this one. This distance is drawn as a transparent circle around marker. vicinity_distance double Distance, in meter, when another GPS position is considered to be in the vicinity of this location. This distance is drawn as a transparent circle around the marker. - TrailDataSource - This parameter is used to create a connection to a data source item from which a GPS trail can be retrieved. The data item that provides the trail information shall provide data fields as shown in Table 17.2, “Trail data fields”. A trail is drawn by connecting the supplied GPS positions with lines.
Table 17.2. Trail data fields
Field Name Data Type Purpose longitude double The longitude coordinate where to place a trail break point. latitude double The latitude coordinate where to place a trail break point. - CategoryImages - This is a list of mappings between marker categories and the image files to use for the categories. This list is represented as a series of category names and image file names that are separated by a semicolon. The category name and image file name is separated by a vertical bar '|'. There is always a 'default' category specified that is used for all markers with a category that is not explicitly defined here.
Example 17.1. Example of a marker category image mapping that sets all markers with a category of 'red' to use the RedPin.png image and the marker with a category of 'blue' to use the BluePin.png image. All other markers will use the DefaultPin.png image.
default|DefaultPin.png;red|RedPin.png;blue|BluePin.png