Map | XYZ Maps Documentation

XYZ Map is a highly customizable WebGL based vector map display that's optimized for map editing, larger raw datasets and frequently changing data.

Hierarchy

Index

Constructors

constructor

Constructors

constructor

new Map(mapEl: HTMLElement, options: MapOptions): Map

example

import {Map} from '@here/xyz-maps-display';

//create map display
const display = new Map( mapDiv, {
    zoomLevel : 19,
    center: {
        longitude: 8.53422,
        latitude: 50.16212
    },
    // add layers to display
    layers: layers
});

Parameters

mapEl: HTMLElement

HTMLElement used to create the map display
options: MapOptions

options to configure for the map

Returns Map

Methods

addEventListener

addEventListener(type: string, listener: (e: MapEvent) => void): void

Adds an event listener to the map. supported events: 'mapviewchangestart', 'mapviewchange', 'mapviewchangeend', 'resize', 'tap', 'dbltap', 'pointerup', 'pointerenter', 'pointerleave', 'pointerdown', 'pointermove', 'pressmove'

Parameters
- type: string
  
  A string representing the event type to listen for.
- listener: (e: MapEvent) => void
  
  the listener function that will be called when an event of the specific type occurs
  - - (e: MapEvent): void
    - Parameters
      - e: MapEvent
      Returns void
Returns void

addLayer

addLayer(layer: TileLayer | CustomLayer, index?: number): void

Adds a layer to the map. If index is defined the layer will be placed at respective index in the layer hierarchy. Otherwise it's added on top (last).

Parameters
- layer: TileLayer | CustomLayer
  
  the layer to add
- Optional index: number
  
  the index in layer hierarchy where the layer should be inserted.
Returns void

addObserver

addObserver(name: string, observer: (name: string, newValue: any, prevValue: any) => void): boolean

Add an observer to the map. Supported observers are: "zoomlevel", "center", "rotation" and "pitch".

Parameters
- name: string
  
  the name of the value to observe
- observer: (name: string, newValue: any, prevValue: any) => void
  
  the observer that will be executed on value changes.
  - - (name: string, newValue: any, prevValue: any): void
    - Parameters
      - name: string
      - newValue: any
      - prevValue: any
      Returns void
Returns boolean

boolean that's indicating if observer was added.

destroy

destroy(): void

Destroy the the map.

Returns void

flyTo

flyTo(center: GeoPoint, options?: { duration?: number }): any
flyTo(center: GeoPoint, zoomTo: number, options?: { duration?: number }): any

Set the map center using a bow animation combining pan and zoom operations.

Parameters
- center: GeoPoint
  
  the geographical coordinate to center the map.
- Optional options: { duration?: number }
  
  options to configure the bow animation
  - Optional duration?: number
    
    the duration of the bow animation in milliseconds
Returns any
Set the map center and zoomlevel using a bow animation combining pan and zoom operations.

Parameters
- center: GeoPoint
  
  the geographical coordinate to center the map.
- zoomTo: number
  
  the zoomlevel the map should be zoomed to.
- Optional options: { duration?: number }
  
  options to configure the bow animation
  - Optional duration?: number
    
    the duration of the bow animation in milliseconds
Returns any

geoToPixel

geoToPixel(longitude: number, latitude: number, altitude?: number): PixelPoint
geoToPixel(coordinate: GeoPoint): PixelPoint

Convert a geographical coordinate to a pixel coordinate relative to the current viewport of the map.

Parameters
- longitude: number
  
  the longitude in degrees
- latitude: number
  
  the latitude in degrees
- Optional altitude: number
  
  the altitude in meters
Returns PixelPoint

the pixel coordinate relative to the current viewport.
Convert a geographical coordinate to a pixel coordinate relative to the current viewport of the map.

Parameters
- coordinate: GeoPoint
  
  the geographical coordinate
Returns PixelPoint

the pixel coordinate relative to the current viewport.

getBehavior

getBehavior(): { drag: boolean; pitch: boolean; rotate: boolean; zoom: boolean }

Get current active map behavior options.

Returns { drag: boolean; pitch: boolean; rotate: boolean; zoom: boolean }
- drag: boolean
  
  indicates if map dragging is enabled or disabled.
- pitch: boolean
  
  indicates if map pitching is enabled or disabled.
