A map for showing geo-spatial data. More...

#include <luciad/maps/Map.h>

Classes
class	Builder
	Builder to create a Map. More...

class	FeatureQuery
	A query specifies which features you are interested in. More...

class	HeightProvider
	A height provider based on the map layers order and visibility. More...

class	IRendererCallback
	This callback can be used to execute tasks on the render thread right before or right after the Map is painted by `Map::Renderer`. More...

class	Renderer
	The Map renderer. More...

class	ViewMapTransformation
	This class allows to transform between view (pixel coordinates on the screen) and map coordinates. More...

Public Types
enum class	LocationMode { ClosestSurface , Terrain }
	Used to determine how the Map::getViewToMapTransformation method determines the point in Map coordinates that corresponds to a given view location. More...

Public Member Functions
virtual	~Map ()=default

virtual void	addObserver (std::shared_ptr< IMapObserver > observer)=0
	Adds an observer that allows to receive change events from this map. More...

virtual void	addRendererCallback (std::shared_ptr< IRendererCallback > rendererCallback)=0
	Adds the given callback to the Map. More...

virtual void	deliverNotifications ()=0
	Delivers any pending notifications. More...

virtual void	destroy ()=0
	Disposes the Map. More...

virtual const AnimationManager &	getAnimationManager () const =0
	Returns the `AnimationManager` attached to this map. More...

virtual AnimationManager &	getAnimationManager ()=0
	Returns the `AnimationManager` attached to this map. More...

virtual Color	getBackgroundColor () const =0
	Returns the background color of the map. More...

virtual std::shared_ptr< Camera >	getCamera () const =0
	Returns the camera used by the renderer. More...

virtual std::shared_ptr< IController >	getController () const =0
	Returns the active controller of the map. More...

virtual MouseCursor	getCursor ()=0
	Returns the cursor of the map. More...

virtual double	getDisplayScale () const =0
	Returns the display scale used to render the map. More...

virtual double	getDpi () const =0
	Returns the DPI value used to calculate map scales. More...

virtual const GraphicsEffects &	getEffects () const =0
	Returns the graphics effects instance that can apply graphics effects on this map. More...

virtual GraphicsEffects &	getEffects ()=0
	Returns the graphics effects instance that can apply graphics effects on this map. More...

virtual const FeatureStateManager &	getFeatureStateManager () const =0
	Returns the FeatureStateManager that keeps track of the feature state (for example selection) for this map. More...

virtual FeatureStateManager &	getFeatureStateManager ()=0
	Returns the FeatureStateManager that keeps track of the feature state (for example selection) for this map. More...

virtual double	getHeight () const =0
	Returns the height of the Map in device independent pixels. More...

virtual const Map::HeightProvider &	getHeightProvider () const =0
	Returns the map based height provider. More...

virtual std::shared_ptr< LayerList >	getLayerList () const =0
	Returns the list of Layer instances that are visualized in this Map. More...

virtual MapNavigator &	getMapNavigator () const =0
	Returns the `MapNavigator` instance that can manipulate the `Camera` of this map. More...

virtual std::shared_ptr< CoordinateReference >	getReference () const =0
	Returns the reference of this Map. More...

virtual Renderer &	getRenderer () const =0
	Returns the renderer for this Map. More...

virtual const ViewMapTransformation &	getViewMapTransformation () const =0
	Returns the transformation that can transform view coordinates to map coordinates and vice-versa. More...

virtual double	getWidth () const =0
	Returns the width of the Map in device independent pixels. More...

virtual bool	is3D () const =0
	Returns whether this Map is visualized in 3D. More...

virtual void	queryFeatures (const Map::FeatureQuery &query, const std::shared_ptr< IMapQueryFeaturesCallback > &callback) const =0
	Queries the features under the given pixel bounds, and passes the result to the given callback. More...

virtual void	removeObserver (const std::shared_ptr< IMapObserver > &observer)=0
	Removes the given observer. More...

virtual void	removeRendererCallback (const std::shared_ptr< IRendererCallback > &rendererCallback)=0
	Removes the given callback from the Map. More...

