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

Inheritance diagram for Luciad.Maps.Map:

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...

interface	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	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
void	AddObserver (Luciad.Maps.IMapObserver observer)
	Adds an observer that allows to receive change events from this map. More...

void	AddRendererCallback (Luciad.Maps.Map.IRendererCallback rendererCallback)
	Adds the given callback to the `Map`. More...

void	DeliverNotifications ()
	Delivers any pending notifications. More...

void	Destroy ()
	Disposes the `Map`. More...

void	Dispose ()

Luciad.Maps.Map.HeightProvider	GetHeightProvider ()
	Returns the map based height provider. More...

Luciad.Maps.Map.Renderer	GetRenderer ()
	Returns the renderer for this `Map`. More...

Luciad.Maps.Map.ViewMapTransformation	GetViewMapTransformation ()
	Returns the transformation that can transform view coordinates to map coordinates and vice-versa. More...

void	QueryFeatures (Luciad.Maps.Map.FeatureQuery query, Luciad.Maps.IMapQueryFeaturesCallback callback)
	Queries the features under the given pixel bounds, and passes the result to the given callback. More...

void	RemoveObserver (Luciad.Maps.IMapObserver observer)
	Removes the given observer. More...

void	RemoveRendererCallback (Luciad.Maps.Map.IRendererCallback rendererCallback)
	Removes the given callback from the `Map`. More...

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. More...

Static Public Member Functions
static Luciad.Maps.Map.Builder	NewBuilder ()
	Creates a new builder to create a map. More...

Properties
Luciad.Animations.AnimationManager	AnimationManager `[get]`
	The `AnimationManager` attached to this map. More...

Luciad.Maps.MapAttributions	Attributions `[get]`
	The attributions for this map. More...

System.Drawing.Color	BackgroundColor `[get, set]`
	The background color of the map. More...

Luciad.Cameras.Camera	Camera `[get, set]`
	The camera used by the renderer. More...

Luciad.Controllers.IController	Controller `[get, set]`
	The active controller of the map. More...

Luciad.Maps.MouseCursor	Cursor `[get, set]`
	The cursor of the map. More...

double	DisplayScale `[get, set]`
	The display scale used to render the map. More...

double	Dpi `[get, set]`
	The DPI value used to calculate map scales. More...

Luciad.Maps.Effects.GraphicsEffects	Effects `[get]`
	The graphics effects instance that can apply graphics effects on this map. More...

Luciad.Layers.Features.FeatureStateManager	FeatureStateManager `[get]`
	The `FeatureStateManager` that keeps track of the feature state (for example selection) for this map. More...

double	Height `[get]`
	The height of the `Map` in device independent pixels. More...

bool	Is3D `[get]`
	Whether this `Map` is visualized in 3D. More...

Luciad.Layers.LayerList	LayerList `[get]`
	The list of `Layer` instances that are visualized in this `Map`. More...

Luciad.Utils.IInvalidationCallback	MapInvalidationCallback `[set]`

Luciad.Maps.MapNavigator	MapNavigator `[get]`
	The `MapNavigator` instance that can manipulate the `Camera` of this map. More...

Luciad.Maps.IMouseCursorCallback	MouseCursorCallback `[set]`

static string	PropertyAttributions = PropertyAttributionsInternal() `[get]`
	Property name for the `MapEvent` that is fired as a result of changed attributions. More...

static string	PropertyBackgroundColor = PropertyBackgroundColorInternal() `[get]`
	Property name for the `MapEvent` that is fired as a result of changing the map's background color. More...

static string	PropertyCamera = PropertyCameraInternal() `[get]`
	Property name for the `MapEvent` that is fired as a result of changing the map's camera. More...

static string	PropertyController = PropertyControllerInternal() `[get]`
	Property name for the `MapEvent` that is fired as a result of changing the map's controller. More...

static string	PropertyDisplayScale = PropertyDisplayScaleInternal() `[get]`
	Property name for the `MapEvent` that is fired as a result of changing the map's display scale. More...

static string	PropertyDpi = PropertyDpiInternal() `[get]`
	Property name for the `MapEvent` that is fired as a result of changing the map's dpi. More...

Luciad.Geodesy.CoordinateReference	Reference `[get]`
	The reference of this `Map`. More...

double	Width `[get]`
	The width of the `Map` in device independent pixels. 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 Luciad.Maps.Map.LocationMode

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.

