LuciadCPillar 2024.0.08
|
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 const MapAttributions & | getAttributions () const =0 |
Returns the attributions for 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 double | getMaxCPUMemoryHint () const =0 |
Returns the hint about the CPU memory consumption allowed by the map. More... | |
virtual double | getMaxGPUMemoryHint () const =0 |
Returns the hint about the GPU memory consumption allowed by the 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 & | propertyAttributions () |
Property name for the MapEvent that is fired as a result of changed attributions. 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... | |
A map for showing geo-spatial 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
You can navigate the map using MapNavigator
. If you want to fully customize map navigation, you can set the Camera
directly.
Related articles:
To support interaction with Feature data, it is possible to query which features are present in a given pixel bounds. Feature states, such as selection, can be tracked by the Map's FeatureStateManager .
Note that Map and its Map::Renderer track on which thread they are constructed. This is done so that, in subsequent calls, they can verify that the same threads are used consistently. When an inconsistency is detected, an assertion is triggered. This means that:
Related article: Threading rules for the Map
To make sure the Map can be rendered on screens with different DPI's, it is possible to configure:
Map#setDpi
Map#setDisplayScale
Related article: Support high-resolution (HiDPI) displays
The map can only be made visible on the screen when integrating it with a UI toolkit. The samples show how this can be done. Next to that, the following article demonstrates how this is done for Qt: Integrate with Qt.
|
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. |
|
virtualdefault |
|
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.
observer | an observer. |
luciad::InvalidArgumentException | when the observer was already added. |
luciad::NullArgumentException | when the observer is nullptr . |
|
pure virtual |
Adds the given callback to the Map.
After calling this method, the Map::Renderer::paint
will start calling the given callback instance.
rendererCallback | a renderer callback instance. Cannot be nullptr . |
NullArgumentException | when the renderer call back is nullptr . |
|
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.
|
pure virtual |
|
pure virtual |
Returns the AnimationManager
attached to this map.
Important notice regarding multi-threading:
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
AnimationManager
attached to this map.Important notice regarding multi-threading:
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
AnimationManager
attached to this map.
|
pure virtual |
Returns the AnimationManager
attached to this map.
Important notice regarding multi-threading:
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
AnimationManager
attached to this map.
|
pure virtual |
Returns the attributions for this map.
|
pure virtual |
Returns the background color of the map.
|
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.
setCamera
for more information.
|
pure virtual |
Returns the active controller of the map.
No default behavior is set.
nullptr
if no controller has been set.
|
pure virtual |
Returns the cursor of the map.
The default value is MouseCursor::defaultCursor
.
Map::setCursor
|
pure virtual |
Returns the display scale used to render the map.
setDisplayScale
has never been called
|
pure virtual |
Returns the DPI value used to calculate map scales.
|
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.
|
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.
|
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.
|
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.
|
pure virtual |
Returns the height of the Map in device independent pixels.
|
pure virtual |
Returns the map based height provider.
|
pure virtual |
|
pure virtual |
Returns the MapNavigator
instance that can manipulate the Camera
of this map.
MapNavigator
instance that can manipulate the Camera
of this map.
|
pure virtual |
Returns the hint about the CPU memory consumption allowed by the map.
|
pure virtual |
Returns the hint about the GPU memory consumption allowed by the map.
|
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.
|
pure virtual |
|
pure virtual |
Returns the transformation that can transform view coordinates to map coordinates and vice-versa.
|
pure virtual |
Returns the width of the Map in device independent pixels.
|
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
.
|
static |
Creates a new builder to create a map.
|
static |
Property name for the MapEvent
that is fired as a result of changed attributions.
|
static |
Property name for the MapEvent
that is fired as a result of changing the map's background color.
|
static |
|
static |
Property name for the MapEvent
that is fired as a result of changing the map's controller.
|
static |
Property name for the MapEvent
that is fired as a result of changing the map's display scale.
|
static |
|
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:
2D:
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.
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 . |
NullArgumentException | when the call back is nullptr . |
|
pure virtual |
Removes the given observer.
If the given observer was never added, an exception is thrown.
observer | an observer. |
luciad::InvalidArgumentException | when the observer is not known. |
luciad::NullArgumentException | when the observer is nullptr . |
|
pure virtual |
Removes the given callback from the Map.
After calling this method, the Map::Renderer::paint
will stop calling the given callback instance.
rendererCallback | a renderer callback instance. Cannot be nullptr . |
NullArgumentException | when the renderer call back is nullptr . |
|
pure virtual |
To be called when the host widget resizes, so that the map can adapt its camera, and graphics related resources.
width | The new map's width expressed in device independent pixels. |
height | The new map's height expressed in device independent pixels. |
luciad::InvalidArgumentException | when the width and/or the height is smaller than or equal to 0. |
|
pure virtual |
Sets the background color of the map.
color | the new background color. |
|
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:
See the threading article for a more detailed explanation on the threading behavior.
camera | the new camera. Cannot be nullptr . |
NullArgumentException | when the camera is nullptr . |
|
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
.
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. |
|
pure virtual |
Sets the cursor of the map.
Changing the cursor triggers a call to the mouse cursor callback if set.
cursor | the new cursor. |
Map::setMouseCursorCallback
|
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.
When a feature is scaled by the display scale, it means that pixel distances are scale. For example:
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:
See the threading article for a more detailed explanation on the threading behavior.
The default is 1.0;
displayScale | the display scale. A value of 1.0 corresponds with a display scale of 100%. |
|
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:
See the threading article for a more detailed explanation on the threading behavior.
dpi | the dpi value |
|
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.
mapInvalidationCallback | a callback that is called when the map has changed. |
|
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.
mouseCursorCallback | a callback that is called when the map has changed. |