VTS Browser API

VTS Browser API

The VTS Browser API provides a platform for interactive rendering of 3D maps.

Using this API you can easily embed 3D maps into your website with functionality that can be tailored to your needs.

Browser

Usage Example

<link rel="stylesheet" type="text/css" href="https://cdn.melown.com/libs/vtsjs/browser/v2/vts-browser.min.css" />
<script type="text/javascript"
 src="https://cdn.melown.com/libs/vtsjs/browser/v2/vts-browser.min.js"></script>

var browser = vts.browser('map-div', {
    position: ["obj",14.824728,50.291323,"float",0,-17,-67,0.00,219,90],
    map: "https://cdn.melown.com/mario/store/melown2015/map-config/melown/Bentky-nad-Jizerou/mapConfig.json"
});

More examples can be found here.

Creation

Factory	Description
vts.browser( <HTMLElement/String> id, <BrowserOptions> options? )	Creates the map browser in the provided HTML element. Initial state of the browser can be set by options.

Options

Map State Options

Option	Type	Default	Runtime	Description
position	Position	null	true	Sets initial map position. If position is not defined then default map position is used.
view	String or View	null	true	Sets initial map view. If position is not defined then default map view is used.
map	URL	null	true	Sets URL to map.

Navigation

Option	Type	Default	Runtime	Description
panAllowed	Bool	true	true	Whether the map can be panned
rotationAllowed	Bool	true	true	Whether the map can be rotated
zoomAlowed	Bool	true	true	Whether the map can be zoomed
jumpAlowed	Bool	false	true	Whether the map can be moved to a new position by doubleclick
navigationMode	String	"free"	true	Sets navigation mode for maps with lat , lon navigation srs. Posible values are: "free", "azimuthal"
minViewExtent	Number	150	true	Sets minimal view extent into which the user can zoom in
maxViewExtent	Number	MAX_INTEGER	true	Sets maximal view extent into which the user can zoom out
sensitivity	Array Numbers	[1, 0.12, 0.05]	true	Sets sensitivity of pan, rotate and zoom user actions
inertia	Array Numbers	[0.81, 0.9, 0.7]	true	Sets inertia of pan, rotate and zoom user actions
positionInUrl	Bool	false	true	Whether the map position will be present in the URL as a URL parameter

Controls

Option	Type	Default	Runtime	Description
controlCompass	Bool	true	true	Sets control visibility
controlZoom	Bool	true	true	Sets control visibility
controlSpace	Bool	true	true	Sets control visibility
controlSearch	Bool	true	true	Sets control visibility
controlSearchValue	String	null	false	Sets initial search value. If position is found map displays this position
controlSearchElement	HTMLElement/String	null	false	Sets in which HTML element will be search bar placed
controlSearchSrs	HTMLElement/String	null	true	Sets in which SRS are coordinates in the search result.
controlSearchFilter	Bool	null	true	Sets whether search results will be filtered by default filter.
controlFullscreen	Bool	false	true	Sets control visibility

Advanced Options

Option	Type	Default	Runtime	Description
mapCache	Number	900	false	Sets map resource cache size in MBs
mapGPUCache	Number	360	false	Sets map GPU cache size in MBs
mapMetatileCache	Number	60	false	Sets map metatile cache size in MBs
mapTexelSizeFit	Number	1.1	false	Sets desired size of of map texels
mapTexelSizeTolerance	Number	2.2	false	Sets maximum temporal size of of map texels
mapDownloadThreads	Number	6	false	Sets how many files can be downloaded concurrently.
mapMaxProcessingTime	Number	2000	false	Sets how much time can used for processing resources during one frame. [unimplemented]
mapMobileMode	Bool	false	false	Forces map to be presented in mobile mode (degraded details). Mobile device is normally detected automatically.
mapMobileModeAutodect	Bool	true	false	Set whether mobile device is autodetected.
mapMobileTexelDegradation	Number	1	false	Sets how much will the map be degraded in mobile mode.
mapNavSamplesPerViewExtent	Number	4	false	Navigation samples per view extent.
mapLoadMode	String	topdown	false	Read more
mapFeaturesReduceMode	string	scr-count1	false	Read more
mapFeaturesReduceParams	Array Numbers	[0, 0, 0, 0, 0]	false	Read more
rendererAntialiasing	Bool	true	false	Set whether rendered primitives will be antialiased
rendererAllowScreenshots	Bool	false	false	Set whether screenshots of color buffer are allowed
rendererAntialiasing	Bool	true	false	Set whether rendered primitives will be antialiased

