You can constrain the user navigation on the map by using one of these constraints:

  • Above terrain and/or mesh: this constraint always keeps the camera at a configurable minimum altitude above the terrain and/or mesh. This constraint has an effect on a 3D map only. By default, the above terrain constraint is enabled, while above mesh is disabled.

  • Bounds constraint: always keeps the map within the configured bounds. This constraint has an effect on a 2D map only. By default, there is no bounds constraint.

  • Scale constraint: keeps the map within a defined minimum and maximum scale range. This constraint has an effect on a 2D map only. By default, there is no scale constraint.

MapNavigatorConstraints allows you to configure the constraints. You can set them through the constraints property of MapNavigator.

The constraints are only applied when the map’s underlying camera (see Map.camera) is not manipulated directly.

Program: Changing the constraints of the main camera
  const boundsRef = getReference("EPSG:4326");
  const bounds = createBounds(boundsRef, [-180, 360, -90, 180]);

  map.mapNavigator.constraints = {
    above: {
      terrain: true,
      mesh: false,
      minAltitude: 10
    },

    limitBounds: {
      bounds: bounds,
      padding: {
        top: 1,
        bottom: 1,
        left: 5,
        right: 5
      }
    },

    scale: {
      minScale: 2e-8,
      maxScale: 2e-4
    }
  };
glow
Figure 1. A glow appears at the limit of the constraint to indicate that the user cannot pan any further when the bounds constraint is enabled.

A conflict may occur when you have set both a scale and a bounds constraint. This can happen when, for example, the 'maxScale' constraint is set to a country level scale, while the bounds constraint is set to the bounds of a city. In such a case, the bounds constraint is respected over the maxScale.To prevent such inconsistencies, it is best to use either the bounds constraint or the scale constraint to restrict the zooming behavior of the map.

Map navigation constraints are also supported on a WebGL 2D map. If the bounds constraint is set, map rotation is not possible.

On a 3D map, bounds and scale constraints are ignored.