Class: OSMBuildings

OSMBuildings


new OSMBuildings( [options])

OSMBuildings
Parameters:
Name Type Argument Description
options Object <optional>
OSMBuildings options
Properties
Name Type Argument Default Description
minZoom Number <optional>
14.5 Global minimum allowed zoom
maxZoom Number <optional>
20 Global maximum allowed zoom
bounds Object <optional>
A bounding box to restrict the map to
state Boolean <optional>
false Store the map state in the URL
disabled Boolean <optional>
false Disable user input
attribution String <optional>
An attribution string
zoom Float <optional>
minZoom..maxZoom Initial zoom, default is middle between global minZoom and maxZoom
rotation Float <optional>
0 Initial rotation
tilt Float <optional>
0 Initial tilt
position Object <optional>
Initial position
Properties
Name Type Argument Default Description
latitude Float <optional>
52.520000
latitude Float <optional>
13.410000
baseURL String <optional>
'.' For locating assets. This is relative to calling page
showBackfaces Boolean <optional>
false Render front and backsides of polygons. false increases performance, true might be needed for bad geometries
fogColor String <optional>
'#e8e0d8' Color to be used for sky gradients and distance fog
backgroundColor String <optional>
'#efe8e0' Overall background color
highlightColor String <optional>
'#f08000' Default color for highlighting features
fastMode Boolean <optional>
false Enables faster rendering at cost of image quality. If performance is an issue, consider also removing effects
effects Array <optional>
[] Which effects to enable. The only effect at the moment is 'shadows'
style Object <optional>
{ color: 'rgb(220, 210, 200)' } Sets the default building style

Methods


addGeoJSON(url, options)

Adds a GeoJSON layer to the map
Parameters:
Name Type Description
url String URL of the GeoJSON file or a JavaScript Object representing a GeoJSON FeatureCollection
options Object Options to apply to the GeoJSON being rendered
Properties
Name Type Argument Default Description
scale Number <optional>
1 Scale the model by this value before rendering
rotation Number <optional>
0 Rotate the model by this much before rendering
elevation Number <optional>
<ground height> The height above ground to place the model at
id String <optional>
An identifier for the object. This is used for getting info about the object later
color String <optional>
A color to apply to the model
minZoom Number <optional>
14.5 Minimum zoom level to show this feature, defaults to and limited by global minZoom
maxZoom Number <optional>
maxZoom Maximum zoom level to show this feature, defaults to and limited by global maxZoom
fadeIn Boolean <optional>
true Fade GeoJSON features; if `false`, then display immediately.

addGeoJSONTiles(url, options)

Adds a GeoJSON tile layer, for rendering the 3D buildings
Parameters:
Name Type Description
url String The URL of the GeoJSON tile server, in the correct format
options Object
Properties
Name Type Argument Default Description
fixedZoom Number <optional>
15
bounds Object <optional>
Currently not used
color String <optional>
A color to apply to all features on this layer
modifier OSMBuildings~modifierFunction <optional>
DISCONTINUED. Use 'loadfeature' event instead.
minZoom Number <optional>
14.5 Minimum zoom level to show features from this layer, defaults to and limited by global minZoom
maxZoom Number <optional>
maxZoom Maximum zoom level to show features from this layer, defaults to and limited by global maxZoom
fadeIn Boolean <optional>
true Fade GeoJSON features; if `false`, then display immediately.

addMapTiles(url, options)

Adds a 2D map source, to render below the 3D buildings
Parameters:
Name Type Description
url String The URL of the map server. This could be Mapbox, or any other tile server that supports the right format
options Object
Properties
Name Type Argument Description
fixedZoom Number <optional>
bounds Object <optional>
Currently not used
color String <optional>
A color to apply to all features on this layer

addOBJ(url, position [, options])

Adds an OBJ (3D object) file to the map Important: objects with exactly the same url are cached and only loaded once
Parameters:
Name Type Argument Description
url String URL of the OBJ file
position Object Where to render the OBJ
Properties
Name Type Description
latitude Float Latitude for the OBJ
longitude Float Longitude for the OBJ
options Object <optional>
Options for rendering the OBJ
Properties
Name Type Argument Default Description
scale Number <optional>
1 Scale the model by this value before rendering
rotation Number <optional>
0 Rotate the model by this much before rendering
elevation Number <optional>
<ground height> The height above ground to place the model at
id String <optional>
An identifier for the object. This is used for getting info about the object later
color String <optional>
A color to apply to the model

appendTo(DOM)

Adds the OSMBuildings to DOM container
Parameters:
Name Type Description
DOM HTMLElement | String container or its id to append the map to

destroy()

Destroys the map

emit(event [, fn])

Trigger a specific event
Parameters:
Name Type Argument Description
event String An event identifier to listen for
fn OSMBuildings~eventListenerFunction <optional>
If given, only remove the given function

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:
bounding coordinates in unspecific order [{latitude,longitude},...]
Type
Array

