Options
All
  • Public
  • Public/Protected
  • All
Menu

Class MapView

The core class of the library to call in order to create a map visualization. It needs to be linked to datasources.

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Properties

Readonly mapRenderingManager

mapRenderingManager: IMapRenderingManager

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

Accessors

animatedExtrusionHandler

animating

  • get animating(): boolean

camera

  • get camera(): PerspectiveCamera

  • The THREE.js camera used by this MapView to render the main scene.

    remarks

    When modifying the camera all derived properties like:

    • MapView.target
    • MapView.zoomLevel
    • MapView.tilt
    • MapView.heading could change. These properties are cached internally and will only be updated in the next animation frame. FIXME: Unfortunately THREE.js is not dispatching any events when camera properties change so we should have an API for enforcing update of cached values.

    Returns PerspectiveCamera

cameraIsMoving

  • get cameraIsMoving(): boolean

canvas

  • get canvas(): HTMLCanvasElement

clearAlpha

  • get clearAlpha(): number
  • set clearAlpha(alpha: number): void

clearColor

  • get clearColor(): number
  • set clearColor(color: number): void

clipPlanesEvaluator

collisionDebugCanvas

  • get collisionDebugCanvas(): HTMLCanvasElement | undefined

copyrightInfo

dataSources

delayLabelsUntilMovementFinished

  • get delayLabelsUntilMovementFinished(): boolean
  • set delayLabelsUntilMovementFinished(value: boolean): void

  • Enables or disables adding of new labels during interaction. Has no influence on already placed labels

    Returns boolean

    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

    Parameters

    • value: boolean

      true to enable adding false to disable them.

    Returns void

    Whether adding of new labels during interaction is enabled.

disposed

  • get disposed(): boolean

dynamicPixelRatio

  • get dynamicPixelRatio(): number | undefined
  • set dynamicPixelRatio(ratio: number | undefined): void

  • PixelRatio ratio for rendering when the camera is moving or an animation is running.

    remarks

    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.

    note

    Since no anti-aliasing is applied during dynamic rendering with dynamicPixelRatio defined, visual artifacts may occur, especially with thin lines..

    note

    The resolution of icons and text labels is not affected.

    default

    undefined

    Returns number | undefined

  • PixelRatio ratio for rendering when the camera is moving or an animation is running.

    remarks

    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.

    note

    Since no anti-aliasing is applied during dynamic rendering with dynamicPixelRatio defined, visual artifacts may occur, especially with thin lines..

    note

    The resolution of icons and text labels is not affected.

    default

    undefined

    Parameters

    • ratio: number | undefined

    Returns void

elevationProvider

enableMixedLod

  • get enableMixedLod(): boolean | undefined
  • set enableMixedLod(enableMixedLod: boolean | undefined): void

env

  • get env(): Env

eventTypes

  • get eventTypes(): string[]

extendedFrustumCulling

  • get extendedFrustumCulling(): boolean
  • set extendedFrustumCulling(value: boolean): void

focalLength

  • get focalLength(): number

fog

forceCameraAspect

  • get forceCameraAspect(): number | undefined
  • set forceCameraAspect(aspect: number | undefined): void

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

    Returns number | undefined

  • Sets the custom forced camera aspect ratio to use while rendering.

    You can disable this behavior by setting the value to undefined.

    Parameters

    • aspect: number | undefined

    Returns void

geoCenter

geoMaxBounds

  • get geoMaxBounds(): GeoBox | undefined
  • set geoMaxBounds(bounds: GeoBox | undefined): void

heading

  • get heading(): number
  • set heading(heading: number): void

imageCache

  • 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 {@link useImageCache} should be used instead.

    Returns MapViewImageCache

isDynamicFrame

  • get isDynamicFrame(): boolean

  • Returns true if the current frame will immediately be followed by another frame.

    deprecated

    This should only be used for the internal handling of the render loop, if you use your own RenderLoop use {@link MapView::renderSync} in combination with MapViewEventNames.FrameComplete

    Returns boolean

languages

  • get languages(): string[] | undefined
  • set languages(languages: string[] | undefined): void

lights

  • get lights(): Light[]

  • Returns Light[]

    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.

lockVisibleTileSet

  • get lockVisibleTileSet(): boolean
  • set lockVisibleTileSet(value: boolean): void

mapAnchors

  • The node in this MapView's scene containing the user MapAnchors.

    remarks

    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.

    Returns MapAnchors

maxFps

  • get maxFps(): number
  • set maxFps(value: number): void

  • Maximum FPS (Frames Per Second).

    remarks

    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.

    Returns number

  • Maximum FPS (Frames Per Second).

    remarks

    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.

    Parameters

    • value: number

    Returns void