virtual void	resize (double width, double height)=0
	To be called when the host widget resizes, so that the map can adapt its camera, and graphics related resources. More...

virtual void	setBackgroundColor (luciad::Color color)=0
	Sets the background color of the map. More...

virtual void	setCamera (const std::shared_ptr< Camera > &camera)=0
	Sets the camera used by the renderer. More...

virtual void	setController (std::shared_ptr< IController > controller)=0
	Sets the active controller of the map. More...

virtual void	setCursor (MouseCursor cursor)=0
	Sets the cursor of the map. More...

virtual void	setDisplayScale (double displayScale)=0
	Sets the display scale used to render the map. More...

virtual void	setDpi (double dpi)=0
	Sets the DPI value used to calculate map scales. More...

virtual void	setMapInvalidationCallback (std::shared_ptr< IInvalidationCallback > mapInvalidationCallback)=0
	Sets the given IInvalidationCallback. More...

virtual void	setMouseCursorCallback (std::shared_ptr< IMouseCursorCallback > mouseCursorCallback)=0
	Sets the given IMouseCursorCallback. More...

Static Public Member Functions
static Builder	newBuilder ()
	Creates a new builder to create a map. More...

static const std::string &	propertyBackgroundColor ()
	Property name for the `MapEvent` that is fired as a result of changing the map's background color. More...

static const std::string &	propertyCamera ()
	Property name for the `MapEvent` that is fired as a result of changing the map's camera. More...

static const std::string &	propertyController ()
	Property name for the `MapEvent` that is fired as a result of changing the map's controller. More...

static const std::string &	propertyDisplayScale ()
	Property name for the `MapEvent` that is fired as a result of changing the map's display scale. More...

static const std::string &	propertyDpi ()
	Property name for the `MapEvent` that is fired as a result of changing the map's dpi. More...

Detailed Description

A map for showing geo-spatial data.

Data

Data can be added to the map using its LayerList. For rendering, all data is transformed to a common coordinate reference for display. As a consequence, many different types of data can be visualized at the same time: raster data (imagery and elevation) and vector data (Feature instances).

The following article shows, among others, how you can add data to the map: Create your first map application

Navigation

You can navigate the map using MapNavigator. If you want to fully customize map navigation, you can set the Camera directly.

Member Enumeration Documentation

◆ LocationMode

enum class luciad::Map::LocationMode

strong

Used to determine how the Map::getViewToMapTransformation method determines the point in Map coordinates that corresponds to a given view location.

Enumerator
ClosestSurface	Defines the view-to-map transformation mode where, for a given view point (pixels), a corresponding position (in Map coordinates) on a closest surface is provided.
Terrain	Defines the view-to-map transformation mode where, for a given view point (pixels) a corresponding position (in Map coordinates) on the terrain is provided.

Constructor & Destructor Documentation

◆ ~Map()

virtual luciad::Map::~Map ( )

virtualdefault

Member Function Documentation

◆ addObserver()

virtual void luciad::Map::addObserver ( std::shared_ptr< IMapObserver > observer )

pure virtual

Adds an observer that allows to receive change events from this map.

Adding the same observer twice is forbidden, and will cause an exception to be thrown.

Parameters

observer an observer.

Exceptions

luciad::InvalidArgumentException	when the observer was already added.
luciad::NullArgumentException	when the observer is `nullptr`.

Since: 2023.1

◆ addRendererCallback()

virtual void luciad::Map::addRendererCallback ( std::shared_ptr< IRendererCallback > rendererCallback )

pure virtual

Adds the given callback to the Map.

After calling this method, the Map::Renderer::paint will start calling the given callback instance.

Parameters

rendererCallback a renderer callback instance. Cannot be nullptr.

Exceptions

NullArgumentException when the renderer call back is nullptr.

Since: 2021.1

◆ deliverNotifications()

virtual void luciad::Map::deliverNotifications ( )

pure virtual

Delivers any pending notifications.

