When a user zooms in and out on a map, it can be useful to change which layers are shown or hidden.

Controlling the visibility of layers has benefits for the performance and usability of your application. For instance, if your vector data set consists of detailed point-of-interest information, it makes sense to show this layer only when the user has zoomed in enough. If you show it any earlier, you visualize all layer objects at once, and the objects just clutter up the map. Because your application needs to visualize so many objects, its performance may also degrade. Similarly, for a layer showing borders of countries, it may not make sense to keep showing the data when the user zooms in.

You can configure a LuciadLightspeed layer to automatically show or hide itself based on the map scale of the view it’s been added to. The article Working with map scales has more background information on map scales in LuciadLightspeed.

You can control visibility in other ways, for example with a scale-aware styler, with TLcdModelQueryConfiguration and SLD , or with clustering. However, these options are mostly useful for hiding only specific objects in a layer, but not for hiding the entire layer. Additionally, these methods work well for vector data, but are less suited for raster data. Setting the scale range on a layer works equally well for any type of data.

Using the map scale range property

The majority of layers in LuciadLightspeed extend from ALspLayer, which has a mutable mapScaleRange property. You can use that property to control the visibility of the layer, even after the layer was constructed.

The scale range in which the layer is visible, is expressed as a map scale interval, with type TLcdDimensionInterval<TLcdMapScale>. The easiest way to construct such a map scale interval is to use the factory method TLcdMapScale.createScaleRange. This example defines a scale range that, once you apply it to a layer, shows the layer only when the scale of the view is between 1:1000 and 1:10:

Program: Create a map scale range
TLcdDimensionInterval<TLcdMapScale> scaleRange = TLcdMapScale.createScaleRange(new TLcdMapScale(1.0 / 1_000), new TLcdMapScale(1.0 / 10));

To change the scale range on a layer, call the setMapScaleRange method. You can define a distinct scale range for each paint representation, so you must pass a paint representation to the method.

Program: Change the map scale range on a layer
aLayer.setMapScaleRange(TLspPaintRepresentation.BODY, aScaleRange);

TLspLayer has a scaleRange property in addition to mapScaleRange. The scaleRange property behaves similarly to mapScaleRange, but the scales are expressed in terms of toolkit pixels/meter instead of a unitless ratio. We recommend using only mapScaleRange whenever possible.

Setting the map scale range when building a layer

For your convenience, you can also set the mapScaleRange property when you construct a layer with raster data through TLspRasterLayerBuilder, or when you construct a vector-based layer through TLspShapeLayerBuilder. For TLspShapeLayerBuilder, it’s possible to set the map scale range independently for the body and label paint representations, using labelMapScaleRange and bodyMapScaleRange respectively.

Program: Define the map scale range on a layer in the builder
ILspEditableStyledLayer layer = TLspRasterLayerBuilder.newBuilder()
                                                      .model(aModel)
                                                      .mapScaleRange(aScaleRange)
                                                      .build();