- rotate: boolean
  
  indicates if map rotation is enabled or disabled.
- zoom: boolean
  
  indicates if map zooming is enabled or disabled.

getCamera

getCamera(): { position: { altitude: number; latitude: number; longitude: number } }

Get the camera of the current viewport.

experimental

Returns { position: { altitude: number; latitude: number; longitude: number } }
- position: { altitude: number; latitude: number; longitude: number }
  
  The camera's center position in geographical coordinates (world-space).
  - altitude: number
  - latitude: number
  - longitude: number

getCenter

getCenter(): GeoPoint

Get the current geographical center of the map.

Returns GeoPoint

the map's geographical center point.

getContainer

getContainer(): HTMLElement

Get the HTMLElement used by the map.

Returns HTMLElement

getFeatureAt

getFeatureAt(position: PixelPoint | PixelRect, options?: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }): { feature: Feature; layer: TileLayer } | undefined

Get most top rendered feature within the given area of map

Parameters
- position: PixelPoint | PixelRect
  
  Point or Rect in pixel to define search area. If a Point is used, width and height must be passed in options parameter.
- Optional options: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }
  
  Describing the options param
  - Optional height?: number
    
    height in pixel of rectangle if point geometry is used.
  - Optional layers?: TileLayer | TileLayer[]
    
    defines the layer(s) to search in.
  - Optional width?: number
    
    width in pixel of rectangle if point geometry is used.
Returns { feature: Feature; layer: TileLayer } | undefined

The result providing found feature and layer. undefined is returned if nothing is found.

getFeaturesAt

getFeaturesAt(position: PixelPoint | PixelRect, options?: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }): { features: Feature[]; layer: TileLayer }[]

Get rendered features within the given area of map

Parameters
- position: PixelPoint | PixelRect
  
  Point or Rect in pixel to define search area. If a Point is used, width and height must be passed in options parameter.
- Optional options: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }
  
  Describing the options param
  - Optional height?: number
    
    height in pixel of rectangle if point geometry is used.
  - Optional layers?: TileLayer | TileLayer[]
    
    defines the layer(s) to search in.
  - Optional width?: number
    
    width in pixel of rectangle if point geometry is used.
Returns { features: Feature[]; layer: TileLayer }[]

zIndex ordered results array

getHeight

getHeight(): number

Get the current height in pixels of map.

Returns number

getLayers

getLayers(): TileLayer[]
getLayers(index: number): TileLayer

Get the current added layer(s) of the map.

Returns TileLayer[]

the layer(s) that are added to the map
Get a specific Layer of the map.

Parameters
- index: number
  
  get a specific layer at index in the layer hierarchy
Returns TileLayer

the layer that is added to the map

getViewBounds

getViewBounds(): GeoRect

Gets the current view bounds of the view port.

Returns GeoRect

getWidth

getWidth(): number

Get the current width in pixels of map.

Returns number

getZoomlevel

getZoomlevel(): number

Get the current zoom level

Returns number

the current zoom level of the map

lockViewport

lockViewport(): { maxLevel: number; minLevel: number; pan: boolean }
lockViewport(options: { maxLevel?: number; minLevel?: number; pan?: boolean }): { maxLevel: number; minLevel: number; pan: boolean }

get the current applied lock status of the map.

Returns { maxLevel: number; minLevel: number; pan: boolean }

the current applied lock options.
- maxLevel: number
- minLevel: number
- pan: boolean
set lock the viewport of the map. by indicating if panning, minLevel and maxLevel should be locked.

Parameters
- options: { maxLevel?: number; minLevel?: number; pan?: boolean }
  
  the lock options.
  - Optional maxLevel?: number
    
    the maximum allowed zoom level that can be zoomed to.
  - Optional minLevel?: number
    
    the minimum allowed zoom level that can be zoomed to.
  - Optional pan?: boolean
    
    true to enable panning, false to disable panning.
Returns { maxLevel: number; minLevel: number; pan: boolean }

the current applied lock options.
- maxLevel: number
- minLevel: number
- pan: boolean

pan

pan(dx: number, dy: number): void

Shift the geographical center of the map in pixels.

Parameters
- dx: number
  
  distance in pixels to pan the map on x axis
- dy: number
  
  distance in pixels to pan the map on y axis
Returns void

pitch

pitch(pitch?: number): number

