| 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 | Initial rotation | ||
| options.tilt | Number | 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 | '.' | ||
| options.showBackfaces | Boolean | false | ||
| options.fogColor | String | '#e8e0d8' | ||
| options.highlightColor | String | '#f08000' | ||
| options.effects | Array | [] | ||
| options.backgroundColor | String | '#efe8e0' | 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 |
OSM Buildings
Class
Methods
addGeoJSON
Adds a GeoJSON object to the map.
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| url | String | URL of the 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 | Rotate the model by this much before rendering | ||
| options.altitude | Number | 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 |
| Type | Description |
|---|---|
| Object | The added object |
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. |
| Type | Description |
|---|---|
| Object | The added layer object |
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 |
| Type | Description |
|---|---|
| Object | The added layer object |
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 | 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 |
| Type | Description |
|---|---|
| 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| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| url | String | URL of the 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 | Rotate the model by this much before rendering | ||
| options.altitude | Number | 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 |
| Type | Description |
|---|---|
| Object | The added object |
appendTo
destroy
Destroys the map
emit
Triggers a specific event
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| event | String | 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.
| Type | Description |
|---|---|
| Array | Bounding coordinates in unspecific order { latitude, longitude }, ... |
getPosition
Get map's current geographic position
Returns| Type | Description |
|---|---|
| Object | Geographic position { latitude, longitude } |
getRotation
Get map's current rotation
Returns| Type | Description |
|---|---|
| Number | Rotation in degrees |
getSize
Get map's current view size in pixels
Returns| Type | Description |
|---|---|
| Object | View size { width, height } |
getTarget
getTilt
Get map's current tilt
Returns| Type | Description |
|---|---|
| Number | Tilt in degrees |
getZoom
Get current zoom level
Returns| Type | Description |
|---|---|
| Number | zoom level |
hide
This replaces any previous show/hide rule.
highlight
This replaces any previous highlighting.
isDisabled
Checks for map interaction disabled
Returns| Type | Description |
|---|---|
| Boolean | flag |
off
Removes an even 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 |
on
Adds an event listener
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| type | String | Event type to listen for | ||
| fn | eventCallback | Callback function |
project
Gets 2d screen position from a 3d point
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| latitude | Number | Latitude of the point | ||
| longitude | Number | Longitude of the point | ||
| altitude | Number | Altitude of the point |
| Type | Description |
|---|---|
| Object | Screen position in pixels { x, y } |
remove
Removes a feature, layer or marker from the map.
screenshot
setDate
Set date for shadow calculations
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| date | Date |
setDisabled
Disables map interaction
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| flag | Boolean |
setPosition
Set map's geographic position
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| pos | Object | The new position | ||
| pos.latitude | Number | |||
| pos.longitude | Number |
setRotation
Set map's rotation
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| rotation | Number | The new rotation angle in degrees |
setSize
Set map view's size in pixels
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| width | Integer | |||
| height | Integer | |||
| size | Object | |||
| size.width | Integer | |||
| size.height | Integer |
setTilt
Set map's tilt
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| tilt | Number | The new tilt in degree |
setZoom
Set zoom level
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| zoom | Number | The new zoom level |
show
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 |
| Type | Description |
|---|---|
| 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| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| type | String | Event type | ||
| payload | any | optional | Payload of any type |
selectorCallback
User defined function that will be called on each feature, for modification before rendering
Parameters| Name | Type | Default | Optional | Description |
|---|---|---|---|---|
| id | String | The feature's id | ||
| feature | Object | The feature |