Static

Events

Global

Documentation

Class

Parameters
NameTypeDefaultOptionalDescription
optionsObjectoptional

OSMBuildings options

options.containerString

A DOM Element or its id to append the viewer to

options.minZoomNumber14.5

Global minimum allowed zoom

options.maxZoomNumber20

Global maximum allowed zoom

options.boundsObjectoptional

A bounding box to restrict the map to

options.stateBooleanfalse

Store the map state in the URL

options.disabledBooleanfalse

Disable user input

options.attributionStringoptional

An attribution string

options.zoomNumberminZoom..maxZoom

Initial zoom, default is middle between global minZoom and maxZoom

options.rotationNumber

Initial rotation

options.tiltNumber

Initial tilt

options.positionObjectoptional

Initial position

options.position.latitudeNumber52.520000

position latitude

options.position.longitudeNumber13.410000

Position longitude

options.baseURLString'.'

For locating assets. This is relative to calling html page

YESSSSSS
options.showBackfacesBooleanfalse

Render front and backsides of polygons. false increases performance, true might be needed for bad geometries

YESSSSSS
options.fogColorString'#e8e0d8'

Color to be used for sky gradients and distance fog

YESSSSSS
options.highlightColorString'#f08000'

Default color for highlighting features

YESSSSSS
options.effectsArray[]

Which effects to enable. The only effect at the moment is 'shadows'

YESSSSSS
options.backgroundColorString'#efe8e0'

Overall background color

options.fastModeBooleanfalse

Enables faster rendering at cost of image quality.

options.styleObjectoptional

Sets the default building style

options.style.colorString'rgb(220, 210, 200)'

Sets the default building color

Methods

addGeoJSON

Adds a GeoJSON object to the map.

Parameters
NameTypeDefaultOptionalDescription
urlString

URL of the GeoJSON file or a JavaScript Object representing a GeoJSON FeatureCollection

optionsObjectoptional

Options to apply to the GeoJSON being rendered

options.scaleNumber1

Scale the model by this value before rendering

options.rotationNumber

Rotate the model by this much before rendering

options.altitudeNumber

The height above ground to place the model at

options.idStringoptional

An identifier for the object. This is used for getting info about the object later

options.colorStringoptional

A color to apply to the model

options.minZoomNumber14.5

Minimum zoom level to show this feature, defaults to and limited by global minZoom

options.maxZoomNumbermaxZoom

Maximum zoom level to show this feature, defaults to and limited by global maxZoom

options.fadeInBooleantrue

Fade GeoJSON features; if false , then display immediately

YESSSSSS
Returns
TypeDescription
Object

The added object

addGeoJSONTiles

Adds a GeoJSON tile layer to the map. This is for continuous building coverage.

Parameters
NameTypeDefaultOptionalDescription
urlStringhttps://{s}.data.osmbuildings.org/0.2/{k}/tile/{z}/{x}/{y}.json

url The URL of the GeoJSON tile server

optionsObject{}optional
options.fixedZoomNumber15

Tiles are fetched for this zoom level only. Other zoom levels are scaled up/down to this value

options.minZoomNumber14.5

Minimum zoom level to show features from this layer. Defaults to and limited by global minZoom.

options.maxZoomNumbermaxZoom

Maximum zoom level to show features from this layer. Defaults to and limited by global maxZoom.

Returns
TypeDescription
Object

The added layer object

addMapTiles

Adds a 2d base map source. This renders below the buildings.

Parameters
NameTypeDefaultOptionalDescription
urlString

The URL of the map server. This could be from Mapbox or other tile servers

Returns
TypeDescription
Object

The added layer object

addMarker

Adds a marker to the map in 3d space.

Parameters
NameTypeDefaultOptionalDescription
positionObject

geographic position including altitude

position.latitudeNumber

latitude

position.longitudeNumber

longitude

position.altitudeNumber

altitude in meters

dataObjectoptional

custom data properties to attach to the marker, i.e. an id

optionsObjectoptional

additional options

options.urlStringoptional

url to an SVG file to use as custom marker. Currently only path properties are supported. Overlapping path's may create strange results.

options.colorStringoptional

color which whole marker will be tinted

Returns
TypeDescription
Object

Marker

addOBJ

Adds an 3d object (OBJ format) file to the map. Important objects with exactly the same url are cached and only loaded once.

Parameters
NameTypeDefaultOptionalDescription
urlString

URL of the OBJ file

positionObject

Where to render the object

position.latitudeNumber

Position latitude for the object

position.longitudeNumber

Position longitude for the object

optionsObject{}optional

Options for rendering the object

options.scaleNumber1

Scale the model by this value before rendering

options.rotationNumber

Rotate the model by this much before rendering

options.altitudeNumber

The height above ground to place the model at

options.idStringoptional

An identifier for the object. This is used for getting info about the object later

