luciad::MapNavigator Class Reference

Class that offers functionality to navigate around the globe. More...

#include <luciad/maps/MapNavigator.h>

Classes
class	AboveConstraintOptions
	Option to configure the navigation constraint to keep the camera above the terrain. More...
class	BoundsConstraintOptions
	Options to configure the constraint to restrict the navigation to specific bounds. More...
class	FitAction
	Class that allows to build a fit action and apply it, either directly or using an animation. More...
class	PanAction
	Class that allows to build a pan action and apply it, either directly or using an animation. More...
class	PitchConstraintOptions
	Options to configure the constraint to restrict the pitch (tilt) of the camera. More...
class	RotateAction
	Class that allows to build a rotate action and apply it, either directly or using an animation. More...
class	ScaleConstraintOptions
	Options to configure the scale constraint to restrict the camera zooming. More...
class	ZoomAction
	Class that allows to build a zoom action and apply it, either directly or using an animation. More...

Public Member Functions
	~MapNavigator ()
void	cancel ()
	Cancels all ongoing navigate actions that were started using this MapNavigator. More...
AboveConstraintOptions &	getAboveConstraint ()
	Returns the above constraint options for this MapNavigator. More...
const AboveConstraintOptions &	getAboveConstraint () const
	Returns the above constraint options for this MapNavigator. More...
BoundsConstraintOptions &	getBoundsConstraint ()
	Returns the constraint that can be used to restrict navigation in such a way that you can not see anything beyond the limit bounds. More...
const BoundsConstraintOptions &	getBoundsConstraint () const
	Returns the constraint that can be used to restrict navigation in such a way that you can not see anything beyond the limit bounds. More...
PitchConstraintOptions &	getPitchConstraint ()
	Returns the constraint that can be used to restrict the pitch (tilt) of the camera on a 3D map. More...
const PitchConstraintOptions &	getPitchConstraint () const
	Returns the constraint that can be used to restrict the pitch (tilt) of the camera on a 3D map. More...
ScaleConstraintOptions &	getScaleConstraint ()
	Returns the scale constraint options that can be used used to restrict the map to a min/max scale. More...
const ScaleConstraintOptions &	getScaleConstraint () const
	Returns the scale constraint options that can be used used to restrict the map to a min/max scale. More...
FitAction	newFitAction () const
	Creates an object that allows to configure fit parameters, and apply them, either directly or using an animation. More...
PanAction	newPanAction () const
	Creates an object that allows to configure pan parameters, and apply them, either directly or using an animation. More...
RotateAction	newRotateAction () const
	Creates an object that allows to configure rotate parameters, and apply them, either directly or using an animation. More...
ZoomAction	newZoomAction () const
	Creates an object that allows to configure zoom parameters, and apply them, either directly or using an animation. More...

Detailed Description

Class that offers functionality to navigate around the globe.

It offers high-level navigation capabilities, built on top of the more low-level camera API.

See documentation of the following classes for example usages:

• MapNavigator::PanAction
• MapNavigator::ZoomAction
• MapNavigator::RotateAction
• MapNavigator::FitAction

This class animates the camera by submitting IAnimations to the map's luciad::Map::getAnimationManager, or by registering Map::IRendererCallback instance. These can be canceled using the MapNavigator::cancel method. Note that starting a new navigate action using MapNavigator will automatically cancel any ongoing navigate actions.

The following navigation constraints can be used to restrict navigation:

• above: keeps the camera above terrain.
• bounds: keeps the camera inside the defined bounds.
• scale: prevents the camera from zooming in or out too far.
• pitch: restricts the pitch (tilt) of the camera

If you use the map's underlying Camera directly, the constraints are not applied. In that case, it's the API user's responsibility to restrict the camera movement.

See also the related articles on

• map navigation.
• map navigation constraints.

Constructor & Destructor Documentation

~MapNavigator()

luciad::MapNavigator::~MapNavigator

(

)

Member Function Documentation

cancel()

void luciad::MapNavigator::cancel

(

)

Cancels all ongoing navigate actions that were started using this MapNavigator.

This includes stopping all animations and all input-based navigate actions. The latter will start ignoring input after this method is called.

Since

2022.1

getAboveConstraint() [1/2]

AboveConstraintOptions & luciad::MapNavigator::getAboveConstraint

(

)

Returns the above constraint options for this MapNavigator.

The above constraint can be used to constrain the camera to remain above the terrain and/or mesh in a 3D map. This constraint is only applicable to 3D maps.

By default, the above constraint is enabled with a minimum altitude of 20.

Example usage:

  // Change the limit
  map->getMapNavigator().getAboveConstraint().setMinAltitude(123.0);

 
  // Disable the constraint
  map->getMapNavigator().getAboveConstraint().setEnabled(false);

Returns

the above constraint options

Since

2021.1

getAboveConstraint() [2/2]

const AboveConstraintOptions & luciad::MapNavigator::getAboveConstraint

(

)

const

Returns the above constraint options for this MapNavigator.

The above constraint can be used to constrain the camera to remain above the terrain and/or mesh in a 3D map. This constraint is only applicable to 3D maps.

By default, the above constraint is enabled with a minimum altitude of 20.

Example usage:

  // Change the limit
  map->getMapNavigator().getAboveConstraint().setMinAltitude(123.0);

 
  // Disable the constraint
  map->getMapNavigator().getAboveConstraint().setEnabled(false);

Returns

the above constraint options

Since

2021.1

getBoundsConstraint() [1/2]

BoundsConstraintOptions & luciad::MapNavigator::getBoundsConstraint

(

)