The map buffers up notifications for delivery to the user on the UI thread. However, as the map does not have a way to schedule any actions on the UI thread, the user himself should call this function on the appropriate thread. For example, this could be done when the UI toolkit or framework indicates that the widget containing this map should be updated.

◆ destroy()

virtual void luciad::Map::destroy ( )

pure virtual

Disposes the Map.

This method cleans all observers and controllers from the map. This method needs to be called before the Map instance is deleted. If this method is not called, some objects will keep a reference on the map, preventing it to be deleted properly.

Since: 2020.1

◆ getAnimationManager() [1/2]

virtual const AnimationManager & luciad::Map::getAnimationManager ( ) const

pure virtual

Returns the AnimationManager attached to this map.

Important notice regarding multi-threading:

You can start and stop animations with the AnimationManager from the UI thread.
The onStart/onUpdate/onStop methods of IAnimation will be invoked from the render thread. Because of this, animations are for example suitable to animate and update the map's camera.

See the related article: Threading rules for the Map

Returns: the AnimationManager attached to this map.

Since: 2021.1

◆ getAnimationManager() [2/2]

virtual AnimationManager & luciad::Map::getAnimationManager ( )

pure virtual

Returns the AnimationManager attached to this map.

Important notice regarding multi-threading:

You can start and stop animations with the AnimationManager from the UI thread.
The onStart/onUpdate/onStop methods of IAnimation will be invoked from the render thread. Because of this, animations are for example suitable to animate and update the map's camera.

See the related article: Threading rules for the Map

Returns: the AnimationManager attached to this map.

Since: 2021.1

◆ getBackgroundColor()

virtual Color luciad::Map::getBackgroundColor ( ) const

pure virtual

Returns the background color of the map.

Returns: the color that is used to render the map background.

Since: 2020.1

◆ getCamera()

virtual std::shared_ptr< Camera > luciad::Map::getCamera ( ) const

pure virtual

Returns the camera used by the renderer.

You can call this method on any thread.

Warning: this method returns the camera instance that was last used by the map renderer. This means that if you set the camera on a different thread than the render thread, a call to get the camera immediately after will not necessarily result in the same camera. See the threading article for a more detailed explanation.

Returns: the camera currently used by the renderer.

See also: setCamera for more information.

Since: 2021.1

◆ getController()

virtual std::shared_ptr< IController > luciad::Map::getController ( ) const

pure virtual

Returns the active controller of the map.

No default behavior is set.

Returns: nullptr if no controller has been set.

◆ getCursor()

virtual MouseCursor luciad::Map::getCursor ( )

pure virtual

Returns the cursor of the map.

The default value is MouseCursor::defaultCursor.

See also: Map::setCursor

Since: 2020.1

◆ getDisplayScale()

virtual double luciad::Map::getDisplayScale ( ) const

pure virtual

Returns the display scale used to render the map.

Returns: the current display scale, will be 1.0 if setDisplayScale has never been called

Since: 2022.0

◆ getDpi()

virtual double luciad::Map::getDpi ( ) const

pure virtual

Returns the DPI value used to calculate map scales.

Returns: the current dpi value.

Since: 2022.0

◆ getEffects() [1/2]

virtual const GraphicsEffects & luciad::Map::getEffects ( ) const

pure virtual

Returns the graphics effects instance that can apply graphics effects on this map.

Have a look at GraphicsEffects for a list of effects that are available.

Returns: the graphics effects instance that can apply graphics effects on this map.

Since: 2022.1

◆ getEffects() [2/2]

virtual GraphicsEffects & luciad::Map::getEffects ( )

pure virtual

Returns the graphics effects instance that can apply graphics effects on this map.

Have a look at GraphicsEffects for a list of effects that are available.

Returns: the graphics effects instance that can apply graphics effects on this map.

Since: 2022.1

◆ getFeatureStateManager() [1/2]

virtual const FeatureStateManager & luciad::Map::getFeatureStateManager ( ) const

pure virtual

Returns the FeatureStateManager that keeps track of the feature state (for example selection) for this map.

Apart from inspecting the feature state, you can use the returned object to change the feature state.