options.colorStringoptional

A color to apply to the model

Returns
TypeDescription
Object

The added object

destroy

Destroys the map

emit

Triggers a specific event

Parameters
NameTypeDefaultOptionalDescription
eventString

Event type to listen for

getBounds

Returns geographical bounds of the current view

  • since the bounds are always axis-aligned they will contain areas that are not currently visible if the current view is not also axis-aligned.

  • The bounds only contain the map area that OSMBuildings considers for rendering. OSMBuildings has a rendering distance of about 3.5km, so the bounds will never extend beyond that, even if the horizon is visible (in which case the bounds would mathematically be infinite).

  • the bounds only consider ground level. For example, buildings whose top is seen at the lower edge of the screen, but whose footprint is outside

  • The bounds only consider ground level. For example, buildings whose top is seen at the lower edge of the screen, but whose footprint is outside of the current view below the lower edge do not contribute to the bounds. so their top may be visible and they may still be out of bounds.

Returns
TypeDescription
Array

Bounding coordinates in unspecific order { latitude, longitude }, ...

getPosition

Get map's current geographic position

Returns
TypeDescription
Object

Geographic position { latitude, longitude }

getRotation

Get map's current rotation

Returns
TypeDescription
Number

Rotation in degrees

getSize

Get map's current view size in pixels

Returns
TypeDescription
Object

View size { width, height }

getTilt

Get map's current tilt

Returns
TypeDescription
Number

Tilt in degrees

getZoom

Get current zoom level

Returns
TypeDescription
Number

zoom level

hide

This replaces any previous show/hide rule.

highlight

This replaces any previous highlighting.

isDisabled

Checks for map interaction disabled

Returns
TypeDescription
Boolean

flag

off

Removes an even listener

Parameters
NameTypeDefaultOptionalDescription
typeString

Event type to listen for

fneventCallbackoptional

If callback is given, only remove that particular listener

on

Adds an event listener

Parameters
NameTypeDefaultOptionalDescription
typeString

Event type to listen for

fneventCallback

Callback function

project

Gets 2d screen position from a 3d point

Parameters
NameTypeDefaultOptionalDescription
latitudeNumber

Latitude of the point

longitudeNumber

Longitude of the point

altitudeNumber

Altitude of the point

Returns
TypeDescription
Object

Screen position in pixels { x, y }

remove

Removes a feature, layer or marker from the map.

setDate

Set date for shadow calculations

Parameters
NameTypeDefaultOptionalDescription
dateDate

setDisabled

Disables map interaction

Parameters
NameTypeDefaultOptionalDescription
flagBoolean

setPosition

Set map's geographic position

Parameters
NameTypeDefaultOptionalDescription
posObject

The new position

pos.latitudeNumber
pos.longitudeNumber

setRotation

Set map's rotation

Parameters
NameTypeDefaultOptionalDescription
rotationNumber

The new rotation angle in degrees

setSize

Set map view's size in pixels

Parameters
NameTypeDefaultOptionalDescription
widthInteger
heightInteger
sizeObject

YESSSSSS
size.widthInteger

YESSSSSS
size.heightInteger

YESSSSSS

setTilt

Set map's tilt

Parameters
NameTypeDefaultOptionalDescription
tiltNumber

The new tilt in degree

setZoom

Set zoom level

Parameters
NameTypeDefaultOptionalDescription
zoomNumber

The new zoom level

unproject

Turns a screen point (x, y) into a geographic position (latitude/longitude/altitude=0). Returns 'undefined' if point would be invisible or lies above horizon.

Parameters
NameTypeDefaultOptionalDescription
xNumber

X position on screen

yNumber

Y position om screen

Returns
TypeDescription
Object

Geographic position { latitude, longitude }

Static

ATTRIBUTION

(String) OSMBuildings attribution

VERSION

(String) OSMBuildings version

Events

busy

Fired when data loading starts

change

Fired when map view has been changed, i.e. zoom, pan, tilt, rotation

doubleclick

Fired when map container has been double clicked/tapped

gesture

Fired when gesture has been performed on the map

idle

Fired when data loading ends

loadfeature

Fired when a 3d object has been loaded

pointerdown

Fired when map container has been clicked/tapped

pointermove

Fired when mouse/finger has been moved

pointerup

Fired when mouse button/finger been lifted

resize

Fired when map container has been resized

rotate

Fired when map view has been rotated

tilt

Fired when map view has been tilted

zoom

Fired when map has been zoomed

Global

eventCallback

User defined function that will be called when an event is fired

Parameters
NameTypeDefaultOptionalDescription
typeString

Event type

payloadanyoptional

Payload of any type

selectorCallback

User defined function that will be called on each feature, for modification before rendering

Parameters
NameTypeDefaultOptionalDescription
idString

The feature's id

featureObject

The feature