Introduction
The ground map is a RezMela feature allowing a large, flat object to be placed in the scene, which serves as a floor and which has Google Maps images displayed horizontally upon it. In this way, a road layout or similar can be created using Google Maps as a template and background.
Use
The ground map is typically centred in the region and covers the entire region. The associated icon displays the same map as the world object. The following controls are available, either through clicking prims at the northern end of the object, or by clicking the "hamburger" menu on the icon to obtain a menu:
Enter new coordinates for the map
Toggle between road map and satellite view
Refresh the map
Zoom in and out
Move north, south, west or east
Load "bookmarks" from a predefined list of places
Construction
The main ground map object consists of a matrix of flat tile prims, each separately scripted and which together form the map surface. The root prim, which contains the main controller script and standard WorldObject script, is somewhat below the centre of the tiles matrix.
Vertical control prims on the northern edge are used as buttons to trigger the various runtime features.
Scripts
The following scripts are used:
Controller
This resides in the root prim, and controls most of the functionality.
Tile
One of these resides in each of the tiles, and displays the map portion under instruction from the controller
Bookmarks
This is in the bookmarks prim, and handles the display and selection of bookmarks
Icon
In the control board icon, this communicates with the main controller and displays the icon map
Data flow and RezMela integration
By necessity, there is a certain amount of complexity in the interactions between the ground map icon and world object scripts, their generic RezMela counterparts, and the RezMela controller script.
This is described in a separate document: Interactions between icons, world objects and controller.
The Ground Map stores "extra data" in the RezMela system. This consists of the following elements:
Latitude
Longitude
Zoom level
Map type ("roadmap"/"satellite")
Configuration
The configuration notecard "Ground map config" in the root prim of the object contains the following data items:
Bookmarks
At the northern edge, there is a prim which displays a list of bookmarked places, any of which may be loaded by clicking on its name.
These bookmarks are stored in a notecard named "Places", in the root prim. The format is CSV: <name>,<latitude>,<longitude>.
The display, and interpretation of the touch event, is handled by the "Ground map bookmarks" script, which resides in that prim. A separate script is necessary because prim drawing cannot currently be achieved in other prims in a linkset. The script receives a list of bookmark names via link message, and on clicking transmits a pointer to that list by the same means.
Points about the maps/search APIs
The script uses the Google Static Maps API, which "lets you embed a Google Maps image on your web page without requiring JavaScript or any dynamic page loading. The Google Static Maps API service creates your map based on URL parameters sent through a standard HTTP request and returns the map as an image you can display on your web page."
It also uses the Google Places API in order to perform searches on place names: "Return a list of places based on a user’s location or search string". This has a separate API key.
Internal representations of positions
Google Maps has its own method of representing coordinates, which is based on a Mercator projection. The script contains functions to translate between these coordinates and geographic decimal latitude/longitude values. The conversion code is based on this article.
Miscellaneous points:
Display delay
In order to reduce the amount of time the map is redrawing, a delaying mechanism is coded which only displays the map tiles when there has been no change for 1.6 seconds. Inevitably, this delays the display of pages by a minimum of that value.