Options
All
  • Public
  • Public/Protected
  • All
Menu

MapNavigator provides utility functions to navigate the map.

A MapNavigator instance can be obtained through the map.mapNavigator property.

All operations are supported in both 2D and 3D. All operations also work on non-georeferenced views (e.g. vertical views or timelines).

All operations can be immediate or animated. The following operations are supported:

  • pan
  • Translate the map so that a given point ends up at a certain location in the view.
  • zoom
  • Change the scale of the map. You can either zoom with a factor or zoom up to a target scale.
  • rotate
  • Rotate the map. You can either rotate towards a target angle or add a delta angle to the current rotation of the camera.
  • fit
  • Fit the map on a target bounds.

Most parameters take a point in either view (point.reference === null), model (point.reference !== null) or map coordinates (point.reference === map.reference). See the JSdoc to check in which reference a point argument can be.

Note that the Map can have navigation restrictions by using constraints. Constraints can be set on the MapNavigator via mapNavigator.constraints. A detailed description of the available constraints and their behavior can be found in the documentation of MapNavigatorConstraints

When these constraints are set, it is not possible to violate these constraints by using the MapNavigator. However, if you use the map's underlying camera directly, the constraints are not applied.

Hierarchy

  • MapNavigator

Overview

Constructors

Private constructor

  • This class should not be instantiated by users of LuciadRIA.

    Returns MapNavigator

Properties

Static ALL

ALL: number
deprecated
see

enabledOperations

Static NONE

NONE: number
deprecated
see

enabledOperations

Accessors

constraints

defaults

  • An object describing the default values used in this MapNavigator.

    Manipulate this object to change the default animation durations (or easing functions) for the different MapNavigator operations.

    You can assign individual properties, like so:
      mapNavigator.defaults.pan.duration = 5000; //change the default pan duration to 5000ms

    Returns MapNavigatorDefaults

  • An object describing the default values used in this MapNavigator.

    Manipulate this object to change the default animation durations (or easing functions) for the different MapNavigator operations.

    You can assign individual properties, like so:
      mapNavigator.defaults.pan.duration = 5000; //change the default pan duration to 5000ms

    Parameters

    Returns any

enabledOperations

  • get enabledOperations(): number
  • set enabledOperations(operations: number): void
  • A property describing the currently enabled operations. Valid values are MapNavigator.ALL and MapNavigator.NONE. Set to MapNavigator.ALL by default.

    deprecated

    mapNavigator.enabledOperations has been deprecated.

    This property will only be respected by the deprecated MapNavigator methods. The new methods (pan, rotate, zoom and fit), will ignore enabledOperations.

    As a replacement, you can use constraints to configure bounds and scale limits to completely 'freeze' the map.

    If you only want to disable user interaction, you also set a 'no-op' controller on the map. This is a controller that consumes all gesture events, without doing anything.

    Returns number

  • A property describing the currently enabled operations. Valid values are MapNavigator.ALL and MapNavigator.NONE. Set to MapNavigator.ALL by default.

    deprecated

    mapNavigator.enabledOperations has been deprecated.

    This property will only be respected by the deprecated MapNavigator methods. The new methods (pan, rotate, zoom and fit), will ignore enabledOperations.

    As a replacement, you can use constraints to configure bounds and scale limits to completely 'freeze' the map.

    If you only want to disable user interaction, you also set a 'no-op' controller on the map. This is a controller that consumes all gesture events, without doing anything.

    Parameters

    • operations: number

    Returns any

Methods