maxZoomLevel

  • get maxZoomLevel(): number
  • set maxZoomLevel(zoomLevel: number): void

minCameraHeight

  • get minCameraHeight(): number

minZoomLevel

  • get minZoomLevel(): number
  • set minZoomLevel(zoomLevel: number): void

nativeWebglAntialiasEnabled

  • get nativeWebglAntialiasEnabled(): boolean

overlayScene

  • get overlayScene(): Scene

pickHandler

pixelRatio

  • get pixelRatio(): number
  • set pixelRatio(pixelRatio: number): void

  • PixelRatio in the WebGlRenderer. May contain values > 1.0 for high resolution screens (HiDPI).

    remarks

    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.

    note

    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.

    memberof

    MapView

    Returns number

  • PixelRatio in the WebGlRenderer. May contain values > 1.0 for high resolution screens (HiDPI).

    remarks

    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.

    note

    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.

    memberof

    MapView

    Parameters

    • pixelRatio: number

    Returns void

pixelToWorld

  • get pixelToWorld(): number

pointOfView

  • get pointOfView(): PerspectiveCamera | undefined
  • set pointOfView(pointOfView: PerspectiveCamera | undefined): void

politicalView

  • get politicalView(): string | undefined
  • set politicalView(pov: string | undefined): void

  • Get currently presented political point of view - the country code.

    note

    Country code is stored in lower-case ISO 3166-1 alpha-2 standard.

    Returns string | undefined

    Country code or undefined if default (majorly accepted) point of view is used.

  • Set the political view (country code) to be used when rendering disputed features (borders).

    note

    Country code should be encoded in lower-case ISO 3166-1 alpha-2 standard.

    Parameters

    • pov: string | undefined

      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.

    Returns void

    Country code or undefined if default (majorly accepted) point of view is used.

postEffects

projection

renderLabels

  • get renderLabels(): boolean
  • set renderLabels(value: boolean): void

renderer

  • get renderer(): WebGLRenderer

resourceComputationType

scene

  • get scene(): Scene

sceneEnvironment

shadowsEnabled

  • get shadowsEnabled(): boolean
  • set shadowsEnabled(enabled: boolean): void

storageLevel

  • get storageLevel(): number

