MapNavigator | LuciadRIA (2022.1.08)

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
zoom
rotate
fit

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

constructor

Properties

ALL
NONE

Accessors

Methods

Constructors

Private constructor

(): MapNavigator

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

get constraints(): MapNavigatorConstraints
set constraints(value: MapNavigatorConstraints): void

Returns the current constraints applied on the Map

Returns MapNavigatorConstraints
Sets constraints on the map

Parameters
- value: MapNavigatorConstraints
Returns any

defaults

get defaults(): MapNavigatorDefaults
set defaults(defaults: MapNavigatorDefaults): void

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
- defaults: MapNavigatorDefaults
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

(bounds: Bounds, allowWarpXYAxis?: boolean): Promise<void>
(fitOptions: MapNavigatorFitOptions): Promise<void>

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 fit operation. The promise will be resolved when the fit operation has completed. The promise will be rejected when the (animated) fit operation 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
- fitOptions: MapNavigatorFitOptions
  
  The options for the fit operation.
Returns Promise<void>

A promise that will be resolved after the fit operation has finished. You have to wait for the promise to resolve, even for non-animated fits.
For animated fits, 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

(eyePoint: Point, yaw: number, pitch: number, roll: number, options?: MapNavigatorLookFromOptions): Promise<void>

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. You have to wait for the promise to resolve, even for non-animated lookFrom operations.
For animated lookFrom operations, 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

(panOptions: MapNavigatorPanOptions): Promise<void>

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
- panOptions: MapNavigatorPanOptions
  
  The options for the pan operation
Returns Promise<void>

A promise that will be resolved after the pan operation has finished. You have to wait for the promise to resolve, even for non-animated pan operations.
For animated panning, 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

(bounded: Bounded): Promise<void>

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
- bounded: Bounded
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

(rotateOptions: MapNavigatorRotateOptions): Promise<void>

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
- rotateOptions: MapNavigatorRotateOptions
  
  The options for the rotate operation
Returns Promise<void>

A promise that will be resolved after the rotate operation has finished. You have to wait for the promise to resolve, even for non-animated rotate operations.
For animated rotations, 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

(viewPoint: Point, spatialPoint: Point): void

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
- viewPoint: Point
- spatialPoint: Point
Returns void

setScale

(scale: number): void
(scale: [number, 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, 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, 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, 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

(zoomOptions: MapNavigatorZoomOptions): Promise<void>

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
- zoomOptions: MapNavigatorZoomOptions
  
  The options for the zoom operation
Returns Promise<void>

A promise that will be resolved after the zoom operation has finished. You have to wait for the promise to resolve, even for non-animated zoom operations.
For animated zooming, the returned Promise will be resolved when the pan animation has completely finished. If the zoom animation is interrupted (for example, by another animation), the promise is rejected.

zoomIn

(): Promise<void>

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

(): Promise<void>

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

(scale: number): Promise<void>
(scale: [number, number]): Promise<void>

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, 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

Hierarchy

Overview

Constructors

Properties

Accessors

Methods

Constructors

Private constructor

Returns MapNavigator

Properties

Static ALL

Static NONE

Accessors

constraints

Returns MapNavigatorConstraints

Parameters

value: MapNavigatorConstraints

Returns any

defaults

Returns MapNavigatorDefaults

Parameters

defaults: MapNavigatorDefaults

Returns any

enabledOperations

Returns number

Parameters

operations: number

Returns any

Methods

fit

Parameters

bounds: Bounds

Optional allowWarpXYAxis: boolean

Returns Promise<void>

Parameters

fitOptions: MapNavigatorFitOptions

Returns Promise<void>

lookFrom

Parameters

eyePoint: Point

yaw: number

pitch: number

roll: number

Optional options: MapNavigatorLookFromOptions

Returns Promise<void>

pan

Parameters

panOptions: MapNavigatorPanOptions

Returns Promise<void>

panBy

Parameters

deltaX: number

deltaY: number

Returns void

panTo

Parameters

bounded: Bounded

Returns Promise<void>

rotate

Parameters

rotateOptions: MapNavigatorRotateOptions

Returns Promise<void>

setCenter

Parameters

viewPoint: Point

spatialPoint: Point

Returns void

setScale

Parameters

scale: number

Returns void

Parameters

scale: [number, number]

Returns void

setScaleFixing

Parameters

scale: number

x: number

y: number

Returns void