Interface MapNavigatorConstraints

The following navigation constraints used to restrict navigation using MapNavigator.constraints.

  • above: keeps the camera above terrain and/or above meshes.
  • limitBounds: keeps the camera inside the defined bounds.
  • scale: prevents the camera from zooming in or out too far.

Note that if you use the map's underlying Camera directly, the constraints are not applied.

By default only the above terrain constraint is enabled. Constraints can be enabled and disabled via MapNavigator.constraints.

This example disables the above constraint and sets the minimum scale constraint value to 1/100000. For other options check the field parameters.

mapNavigator.constraints.above = null;

mapNavigator.constraints.scale = {
    minScale: 1/100000
  };

Since

2019.0

Hierarchy

  • MapNavigatorConstraints

Properties

above? limitBounds? scale? wrapAroundWorld?

Properties

Optional above

above?: null | AboveConstraintOptions

The above constraint can be used to constrain the camera to remain above the terrain and/or mesh in a 3D map. For 3D cartesian maps, the above constraint is always disabled, regardless of what is configured.

This constraint is only applicable to 3D WebGL maps (3D hardware accelerated maps).

The above camera constraint can be configured with the AboveConstraintOptions

When set to null AboveConstraintOptions.terrain and AboveConstraintOptions.mesh will be set to false and AboveConstraintOptions.minAltitude set to 0.

The following example applies above terrain constraints and sets the minimum altitude to 20m
mapNavigator.constraints = {
    above: {
      terrain: true,
      mesh: false,
      minAltitude: 20
    }
}

Optional limitBounds

limitBounds?: null | LimitBoundsOptions

The bounds constraint can be used to restrict navigation to the specified bounds. By default this constraint is disabled.

This constraint only works in 2D

The LimitBoundsOptions can be used to configure the bounds constraint:

When set to null, all values will be restored to their default values.

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.

If this constraint is enabled, map rotation is not possible.

The following example configures the bounds constraint with bounds and a padding for the top and right side of 5 pixels.

mapNavigator.constraints = {
 limitBounds: {
   bounds: createBounds( ReferenceProvider.getReference("CRS:84"), [50, 4, 20, 20]),
   padding: {
     right: 5,
     top: 5
   }
  }
 }

Optional scale

scale?: null | ScaleConstraintOptions

The scale constraint can be used to restrict the map to a min/max scale. By default the scale constraint is disabled.

The scale value is the ratio between the distance, as it is measured on the screen of the device, to the distance in the real world.

This constraint only works in 2D.

The scale constraint can be configured with the ScaleConstraintOptions.

  • When set to null, all values will be restored to their default values.

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.

The following example shows how to configure the scale constraint:

mapNavigator.constraints = {
 scale: {
   minScale: 2e-8,
   maxScale: 1e-4
 }
}

Optional wrapAroundWorld

wrapAroundWorld?: null | WrapAroundWorldConstraintOptions

A constraint that applies to Map.wrapAroundWorld maps.

By default, a constraint is active that limits the max number of visible worlds to 1. This constraint only has effect on maps that have Map.wrapAroundWorld enabled.

Usage:

  map.mapNavigator.constraints.wrapAroundWorld = {
    maxNumberOfWorlds: 3
  };

For more information on working with maps that wrap around the dateline, check out the Configuring a map to wrap around the dateline guide.

Since

2023.1

Settings

Member Visibility

Theme