Load modes

Sets how will be map loaded. Possible values are: "topdown", "fit", "fitonly". The "topdown" mode load map gradually from lower detail to final detail level. The "fit" mode loads map only in final detail level with some detail tolerance during map navigation. The "fitonly" mode loads map only in final detail level, but without detail tolerance during map navigation.

Geodata reduce modes

Sets how geodata features will be reduced. Supported values are: "scr-count1", "scr-count7". The mode "scr-count1" is only used to disable "scr-count7". The mode "scr-count7" will reduce number of rendered geodata features (works only for: points,labels,icons) to density defined by mapFeaturesReduceParams. Which features are more important then other is based on value of feature property "importace-source" (defined in geodata styles).

Reduce modes parameters

Sets parameters for mapFeaturesReduceMode. Default values for "scr-count1" are [0, 0, 0, 0, 0]. The mode "scr-count7" have following parameters [margin, density, distanceWeight, visibilityEnabled, visibilityThreshold]. First parameter is margin around labels or icons (units are inches). Second parameter is density which defines maximum number of geodata features per square inch. Third parameter defines how much distance affects resulting importance. Fourth parameter enables or disables visibility test (0 - disabled, 1 - enabled). Visibility test means that features which are hidden behind terrain will not be rendered. Fifth parameter sets how far have to be feature behind terrain to be hidden (units are meters). Default values for "scr-count7" are [0.05,999,1,0,1000].

Events

Creating Event Listener

Method	Returns	Description
on(<String> name, <Function> function)	Function	Creates an event listener. Which event is listened to is defined by its name. Once the event occurs the provided function is called. The method returns a function which is a destructor of the created event listener.

General Events

Event	Data content	Description
tick	null	Core heart beat

Browser Interfaces

Interface	Returns	Description
map	<Map>	Returns the Map interface. The interface is returned only when maps is loaded (after map-loaded event) otherwise returns null value.
ui	<UI>	Returns the UI interface
autopilot	<Autopilot>	Returns the Autopilot interface
presenter	<Presetner>	Returns the Presenter interface
renderer	<Renderer>	Returns the Renderer interface
proj4	<UI>	Returns the Proj4 interface
utils	<utils>	Returns the utils interface
math	<math>	Returns the math interface
vec3	<vec3>	Returns the ve3 interface
mat4	<mat4>	Returns the mat4 interface

Browser Methods

Method	Returns	Description
loadMap()	this	Loads a map [experimental]
destroyMap()	this	Destroys a loaded map [experimental]
destroy	this	All core resource are released [experimental]

Methods for Options

Most map options can be set in runtime by the following methods. Whether an option can be changed in runtime is indicated by "Runtime" value in the options table.

Method	Returns	Description
setParam(<String> key, <?> value)	this	Sets a map option
setParams(<BrowserOptions> options)	this	Sets map options
getParam(<String> key)	this	Gets a map option value

More Examples

Display a map at specific position with specific map view:

var browser = vts.browser('map-div', {
    position: ["obj",14.82554328875602,50.29168884599104,"float",0,106,-47,0,219,55],
    view : {
               "freeLayers" : {
			"mapzen-all" : {}
		},
		"surfaces" : {
			"melown-benatky-nad-jizerou" : [],
			"melown-gtopo30-world" : [ "bmng08-world", "mapycz-ophoto-cz" ]
		}
    }
    map: "https://cdn.melown.com/mario/store/melown2015/map-config/melown/Bentky-nad-Jizerou/mapConfig.json"
});

Display a map and set the position and view programmatically:

var browser = vts.browser('map-div', {
    map: "https://cdn.melown.com/mario/store/melown2015/map-config/melown/Bentky-nad-Jizerou/mapConfig.json"
});

browser.on("map-loaded", (function(){
    var map = browser.map;
    map.setPosition(["obj",14.82554328875602,50.29168884599104,"float",0,106,-47,0,219,55]);  
    map.setView({
               "freeLayers" : {
			"mapzen-all" : {}
		},
		"surfaces" : {
			"melown-benatky-nad-jizerou" : [],
			"melown-gtopo30-world" : [ "bmng08-world", "mapycz-ophoto-cz" ]
		}
    });  
}));