Documentation

Class

OSMBuildings

Parameters
NameTypeDefaultOptionalDescription
optionsObjectoptional

OSMBuildings options

options.minZoomNumber1

Global minimum allowed zoom

options.maxZoomNumber1

Global maximum allowed zoom

options.boundsObjectoptional

A bounding box to restrict the map to

options.stateBoolean1

Store the map state in the URL

options.disabledBoolean1

Disable user input

options.attributionStringoptional

An attribution string

options.zoomNumber1

Initial zoom, default is middle between global minZoom and maxZoom

options.rotationNumber

Initial rotation

options.tiltNumber

Initial tilt

options.positionObjectoptional

Initial position

options.position.latitudeNumber1

position latitude

options.position.longitudeNumber1

Position longitude

options.baseURLString1

For locating assets. This is relative to calling html page

options.showBackfacesBoolean1

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

options.fogColorString1

Color to be used for sky gradients and distance fog

options.backgroundColorString1

Overall background color

options.highlightColorString1

Default color for highlighting features

options.fastModeBoolean1

Enables faster rendering at cost of image quality. If performance is an issue, consider also removing effects

options.effectsArray1

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

options.styleObjectoptional

Sets the default building style

options.style.colorString1

Sets the default building color

Methods

addGeoJSON

Adds a GeoJSON object to the map.
In order to remove the object use myObj.destroy()

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

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

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

options.maxZoomNumber1

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

options.fadeInBoolean1

Fade GeoJSON features; if false, then display immediately

Returns
TypeDescription
Object

The added object

addGeoJSONTiles

Adds a GeoJSON tile layer to the map.
This is for continuous building coverage.
In order to remove the layer use myLayer.destroy()

Parameters
NameTypeDefaultOptionalDescription
urlString1

url The URL of the GeoJSON tile server

optionsObjectoptional
options.fixedZoomNumber1

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

options.colorStringoptional

A color to apply to all features on this layer

options.minZoomNumber1

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

options.maxZoomNumber1

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

options.fadeInBoolean1

Fade GeoJSON features. If false, then display immediately.

Returns
TypeDescription
Object

The added layer object

addMapTiles

Adds a 2d base map source. This renders below the buildings.
In order to remove the layer use myLayer.destroy()

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

addOBJ

Adds an 3D object (OBJ format) file to the map.
Important: objects with exactly the same url are cached and only loaded once.
In order to remove the object, use myObj.destroy()

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

optionsObjectoptional

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

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

appendTo

Adds OSMBuildings to DOM container

Parameters
NameTypeDefaultOptionalDescription
widthIntegeroptional

Enforce width of container

heightIntegeroptional

Enforce height of container

destroy

Destroys the map

emit

Trigger a specific event

Parameters
NameTypeDefaultOptionalDescription
payloadanyoptional

Any kind of payload

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 }

getTarget

Returns the feature from a position on the screen. Works asynchronous.

Parameters
NameTypeDefaultOptionalDescription
xInteger

X coordinate (in pixels) of position on the screen

yInteger

Y coordinate (in pixels) of position on the screen

callbackgetTargetCallback

Callback function that receives the object

getTilt

Get map's current tilt

Returns
TypeDescription
Number

Tilt in degrees

getZoom

Get current zoom level

Returns
TypeDescription
Number

zoom level

hide

Sets a function that defines which objects to hide on this layer

Parameters
NameTypeDefaultOptionalDescription
selectorselectorCallback

A function that will get run on each feature, and returns a boolean indicating whether or not to hide the feature

durationInteger

How long to fade in the feature

highlight

Highlight a given feature by id.
Currently, the highlight can only be applied to one feature.
Set id to null in order to un-highlight.

Parameters
NameTypeDefaultOptionalDescription
idString

The feature's id. For OSM buildings, it's the OSM id. For other objects, it's whatever is defined in the options passed to it.

highlightColorString

An optional color string to be used for highlighting

off

Removes event listeners

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

Get screen position from a 3d point

Parameters
NameTypeDefaultOptionalDescription
latitudeNumber

Latitude of the point

longitudeNumber

Longitude of the point

elevationNumber

Elevation of the point

Returns
TypeDescription
Object

Screen position in pixels { x, y }

screenshot

Take a screenshot. Works asynchronous.

Parameters
NameTypeDefaultOptionalDescription
callbackscreenshotCallback

Callback function that receives the screenshot

setDate

Set date for shadow calculations

Parameters
NameTypeDefaultOptionalDescription
dateDate

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
sizeObject
size.widthInteger
size.heightInteger

setTilt

Set map's tilt

Parameters
NameTypeDefaultOptionalDescription
tiltNumber

The new tilt in degree

setZoom

Set zoom level

Parameters
NameTypeDefaultOptionalDescription
zoomNumber

The new zoom level

show

Sets a function that selects objects to show on this layer

Parameters
NameTypeDefaultOptionalDescription
selectorselectorCallback

A function that will get run on each feature, and returns a boolean indicating whether or not to show the feature

durationInteger

How long to fade out the feature

unproject

Turns a screen point (x, y) into a geographic position (latitude/longitude/elevation=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

getTargetCallback

User defined callback function for getTarget()

Parameters
NameTypeDefaultOptionalDescription
featureObject

The feature

screenshotCallback

User defined callback function for screenshot()

Parameters
NameTypeDefaultOptionalDescription
screenshotImage

The screenshot

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