getPosition()

Returns the map's current geographic position
Returns:
Geographic position {latitude,longitude}
Type
Object

getRotation()

Returns the map's current rotation
Returns:
Rotation in degree
Type
Number

getSize()

Returns the map's current view size in pixels
Returns:
View size {width,height}
Type
Object

getTarget(x, y, callback)

Returns the feature from a position on the screen. Works asynchronous.
Parameters:
Name Type Description
x Integer The x coordinate (in pixels) of position on the screen
y Integer The y coordinate (in pixels) of position on the screen
callback OSMBuildings~getTargetCallback A callback function that receives the object

getTilt()

Returns the map's current tilt
Returns:
Tilt in degree
Type
Number

getZoom()

Gets current zoom level
Returns:
zoom level
Type
Number

hide(selector [, duration])

Sets a function that defines which objects to hide on this layer
Parameters:
Name Type Argument Default Description
selector OSMBuildings~selectorFunction A function that will get run on each feature, and returns a boolean indicating whether or not to hide the feature
duration Integer <optional>
0 How long to hide the feature for

highlight(id, highlightColor)

Highlight a given feature by id. Currently, the highlight can only be applied to one feature. Set id = `null` in order to un-highlight
Parameters:
Name Type Description
id String 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.
highlightColor String An optional color string to be used for highlighting

off(event [, fn])

Removes event listeners
Parameters:
Name Type Argument Description
event String An event identifier to listen for
fn OSMBuildings~eventListenerFunction <optional>
If given, only remove the given function

on(event, callback)

Adds an event listener
Parameters:
Name Type Description
event String An event identifier to listen for
callback OSMBuildings~eventListenerFunction

project(latitude, longitude, elevation)

Returns the screen position of the point
Parameters:
Name Type Description
latitude Float Latitude of the point
longitude Float Longitude of the point
elevation Float Elevation of the point
Returns:
Screen position in pixels {x,y}
Type
Object

remove()

DEPRECATED

screenshot(callback)

Take a screenshot. Works asynchronous.
Parameters:
Name Type Description
callback OSMBuildings~screenshotCallback A callback function that receives the screenshot

setDate(date)

Sets the date for shadow calculations
Parameters:
Name Type Description
date Date

setPosition(pos)

Sets the map's geographic position
Parameters:
Name Type Description
pos Object The new position
Properties
Name Type Description
latitude Float
longitude Float
Fires:

setRotation(rotation)

Set's the map's rotation
Parameters:
Name Type Description
rotation Float The new rotation angle
Fires:

setSize(size)

Sets the map view's size in pixels
Parameters:
Name Type Description
size Object
Properties
Name Type Description
width Integer
height Integer
Fires:

setStyle()

DEPRECATED. This should be done initially or on feature basis

setTilt(tilt)

Sets the map's tilt
Parameters:
Name Type Description
tilt Float The new tilt
Fires:

setZoom(zoom, e)

Sets the zoom level
Parameters:
Name Type Description
zoom Float The new zoom level
e Object **Not currently used**
Fires:

show(selector [, duration])

Sets a function that defines which objects to show on this layer
Parameters:
Name Type Argument Default Description
selector OSMBuildings~selectorFunction A function that will get run on each feature, and returns a boolean indicating whether or not to show the feature
duration Integer <optional>
0 How long to show the feature for

unproject(x, y)

Returns the geographic position (latitude/longitude) of the map layer (elevation==0) at viewport position (x,y), or 'undefined' if no part of the map plane would be rendered at (x,y) - e.g. if (x,y) lies above the horizon.
Parameters:
Name Type Description
x Number the x position in the viewport
y Number the y position in the viewport
Returns:
Geographic position {latitude,longitude}
Type
Object

Type Definitions


eventListenerFunction()

A function that will be called when an event is fired. The parameters passed to the function depend on what type of event it is

getTargetCallback(feature)

A callback function for getTarget
Parameters:
Name Type Description
feature Object The feature

modifierFunction(id, properties)

A function that will be called on each feature, for modification before rendering
Parameters:
Name Type Description
id String The feature's id
properties Object The feature's properties

screenshotCallback(screenshot)

A callback function for screnshot
Parameters:
Name Type Description
screenshot The screenshot

selectorFunction(id, data)

A function that will be called on each feature, for modification before rendering
Parameters:
Name Type Description
id String The feature's id
data Object The feature's data

Events


busy

Fired when data loading starts

change

Fired when the map is zoomed, tilted or panned

idle

Fired when data loading ends

loadfeature

Fired when a 3d object has been loaded

loadfeature

Fired when a 3d object has been loaded

resize

Fired when the map is resized

rotate

Fired when the map is rotated

tilt

Fired when the map is tilted

zoom

Fired when the map is zoomed (in either direction)