Set or get map pitch (tilt) in degrees

Parameters
- Optional pitch: number
  
  pitch in degrees
Returns number

pixelToGeo

pixelToGeo(x: number, y: number): GeoPoint
pixelToGeo(position: PixelPoint): GeoPoint

Converts from screen pixel to geo coordinate

Parameters
- x: number
  
  the x position on screen in pixel
- y: number
  
  the y position on screen in pixel
Returns GeoPoint

the geographical coordinate
Converts from screen pixel to geo coordinate

Parameters
- position: PixelPoint
  
  the pixel coordinate on screen
Returns GeoPoint

the geographical coordinate

refresh

refresh(layers?: TileLayer | Layer | (TileLayer | Layer)[]): void

Refresh the map view. Manually trigger re-rendering of specific layer(s) of the map.

Parameters
- Optional layers: TileLayer | Layer | (TileLayer | Layer)[]
  
  the layer(s) that should be refreshed/re-rendered.
Returns void

removeEventListener

removeEventListener(type: string, listener: (e: MapEvent) => void): void

Removes an event listener to the map.

Parameters
- type: string
  
  A string representing the event type to listen for.
- listener: (e: MapEvent) => void
  
  The EventListener function of the event handler to remove from the editor.
  - - (e: MapEvent): void
    - Parameters
      - e: MapEvent
      Returns void
Returns void

removeLayer

removeLayer(layer: TileLayer | CustomLayer): void

Remove a layer from the map.

Parameters
- layer: TileLayer | CustomLayer
  
  the layer to remove
Returns void

removeObserver

removeObserver(name: string, observer: (name: string, newValue: any, prevValue: any) => void): boolean

Removes an observer from the map.

Parameters
- name: string
  
  the name of the value to observe
- observer: (name: string, newValue: any, prevValue: any) => void
  
  the observer that should be removed.
  - - (name: string, newValue: any, prevValue: any): void
    - Parameters
      - name: string
      - newValue: any
      - prevValue: any
      Returns void
Returns boolean

boolean that's indicating if observer was removed.

resize

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

Resize the map view. If no width/height is passed the map will resize automatically to the maximum possible size defined by the HTMLElement.

Parameters
- Optional width: number
  
  new width in pixels
- Optional height: number
  
  new height in pixels
Returns void

rotate

rotate(rotation?: number): number

Set or get map rotation along z-axis

Parameters
- Optional rotation: number
  
  set absolute map rotation in degrees
Returns number

current applied rotation in degrees

setBackgroundColor

setBackgroundColor(color: Color): void

Set the background color of the map

Parameters
- color: Color
  
  the background color to set
Returns void

setBehavior

setBehavior(options: { drag?: boolean; pitch?: boolean; rotate?: boolean; zoom?: boolean }): void
setBehavior(behavior: string, active: boolean): any

Set the map behavior on user interaction.
example
```
// to deactivate map zoom on mouse scroll:
setBehavior({zoom: false, drag: true});
```
Parameters
- options: { drag?: boolean; pitch?: boolean; rotate?: boolean; zoom?: boolean }
  
  Behavior options
  - Optional drag?: boolean
    
    true to enable map dragging, false to disable.
  - Optional pitch?: boolean
    
    true to enable map pitching, false to disable.
  - Optional rotate?: boolean
    
    true to enable map rotation, false to disable.
  - Optional zoom?: boolean
    
    true to enable map zooming, false to disable.
Returns void
Enable/Disable a specific map behavior on user interaction. Possible behavior are: "zoom", "drag", "pitch" and "rotate
example
```
// to deactivate map zoom on mouse scroll:
setBehavior('zoom',true);
```
Parameters
- behavior: string
  
  the behavior that should be disabled or enabled.
- active: boolean
  
  true to enable, false to disable
Returns any

setCenter

setCenter(center: GeoPoint): any
setCenter(longitude: number | GeoPoint, latitude: number): any

Set new geographical center for the map.
example
```
display.setCenter({longitude: 8.53422, latitude: 50.16212});
```
Parameters
- center: GeoPoint
  
  the geographical coordinate to center the map
Returns any
Set new geographical center for the map.
example
```
display.setCenter(8.53422, 50.16212);
```
Parameters
- longitude: number | GeoPoint
- latitude: number
  
  latitude to center the map
