Class Map
- All Implemented Interfaces:
AutoCloseable
- Data
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
MapNavigator
. If you want to fully customize map navigation, you can set the Camera
directly.
Related articles:
- How to scale, pan, rotate, and fit a map with the MapNavigator API
- How to manipulate the camera of a Map with the camera API
- Interacting with Features data
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
.
- Threading
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:
- All functions on
Map
, exceptgetRenderer()
must be called on the thread on which theMap
was constructed (the "UI" thread). - All functions on
Map.Renderer
must be called on the thread on whichgetRenderer()
was called the first time (the "Render" thread).
Related article: Threading rules for the Map
- DPI and display scaling
Map
can be rendered on screens with different DPI's, it is possible to configure:
- The DPI: see
Map#setDpi
- The display scale: see
Map#setDisplayScale
Related article: Support high-resolution (HiDPI) displays
- Integrating the map with your UI toolkit
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic final class
static final class
A query specifies which features you are interested in.static final class
A height provider based on the map layers order and visibility.static interface
This callback can be used to execute tasks on the render thread right before or right after theMap
is painted byMap.Renderer
.static enum
Used to determine how the Map::getViewToMapTransformation method determines the point inMap
coordinates that corresponds to a given view location.static final class
TheMap
renderer.static final class
This class allows to transform between view (pixel coordinates on the screen) and map coordinates. -
Field Summary
Modifier and TypeFieldDescriptionstatic final String
Property name for theMapEvent
that is fired as a result of changed attributions.static final String
Property name for theMapEvent
that is fired as a result of changing the map's background color.static final String
Property name for theMapEvent
that is fired as a result of changing the map's camera.static final String
Property name for theMapEvent
that is fired as a result of changing the map's controller.static final String
Property name for theMapEvent
that is fired as a result of changing the map's display scale.static final String
Property name for theMapEvent
that is fired as a result of changing the map's dpi. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addObserver
(IMapObserver observer) Adds an observer that allows to receive change events from this map.void
addRendererCallback
(Map.IRendererCallback rendererCallback) Adds the given callback to theMap
.void
close()
void
Delivers any pending notifications.void
destroy()
Disposes theMap
.protected void
finalize()
Returns theAnimationManager
attached to this map.Returns the attributions for this map.android.graphics.Color
Returns the background color of the map.Returns the camera used by the renderer.Returns the active controller of the map.Returns the cursor of the map.double
Returns the display scale used to render the map.double
getDpi()
Returns the DPI value used to calculate map scales.Returns the graphics effects instance that can apply graphics effects on this map.Returns theFeatureStateManager
that keeps track of the feature state (for example selection) for this map.double
Returns the height of theMap
in device independent pixels.Returns the map based height provider.Returns theMapNavigator
instance that can manipulate theCamera
of this map.double
Returns the hint about the CPU memory consumption allowed by the map.double
Returns the hint about the GPU memory consumption allowed by the map.Returns the reference of thisMap
.Returns the renderer for thisMap
.Returns the transformation that can transform view coordinates to map coordinates and vice-versa.double
getWidth()
Returns the width of theMap
in device independent pixels.boolean
is3D()
Returns whether thisMap
is visualized in 3D.static Map.Builder
Creates a new builder to create a map.void
queryFeatures
(Map.FeatureQuery query, IMapQueryFeaturesCallback callback) Queries the features under the given pixel bounds, and passes the result to the given callback.void
removeObserver
(IMapObserver observer) Removes the given observer.void
removeRendererCallback
(Map.IRendererCallback rendererCallback) Removes the given callback from theMap
.void
resize
(double width, double height) To be called when the host widget resizes, so that the map can adapt its camera, and graphics related resources.void
setBackgroundColor
(android.graphics.Color color) Sets the background color of the map.void
Sets the camera used by the renderer.void
setController
(IController controller) Sets the active controller of the map.void
setCursor
(MouseCursor cursor) Sets the cursor of the map.void
setDisplayScale
(double displayScale) Sets the display scale used to render the map.void
setDpi
(double dpi) Sets the DPI value used to calculate map scales.void
setMapInvalidationCallback
(IInvalidationCallback mapInvalidationCallback) Sets the givenIInvalidationCallback
.void
setMouseCursorCallback
(IMouseCursorCallback mouseCursorCallback) Sets the givenIMouseCursorCallback
.
-
Field Details
-
PropertyAttributions
Property name for theMapEvent
that is fired as a result of changed attributions.- Since:
- 2024.0
- See Also:
-
PropertyBackgroundColor
Property name for theMapEvent
that is fired as a result of changing the map's background color.- Since:
- 2023.1
- See Also:
-
PropertyCamera
Property name for theMapEvent
that is fired as a result of changing the map's camera.- Since:
- 2023.1
- See Also:
-
PropertyController
Property name for theMapEvent
that is fired as a result of changing the map's controller.- Since:
- 2023.1
- See Also:
-
PropertyDisplayScale
Property name for theMapEvent
that is fired as a result of changing the map's display scale.- Since:
- 2023.1
- See Also:
-
PropertyDpi
Property name for theMapEvent
that is fired as a result of changing the map's dpi.- Since:
- 2023.1
- See Also:
-
-
Method Details
-
finalize
protected void finalize() -
close
public void close()- Specified by:
close
in interfaceAutoCloseable
-
newBuilder
Creates a new builder to create a map.- Returns:
- a new builder to create a map.
-
destroy
public void destroy() -
setMapInvalidationCallback
Sets the givenIInvalidationCallback
.This callback is called when the map has changed, and needs to be repainted. Can be
null
. The callback is owned by the calling code, i.e. typically code that integrates theMap
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.
-
getRenderer
Returns the renderer for thisMap
.The
Renderer
owns the OpenGL resources related to thisMap
. It can only be interacted with while the OpenGL context is current.- Returns:
- the renderer for this
Map
.
-
deliverNotifications
public void deliverNotifications()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.
-
resize
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.- Throws:
IllegalArgumentException
- when the width and/or the height is smaller than or equal to 0.
-
getWidth
public double getWidth()Returns the width of theMap
in device independent pixels.- Returns:
- the width of the
Map
in device independent pixels.
-
getHeight
public double getHeight()Returns the height of theMap
in device independent pixels.- Returns:
- the height of the
Map
in device independent pixels.
-
getLayerList
-
getReference
Returns the reference of thisMap
.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, theMap
is painted in 3D, and all data is pointed on the globe.- Returns:
- the reference of this
Map
.
-
setCamera
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 benull
.- Throws:
NullPointerException
- when the camera isnull
.
- when called on the render thread, the camera is immediately updated. You can for example get access to the render thread using the
-
getCamera
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:
-
getFeatureStateManager
Returns theFeatureStateManager
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.
-
queryFeatures
public void queryFeatures(@NotNull Map.FeatureQuery query, @NotNull IMapQueryFeaturesCallback callback) throws NullPointerException 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.- Parameters:
query
- the feature query containing the parameters to use to query the visible featurescallback
- a callback which can handle the result of the query operation. Cannot benull
.- Throws:
NullPointerException
- when the call back isnull
.
-
getViewMapTransformation
Returns the transformation that can transform view coordinates to map coordinates and vice-versa.- Returns:
- the view <> map transformation.
-
setBackgroundColor
public void setBackgroundColor(@NotNull android.graphics.Color color) Sets the background color of the map.- Parameters:
color
- the new background color.
-
getBackgroundColor
@NotNull public android.graphics.Color getBackgroundColor()Returns the background color of the map.- Returns:
- the color that is used to render the map background.
-
setController
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
IController#onActivate
to let the controller know it is activated. The previous controller if present will first receive a call toIController#onDeactivate
.- Parameters:
controller
- The new active controller. Ifnull
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.
-
getController
Returns the active controller of the map.No default behavior is set.
- Returns:
null
if no controller has been set.
-
getAnimationManager
Returns theAnimationManager
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'scamera
.
See the related article: Threading rules for the 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'scamera
.
See the related article: Threading rules for the Map
- Returns:
- the
AnimationManager
attached to this map.
- You can start and stop animations with the
-
setCursor
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:
-
getCursor
Returns the cursor of the map.The default value is
MouseCursor#defaultCursor
.- See Also:
-
setMouseCursorCallback
Sets the givenIMouseCursorCallback
.This callback is called when the map's cursor has changed. Can be
null
. The callback is owned by the calling code, i.e. typically code that integrates theMap
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.
-
is3D
public boolean is3D()Returns whether thisMap
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 anorthographic camera
.- Returns:
- whether this
Map
is visualized in 3D.
-
getDisplayScale
public double getDisplayScale()Returns the display scale used to render the map.- Returns:
- the current display scale, will be 1.0 if
setDisplayScale
has never been called
-
setDisplayScale
public void setDisplayScale(double displayScale) 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%.
-
getDpi
public double getDpi()Returns the DPI value used to calculate map scales.- Returns:
- the current dpi value.
-
setDpi
public void setDpi(double dpi) 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
-
getAttributions
Returns the attributions for this map.- Returns:
- the map attributions.
- Since:
- 2024.0
-
addRendererCallback
public void addRendererCallback(@NotNull Map.IRendererCallback rendererCallback) throws NullPointerException Adds the given callback to theMap
.After calling this method, the
Map.Renderer#paint
will start calling the given callback instance.- Parameters:
rendererCallback
- a renderer callback instance. Cannot benull
.- Throws:
NullPointerException
- when the renderer call back isnull
.
-
removeRendererCallback
public void removeRendererCallback(@NotNull Map.IRendererCallback rendererCallback) throws NullPointerException Removes the given callback from theMap
.After calling this method, the
Map.Renderer#paint
will stop calling the given callback instance.- Parameters:
rendererCallback
- a renderer callback instance. Cannot benull
.- Throws:
NullPointerException
- when the renderer call back isnull
.
-
addObserver
public void addObserver(@NotNull IMapObserver observer) throws IllegalArgumentException, NullPointerException 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.- Throws:
IllegalArgumentException
- when the observer was already added.NullPointerException
- when the observer isnull
.- Since:
- 2023.1
-
removeObserver
public void removeObserver(@NotNull IMapObserver observer) throws IllegalArgumentException, NullPointerException Removes the given observer.If the given observer was never added, an exception is thrown.
- Parameters:
observer
- an observer.- Throws:
IllegalArgumentException
- when the observer is not known.NullPointerException
- when the observer isnull
.- Since:
- 2023.1
-
getEffects
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.
-
getHeightProvider
Returns the map based height provider.- Returns:
- the map based height provider.
- Since:
- 2023.0
-
getMaxCPUMemoryHint
public double getMaxCPUMemoryHint()Returns the hint about the CPU memory consumption allowed by the map.- Returns:
- a hint for the maximum CPU memory usage, defined in MB.
- Since:
- 2024.0.02
-
getMaxGPUMemoryHint
public double getMaxGPUMemoryHint()Returns the hint about the GPU memory consumption allowed by the map.- Returns:
- a hint for the maximum GPU memory usage, defined in MB.
- Since:
- 2024.0.02
-