Creates a new map.
either the DOM node in the web-page which will hold the map or that node's id. The container for a map is typically a DIV-element.
the map configuration.
Event hook that is called when the map comes to rest. For example, this event is fired after the user has finished panning or zooming the map.
The "idle" event type
the callback to be invoked when the map comes to rest.
value to use as this when executing callback
Event hook that is called when the selection of the map changes.
The "SelectionChanged" event type
callback to be invoked when there is a selection change. The callback 'selectionChangeEvents' parameter is an object with 'selectionChanges', which is an array of SelectionChangeInfo. If the selection changes across multiple layers then the 'selectionChanges' array will contain one object for each layer in which selection changes occurred.
value to use as this when executing callback.
Event hook that is called when the hover of the map changes.
The "HoverChanged" event type
callback to be invoked when there is a hover change. The callback 'hoverChangeEvents' parameter is an object with 'hoverChanges', which is an array of HoverChangeInfo. If the selection changes across multiple layers then the 'hoverChanges' array will contain one object for each layer in which selection changes occurred.
value to use as this when executing callback.
Event hook that is called when the map extent has changed, for instance by panning or zooming. Note that the MapChange event is fired only once per frame.
The "MapChange" event type
callback to be invoked when the map extent has changed.
value to use as this when executing callback
Event hook that is called when a balloon opens on the map.
The "ShowBalloon" event type
callback to be invoked when a balloon opens on the map.
value to use as this when executing callback
Event hook that is called when a balloon closes on the map.
The "HideBalloon" event type
callback to be invoked when a balloon closes on the map.
value to use as this when executing callback
Event hook that is called when Map.controller changes. Note that:
The "ControllerChanged" event type
Callback to be invoked when the controller on the map changes. The callback gets 2 parameters, the first is 'newController', which is the new Controller active on the map. The second is the previous Controller that was active on the map.
value to use as this when executing callback
The camera that is used by this map.
For now, you can only set a PerspectiveCamera instances on a map if the
map has a geocentric reference (EPSG:4978
), and you can
only set a OrthographicCamera on the map if the map does NOT have
a geocentric reference (ie. it's a projected (grid) or cartesian reference).
The camera that is used by this map.
For now, you can only set a PerspectiveCamera instances on a map if the
map has a geocentric reference (EPSG:4978
), and you can
only set a OrthographicCamera on the map if the map does NOT have
a geocentric reference (ie. it's a projected (grid) or cartesian reference).
The key used to animate the camera on the map.
The currently active controller of the map. A controller defines how user input is interpreted. If no controller is explicitly configured on the map, a number of defaults apply. See the Controller documentation for more details about these defaults.
map.controller = new BasicCreateController("point");
The currently active controller of the map. A controller defines how user input is interpreted. If no controller is explicitly configured on the map, a number of defaults apply. See the Controller documentation for more details about these defaults.
map.controller = new BasicCreateController("point");
The map's CursorManager. Use this to change the mouse cursor on the map's DOM node.
See the Implementing custom user interaction guide for more information on working with cursors on the map.
The DOM node in which the map is contained. This is the same node which was passed by ID at map construction.
The number of virtual pixels ("dots") on the screen per centimeter, as determined by the
Map
.
This value usually varies depending on the device, OS-settings and browser.
The number of virtual pixels ("dots") on the screen per inch, as determined by the
Map
.
This value usually varies depending on the device, OS-settings and browser.
The graphics effects that are applied on this map. Have a look at GraphicsEffects for a list of effects that are available.
You should directly assign properties of the effects fields.
Any effect that has complex parameters (using an object literal) can be disabled by setting its value to null. For simple effects that have boolean toggles, you can turn the effect off by setting the boolean value to false.:
map.effects.light = null;
map.effects.atmosphere = false;
A CSS color string to indicate the desired color of the globe if no imagery layers are present.
This only has an effect on 3D maps. On 2D maps, there is no globe. By default, the globe is light-grey. map.globeColor = "#aabbcc"; // or "rgba(110, 120, 130, 1.0)"
A CSS color string to indicate the desired color of the globe if no imagery layers are present.
This only has an effect on 3D maps. On 2D maps, there is no globe. By default, the globe is light-grey. map.globeColor = "#aabbcc"; // or "rgba(110, 120, 130, 1.0)"
The set of objects which are currently displayed as "hovered" (i.e. a cursor is hovering over them).
The layer tree that contains all of the layers in this map. This property is immutable.
Returns the current bounds of the map as a rectangle in the map's reference.
The map's MapNavigator. Use this to manipulate the area which is shown in the map.
Returns the scale values of this map view as an array of two Numbers (scale along the X-axes and the Y-axes, in that order). This is a read-only property.
In the case when the unit of measure is a length (like distance, altitude, easting,....),
the scale is the ratio between the distance, as it is measured on the screen of the device, to
the distance in the real world.
This corresponds with paper map scales. For instance to obtain a 1:10000 map display the
scale should be set to 1 / 10000
.
In the case when the unit of measure is of a different type (for example, time or temperature), the scale is the ratio of 1cm on the screen per units of measure. For example, such a scale might express something like 1cm equals 5 hours.
Note that since web browsers do not provide unambiguous information on the correct screen
resolution (which is commonly expressed in dpi (dots per inch)), the distance of 1cm on a
device's display is an approximation.
To retrieve the conversion factor used by LuciadRIA,
you can use the dotsPerCentimeter property of
the Map
.
The transformation that can be used to transform coordinates specified in the Map's reference to view coordinates (pixels). See viewToMapTransformation for the inverse transformation.
In a 3D map, this transformation will throw OutOfBoundsError when the world coordinate is not visible in the current view. This happens when the world coordinate is obscured by terrain or on the back-facing side of the globe.
The maximum scale value of the map. A user can not zoom in further than this value. The value is an array of 2 positive numbers: the first for the scale along the horizontal axis, the second for the scale along the vertical axis. These values may also be set with a single number value for convenience.
The default value of the horizontal and vertical components is Infinity
,
meaning there is no upper scale limit in both dimensions.
An error will be thrown when attempting to set an invalid value (e.g. the maxMapScale is smaller than the minMapScale).
Note that this value may conflict with the minimum scale which is implied by the bounds constraint (Map.restrictNavigationToBounds). When this value is smaller than that minimum-scale (which depends on the width/height of those bounds as well as the width/height of the view), the scale of the bounds-restriction will have precedence over this one.
This value may conflict with the scale implied by the navigation restriction Map.getBoundsNavigationRestriction. Because the map will be zoomed in so no data outside the restriction is shown, that scale value may be larger than this value. If that is the case, the scale value of the restriction will take precedence. Note that in such a case, it is impossible to zoom the map.
The maximum scale value of the map. A user can not zoom in further than this value. The value is an array of 2 positive numbers: the first for the scale along the horizontal axis, the second for the scale along the vertical axis. These values may also be set with a single number value for convenience.
The default value of the horizontal and vertical components is Infinity
,
meaning there is no upper scale limit in both dimensions.
An error will be thrown when attempting to set an invalid value (e.g. the maxMapScale is smaller than the minMapScale).
Note that this value may conflict with the minimum scale which is implied by the bounds constraint (Map.restrictNavigationToBounds). When this value is smaller than that minimum-scale (which depends on the width/height of those bounds as well as the width/height of the view), the scale of the bounds-restriction will have precedence over this one.
This value may conflict with the scale implied by the navigation restriction Map.getBoundsNavigationRestriction. Because the map will be zoomed in so no data outside the restriction is shown, that scale value may be larger than this value. If that is the case, the scale value of the restriction will take precedence. Note that in such a case, it is impossible to zoom the map.
The minimum scale value of the map. A user can not zoom out further than this value. The value is an array of 2 positive numbers: the first for the scale along the horizontal axis, the second for the scale along the vertical axis. These values may also be set with a single number value for convenience.
The default value of the horizontal and vertical components is 0
, meaning there
is no lower scale limit in both dimensions.
An error will be thrown when attempting to set an invalid value (e.g. the minMapScale is larger than the maxMapScale).
map.minMapScale = 1/200000;
map.maxMapScale = 1/50000;
The minimum scale value of the map. A user can not zoom out further than this value. The value is an array of 2 positive numbers: the first for the scale along the horizontal axis, the second for the scale along the vertical axis. These values may also be set with a single number value for convenience.
The default value of the horizontal and vertical components is 0
, meaning there
is no lower scale limit in both dimensions.
An error will be thrown when attempting to set an invalid value (e.g. the minMapScale is larger than the maxMapScale).
map.minMapScale = 1/200000;
map.maxMapScale = 1/50000;
The current world reference of the map.
The selected objects of the map. This is an array of Object
s where each
Object
contains the layer and the selected objects as properties. The name of
those properties is layer
and selected
respectively.
Performing an action on each selected object of a certain layer can for example be achieved as shown below.
var map = ...;
var selection = map.selectedObjects;
var i, j;
var layer, selectedObjects,selectedObject;
for ( i = 0; i < selection.length; i++ ){
layer = selection[i].layer;
if ( isSearchedLayer( layer ) ){
selectedObjects = selection[i].selected;//array of the selected objects for layer
for ( j = 0; j < selectedObjects.length; j++ ){
selectedObject = selectedObjects[j];
//do something with the selected object
}
}
}
The size of the view - including the border - as an array with two Numbers, representing the width and height in pixels.
The size of the view - excluding the border - as an array with two Numbers, representing the width and height in pixels. This is the size of the area where the data (not the axes) is rendered.
The transformation that can be used to transform coordinates specified in view coordinates (pixels) to the map reference. See mapToViewTransformation for the inverse transformation.
In a 3D map, this transformation will return a world point on the terrain at the input view coordinate. If the view coordinate does not hit the terrain, the transformation will throw OutOfBoundsError.
In a 2D map, the world point will never contain elevation.
This is a shorthand for Map#getViewToMapTransformation(LocationMode.TERRAIN)
Clear the current set of hovered objects. See hoverObjects for more information.
Clear the current selection.
This method must be called if the map is to be removed from the web page. This method cleans up the DOM and unregisters DOM event handlers.
Retrieve the bounds to which the navigation is restricted. You should not modify this object while it is set on the map.
the navigation restriction.
Creates a Transformation object that is used to transform a view position to a corresponding world (map) position in 3D scenes, based on a mechanism that is defined by LocationMode parameter.
In 3D space there are multiple interpretations possible for a given view point expressed in pixel coordinates.
Possible options are:
Note: In 2D space the LocationMode parameter is disregarded and the returned Transformation object is same as the one obtained by viewToMapTransformation.
If the view coordinate does not represent a point on an object or terrain, then OutOfBoundsError will be thrown.
The first image shows the view point that was used for the transformations. The second image shows from a different perspective
the transformation results, points that were created by the Transformation object with different locationMode properties.
the location mode the returned Transformation object will use. Default value is the LocationMode.TERRAIN mode.
Optional object literal with location mode specific options.
Hides the currently shown balloon, if any.
Updates the set of objects which are displayed as "hovered" (i.e. a cursor is hovering over them). Note that this method probably should not be called except from a custom Controller which is reacting to a cursor. If you try to hover an object that is not available in the layer, a ProgrammingError will be thrown. Objects that do not pass the layer's filter (if any) will not be hovered.
a list of objects organized by layer
refreshes the map unconditionally.
Determine whether a particular object on a layer is displayed as "hovered" (i.e. a cursor is hovering over it).
The layer on which the object is sitting
The object whose hover status is to be determined
true if the object is hovered
Determines whether a view coordinate is inside one of the map borders or not. See the Map constructor to define a border.
the border for which you want to verify the given coordinate
the x coordinate
the y coordinate
true if the coordinate is located in the map's border, false otherwise
Determine whether a particular object on a layer is selected.
The layer on which the object is sitting
The object whose selection status is to be determined
true if the object is selected
Override this when you wish to respond to click events on the map
the click event on the map
Override this method to add view-wide content to the map's context menu.
the context menu
Override this method to display a populated context menu. Implementations of this method should provide the required glue code to display the context menu using UI toolkit dependent code.
the page position at which to show the context menu. The position already compensates for the current scrolling offset of the document
the context menu
Retrieves all touched Features
in an array of {luciad.view.PickInfo} objects. The type of the
underlying layer determines the content of the array:
FeatureLayer
, the method returns the touched Features directly from the modelTileSet3DLayer
, the method returns an array of proxy features with metadata about the
touched 3D geometry. For more information and edge cases, consult the developer guide.
A pick info object is a JavaScript object with two properties: the objects
that were touched, and the layer
these objects reside in. One pickinfo
object for each layer with a touched object will be added to the result.
an x location (view space, in pixels)
an y location (view coordinates, in pixels)
the maximum distance (in pixels) between a touched object and [x,y].
a list of pick info objects. Layers without touched objects are not in the list.
Retrieves all touched Features
in an array of pick info objects: a pick info object
is a JavaScript object with two properties: the objects
that were touched,
and the layer
these objects reside in. One pickinfo object for each layer
with a touched object will be added to the result.
a x location (view-space, in pixels, the x-coordinate of the center of the rectangle)
a y location (view-space, in pixels, the y-coordinate of the center of the rectangle)
the width of the rectangle in which the objects must lie (in pixels)
width
will be clamped to 1 if it's smaller than 1.
the height of the rectangle in which the objects must lie (in pixels)
height
will be clamped to 1 if it's smaller than 1.
a list of pick info objects. Layers without touched objects are not in the list.
Retrieves the first touched Feature
. The return value of the result is null if no object
is touched, or a PickInfo object, with two properties: the
objects
that were touched (in this case it will be an array with a single element), and the
layer
that object resides in.
The closest object is picked by checking distances between the input location and feature shapes, or their labels
if the paintRepresentations
parameter includes the PaintRepresentation.LABEL.
an x location (view space, in pixels)
an y location (view space, in pixels)
the maximum distance (in pixels) between a touched object and [x,y]
.
a pick info object containing the first touched object,
or null
.
Retrieves the first touched Feature
. The return value of the result is null if no object
is touched, or a PickInfo object, with two properties: the
objects
that were touched (in this case it will be an array with a single element), and the
layer
that object resides in.
The closest object is picked by checking distances between the input location and feature shapes, or their labels
if the paintRepresentations
parameter includes the PaintRepresentation.LABEL.
an x location (view space, in pixels, the x-coordinate of the center of the rectangle)
an y location (view space, in pixels, the y-coordinate of the center of the rectangle)
the width of the rectangle in which the first touched object must lie (in pixels)
width
will be clamped to 1 if it's smaller than 1.
the height of the rectangle in which the first touched object must lie (in pixels)
height
will be clamped to 1 if it's smaller than 1.
a pick info object containing the first touched object,
or null
.
This method can be called when the size of the map's container has changed. The map will automatically refit itself to the size of the Map container at that time.
The map listens by default to window resize events to resize automatically. However, if the map container is resized by JavaScript, for example by a JavaScript SplitContainer component that divides the web page in two parts that can be resized, there is no way to detect this resizing of the map container automatically. In that case this method can be called by the application developer
Restores the state of the map based on a state object that has been returned by the saveState method.
It is possible to restore the state of a map with a reference that's different from this map's reference. Note that this is only true if a matching camera position can be found.
For example, it is not possible to restore a map state that's looking at Australia if this map has a Polar Stereographic North reference (because the southern hemisphere is not defined in that projection). In that case, an Error is thrown.
A map state
A promise that will be resolved after the restoreState operation has finished.
Non-animated restoreState operations are synchronous and effective immediately. An already resolved Promise will be returned. In this case, you don't have to use the Promise callbacks to wait for the operation to be completed (but you can, this is useful when switching between animated and non-animated versions).
For animated restoreState operations, the call is asynchronous. The returned Promise will be resolved when the restoreState animation has completely finished. If the restoreState animation is interrupted (for example, by another animation), the promise is rejected.
Specify a bounds which identifies the area beyond which the map cannot zoom or pan.
When set, a user will not be able to zoom or pan to an area that falls outside this bounds. The default
value is null
.
While the bounds can be specified in any spatial reference, the constraints will be evaluated on a bounds in the spatial reference of the map. For example, if the map's reference is in a Mercator grid reference, but the bounds constraint is specified in a geodetic reference, this bounds will be first converted to a bounds in a Mercator grid reference.
Visual feedback will be shown when the user hits the edges of the constraint during panning. Note that the style of this feedback cannot be modified.
When calling this method and the center of the view is not inside this bounds, the map will fit on this bounds.
To cancel the constraint, call this method with null
.
On a 3D map, the constraint is ignored.
On a 2D map, rotation is not possible when there is a constraint.
the bounding box restriction.
Returns the current state of the map, so that it can be restored at a later time. Currently this state encompasses a snapshot of the mapToViewTransformation configuration. The returned state object does not have a fixed layout, so accessing properties of the state is not allowed.
The state of the map does not include the state of the individual layers, nor any of the the navigation or scale restrictions.
If you're using a custom map reference, this reference needs to have an identifier when saving the map state. When restoring the saved state, ensure the reference can be retrieved from the ReferenceProvider, using the reference identifier.
the current map state
Selects a number of objects, passed to this method as an array of PickInfo objects.
A PickInfo object is a JavaScript object with two properties: the objects
property is an array of the objects that must be selected, the layer
property
indicates what the layer is these objects are supposed to be in. If you try to select
an object that is not available in the layer, a ProgrammingError will be thrown.
Note: You can select features only on a layer that is marked as selectable
.
Also, objects that do not pass the layer's filter will not be selected either.
an array of PickInfo objects
Places a balloon on the map. All parameters except the object
parameter are
optional. If the contentProvider
option is present it will be used to generate
the balloon content. If not, the balloonContentProvider
of the layer will be
used to generate the balloon content, provided the layer is configured with one. In all
other cases, a string representation of the object will be used as the balloon's content.
The balloon can be styled using the following CSS selectors:
.luciad .lcdBalloon
: The balloon's container element. This element is absolutely positioned by LuciadRIA..luciad .lcdBalloon .lcdFrame
: A container that wraps the header and the content. .luciad .lcdBalloon .lcdHeader
: The header of the balloon. Contains the close button..luciad .lcdBalloon .lcdClose
: The close button of the balloon..luciad .lcdBalloon .lcdContent
: The main content of the balloon.See samples/common/sample-common-style.css for an example usage of these selectors.
Only one balloon instance can be shown at the same time. Consider using labels if you want to show balloons for multiple objects at the same time. Labels support HTML so they can show the same contents as a balloon. An additional benefit is that labels can be decluttered.
An options object that may contain the following properties:
Feature
, it should belong to
the model of the layer. If it is a Shape
, it will be used as the position for the balloon.
contentProvider
option is omitted, this
layer's balloonContentProvider will be
used to generate the balloon's content.
...
//show balloon on the 1st selected object when the selection changes on the map.
map.on("SelectionChanged", function(event) {
var showBalloonObject = null, showBalloonLayer = null;
for(var i = 0; i < event.selectionChanges.length; i++) {
var selectionChange = event.selectionChanges[i];
if (selectionChange.selected.length > 0) {
showBalloonObject = selectionChange.selected[0];
showBalloonLayer = selectionChange.layer;
break;
}
}
if (showBalloonObject) {
map.showBalloon({
panTo: true,
layer: showBalloonLayer,
object: showBalloonObject,
contentProvider: function(o){
return "You've selected object with id: " + o.id;
}
});
} else {
map.hideBalloon();
}
});
...
Call this method to show a context menu at the given position.
the page position at which to show the context menu. The passed position should compensate for the current scrolling offset of the document
the context menu info object. This object will be passed to onCreateContextMenu
a boolean indicating whether a context menu was shown. If no context menu was shown (because there are no items in the menu, cf. onCreateContextMenu), false
is returned.
The Map is the main view component that displays a number of layers.
To create a default 2D map, simply do:
map = new Map("map");
To create a hardware-accelerated 2D map, use WebGLMap:
map = new WebGLMap("map");
To create a hardware-accelerated 3D map, use WebGLMap with reference EPSG:4978:
map = new WebGLMap("map", { reference: getReference("EPSG:4978") });