Returns: the FeatureStateManager that keeps track of the feature state for this map.

◆ getFeatureStateManager() [2/2]

virtual FeatureStateManager & luciad::Map::getFeatureStateManager ( )

pure virtual

Returns the FeatureStateManager that keeps track of the feature state (for example selection) for this map.

Apart from inspecting the feature state, you can use the returned object to change the feature state.

Returns: the FeatureStateManager that keeps track of the feature state for this map.

◆ getHeight()

virtual double luciad::Map::getHeight ( ) const

pure virtual

Returns the height of the Map in device independent pixels.

Returns: the height of the Map in device independent pixels.

◆ getHeightProvider()

virtual const Map::HeightProvider & luciad::Map::getHeightProvider ( ) const

pure virtual

Returns the map based height provider.

Returns: the map based height provider.

Since: 2023.0

◆ getLayerList()

virtual std::shared_ptr< LayerList > luciad::Map::getLayerList ( ) const

pure virtual

Returns the list of Layer instances that are visualized in this Map.

The methods offered on this class can be used to add/move/remove layers.

Returns: the list of Layer instances that are visualized in this Map.

◆ getMapNavigator()

virtual MapNavigator & luciad::Map::getMapNavigator ( ) const

pure virtual

Returns the MapNavigator instance that can manipulate the Camera of this map.

Returns: the MapNavigator instance that can manipulate the Camera of this map.

Since: 2021.1

◆ getReference()

virtual std::shared_ptr< CoordinateReference > luciad::Map::getReference ( ) const

pure virtual

Returns the reference of this Map.

This reference determines how the Map is visualized. When a projected (2D) reference is used, all data on the map is painted in this reference. When a (3D) geocentric reference is used, the Map is painted in 3D, and all data is pointed on the globe.

Returns: the reference of this Map.

◆ getRenderer()

virtual Renderer & luciad::Map::getRenderer ( ) const

pure virtual

Returns the renderer for this Map.

The Renderer owns the OpenGL resources related to this Map. It can only be interacted with while the OpenGL context is current.

Returns: the renderer for this Map.

◆ getViewMapTransformation()

virtual const ViewMapTransformation & luciad::Map::getViewMapTransformation ( ) const

pure virtual

Returns the transformation that can transform view coordinates to map coordinates and vice-versa.

Returns: the view <> map transformation.

◆ getWidth()

virtual double luciad::Map::getWidth ( ) const

pure virtual

Returns the width of the Map in device independent pixels.

Returns: the width of the Map in device independent pixels.

◆ is3D()

virtual bool luciad::Map::is3D ( ) const

pure virtual

Returns whether this Map is visualized in 3D.

Currently, this will only be true if the map reference is geocentric.

Having a 2D map limits the navigation, for example the camera can not be tilted and will always be top-down.

Currently, 3D maps always use a perspective camera and 2D maps always use an orthographic camera.

Returns: whether this Map is visualized in 3D.

Since: 2021.1

◆ newBuilder()

static Builder luciad::Map::newBuilder ( )

static

Creates a new builder to create a map.

Returns: a new builder to create a map.

◆ propertyBackgroundColor()

static const std::string & luciad::Map::propertyBackgroundColor ( )

static

Property name for the MapEvent that is fired as a result of changing the map's background color.

See also: setBackgroundColor

Since: 2023.1

◆ propertyCamera()

static const std::string & luciad::Map::propertyCamera ( )

static

Property name for the MapEvent that is fired as a result of changing the map's camera.

See also: setCamera

Since: 2023.1

◆ propertyController()

static const std::string & luciad::Map::propertyController ( )

static

Property name for the MapEvent that is fired as a result of changing the map's controller.

See also: setController

Since: 2023.1

◆ propertyDisplayScale()

static const std::string & luciad::Map::propertyDisplayScale ( )

static

Property name for the MapEvent that is fired as a result of changing the map's display scale.

See also: setDisplayScale

Since: 2023.1

◆ propertyDpi()

static const std::string & luciad::Map::propertyDpi ( )

static

