Class Map

java.lang.Object
com.luciad.maps.Map
All Implemented Interfaces:
AutoCloseable

public final class Map extends Object implements AutoCloseable
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.

Related articles:

Interacting with Features data
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 .

Threading
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:
  • All functions on Map, except getRenderer() must be called on the thread on which the Map was constructed (the "UI" thread).
  • All functions on Map.Renderer must be called on the thread on which getRenderer() was called the first time (the "Render" thread).

Related article: Threading rules for the Map

DPI and display scaling
To make sure the Map can be rendered on screens with different DPI's, it is possible to configure:

Related article: Support high-resolution (HiDPI) displays

Integrating the map with your UI toolkit
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.
  • Field Details Link icon

    • PropertyAttributions Link icon

      public static final String PropertyAttributions
      Property name for the MapEvent that is fired as a result of changed attributions.
      Since:
      2024.0
      See Also:
      • invalid reference
        getMapAttributions
    • PropertyBackgroundColor Link icon

      public static final String PropertyBackgroundColor
      Property name for the MapEvent that is fired as a result of changing the map's background color.
      Since:
      2023.1
      See Also:
    • PropertyCamera Link icon

      public static final String PropertyCamera
      Property name for the MapEvent that is fired as a result of changing the map's camera.
      Since:
      2023.1
      See Also:
    • PropertyController Link icon

      public static final String PropertyController
      Property name for the MapEvent that is fired as a result of changing the map's controller.
      Since:
      2023.1
      See Also:
    • PropertyDisplayScale Link icon

      public static final String PropertyDisplayScale
      Property name for the MapEvent that is fired as a result of changing the map's display scale.
      Since:
      2023.1
      See Also:
    • PropertyDpi Link icon

      public static final String PropertyDpi
      Property name for the MapEvent that is fired as a result of changing the map's dpi.
      Since:
      2023.1
      See Also:
  • Method Details Link icon

    • finalize Link icon

      protected void finalize()
      Overrides:
      finalize in class Object
    • close Link icon

      public void close()
      Specified by:
      close in interface AutoCloseable
    • newBuilder Link icon

      @NotNull public static Map.Builder newBuilder()
      Creates a new builder to create a map.
      Returns:
      a new builder to create a map.
    • destroy Link icon

      public void destroy()
      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.

    • setMapInvalidationCallback Link icon

      public void setMapInvalidationCallback(@Nullable IInvalidationCallback mapInvalidationCallback)
      Sets the given IInvalidationCallback.

      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 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.
    • getRenderer Link icon

      @NotNull public Map.Renderer getRenderer()
      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.
    • deliverNotifications Link icon

      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 Link icon

      public void resize(double width, double height) throws IllegalArgumentException
      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 Link icon

      public double getWidth()
      Returns the width of the Map in device independent pixels.
      Returns:
      the width of the Map in device independent pixels.
    • getHeight Link icon

      public double getHeight()
      Returns the height of the Map in device independent pixels.
      Returns:
      the height of the Map in device independent pixels.
    • getLayerList Link icon

      @NotNull public LayerList getLayerList()
      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.
    • getReference Link icon

      @NotNull public CoordinateReference getReference()
      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.
    • getMapNavigator Link icon

      @NotNull public MapNavigator getMapNavigator()
      Returns the MapNavigator instance that can manipulate the Camera of this map.
      Returns:
      the MapNavigator instance that can manipulate the Camera of this map.
    • setCamera Link icon

      public void setCamera(@NotNull Camera camera) throws NullPointerException
      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 null.
      Throws:
      NullPointerException - when the camera is null.
    • getCamera Link icon

      @NotNull public Camera 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 Link icon

      @NotNull public FeatureStateManager getFeatureStateManager()
      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.
    • queryFeatures Link icon

      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:

      • 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 null.
      Throws:
      NullPointerException - when the call back is null.
    • getViewMapTransformation Link icon

      @NotNull public Map.ViewMapTransformation getViewMapTransformation()
      Returns the transformation that can transform view coordinates to map coordinates and vice-versa.
      Returns:
      the view <> map transformation.
    • setBackgroundColor Link icon

      public void setBackgroundColor(@NotNull android.graphics.Color color)
      Sets the background color of the map.
      Parameters:
      color - the new background color.
    • getBackgroundColor Link icon

      @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 Link icon

      public void setController(@Nullable IController controller)
      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 to IController#onDeactivate.

      Parameters:
      controller - The new active controller. If null 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 Link icon

      @Nullable public IController getController()
      Returns the active controller of the map.

      No default behavior is set.

      Returns:
      null if no controller has been set.
    • getAnimationManager Link icon

      @NotNull public AnimationManager getAnimationManager()
      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

      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.
    • setCursor Link icon

      public void setCursor(@NotNull MouseCursor cursor)
      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 Link icon

      @NotNull public MouseCursor getCursor()
      Returns the cursor of the map.

      The default value is MouseCursor#defaultCursor.

      See Also:
    • setMouseCursorCallback Link icon

      public void setMouseCursorCallback(@Nullable IMouseCursorCallback mouseCursorCallback)
      Sets the given IMouseCursorCallback.

      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 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.
    • is3D Link icon

      public boolean is3D()
      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.
    • getDisplayScale Link icon

      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 Link icon

      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 Link icon

      public double getDpi()
      Returns the DPI value used to calculate map scales.
      Returns:
      the current dpi value.
    • setDpi Link icon

      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 Link icon

      @NotNull public MapAttributions getAttributions()
      Returns the attributions for this map.
      Returns:
      the map attributions.
      Since:
      2024.0
    • addRendererCallback Link icon

      public void addRendererCallback(@NotNull Map.IRendererCallback rendererCallback) throws NullPointerException
      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 null.
      Throws:
      NullPointerException - when the renderer call back is null.
    • removeRendererCallback Link icon

      public void removeRendererCallback(@NotNull Map.IRendererCallback rendererCallback) throws NullPointerException
      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 null.
      Throws:
      NullPointerException - when the renderer call back is null.
    • addObserver Link icon

      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 is null.
      Since:
      2023.1
    • removeObserver Link icon

      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 is null.
      Since:
      2023.1
    • getEffects Link icon

      @NotNull public GraphicsEffects 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 Link icon

      @NotNull public Map.HeightProvider getHeightProvider()
      Returns the map based height provider.
      Returns:
      the map based height provider.
      Since:
      2023.0
    • getMaxCPUMemoryHint Link icon

      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 Link icon

      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