fit

  • Fits a specified area into a view using an animation. The map will be modified so that the area specified by the bounds-parameters is in the center.

    It is both possible to either maintain the map's current scale ratio, or have it adapt in order to obtain a perfect fit. The scale ratio is the ratio between the scale for the x-axis and the scale ratio of the y-axis.

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.fit(bounds, allowWarpXYAxis) has been deprecated. Use the new MapNavigator.fit(fitOptions instead). You can replace this call with the new equivalent fit:

    map.mapNavigator.fit({bounds: bounds, allowWarpXYAxis: allowWarpXYAxis, animate: true});

    Parameters

    • bounds: Bounds

      The area to show. It is interpreted as a 2D bounds (i.e. the depth will not be taken into account).

    • Optional allowWarpXYAxis: boolean

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

  • Performs a fit operation.

    Use this operation to ensure that the map covers a certain area.

    Note: For backwards compatibility, when a Bounds is passed instead of an options literal, the deprecated version of fit will be used.

    After the fit operation, the view extents will fit the extents of fitOptions.target. The map's rotation might be affected by the fit operation. It is not guaranteed that rotation will be preserved.

    Parameters

    Returns Promise<void>

    A promise that will be resolved after the fit operation has finished.

    Non-animated fit operations are synchronous and effective immediately. An already resolved Promise will be returned. In this case, you don't have to use the Promise callbacks to wait for the operation to be completed (but you can, this is useful when switching between animated and non-animated versions).

    For animated fit operations, the call is asynchronous. The returned Promise will be resolved when the fit animation has completely finished. If the fit animation is interrupted (for example, by another animation), the promise is rejected.

lookFrom

  • Positions the viewer at a given eye point. This method can be used to look around freely from a fixed position.

    This method will only perform an operation if the Map's reference (Map.reference) is a geocentric 3D reference (e.g. EPSG:4978). If the map is not a 3D map, this method will throw an error.

    Parameters

    • eyePoint: Point

      the point at which to put the eye point. The point can have any spatial reference.

    • yaw: number

      the desired yaw angle from the eye point to the reference point (in degrees). This is similar to turning your head left to right. 0 means looking north, and the degrees count clockwise.

    • pitch: number

      the desired pitch angle from the eye point to the reference point (in degrees). This value must be between -89 and 89 degrees. This is similar to nodding your head up and down. -89 means looking straight down, 0 is looking straight ahead to the horizon, and 89 is degrees is looking straight up.

    • roll: number

      the desired roll angle of the viewer around its line-of-sight axis (in degrees). This is similar to turning your entire head upside down (if you could). The rotation is clockwise.

    • Optional options: MapNavigatorLookFromOptions

      the options for the lookFrom operation

    Returns Promise<void>

    A promise that will be resolved after the lookFrom operation has finished.

    Non-animated lookFrom operations are synchronous and effective immediately. An already resolved Promise will be returned. In this case, you don't have to use the Promise callbacks to wait for the operation to be completed (but you can, this is useful when switching between animated and non-animated versions).

    For animated lookFrom operations, the call is asynchronous. The returned Promise will be resolved when the lookFrom animation has completely finished. If the lookFrom animation is interrupted (for example, by another animation), the promise is rejected.

pan

  • Performs a pan operation.

    Use this operation to:

    • center the map on a certain model or world location
    • shift the map in a certain direction by a certain amount in pixels or world units

    After the pan operation, targetLocation will be at toViewLocation.

    Parameters

    Returns Promise<void>

    A promise that will be resolved after the pan operation has finished.

    Non-animated pan operations are synchronous and effective immediately. An already resolved Promise will be returned. In this case, you don't have to use the Promise callbacks to wait for the operation to be completed (but you can, this is useful when switching between animated and non-animated versions).

    For animated pan operations, the call is asynchronous. The returned Promise will be resolved when the pan animation has completely finished. If the pan animation is interrupted (for example, by another animation), the promise is rejected.

panBy

  • (deltaX: number, deltaY: number): void
  • Scroll or pan the view by the given amount in pixel coordinates. This method has an immediate effect and will interrupt ongoing animations.

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.panBy(deltaX, deltaY) has been deprecated. Use the new MapNavigator.pan(panOptions) instead. You can replace this call with a pan call that pans the center of the view to an offsetted location:

    var centerOfView = createPoint(null, [map.viewSize[0] / 2, map.viewSize[1] / 2]);
    var offsetFromCenterOfView = centerOfView.copy();
    offsetFromCenterOfView.translate(deltaX, deltaY);
    map.mapNavigator.pan({targetLocation: centerOfView, toViewLocation: offsetFromCenterOfView});

    Parameters

    • deltaX: number

      the horizontal distance (in pixels).

    • deltaY: number

      the vertical distance (in pixels).

    Returns void