Property name for the MapEvent that is fired as a result of changing the map's dpi.

See also: setDpi

Since: 2023.1

◆ queryFeatures()

virtual void luciad::Map::queryFeatures	(	const Map::FeatureQuery &	query,
		const std::shared_ptr< IMapQueryFeaturesCallback > &	callback
	)		const

pure virtual

Queries the features under the given pixel bounds, and passes the result to the given callback.

All visible layers are taken into account. The features are sorted using the following criteria:

3D:

Labels
Top Most feature (unless draped)
Layer order
Feature Z order in the layer
Unspecified Order

2D:

Labels
Layer order
Feature Z order in the layer
Unspecified Order

It is possible that the same feature appears multiple times in the result list, once for each part of the feature. When a feature is for example painted using 2 draw calls, all 2 parts of the feature can be returned if they are hit. A typical example is a feature is painted using both a geometry on the map and a label. It is up to the caller of this method to filter out duplicate feature hits if needed.

Parameters

query	the feature query containing the parameters to use to query the visible features
callback	a callback which can handle the result of the query operation. Cannot be `nullptr`.

Exceptions

NullArgumentException when the call back is nullptr.

◆ removeObserver()

virtual void luciad::Map::removeObserver ( const std::shared_ptr< IMapObserver > & observer )

pure virtual

Removes the given observer.

If the given observer was never added, an exception is thrown.

Parameters

observer an observer.

Exceptions

luciad::InvalidArgumentException	when the observer is not known.
luciad::NullArgumentException	when the observer is `nullptr`.

Since: 2023.1

◆ removeRendererCallback()

virtual void luciad::Map::removeRendererCallback ( const std::shared_ptr< IRendererCallback > & rendererCallback )

pure virtual

Removes the given callback from the Map.

After calling this method, the Map::Renderer::paint will stop calling the given callback instance.

Parameters

rendererCallback a renderer callback instance. Cannot be nullptr.

Exceptions

NullArgumentException when the renderer call back is nullptr.

Since: 2021.1

◆ resize()

virtual void luciad::Map::resize	(	double	width,
		double	height
	)

pure virtual

To be called when the host widget resizes, so that the map can adapt its camera, and graphics related resources.

Parameters

width	The new map's width expressed in device independent pixels.
height	The new map's height expressed in device independent pixels.

Exceptions

luciad::InvalidArgumentException when the width and/or the height is smaller than or equal to 0.

◆ setBackgroundColor()

virtual void luciad::Map::setBackgroundColor ( luciad::Color color )

pure virtual

Sets the background color of the map.

Parameters

color the new background color.

Since: 2021.1

◆ setCamera()

virtual void luciad::Map::setCamera ( const std::shared_ptr< Camera > & camera )

pure virtual

Sets the camera used by the renderer.

This method is only needed when you want to navigate in a different way than using MapNavigator.

You can call this method on any thread, but its behavior is slightly different:

when called on the render thread, the camera is immediately updated. You can for example get access to the render thread using the animation manager, which performs animation updated on the render thread.
when called on an other thread, the camera is updated on the next repaint. This is done to prevent camera changes while painting the map.

See the threading article for a more detailed explanation on the threading behavior.

Parameters

camera the new camera. Cannot be nullptr.

Exceptions

NullArgumentException when the camera is nullptr.

Since: 2021.1

◆ setController()

virtual void luciad::Map::setController ( std::shared_ptr< IController > controller )

pure virtual

Sets the active controller of the map.

This activates a controller, so that it can interact with the map. When a controller is set, the map will call luciad::IController::onActivate to let the controller know it is activated. The previous controller if present will first receive a call to luciad::IController::onDeactivate.

Parameters

controller The new active controller. If nullptr is given, that will only deactivate the previous one. Given that, no further interaction will be possible on the map until a controller is set again.

◆ setCursor()

virtual void luciad::Map::setCursor ( MouseCursor cursor )

pure virtual

Sets the cursor of the map.

Changing the cursor triggers a call to the mouse cursor callback if set.

Parameters

cursor the new cursor.

