How to work with Layers

What are layers?

In the context of creating and using markers in XP360, a layer is a group of markers. Adding markers to different layers allows you to better manage those markers as part of a group instead of modifying each marker individually. An example would be adding markers for restaurants to a layer named “food”, and markers for hotels to a layer named “hotels”. You can then interact with and modify the markers in the “food” layer without the “hotel” markers being changed.

What can they be used for?

Here are a few examples of what layers can be used for:

  • Grouping your markers into layers allows you to show/hide a whole layer in the viewer without affecting other markers. Ex: Hiding a layer of “Property Sold” markers to just show remaining “For Sale” markers

  • Having markers in a layer allows you to easily find/modify all the markers without the worry of changing an unrelated marker. Ex: Changing the color of all the “Property Sold” markers, while leaving every other kind of marker as the default color

  • When you have a large number of markers, adding them to layers can help you keep track of what the markers are or what “group” they belong to. Ex: Separating markers into different layers for “food”, “hotels”, “entertainment”, “banks”, “parks”, “medical”, etc…

How to add/change layers?

There are two easy ways to add a layer, and one way that can be used if the first two ways can’t be used. The three methods to add a layer are as follows:

Method 1) When adding a marker, there is a “layer” parameter that can be used to add the marker to a specific layer (using the layer name). If this isn’t set when making the marker, it will be added to a layer named “default”. If you attempt to add a marker to a layer that doesn’t exist yet, a new one will be created with the name you specify.

Method 2) When constructing your AerialSphere object, there is a parameter called sphereData which takes an object that specifies all the settings for the created aerialSphere object. sphereData has an array named “layers” which is where all the layer information is created (and stored for future use). When creating your sphereData object (as part of AerialSphere object creation), you can use a specified “layers” array consisting of one or more objects with the following information (this will create all layers from the start):

  • name: The name of the layer. Markers can be added to this layer later on by using this name, and the layer can be grabbed using this name as well.

    • visible: Whether the markers in this layer should be visible or not. The layer is visible when set to true and hidden when set to false

    • markers: This is an array of marker objects that are part of this layer. If you have an array of markers for this layer during creation, it can be added here. Otherwise they will need to be added as normal (clarified in “Working with Markers”)

Method 3) This method should only be used if the previous two methods can’t be used, which usually happens when you need to add a layer after the AerialSphere object has been created, and all markers have already been added. Just as you can create an array of “layer” objects when creating sphereData, you can create a new array of “layer” objects and overwrite what is in sphereData with the new array. Keep in mind that overwriting this way will get rid of all previous layers (and any markers added to those layers), so it is a good idea to first grab the array of layers and add/change from there to ensure no data is lost. 

  • To grab your current array of layers, you can call aerialSphere.getData(), which will return the sphereData object, which includes the current array of layers. 

    • Once you have created/changed the array of layers you got in the last step, you will have to use aerialSphere.sendData() to overwrite the previous array. The object you send through sendData() will look like this: { layers: [{layer1}, {layer2}, {layer3}] }

      • layer1, layer2, and layer3 are all “layer” objects, as described in Method 2

Functions to work with layers

There are two main functions you will use when working with layers: getLayer() and setLayerVisibility()

  • getLayer(layerName) will return the layer object with the matching layer name. Keep in mind that this is just a copy of the associated layer, so any changes you make to the grabbed object will not reflect in the viewer. If you want changes to be reflected in the viewer, you will need to overwrite the previous layer with your new changed layer (see Method 3 above)

  • setLayerVisibility(layerName, isVisible) allows you to set the visibility of the specified layer (via layerName) to be either true or false (vis isVisible). Unlike getLayer(), this will be reflected in the viewer as soon as you call the function.