Member Function Documentation

◆ AddObserver()

void Luciad.Maps.Map.AddObserver ( Luciad.Maps.IMapObserver observer )

inline

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

System.ArgumentException	when the observer was already added.
System.ArgumentNullException	when the observer is `null`.

Since: 2023.1

◆ AddRendererCallback()

void Luciad.Maps.Map.AddRendererCallback ( Luciad.Maps.Map.IRendererCallback rendererCallback )

inline

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.

Exceptions

System.ArgumentNullException when the renderer call back is null.

Since: 2021.1

◆ DeliverNotifications()

void Luciad.Maps.Map.DeliverNotifications ( )

inline

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()

void Luciad.Maps.Map.Destroy ( )

inline

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

◆ Dispose()

void Luciad.Maps.Map.Dispose ( )

inline

◆ GetHeightProvider()

Luciad.Maps.Map.HeightProvider Luciad.Maps.Map.GetHeightProvider ( )

inline

Returns the map based height provider.

Returns: the map based height provider.

Since: 2023.0

◆ GetRenderer()

Luciad.Maps.Map.Renderer Luciad.Maps.Map.GetRenderer ( )

inline

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()

Luciad.Maps.Map.ViewMapTransformation Luciad.Maps.Map.GetViewMapTransformation ( )

inline

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

Returns: the view <> map transformation.

◆ NewBuilder()

static Luciad.Maps.Map.Builder Luciad.Maps.Map.NewBuilder ( )

inlinestatic

Creates a new builder to create a map.

Returns: a new builder to create a map.

◆ QueryFeatures()

void Luciad.Maps.Map.QueryFeatures	(	Luciad.Maps.Map.FeatureQuery	query,
		Luciad.Maps.IMapQueryFeaturesCallback	callback
	)