See also: Map::setMouseCursorCallback

Since: 2020.1

◆ setDisplayScale()

virtual void luciad::Map::setDisplayScale ( double displayScale )

pure virtual

Sets the display scale used to render the map.

Specify the display scale to allow the renderer to scale the graphics on high DPI displays.

display scale > 1: all features are enlarged
display scale < 1: all features are made smaller
display scale == 1: all features remain unscaled

When a feature is scaled by the display scale, it means that pixel distances are scale. For example:

the icon size on the screen is scaled
line widths change

This method must be called every time the display or its display scale changes to ensure proper rendering.

You can call this method on any thread, but its behavior is slightly different:

when called on the render thread, the DPI is immediately updated.
when called on an other thread, the DPI will be updated on the next repaint.

See the threading article for a more detailed explanation on the threading behavior.

The default is 1.0;

Parameters

displayScale the display scale. A value of 1.0 corresponds with a display scale of 100%.

Since: 2022.0

◆ setDpi()

virtual void luciad::Map::setDpi ( double dpi )

pure virtual

Sets the DPI value used to calculate map scales.

By default, the map uses the default DPI of your platform (96 on Windows/Linux, 72 on MacOS, 160 on Android). The DPI value should be set to the physical DPI value of the display to get accurate results.

You can call this method on any thread, but its behavior is slightly different:

when called on the render thread, the DPI is immediately updated.
when called on an other thread, the DPI will be updated on the next repaint.

See the threading article for a more detailed explanation on the threading behavior.

Parameters

dpi	the dpi value

Since: 2022.0

◆ setMapInvalidationCallback()

virtual void luciad::Map::setMapInvalidationCallback ( std::shared_ptr< IInvalidationCallback > mapInvalidationCallback )

pure virtual

Sets the given IInvalidationCallback.

This callback is called when the map has changed, and needs to be repainted. Can be nullptr. The callback is owned by the calling code, i.e. typically code that integrates the Map in a UI framework. Beware that this callback should not call (directly or indirectly) the map (for example Map::paint) because it can be called on any thread.

Parameters

mapInvalidationCallback a callback that is called when the map has changed.

◆ setMouseCursorCallback()

virtual void luciad::Map::setMouseCursorCallback ( std::shared_ptr< IMouseCursorCallback > mouseCursorCallback )

pure virtual

Sets the given IMouseCursorCallback.

This callback is called when the map's cursor has changed. Can be nullptr. The callback is owned by the calling code, i.e. typically code that integrates the Map in a UI framework. Beware that this callback should not call (directly or indirectly) the map (for example Map::paint) because it can be called on any thread.

Parameters

mouseCursorCallback a callback that is called when the map has changed.

Since: 2020.1

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ LocationMode

Constructor & Destructor Documentation

◆ ~Map()

Member Function Documentation

◆ addObserver()

◆ addRendererCallback()

◆ deliverNotifications()

◆ destroy()

◆ getAnimationManager() [1/2]

◆ getAnimationManager() [2/2]

◆ getBackgroundColor()

◆ getCamera()

◆ getController()

◆ getCursor()

◆ getDisplayScale()

◆ getDpi()

◆ getEffects() [1/2]

◆ getEffects() [2/2]

◆ getFeatureStateManager() [1/2]

◆ getFeatureStateManager() [2/2]

◆ getHeight()

◆ getHeightProvider()

◆ getLayerList()

◆ getMapNavigator()

◆ getReference()

◆ getRenderer()

◆ getViewMapTransformation()

◆ getWidth()

◆ is3D()

◆ newBuilder()

◆ propertyBackgroundColor()

◆ propertyCamera()

◆ propertyController()

◆ propertyDisplayScale()

◆ propertyDpi()

◆ queryFeatures()

◆ removeObserver()

◆ removeRendererCallback()

◆ resize()

◆ setBackgroundColor()

◆ setCamera()

◆ setController()

◆ setCursor()

◆ setDisplayScale()

◆ setDpi()

◆ setMapInvalidationCallback()

◆ setMouseCursorCallback()