Returns any

setViewBounds

setViewBounds(bounds: GeoRect | [number, number, number, number] | GeoJSONFeature | GeoJSONFeature[] | GeoJSONFeatureCollection, animate?: boolean): any
setViewBounds(bounds: GeoRect | [number, number, number, number] | GeoJSONFeature | GeoJSONFeature[] | GeoJSONFeatureCollection, animationOptions?: { duration?: number }): any

Set view bounds for the map to display.

Parameters
- bounds: GeoRect | [number, number, number, number] | GeoJSONFeature | GeoJSONFeature[] | GeoJSONFeatureCollection
  
  GeoRect, GeoJson Feature or an GeoJson bbox [minLon, minLat, maxLon, maxLat] defining the view bounds.
- Optional animate: boolean
  
  animate using a bow animation @see Map.flyTo. true to enable, false to disable.
Returns any
Set view bounds for the map to display.

Parameters
- bounds: GeoRect | [number, number, number, number] | GeoJSONFeature | GeoJSONFeature[] | GeoJSONFeatureCollection
  
  GeoRect, GeoJson Feature or an GeoJson bbox [minLon, minLat, maxLon, maxLat] defining the view bounds.
- Optional animationOptions: { duration?: number }
  
  options to configure the bow animation @see Map.flyTo.
  - Optional duration?: number
    
    the duration of the bow animation in milliseconds
Returns any

setZoomlevel

setZoomlevel(zoomTo: number, fixedX?: number, fixedY?: number, animate?: number): void

Set zoomlevel with an optional anchor point.

Parameters
- zoomTo: number
  
  new zoomlevel
- Optional fixedX: number
  
  x coordinate of fixed anchor point on screen in pixels
- Optional fixedY: number
  
  y coordinate of fixed anchor point on screen in pixels
- Optional animate: number
  
  zoom transition animation time in milliseconds [default: 0]
Returns void

snapshot

snapshot(callback: (screenshot: HTMLCanvasElement) => void, dx?: number, dy?: number, width?: number, height?: number): void

Take a snapshot of the current map's viewport.

Parameters
- callback: (screenshot: HTMLCanvasElement) => void
  
  Callback function that will be called when the requested snapshot has been captured.
  - - (screenshot: HTMLCanvasElement): void
    - Parameters
      - screenshot: HTMLCanvasElement
      Returns void
- Optional dx: number
  
  x coordinate of the left edge of the capturing rectangle in pixel
- Optional dy: number
  
  y coordinate of the top edge of the capturing rectangle in pixel
- Optional width: number
  
  width of the capturing rectangle in pixel
- Optional height: number
  
  height of the capturing rectangle in pixel
Returns void

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

mapEl: HTMLElement

options: MapOptions

Returns Map

Methods

addEventListener

Parameters

type: string

listener: (e: MapEvent) => void

Parameters

e: MapEvent

Returns void

Returns void

addLayer

Parameters

layer: TileLayer | CustomLayer

Optional index: number

Returns void

addObserver

Parameters

name: string

observer: (name: string, newValue: any, prevValue: any) => void

Parameters

name: string

newValue: any

prevValue: any

Returns void

Returns boolean

destroy

Returns void

flyTo

Parameters

center: GeoPoint

Optional options: { duration?: number }

Optional duration?: number

Returns any

Parameters

center: GeoPoint

zoomTo: number

Optional options: { duration?: number }

Optional duration?: number

Returns any

geoToPixel

Parameters

longitude: number

latitude: number

Optional altitude: number

Returns PixelPoint

Parameters

coordinate: GeoPoint

Returns PixelPoint

getBehavior

Returns { drag: boolean; pitch: boolean; rotate: boolean; zoom: boolean }

drag: boolean

pitch: boolean

rotate: boolean

zoom: boolean

getCamera

Returns { position: { altitude: number; latitude: number; longitude: number } }

position: { altitude: number; latitude: number; longitude: number }

altitude: number

latitude: number

longitude: number

getCenter

Returns GeoPoint

getContainer

Returns HTMLElement

getFeatureAt

Parameters

position: PixelPoint | PixelRect

Optional options: { height?: number; layers?: TileLayer | TileLayer[]; width?: number }

Optional height?: number

Optional layers?: TileLayer | TileLayer[]

Optional width?: number