panTo

  • Perform an animated pan to the of the given bounded defined in the given geographic reference.

    This method differs from setCenter in the fact that panning is performed through a smooth animation, while the setCenter method immediately updates the map.

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.panTo(bounded) has been deprecated. Use the new MapNavigator.pan(panOptions) instead. You can replace this call with the new equivalent pan:

    map.mapNavigator.pan({targetLocation: bounded.bounds.focusPoint, animate: true});

    Parameters

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

rotate

  • Performs a rotate operation. Use this operation to:

    • rotate to a specific orientation angle (in some projections, this is a heading or azimuth)
    • rotate by a delta angle relative to the current rotation
    • adapt camera pitch in 3D

    If you rotate to a target angle, you cannot rotate with a delta and vice-versa.

    2D only options will be ignored in 3D (and vice-versa).

    Note that map rotation will be disabled (fixed to 0) in the following cases:

    • A navigation bounds constraint is set on the map (cfr. constraints)
    • Axes are configured on the map
    • There is a GoogleLayer present on the map

    Parameters

    Returns Promise<void>

    A promise that will be resolved after the rotate operation has finished.

    Non-animated rotate operations are synchronous and effective immediately. An already resolved Promise will be returned. In this case, you don't have to use the Promise callbacks to wait for the operation to be completed (but you can, this is useful when switching between animated and non-animated versions).

    For animated rotate operations, the call is asynchronous. The returned Promise will be resolved when the rotate animation has completely finished. If the rotate animation is interrupted (for example, by another animation), the promise is rejected.

setCenter

  • Position the map so that the given view point (in pixels) maps onto the given spatial coordinate. This method has an immediate effect and will interrupt ongoing animations.

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.setCenter() has been deprecated. Use the new MapNavigator.pan(panOptions) instead. You can replace this call with the new equivalent pan:

    map.mapNavigator.pan({targetLocation: spatialPoint, toViewLocation: viewPoint}));

    Parameters

    Returns void

setScale

  • (scale: number): void
  • (scale: number[]): void
  • Sets the scale of the map. This method has an immediate effect and will interrupt ongoing animations. Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.setScale() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({targetScale: scale});

    Parameters

    • scale: number

      the desired scale

    Returns void

  • Sets the scale of the map in a non uniform way. Non uniform: the scale to be applied on the X-axis can differ from the scale applied on the Y axis. Scale factors for each axis must be passed in the scale array.

    deprecated

    mapNavigator.setScale() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({targetScale: {x: scale[0], y: scale[1]}});

    Parameters

    • scale: number[]

      An array containing scale factors for each axis; First element in the array contains the scale factor for the X-axis, the second element the scale factor for the Y axis.

    Returns void

