The TileSet3DLayer allows you to perform selection operations on the layer. To ensure that a TileSet3DLayer can have selectable parts, the following conditions must be met:

  1. The TileSet3DLayer.selectable property must be true.

  2. The TileSet3DLayer.idProperty must be set at construction time.

The idProperty of a TileSet3DLayer refers to a property name that exists in the metadata of the tileset. For OGC 3D Tiles, the metadata is part of the batch table. The idProperty is often specific to the domain and the data. Therefore, you cannot generalize it for all use cases.

The figure Figure 1, “An example of a simple dataset with metadata.” shows a simple example of 4 cubes and their metadata property names and values. Note that in this hypothetical sample, all cubes are part of the same single TileSet3DLayer dataset:

ogc3d tiles selection none
Figure 1. An example of a simple dataset with metadata.

If we were to use the GUID property in this dataset, and applied a selection on all data with GUID equal to 1, we would get the following result:

ogc3d tiles selection guid
Figure 2. The example dataset with GUID selected as the idProperty. The cube with GUID equal to 1 is selected.

The idProperty does not have to be unique in the dataset. You can choose any existing metadata field name in your dataset for your idProperty.

If we set the idProperty to the Material property in the previous example, and clicked on a wooden cube, all wooden cubes would be selected:

ogc3d tiles selection material
Figure 3. The example dataset with Material selected as the idProperty. The user clicked on one of the wooden cubes.

To create a new TileSet3DLayer with an idProperty of GUID, you can use:

const ogc3dTilesLayer = new TileSet3DLayer(model, {
  selectable: true,
  idProperty: "GUID" // Must be a property name that also exists in the metadata of the TileSet3DLayer
});

The list of metadata properties available as idProperty is part of the modelDescriptor of the model.

Once you have your selectable TileSet3DLayer up and running, you can start listening to SelectionChanged events. This is similar to how you would listen to selection changes in a FeatureLayer. See Selecting and deselecting objects on the map through the API.

Similar to FeatureLayer, a SelectionChanged event contains a set of Feature objects that are part of the current selection in your TileSet3DLayer. Although TileSet3DLayer does not explicitly contain Feature objects, the interface is used to convey properties about the selected 3D mesh data.

The Feature objects returned by the SelectionChanged event contain this information:

  • The id is the value of the selected idProperty

  • The shape is a Point with the map coordinates indicating where the mouse interacted with the TileSet3DLayer

  • The properties contain all metadata properties about the selected feature.

Handling selection without an idProperty

If your dataset does not contain any metadata, you cannot perform selection operations, not even if you enable TileSet3DLayer.selectable.

It is however possible to use the Map.pickAt() function to find out if a view- coordinate touches a TileSet3DLayer. In this scenario, the Map.pickAt() function returns a reference to the TileSet3DLayer, but it contains a Feature with its id set to the string "unknown" and its properties undefined. This indicates that the mouse interacts with the view-coordinate at the specific pixel location, but that it cannot actually be selected.

For these cases, no SelectionChanged event will be fired, because the selection on the map did not actually change.

Changing the styling of the selection

By default, selecting a Feature in a TileSet3DLayer changes its color on the map. The default selection color is orange.

To change the default color, you can override the MeshStyle.selectedColorExpression. This is an expression that is applied to any part of your mesh where the idProperty attribute has the currently selected property value as true.

This expression is made available for reasons of convenience. It is possible to set it to null to prevent selection from changing the color of your TileSet3DLayer.

It is also possible to write a more complex expression in MeshStyle.colorExpression to further customize selection styling. You will not typically need this option, unless for very specific use cases.

Programmatic selection and its limits

To perform programmatic selection operations on the map, use the Map.selectObjects() function. See Selecting and deselecting objects on the map through the API for more details.

The interface is exactly the same for a TileSet3DLayer and a FeatureLayer, with the exception that a TileSet3DLayer does not actually contain a set of Feature objects. It is possible to create Feature objects as needed. The only condition is that you set their Feature.id property to the desired property value.

One limitation for programmatic selection is that when you programmatically select a feature that has not been selected before, the resulting SelectionChanged event will not contain any metadata in its feature properties.

Although the TileSet3DLayer allows you to select multiple objects at the same time, keep in mind that the number of simultaneously selected objects is subject to hardware limitations. We recommend selecting only a few objects at the same time. Selecting thousands of objects could trigger an overflow of the internal WebGL shader code.