Returns the constraint that can be used to restrict navigation in such a way that you can not see anything beyond the limit bounds.

By default this constraint is disabled.

This constraint only works in 2D.

A conflict may occur when you use both a scale and a bounds constraint. This can happen when, for example, the maxZoomedIn 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 scale constraint. 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 and not both.

If this constraint is enabled (and if valid bounds are provided), map rotation is not possible.

The following example configures the bounds constraint with bounds and a padding of 5 pixels.

  auto wgs84 = *CoordinateReferenceProvider::create("EPSG:4326");
  auto bounds = Bounds(wgs84, Coordinate(50.0, 4.0), 20.0, 20.0, 0.0);
  auto& boundsConstraint = map->getMapNavigator().getBoundsConstraint();
  boundsConstraint.setEnabled(true);
  boundsConstraint.setBounds(bounds);
  boundsConstraint.setPadding(5.0);

Returns

the limit bounds constraint options

Since

2021.1

getBoundsConstraint() [2/2]

const BoundsConstraintOptions & luciad::MapNavigator::getBoundsConstraint

(

)

const

Returns the constraint that can be used to restrict navigation in such a way that you can not see anything beyond the limit bounds.

By default this constraint is disabled.

This constraint only works in 2D.

A conflict may occur when you use both a scale and a bounds constraint. This can happen when, for example, the maxZoomedIn 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 scale constraint. 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 and not both.

If this constraint is enabled (and if valid bounds are provided), map rotation is not possible.

The following example configures the bounds constraint with bounds and a padding of 5 pixels.

  auto wgs84 = *CoordinateReferenceProvider::create("EPSG:4326");
  auto bounds = Bounds(wgs84, Coordinate(50.0, 4.0), 20.0, 20.0, 0.0);
  auto& boundsConstraint = map->getMapNavigator().getBoundsConstraint();
  boundsConstraint.setEnabled(true);
  boundsConstraint.setBounds(bounds);
  boundsConstraint.setPadding(5.0);

Returns

the limit bounds constraint options

Since

2021.1

getPitchConstraint() [1/2]

PitchConstraintOptions & luciad::MapNavigator::getPitchConstraint

(

)

Returns the constraint that can be used to restrict the pitch (tilt) of the camera on a 3D map.

The constraint is always enabled, but its default values don't impose restrictions on the pitch of the camera.

This constraint only works in 3D.

The following example sets the min and max pitch limits.

  map->getMapNavigator().getPitchConstraint().setMinPitch(-45.0);
  map->getMapNavigator().getPitchConstraint().setMaxPitch(45.0);

Returns

the pitch constraint options

Since

2021.1

getPitchConstraint() [2/2]

const PitchConstraintOptions & luciad::MapNavigator::getPitchConstraint

(

)

const

Returns the constraint that can be used to restrict the pitch (tilt) of the camera on a 3D map.

The constraint is always enabled, but its default values don't impose restrictions on the pitch of the camera.

This constraint only works in 3D.

The following example sets the min and max pitch limits.

  map->getMapNavigator().getPitchConstraint().setMinPitch(-45.0);
  map->getMapNavigator().getPitchConstraint().setMaxPitch(45.0);

Returns

the pitch constraint options

Since

2021.1

getScaleConstraint() [1/2]

ScaleConstraintOptions & luciad::MapNavigator::getScaleConstraint

(

)

Returns the scale constraint options that can be used used to restrict the map to a min/max scale.

By default the scale constraint is configured not to impose limitations.

This constraint only works in 2D.

A conflict may occur when you use both a scale and a bounds constraint. This can happen when, for example, the maxZoomedIn 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 scale constraint. 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 and not both.

The following example shows how to configure the scale constraint:

  // Limit zooming in
  map->getMapNavigator().getScaleConstraint().setZoomInLimit(MapScale::fromDenominator(1000.0));

Returns

the scale constraint options

Since

2021.1

getScaleConstraint() [2/2]

const ScaleConstraintOptions & luciad::MapNavigator::getScaleConstraint

(

)

const

Returns the scale constraint options that can be used used to restrict the map to a min/max scale.

By default the scale constraint is configured not to impose limitations.

This constraint only works in 2D.

A conflict may occur when you use both a scale and a bounds constraint. This can happen when, for example, the maxZoomedIn 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 scale constraint. 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 and not both.

The following example shows how to configure the scale constraint:

  // Limit zooming in
  map->getMapNavigator().getScaleConstraint().setZoomInLimit(MapScale::fromDenominator(1000.0));

Returns

the scale constraint options

Since

2021.1

newFitAction()

FitAction luciad::MapNavigator::newFitAction

(

)

const

Creates an object that allows to configure fit parameters, and apply them, either directly or using an animation.

Returns

an object that allows to configure fit parameters, and apply them, either directly or using an animation.

newPanAction()

PanAction luciad::MapNavigator::newPanAction

(

)

const

Creates an object that allows to configure pan parameters, and apply them, either directly or using an animation.

Returns

an object that allows to configure pan parameters, and apply them, either directly or using an animation.

newRotateAction()

RotateAction luciad::MapNavigator::newRotateAction

(

)

const

Creates an object that allows to configure rotate parameters, and apply them, either directly or using an animation.

Returns

an object that allows to configure rotate parameters, and apply them, either directly or using an animation.

newZoomAction()

ZoomAction luciad::MapNavigator::newZoomAction

(

)

const

Creates an object that allows to configure zoom parameters, and apply them, either directly or using an animation.

Returns

an object that allows to configure zoom parameters, and apply them, either directly or using an animation.