Attaching GameObjects to the map

To position GameObjects on the map by a latitude, longitude, and altitude, the MapPin component can be used.

The MapPin will take over the positioning a GameObject by updating it's transform each frame so that the position of the GameObject is synchronized to the specified location on the Map. As the map view changes via translation or zoom, the MapPin's position will update accordingly.

There are two approaches that can be used to attach a MapPin. Both approaches are used in the sample project.

Adding a child MapPin to the MapRenderer

The simplest approach is to create a GameObject with a MapPin component and place it as a child of the MapRenderer in the scene hierarchy.

The MapRenderer will automatically detect any MapPin components which are immediate children and then update their positions accordingly.

This approach is good if you just have a few unique objects that need to be pinned to the map.

Using the MapPinLayer

This approach is better suited for large data sets where clustering may be required:

• Add a MapPinLayer component to the MapRenderer's GameObject.

  

• In a script, get a reference to the MapPinLayer and add MapPin instances to the the layer's MapPins collection.

  // Generate a MapPin for each of the locations and add it to the layer.
  foreach (var mapPinLocation in _mapPinLocations)
  {
     var mapPin = Instantiate(_mapPinPrefab);
     mapPin.Location = mapPinLocation;
     _mapPinLayer.MapPins.Add(mapPin);
  }

Clustering

An advantage of the MapPinLayer is that it supports clustering. This requires the use of a special type of component, a ClusterMapPin. When MapPins are clustered, the ClusterMapPin is shown in the place of the various MapPins that associate to it.

To enable the clustering functionality, a ClusterMapPin prefab must be specified on the MapPinLayer.

An instance of this prefab is then displayed in place of a group of MapPins until the level of detail of the current map view is high enough to display individual pins. The threshold at which clustering occurs can be adjusted in the MapPinLayer.

Clustering is highly recommended for large datasets as this will reduce the number of MapPin instances that need to be rendered for zoomed out views. Besides this rendering performance benefit, it is often preferable to cluster MapPins from a usability perspective since dense, cluttered views will make it more difficult for the user to interact with individual MapPins.

Clusters are created at every zoom level, so as the zoom level of the MapRenderer changes, the visible clusters and MapPins may change as well.

A note on performance

Creating and adding many MapPins at once, either to a MapPinLayer or as children of the MapRenderer, could be time consuming and thus cause a frame hitch. If the MapPins can be initialized and added all at startup, this may be an acceptable one time hit. However, if data is being streamed and converted to MapPins throughout the app's lifetime, consider spreading out the MapPin creation and addition over multiple frames, i.e. time slice the additions. This will help to maintain render performance.