inline

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`.

Exceptions

System.ArgumentNullException when the call back is null.

◆ RemoveObserver()

void Luciad.Maps.Map.RemoveObserver ( Luciad.Maps.IMapObserver observer )

inline

Removes the given observer.

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

Parameters

observer an observer.

Exceptions

System.ArgumentException	when the observer is not known.
System.ArgumentNullException	when the observer is `null`.

Since: 2023.1

◆ RemoveRendererCallback()

void Luciad.Maps.Map.RemoveRendererCallback ( Luciad.Maps.Map.IRendererCallback rendererCallback )

inline

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.

Exceptions

System.ArgumentNullException when the renderer call back is null.

Since: 2021.1

◆ Resize()

void Luciad.Maps.Map.Resize	(	double	width,
		double	height
	)

inline

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

System.ArgumentException when the width and/or the height is smaller than or equal to 0.

Property Documentation

◆ AnimationManager

Luciad.Animations.AnimationManager Luciad.Maps.Map.AnimationManager

get

The AnimationManager attached to this map.

[get]

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

Since: 2021.1 [get]

◆ Attributions

Luciad.Maps.MapAttributions Luciad.Maps.Map.Attributions

get

The attributions for this map.

[get]

Returns the attributions for this map.

Since: 2024.0 [get]

◆ BackgroundColor

System.Drawing.Color Luciad.Maps.Map.BackgroundColor

getset

The background color of the map.

[get]

Returns the background color of the map.

[set]

Sets the background color of the map.

Since: 2020.1 [get]; 2021.1 [set]

◆ Camera

Luciad.Cameras.Camera Luciad.Maps.Map.Camera

getset

The camera used by the renderer.

[get]

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.

[set]

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.

Exceptions

System.ArgumentNullException when the camera is null.

Since: 2021.1

See also: Camera for more information.

◆ Controller

Luciad.Controllers.IController Luciad.Maps.Map.Controller

getset

The active controller of the map.

[get]

Returns the active controller of the map. No default behavior is set.

[set]

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.

◆ Cursor

Luciad.Maps.MouseCursor Luciad.Maps.Map.Cursor

getset

The cursor of the map.

[get]

Returns the cursor of the map. The default value is MouseCursor.defaultCursor.

[set]

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

Since: 2020.1

See also: Map.Cursor; Map.MouseCursorCallback

◆ DisplayScale

double Luciad.Maps.Map.DisplayScale

getset

The display scale used to render the map.

[get]

Returns the display scale used to render the map.

[set]

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;

Since: 2022.0

◆ Dpi

double Luciad.Maps.Map.Dpi

getset

The DPI value used to calculate map scales.

[get]

Returns the DPI value used to calculate map scales.

[set]

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.

Since: 2022.0

◆ Effects

Luciad.Maps.Effects.GraphicsEffects Luciad.Maps.Map.Effects

get

The graphics effects instance that can apply graphics effects on this map.

[get]

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.

Since: 2022.1 [get]

◆ FeatureStateManager

Luciad.Layers.Features.FeatureStateManager Luciad.Maps.Map.FeatureStateManager

get

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

[get]

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.

◆ Height

double Luciad.Maps.Map.Height

get

The height of the Map in device independent pixels.

[get]

Returns the height of the Map in device independent pixels.

◆ Is3D

bool Luciad.Maps.Map.Is3D

get

Whether this Map is visualized in 3D.

[get]

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.

Since: 2021.1 [get]

◆ LayerList

Luciad.Layers.LayerList Luciad.Maps.Map.LayerList

get

The list of Layer instances that are visualized in this Map.

[get]

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.

◆ MapInvalidationCallback

Luciad.Utils.IInvalidationCallback Luciad.Maps.Map.MapInvalidationCallback

set

[set]

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.

◆ MapNavigator

Luciad.Maps.MapNavigator Luciad.Maps.Map.MapNavigator

get

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

[get]

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

Since: 2021.1 [get]

◆ MouseCursorCallback

Luciad.Maps.IMouseCursorCallback Luciad.Maps.Map.MouseCursorCallback

set

[set]

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.

Since: 2020.1 [set]

◆ PropertyAttributions

string Luciad.Maps.Map.PropertyAttributions = PropertyAttributionsInternal()

staticget

Property name for the MapEvent that is fired as a result of changed attributions.

Since: 2024.0

See also: getMapAttributions

◆ PropertyBackgroundColor

string Luciad.Maps.Map.PropertyBackgroundColor = PropertyBackgroundColorInternal()

staticget

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

Since: 2023.1

See also: BackgroundColor

◆ PropertyCamera

string Luciad.Maps.Map.PropertyCamera = PropertyCameraInternal()

staticget

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

Since: 2023.1

See also: Camera

◆ PropertyController

string Luciad.Maps.Map.PropertyController = PropertyControllerInternal()

staticget

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

Since: 2023.1

See also: Controller

◆ PropertyDisplayScale

string Luciad.Maps.Map.PropertyDisplayScale = PropertyDisplayScaleInternal()

staticget

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

Since: 2023.1

See also: DisplayScale

◆ PropertyDpi

string Luciad.Maps.Map.PropertyDpi = PropertyDpiInternal()

staticget

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

Since: 2023.1

See also: Dpi

◆ Reference

Luciad.Geodesy.CoordinateReference Luciad.Maps.Map.Reference

get

The reference of this Map.

[get]

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.

◆ Width

double Luciad.Maps.Map.Width

get

The width of the Map in device independent pixels.

[get]

Returns the width of the Map in device independent pixels.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Member Enumeration Documentation

◆ LocationMode

Member Function Documentation

◆ AddObserver()

◆ AddRendererCallback()

◆ DeliverNotifications()

◆ Destroy()

◆ Dispose()

◆ GetHeightProvider()

◆ GetRenderer()

◆ GetViewMapTransformation()

◆ NewBuilder()

◆ QueryFeatures()

◆ RemoveObserver()

◆ RemoveRendererCallback()

◆ Resize()

Property Documentation

◆ AnimationManager

[get]

◆ Attributions

[get]

◆ BackgroundColor

[get]

[set]

◆ Camera

[get]

[set]

◆ Controller

[get]

[set]

◆ Cursor

[get]

[set]

◆ DisplayScale

[get]

[set]

◆ Dpi

[get]

[set]

◆ Effects

[get]

◆ FeatureStateManager

[get]

◆ Height

[get]

◆ Is3D

[get]

◆ LayerList

[get]

◆ MapInvalidationCallback

[set]

◆ MapNavigator

[get]

◆ MouseCursorCallback

[set]

◆ PropertyAttributions

◆ PropertyBackgroundColor

◆ PropertyCamera

◆ PropertyController

◆ PropertyDisplayScale

◆ PropertyDpi

◆ Reference

[get]

◆ Width

[get]