Constructs a new MapView with the given options or canvas element.
The MapView options or the HTML canvas element used to display the map.
Readonly mapThe instance of MapRenderingManager managing the rendering of the map. It is a public property to allow access and modification of some parameters of the rendering process at runtime.
The AnimatedExtrusionHandler controls animated extrusion effect of the extruded objects in the Tile
Returns true if this MapView is constantly redrawing the scene.
The THREE.js camera used by this MapView to render the main scene.
When modifying the camera all derived properties like:
Returns true if the camera moved in the last frame.
The HTML canvas element used by this MapView.
The alpha used to clear the view.
The alpha used to clear the view.
The color used to clear the view.
The color used to clear the view.
Get camera clipping planes evaluator used.
Changes the clip planes evaluator at run time.
The HTML canvas element used by this MapView.
Returns DataSources displayed by this MapView.
Whether adding of new labels during interaction is enabled.
Enables or disables adding of new labels during interaction. Has no influence on already placed labels
true to enable adding false to disable them.
Is true if dispose() as been called on MapView.
PixelRatio ratio for rendering when the camera is moving or an animation is running.
Useful when rendering on high resolution displays with low performance GPUs that may be fill-rate-limited.
If a value is specified, a low resolution render pass is used to render the scene into a low resolution render target, before it is copied to the screen.
A value of undefined disables the low res render pass. Values between 0.5 and
window.devicePixelRatio can be tried to give good results. The value should not be larger
than window.devicePixelRatio.
Since no anti-aliasing is applied during dynamic rendering with dynamicPixelRatio
defined, visual artifacts may occur, especially with thin lines..
The resolution of icons and text labels is not affected.
undefined
Returns the elevation provider.
Environment used to evaluate dynamic scene expressions.
Retrieve the registered event types.
Array of event types.
Specifies whether extended frustum culling is enabled or disabled.
Enable of disable extended frustum culling.
The distance (in pixels) between the screen and the camera.
Use getFocalLength
Public access to MapViewFog allowing to toggle it by setting its enabled property.
Gets the value of the forced custom camera aspect.
Every time a frame is rendered, MapView resets the camera aspect.
You can disable this behavior by setting the value to undefined.
Sets the custom forced camera aspect ratio to use while rendering.
Internal
The position in geo coordinates of the center of the scene.
The position in geo coordinates of the center of the scene.
Longitude values outside of -180 and +180 are acceptable.
The view's maximum bounds in geo coordinates if any.
Sets or clears the view's maximum bounds in geo coordinates.
If set, the view will be constrained to the given geo bounds.
Returns heading angle in degrees.
Set the heading angle of the map.
: New heading angle in degrees.
Internal
Get the ImageCache that belongs to this MapView.
Images stored in this cache are primarily used for POIs (icons) and they are used with the current theme. Although images can be explicitly added and removed from the cache, it is advised not to remove images from this cache. If an image that is part of client code should be removed at any point other than changing the theme, the useImageCache should be used instead.
Returns true if the current frame will immediately be followed by another frame.
This should only be used for the internal handling of the render loop, if you use your own RenderLoop use ::renderSync in combination with FrameComplete
Lists the ISO 639-1 language codes for DataSources to use.
Sets the list of ISO 639-1 language codes for DataSources to use.
The lights configured by the theme, this is just a convenience method, because the lights can still be accessed by traversing the children of the [[scene]].
Returns the status of frustum culling after each update.
Enable of disable frustum culling after each update.
The node in this MapView's scene containing the user MapAnchors.
All (first level) children of this node will be positioned in world space according to the [[MapAnchor.geoPosition]]. Deeper level children can be used to position custom objects relative to the anchor node.
Maximum FPS (Frames Per Second).
If VSync in enabled, the specified number may not be
reached, but instead the next smaller number than maxFps that is equal to the refresh rate
divided by an integer number.
E.g.: If the monitors refresh rate is set to 60hz, and if maxFps is set to a value of 40
(60hz/1.5), the actual used FPS may be 30 (60hz/2). For displays that have a refresh rate of
60hz, good values for maxFps are 30, 20, 15, 12, 10, 6, 3 and 1. A value of 0 is ignored.
The maximum zoom level. Default is 14.
The maximum zoom level.
The minimum camera height in meters.
The minimum zoom level.
The minimum zoom level.
Returns true if the native WebGL antialiasing is enabled.
true for pixelRatio < 2.0, false otherwise.
The THREE.js overlay scene
Get the [[PickHandler]] for this mapView.
PixelRatio in the WebGlRenderer. May contain values > 1.0 for high resolution screens (HiDPI).
A value of undefined will make the getter return window.devicePixelRatio, setting a value
of 1.0 will disable the use of HiDPI on all devices.
Since the current pixelRatio may have been used in some calculations (e.g. the icons)
they may appear in the wrong size now. To ensure proper display of data, a call to
clearTileCache() is required if the pixelRatio is changed after tiles have been loaded.
MapView
Returns the ratio between a pixel and a world unit for the current camera (in the center of the camera projection).
Gets the optional camera used to render the scene.
Sets the optional camera used to render the scene.
Get currently presented political point of view - the country code.
Country code or undefined if default (majorly accepted) point of view is used.
Country code is stored in lower-case ISO 3166-1 alpha-2 standard.
Set the political view (country code) to be used when rendering disputed features (borders).
The code of the country which point of view should be presented,
if undefined or empty string is set then "defacto" or most widely accepted point of view
will be presented.
Country code should be encoded in lower-case ISO 3166-1 alpha-2 standard.
The abstraction of the MapRenderingManager API for post effects.
The projection used to project geo coordinates to world coordinates.
Changes the projection at run time.
The @xyzmaps/harp-geoutils#Projection instance to use.
Whether label rendering is enabled.
Enables or disables rendering of labels.
true to enable labels false to disable them.
The THREE.js WebGLRenderer used by this scene.
The way the cache usage is computed, either based on size in MB (mega bytes) or in number of tiles.
The THREE.js scene used by this MapView.
Internal
The MapViewEnvironment used by this MapView.
Returns the storage level for the given camera setup.
Actual storage level of the rendered data also depends on storageLevelOffset.
Get geo coordinates of camera focus (target) point.
geo coordinates of the camera focus point.
This point is not necessarily on the ground, i.e.:
Internal
Get distance from camera to the point of focus in world units.
Last known focus point distance.
If camera does not point to any ground anymore the last focus point distance is then returned.
Gets the current Theme used by this MapView to style map elements.
Changes the Theme used by this MapView to style map elements.
use MapView.setTheme instead
Beta
Beta
The [[TileGeometryManager]] manages geometry during loading and handles hiding geometry of specified [[GeometryKind]]s.
Returns tilt angle in degrees.
Set the tilt angle of the map.
: New tilt angle in degrees.
Returns true if an update has already been requested, such that after a currently rendering
frame, the next frame will be rendered immediately.
@xyzmaps/harp-utils#UriResolver used to resolve application/deployment
specific URIs into actual URLs that can be loaded with fetch.
Get the ImageCache for user images that belongs to this MapView.
Images added to this cache can be removed if no longer required.
Internal
Get object describing frustum planes distances and min/max visibility range for actual camera setup.
Near and far plane distance are self explanatory while minimum and maximum visibility range describes the extreme near/far planes distances that may be achieved with current camera settings, meaning at current zoom level (ground distance) and any possible orientation.
Visibility is directly related to camera [[ClipPlaneEvaluator]] used and determines the maximum possible distance of camera far clipping plane regardless of tilt, but may change whenever zoom level changes. Distance is measured in world units which may be approximately equal to meters, but this depends on the distortion related to projection type used.
Returns height of the viewport in pixels.
Access the VisibleTileSet to get access to all current datasources and their visible tiles.
The position in world coordinates of the center of the scene.
Internal
Get world coordinates of camera focus point.
world coordinates of the camera focus point.
The focus point coordinates are updated with each camera update so you don't need to re-calculate it, although if the camera started looking to the void, the last focus point is stored.
Returns the ratio between a world and a pixel unit for the current camera (in the center of the camera projection).
Returns the zoom level for the given camera setup.
Adds a new DataSource to this MapView.
The data source.
MapView needs at least one DataSource to display something.
Adds an event listener. There are various events that are sent before or after a new frame is rendered.
One of the [[MapViewEventNames]] strings.
The callback invoked when the MapView needs to render a new frame.
[[MapViewEventNames]].
let frameCount = 0;
mapView.addEventListener(MapViewEventNames.Render, () => {
++frameCount;
});
Adds new overlay text elements to this MapView.
Array of TextElement to be added.
Clears any elevation sources and provider previously set.
The datasource to be cleared.
Clear the tile cache.
Optional dataSourceName: stringThe name of the DataSource.
Optional filter: ((tile) => boolean)Optional tile filter
Remove the Tile objects created by cacheable DataSources. If a DataSource name is provided, this method restricts the eviction the DataSource with the given name.
Disposes this MapView.
true to force ThreeJS to loose the context. Supply false to keep
the context for further use.
This function cleans the resources that are managed manually including those that exist in shared caches.
Note: This function does not try to clean objects that can be disposed off easily by
TypeScript's garbage collecting mechanism. Consequently, if you need to perform a full
cleanup, you must ensure that all references to this MapView are removed.
Apply a visitor function to all tiles in the cache.
Visitor function
Apply visitor to all visible tiles.
Visitor function
Returns the unique DataSource matching the given name.
Returns the array of DataSources referring to the same [[StyleSet]].
Same as getGeoCoordinatesAt but always returning a geo coordinate.
Returns the @xyzmaps/harp-geoutils#GeoCoordinates from the given screen position.
The X position in css/client coordinates (without applied display ratio).
The Y position in css/client coordinates (without applied display ratio).
Optional fallback: booleanWhether to compute a fallback position if the earth surface is not hit.
Un-normalized geo coordinates
If fallback !== true the return value can be null, in case the camera has a high tilt
and the given (x, y) value is not intersecting the ground plane.
If fallback === true the return value will always exist but it might not be on the earth
surface.
If tileWrappingEnabled is true the returned geo coordinates will have a
longitude clamped to [-180,180] degrees.
The returned geo coordinates are not normalized so that a map object placed at that position
will be below the (x,y) screen coordinates, regardless which world repetition was on screen.
Returns the normalized screen coordinates from the given pixel position.
The X position in css/client coordinates (without applied display ratio).
The Y position in css/client coordinates (without applied display ratio).
Returns the screen position of the given geo or world position.
The position as a @xyzmaps/harp-geoutils#GeoCoordLike or THREE.Vector3 world position.
The screen position in CSS/client coordinates (no pixel ratio applied) or
undefined.
Returns the world space position from the given screen position.
The X position in css/client coordinates (without applied display ratio).
The Y position in css/client coordinates (without applied display ratio).
Whether to compute a fallback position if the earth surface is not hit.
If fallback !== true the return value can be null, in case the camera has a high tilt
and the given (x, y) value is not intersecting the ground plane.
If fallback === true the return value will always exist but it might not be on the earth
surface.
Returns the world space position from the given screen position.
The X position in css/client coordinates (without applied display ratio).
The Y position in css/client coordinates (without applied display ratio).
Optional fallback: booleanWhether to compute a fallback position if the earth surface is not hit.
If fallback !== true the return value can be null, in case the camera has a high tilt
and the given (x, y) value is not intersecting the ground plane.
If fallback === true the return value will always exist but it might not be on the earth
surface.
Checks if listener is added to an event type.
The type of event to listen to.
Optional listener: ((event) => void)The function that gets called when the event is fired.
Do a raycast on all objects in the scene. Useful for picking.
The X position in css/client coordinates (without applied display ratio).
The Y position in css/client coordinates (without applied display ratio).
Optional parameters: IntersectParamsThe intersection test behaviour may be adjusted by providing an instance of IntersectParams.
The list of intersection results.
Limited to objects that THREE.js can raycast, the solid lines that get their geometry in the shader cannot be tested for intersection.
Note, if a DataSource adds an [[Object3D]] to a Tile, it will be only pickable once MapView.render has been called, this is because MapView.render method creates the internal three.js root [[Object3D]] which is used in the [[PickHandler]] internally. This method will not test for intersection custom objects added to the scene by for example calling directly the [[scene.add]] method from THREE.
Returns true if the specified DataSource is enabled.
Adjusts the camera to look at a given geo coordinate with tilt and heading angles.
target and boundsIf bounds are specified, zoomLevel and distance parameters are ignored and lookAt
calculates best zoomLevel (and possibly target) to fit given bounds.
Following table shows how relation between bounds and target.
bounds |
target |
actual target |
|---|---|---|
| @xyzmaps/harp-geoutils#GeoBox | defined | params.target is used |
| @xyzmaps/harp-geoutils#GeoBox | undefined |
bounds.center is used as new target |
| @xyzmaps/harp-geoutils#GeoBoxExtentLike | undefined |
current MapView.target is used |
| @xyzmaps/harp-geoutils#GeoBoxExtentLike | defined | params.target is used |
| [[GeoCoordLike]][] | undefined |
new target is calculated as center of world box covering given points |
| [[GeoCoordLike]][] | defined | params.target is used and zoomLevel is adjusted to view all given geo points |
In each case, lookAt finds minimum zoomLevel that covers given extents or geo points.
With flat projection, if bounds represents points on both sides of anti-meridian, and
tileWrappingEnabled is used, lookAt will use this knowledge and find
minimal view that may cover "next" or "previous" world.
With sphere projection if bounds represents points on both sides of globe, best effort
method is used to find best `target``.
mapView.lookAt({heading: 90})
// look east retaining current `target`, `zoomLevel` and `tilt`
mapView.lookAt({lat: 40.707, lng: -74.01})
// look at Manhattan, New York retaining other view params
mapView.lookAt(bounds: { latitudeSpan: 10, longitudeSpan: 10})
// look at current `target`, but extending zoomLevel so we see 10 degrees of lat/long span
@see More examples in [[LookAtExample]].
@param params - {@link LookAtParams}
{@labels WITH_PARAMS}
The method that sets the camera to the desired angle (tiltDeg) and distance (in meters)
to the target location, from a certain heading (headingAngle).
The location to look at.
The distance of the camera to the target in meters.
Optional tiltDeg: numberThe camera tilt angle in degrees (0 is vertical), curbed below 89deg
Optional headingDeg: numberThe camera heading angle in degrees and clockwise (as opposed to yaw)
0
0
starting north.
Use lookAt version with LookAtParams object parameter.
Visit each tile in visible, rendered, and cached sets.
Optional dataSource: DataSourceIf passed, only the tiles from this DataSource instance
are processed. If undefined, tiles from all DataSources are processed.
Optional filter: ((tile) => boolean)Optional tile filter
Removes DataSource from this MapView.
The data source to be removed
Removes the given dynamic property from this MapView.
The name of the property to remove.
Property names starting with a $-sign are reserved and any attempt to change their value
will result in an error.
Removes an event listener. There are various events that are sent before or after a new frame is rendered.
One of the [[MapViewEventNames]] strings.
Optional listener: ((event) => void)The callback invoked when the MapView needs to render a new frame.
[[MapViewEventNames]].
mapView.removeEventListener(MapViewEventNames.Render, listener);
Moves the camera to the specified @xyzmaps/harp-geoutils#GeoCoordinates,
sets the desired zoomLevel and
adjusts the yaw and pitch.
Geolocation to move the camera to.
Desired zoom level.
Camera yaw in degrees, counter-clockwise (as opposed to heading), starting north.
Camera pitch in degrees.
The pitch of the camera is always curbed so that the camera cannot look above the horizon. This paradigm is necessary in @xyzmaps/harp-map-controls#MapControls, where the center of the screen is used for the orbiting interaction (3 fingers / right mouse button).
Use (MapView.lookAt:WITH_PARAMS) instead.
Updates the value of a dynamic property.
The name of the property.
The value of the property.
Property names starting with a $-sign are reserved and any attempt to change their value
will result in an error.
Themes can access dynamic properties using the Expr operator ["dynamic-properties"],
for example:
["get", "property name", ["dynamic-properties"]]
Sets the DataSource which contains the elevations, the elevation range source, and the elevation provider.
The datasource containing the terrain tiles.
Allows access to the elevation min / max per tile.
Allows access to the elevation at a given location or a ray from the camera.
Only a single elevation source is possible per MapView. If the terrain-datasource is merged with this repository, we could internally construct the ElevationRangeSource and the ElevationProvider and access would be granted to the application when it asks for it, to simplify the API.
Set's the way in which the fov is calculated on the map view.
How the FOV is calculated.
Note, for this to take visual effect, the map should be rendered after calling this function.
Generated using TypeDoc
The core class of the library to call in order to create a map visualization. It needs to be linked to datasources.