target

  • Get geo coordinates of camera focus (target) point.

    remarks

    This point is not necessarily on the ground, i.e.:

    • if the tilt is high and projection is {@link @here/harp-geoutils#sphereProjection}`
    • if the camera was modified directly and is not pointing to the ground. In any case the projection of the target point will be in the center of the screen.

    Returns GeoCoordinates

    geo coordinates of the camera focus point.

targetDistance

  • get targetDistance(): number
  • internal

    Get distance from camera to the point of focus in world units.

    note

    If camera does not point to any ground anymore the last focus point distance is then returned.

    Returns number

    Last known focus point distance.

taskQueue

theme

  • get theme(): Theme
  • set theme(theme: Theme): void

throttlingEnabled

  • get throttlingEnabled(): boolean
  • set throttlingEnabled(enabled: boolean): void

tileGeometryManager

tileWrappingEnabled

  • get tileWrappingEnabled(): boolean
  • set tileWrappingEnabled(enabled: boolean): void

tilt

  • get tilt(): number
  • set tilt(tilt: number): void

updatePending

  • get updatePending(): boolean

  • Returns true if an update has already been requested, such that after a currently rendering frame, the next frame will be rendered immediately.

    Returns boolean

uriResolver

userImageCache

viewRanges

  • Get object describing frustum planes distances and min/max visibility range for actual camera setup.

    remarks

    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.

    note

    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.

    internal

    Returns ViewRanges

viewportHeight

  • get viewportHeight(): number

visibleTileSet

worldCenter

  • get worldCenter(): Vector3

worldTarget

  • get worldTarget(): Vector3
  • internal

    Get world coordinates of camera focus point.

    remarks
    note

    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 Vector3

    world coordinates of the camera focus point.

worldToPixel

  • get worldToPixel(): number

zoomLevel

  • get zoomLevel(): number
  • set zoomLevel(zoomLevel: number): void

Methods

addDataSource

  • addDataSource(dataSource: DataSource): Promise<void>

addEventListener

addOverlayText

beginAnimation

  • beginAnimation(): void

clearElevationSource

  • clearElevationSource(elevationSource: DataSource): void

clearOverlayText

  • clearOverlayText(): void

clearTileCache

  • clearTileCache(dataSourceName?: undefined | string, filter?: undefined | ((tile: Tile) => boolean)): void

dispatchEvent

  • dispatchEvent(event: Event): void

dispose

  • dispose(freeContext?: boolean): void

  • Disposes this MapView.

    override
    remarks

    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.

    Parameters

    • Default value freeContext: boolean = true

      true to force ThreeJS to loose the context. Supply false to keep the context for further use.

    Returns void

endAnimation

  • endAnimation(): void

forEachCachedTile

  • forEachCachedTile(visitor: (tile: Tile) => void): void

forEachVisibleTile

  • forEachVisibleTile(fun: (tile: Tile) => void): void

getCacheSize

  • getCacheSize(): number

getDataSourceByName

  • getDataSourceByName(dataSourceName: string): DataSource | undefined

getDataSourcesByStyleSetName

  • getDataSourcesByStyleSetName(styleSetName: string): DataSource[]

getGeoCoordinatesAt

  • getGeoCoordinatesAt(x: number, y: number, fallback: true): GeoCoordinates
  • getGeoCoordinatesAt(x: number, y: number, fallback?: undefined | false | true): GeoCoordinates | null

  • Same as MapView.getGeoCoordinatesAt but always returning a geo coordinate.

    Parameters

    • x: number
    • y: number
    • fallback: true

    Returns GeoCoordinates

  • Returns the {@link @here/harp-geoutils#GeoCoordinates} from the given screen position.

    remarks

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

    Parameters

    • x: number

      The X position in css/client coordinates (without applied display ratio).

    • y: number

      The Y position in css/client coordinates (without applied display ratio).

    • Optional fallback: undefined | false | true

      Whether to compute a fallback position if the earth surface is not hit.

    Returns GeoCoordinates | null

    Un-normalized geo coordinates

getNormalizedScreenCoordinates

  • getNormalizedScreenCoordinates(x: number, y: number): Vector3

  • Returns the normalized screen coordinates from the given pixel position.

    Parameters

    • x: number

      The X position in css/client coordinates (without applied display ratio).

    • y: number

      The Y position in css/client coordinates (without applied display ratio).

    Returns Vector3

getScreenPosition

  • getScreenPosition(pos: GeoCoordLike | Vector3): Vector2 | undefined

  • Returns the screen position of the given geo or world position.

    Parameters

    Returns Vector2 | undefined

    The screen position in CSS/client coordinates (no pixel ratio applied) or undefined.

getTheme

  • getTheme(): Promise<Theme>

getWorldPositionAt

  • getWorldPositionAt(x: number, y: number, fallback: true): Vector3
  • getWorldPositionAt(x: number, y: number, fallback?: undefined | false | true): Vector3 | null

  • Returns the world space position from the given screen position.

    remarks

    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.

    Parameters

    • x: number

      The X position in css/client coordinates (without applied display ratio).

    • y: number

      The Y position in css/client coordinates (without applied display ratio).

    • fallback: true

      Whether to compute a fallback position if the earth surface is not hit.

    Returns Vector3

  • Returns the world space position from the given screen position.

    remarks

    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.

    Parameters

    • x: number
    • y: number
    • Optional fallback: undefined | false | true

    Returns Vector3 | null

hasEventListener

  • hasEventListener(type: string, listener?: undefined | ((event: Event) => void)): boolean

intersectMapObjects

  • Do a raycast on all objects in the scene. Useful for picking.

    remarks

    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 {@link MapView.render} has been called, this is because {@link 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.

    Parameters

    • x: number

      The X position in css/client coordinates (without applied display ratio).

    • y: number

      The Y position in css/client coordinates (without applied display ratio).

    • Optional parameters: IntersectParams

      The intersection test behaviour may be adjusted by providing an instance of IntersectParams.

    Returns PickResult[]

    The list of intersection results.

isDataSourceEnabled

  • isDataSourceEnabled(dataSource: DataSource): boolean

listeners

  • listeners(type: string): Array<(event: Event) => void> | undefined

loadPostEffects

  • loadPostEffects(postEffectsFile: string): void

lookAt

  • lookAt(params: Partial<LookAtParams>): void
  • lookAt(target: GeoCoordLike, distance: number, tiltDeg?: undefined | number, headingDeg?: undefined | number): void

  • Adjusts the camera to look at a given geo coordinate with tilt and heading angles.

    remarks

    Note on target and bounds

    If 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
    {@link @here/harp-geoutils#GeoBox} defined params.target is used
    {@link @here/harp-geoutils#GeoBox} undefined bounds.center is used as new target
    {@link @here/harp-geoutils#GeoBoxExtentLike} undefined current MapView.target is used
    {@link @here/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 MapViewOptions.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``.

    Examples

     
    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.

    Parameters

    Returns void

  • The method that sets the camera to the desired angle (tiltDeg) and distance (in meters) to the target location, from a certain heading (headingAngle).

    remarks
    deprecated

    Use lookAt version with LookAtParams object parameter.

    Parameters

    • target: GeoCoordLike

      The location to look at.

    • distance: number

      The distance of the camera to the target in meters.

    • Optional tiltDeg: undefined | number

      The camera tilt angle in degrees (0 is vertical), curbed below 89deg @default 0

    • Optional headingDeg: undefined | number

      The camera heading angle in degrees and clockwise (as opposed to yaw) @default 0 starting north.

    Returns void

markTilesDirty

  • markTilesDirty(dataSource?: DataSource, filter?: undefined | ((tile: Tile) => boolean)): void

  • Visit each tile in visible, rendered, and cached sets.

    remarks
    • Visible and temporarily rendered tiles will be marked for update and retained.
    • Cached but not rendered/visible will be evicted.

    Parameters

    • Optional dataSource: DataSource

      If passed, only the tiles from this DataSource instance are processed. If undefined, tiles from all DataSources are processed.

    • Optional filter: undefined | ((tile: Tile) => boolean)

      Optional tile filter

    Returns void

ndcToView

  • ndcToView(vector: Vector3Like, result: Vector3): Vector3

removeAllEventListeners

  • removeAllEventListeners(): void

removeDataSource

removeDynamicProperty

  • removeDynamicProperty(name: string): void

  • Removes the given dynamic property from this MapView.

    remarks

    Property names starting with a $-sign are reserved and any attempt to change their value will result in an error.

    Parameters

    • name: string

      The name of the property to remove.

    Returns void

removeEventListener

renderSync

  • renderSync(frameStartTime?: undefined | number): void

  • Redraws scene immediately

    remarks
    note

    Before using this method, set synchronousRendering to true in the MapViewOptions

    Parameters

    • Optional frameStartTime: undefined | number

      Optional timestamp for start of frame. Default: [[PerformanceTimer.now()]]

    Returns void

requestUpdateIfNeeded

  • requestUpdateIfNeeded(): void

resetTextRenderer

resize

  • resize(width: number, height: number): void

  • Resize the HTML canvas element and the THREE.js WebGLRenderer.

    Parameters

    • width: number

      The new width.

    • height: number

      The new height.

    Returns void

setCacheSize

  • setCacheSize(size: number, numVisibleTiles?: undefined | number): void

  • Sets the cache size in number of tiles.

    Parameters

    • size: number

      The cache size in tiles.

    • Optional numVisibleTiles: undefined | number

      The number of tiles visible, which is size/2 by default.

    Returns void

setCameraGeolocationAndZoom

  • setCameraGeolocationAndZoom(geoPos: GeoCoordinates, zoomLevel: number, yawDeg?: number, pitchDeg?: number): void

  • Moves the camera to the specified {@link @here/harp-geoutils#GeoCoordinates}, sets the desired zoomLevel and adjusts the yaw and pitch.

    remarks

    The pitch of the camera is always curbed so that the camera cannot look above the horizon. This paradigm is necessary in {@link @here/harp-map-controls#MapControls}, where the center of the screen is used for the orbiting interaction (3 fingers / right mouse button).

    deprecated

    Use {@link (MapView.lookAt:WITH_PARAMS)} instead.

    Parameters

    • geoPos: GeoCoordinates

      Geolocation to move the camera to.

    • zoomLevel: number

      Desired zoom level.

    • Default value yawDeg: number = 0

      Camera yaw in degrees, counter-clockwise (as opposed to heading), starting north.

    • Default value pitchDeg: number = 0

      Camera pitch in degrees.

    Returns void

setDynamicProperty

  • setDynamicProperty(name: string, value: Value): void

  • Updates the value of a dynamic property.

    remarks

    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"]]

    Parameters

    • name: string

      The name of the property.

    • value: Value

      The value of the property.

    Returns void

setElevationSource

  • Sets the DataSource which contains the elevations, the elevation range source, and the elevation provider.

    remarks

    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.

    Parameters

    • elevationSource: DataSource

      The datasource containing the terrain tiles.

    • elevationRangeSource: ElevationRangeSource

      Allows access to the elevation min / max per tile.

    • elevationProvider: ElevationProvider

      Allows access to the elevation at a given location or a ray from the camera.

    Returns Promise<void>

setFovCalculation

  • Set's the way in which the fov is calculated on the map view.

    remarks

    Note, for this to take visual effect, the map should be rendered after calling this function.

    Parameters

    Returns void

setTheme

update

  • update(): void

Generated using TypeDoc