setScaleFixing

  • (scale: number, x: number, y: number): void
  • (scale: number[], x: number, y: number): void
  • Sets the scale on the map, while fixing to the given point in pixel coordinates. Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.setScaleFixing() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({targetScale: scale, location: createPoint(null, [x,y]});

    Parameters

    • scale: number

      the desired scale

    • x: number

      the x-coordinate to fix on

    • y: number

      the y-coordinate to fix on

    Returns void

  • Sets a non-uniform scale on the map, while fixing to the given point in pixel coordinates. Non uniform: the scale to be applied on the X-axis can differ from the scale applied on the Y axis. Scale factors for each axis must be applied in the scale array. Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.setScaleFixing() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({targetScale: {x: scale[0], y: scale[1]}, location: createPoint(null, [x,y]});

    Parameters

    • scale: number[]

      the desired scale factors in an array, one scale factor for each axis

    • x: number

      the x-coordinate to fix on

    • y: number

      the y-coordinate to fix on

    Returns void

zoom

  • Performs a zoom operation.

    Use this operation to:

    • zoom in or zoom out by a certain factor
    • set the scale of the map to a specific scale

    You must specify either a factor or a target scale, but you can not use both in the same zoom operation.

    Can be used for both uniform zooming (same x- and y-scale, commonly used on georeferenced maps) and non-uniform zooming (different x- and y-scale, commonly used for non-georeferenced maps).

    Parameters

    Returns Promise<void>

    A promise that will be resolved after the pan operation has finished.

    Non-animated zoom operations are synchronous and effective immediately. An already resolved Promise will be returned. In this case, you don't have to use the Promise callbacks to wait for the operation to be completed (but you can, this is useful when switching between animated and non-animated versions).

    For animated zoom operations, the call is asynchronous. The returned Promise will be resolved when the zoom animation has completely finished. If the zoom animation is interrupted (for example, by another animation), the promise is rejected.

zoomIn

  • Perform an animated zoom in (by a fixed amount).

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.zoomIn() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({factor: 2.0, animate: true});

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

zoomInFixing

  • (x: number, y: number): Promise<void>
  • Perform an animation zoom-in, fixing on the given view position (passed as x and y coordinates)

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.zoomInFixing() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({factor: 2.0, location: createPoint(null, [x, y]), animate: true});

    Parameters

    • x: number

      view x-coordinate

    • y: number

      view y-coordinate

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

zoomInFixingWithScaleFactor

  • (x: number, y: number, xScaleFactor: number, yScaleFactor: number): Promise<void>
  • Zoom in on the given view position, with the desired scale factors. Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.zoomInFixingWithScaleFactor() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({factor: {x: xScaleFactor, y: yScaleFactor}, location: createPoint(null, [x, y]), animate: true});

    Parameters

    • x: number

      view x-coordinate

    • y: number

      view y-coordinate

    • xScaleFactor: number

      the scale factor over the X axis to apply (for example, a value of 2 doubles the scale)

    • yScaleFactor: number

      the scale factor over the Y axis to apply (for example, a value of 2 doubles the scale)

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

zoomOut

  • Perform an animated zoom out (by a fixed amount).

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.zoomOut() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({factor: 0.5, animate: true});

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

zoomOutFixing

  • (x: number, y: number): Promise<void>
  • Perform an animated zoom-out, fixing on the given view position (passed as x and y coordinates)

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.zoomOutFixing() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({factor: 0.5, location: createPoint(null, [x, y]), animate: true});

    Parameters

    • x: number

      view x-coordinate

    • y: number

      view y-coordinate

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

zoomOutFixingWithScaleFactor

  • (x: number, y: number, xScaleFactor: number, yScaleFactor: number): Promise<void>
  • Zoom out on the given view position, with the desired scale factors.

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.zoomOutFixingWithScaleFactor() has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({factor: {x: 1 / xScaleFactor, y: 1 / yScaleFactor}, location: createPoint(null, [x, y]), animate: true});

    Parameters

    • x: number

      view x-coordinate

    • y: number

      view y-coordinate

    • xScaleFactor: number

      the scale factor over the X axis to apply (for example, a value of 2 halves the scale)

    • yScaleFactor: number

      the scale factor over the Y axis to apply (for example, a value of 2 halves the scale)

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

zoomTo

  • Perform an animated zoom so that the map has the desired scale.

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.zoomTo(scale) has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({targetScale: scale, animate: true});

    Parameters

    • scale: number

      the desired scale.

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

  • Perform an animated zoom so that the map has the desired, non-uniform scale. Non uniform: the scale to be applied on the X-axis can differ from the scale applied on the Y axis. Scale factors for each axis must be passed in the scale array.

    Note that this method will only have an effect if enabledOperations is set to ALL.

    deprecated

    mapNavigator.zoomTo(scale) has been deprecated. Use the new MapNavigator.zoom(zoomOptions) instead. You can replace this call with the new equivalent zoom:

    map.mapNavigator.zoom({targetScale: scale, animate: true});

    Parameters

    • scale: number[]

      The desired scales for each view axis.

    Returns Promise<void>

    A promise which represents the completion of the animation. The promise will be resolved when the animation has completed. The promise will be rejected when the animation is interrupted.

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Type alias with type parameter
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method