Documentation

Class

OSMBuildings

Parameters

Name	Type	Default	Optional	Description
options	Object		optional	OSMBuildings options
options.container	String			A DOM Element or its id to append the viewer to
options.minZoom	Number	14.5		Global minimum allowed zoom
options.maxZoom	Number	20		Global maximum allowed zoom
options.bounds	Object		optional	A bounding box to restrict the map to
options.state	Boolean	false		Store the map state in the URL
options.disabled	Boolean	false		Disable user input
options.attribution	String		optional	An attribution string
options.zoom	Number	minZoom..maxZoom		Initial zoom, default is middle between global minZoom and maxZoom
options.rotation	Number	0		Initial rotation
options.tilt	Number	0		Initial tilt
options.position	Object		optional	Initial position
options.position.latitude	Number	52.520000		position latitude
options.position.longitude	Number	13.410000		Position longitude
options.baseURL	String	'.'		DEPRECATED For locating assets. This is relative to calling html page
options.showBackfaces	Boolean	false		DEPRECATED Render front and backsides of polygons. false increases performance, true might be needed for bad geometries
options.fogColor	String	'#e8e0d8'		Color to be used for sky gradients, distance fog and color benath the map
options.highlightColor	String	'#f08000'		DEPRECATED Default color for highlighting features
options.effects	Array		optional	DEPRECATED Which effects to enable. The only effect at the moment is 'shadows'
options.backgroundColor	String		optional	DEPRECATED Overall background color
options.fastMode	Boolean	false		Enables faster rendering at cost of image quality.
options.style	Object		optional	Sets the default building style
options.style.color	String	'rgb(220, 210, 200)'		Sets the default building color

Top

Methods

appendTo

DEPRECATED

Top

on

Adds an event listener

Parameters

Name	Type	Default	Optional	Description
type	String			Event type to listen for
fn	eventCallback			Callback function

Top

off

Removes an event listener

Parameters

Name	Type	Default	Optional	Description
type	String			Event type to listen for
fn	eventCallback		optional	If callback is given, only remove that particular listener

Top

emit

Triggers a specific event

Parameters

Name	Type	Default	Optional	Description
event	String			Event type to listen for

Top

setDate

Set date for shadow calculations

Parameters

Name	Type	Default	Optional	Description
date	Date

Top

project

Gets 2d screen position from a 3d point

Parameters

Name	Type	Description
latitude	Number	Latitude of the point
longitude	Number	Longitude of the point
altitude	Number	Altitude of the point

Returns

Type	Description
Object	Screen position in pixels { x, y }

Top

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

Name	Type	Default	Optional	Description
x	Number			X position on screen
y	Number			Y position om screen

Returns

Type	Description
Object	Geographic position { latitude, longitude }

Top

remove

Removes a feature, layer or marker from the map.

Top

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

Name	Type	Default	Optional	Description
url	String			Absolute URL to OBJ file
position	Object			Where to render the object
position.latitude	Number			Position latitude for the object
position.longitude	Number			Position longitude for the object
options	Object	{}	optional	Options for rendering the object
options.scale	Number	1		Scale the model by this value before rendering
options.rotation	Number	0		Rotate the model by this much before rendering
options.altitude	Number	0		The height above ground to place the model at
options.id	String		optional	An identifier for the object. This is used for getting info about the object later
options.color	String		optional	A color to apply to the model
options.swapYZ	Boolean		optional	Swap y and z coordinates. Use this if your model is standing upright on one side

Returns

Type	Description
Object	The added object

Top

addGeoJSON

Adds a GeoJSON object to the map.

Parameters

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

Returns

Type	Description
Object	The added object

Top

addGeoJSONTiles

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

Parameters

Name	Type	Default	Optional	Description
url	String	https://{s}.data.osmbuildings.org/0.2/{k}/tile/{z}/{x}/{y}.json		url The URL of the GeoJSON tile server
options	Object	{}	optional
options.fixedZoom	Number	15		Tiles are fetched for this zoom level only. Other zoom levels are scaled up/down to this value
options.minZoom	Number	14.5		Minimum zoom level to show features from this layer. Defaults to and limited by global minZoom.
options.maxZoom	Number	maxZoom		Maximum zoom level to show features from this layer. Defaults to and limited by global maxZoom.

Returns

Type	Description
Object	The added layer object

Top

addMapTiles

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

Parameters

Name	Type	Default	Optional	Description
url	String			The URL of the map server. This could be from Mapbox or other tile servers

Returns

Type	Description
Object	The added layer object

Top

highlight

This replaces any previous highlighting.

Top

hide

This replaces any previous show/hide rule.

Top

show

DEPRECATED

Top

getTarget

DEPRECATED

Top

screenshot

DEPRECATED

Top

setDisabled

Disables map interaction

Parameters

Name	Type	Default	Optional	Description
flag	Boolean

Top

isDisabled

Checks for map interaction disabled

Returns

Type	Description
Boolean	flag

Top

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

Type	Description
Array	Bounding coordinates in unspecific order { latitude, longitude }, ...

Top

setZoom

Set zoom level

Parameters

Name	Type	Default	Optional	Description
zoom	Number			The new zoom level

Top

getZoom

Get current zoom level

Returns

Type	Description
Number	zoom level

Top

setPosition

Set map's geographic position

Parameters

Name	Type	Description
pos	Object	The new position
pos.latitude	Number
pos.longitude	Number

Top

getPosition

Get map's current geographic position

Returns

Type	Description
Object	Geographic position { latitude, longitude }

Top

setSize

Set map view's size in pixels

Parameters

Name	Type	Description
width	Integer
height	Integer
size	Object	DEPRECATED
size.width	Integer	DEPRECATED
size.height	Integer	DEPRECATED

Top

getSize

Get map's current view size in pixels

Returns

Type	Description
Object	View size { width, height }

Top

setRotation

Set map's rotation

Parameters

Name	Type	Default	Optional	Description
rotation	Number			The new rotation angle in degrees

Top

getRotation

Get map's current rotation

Returns

Type	Description
Number	Rotation in degrees

Top

setTilt

Set map's tilt

Parameters

Name	Type	Default	Optional	Description
tilt	Number			The new tilt in degree

Top

getTilt

Get map's current tilt

Returns

Type	Description
Number	Tilt in degrees

Top

addMarker

Adds a marker to the map in 3d space.

Parameters

Name	Type	Default	Optional	Description
position	Object			geographic position including altitude
position.latitude	Number			latitude
position.longitude	Number			longitude
position.altitude	Number	0		altitude in meters
data	Object		optional	custom data properties to attach to the marker, i.e. an id
options	Object		optional	additional options
options.url	String		optional	url to an SVG file to use as custom marker. Currently only path properties are supported. Overlapping path's may create strange results.
options.color	String		optional	color which whole marker will be tinted