VTS Browser Map API

VTS Browser Map API

This VTS Browser Presenter module provides methods for map.

Methods for Modifying Map State

Method	Returns	Description
setPosition(<Position> position)	this	Sets map position
setView(<String/View> view)	this	Sets map view by ViewID or by View object

Methods for Getting Map State

Method	Returns	Description
getPosition	Position	Returns the current map position
getView	String	Returns the current map view
getCurrentCredits	Array of Strings	Returns credits for the currently visible area

Methods for Layers, Surfaces and Views

Method	Returns	Description
getViews	Array of Strings	Returns an array of supported viewIDs
getViewInfo(<String> viewID)	View	Returns view info
getBoundLayers	Array of Strings	Returns an array of supported free layers
getBoundLayerInfo(<String> layerID)	BoundLayer	Returns bound layer info
getFreeLayers	Array of Strings	Returns an array of supported free layers
getFreeLayerInfo (<String> layerID)	FreeLayer	Returns free layer info
addFreeLayer (<String> layerID, <FreeLayer> layer)	this	Adds free layer to the map
removeFreeLayer (<String> layerID)	this	Removes free layer from the map
getSurfaces	Array of Strings	Returns an array of supported surfaces
getSurfaceInfo(<String> surfaceID)	Surface	Returns surface info
getReferenceFrame()	ReferenceFrame	Returns an object with reference frame information
getSrses	Array of Strings	Returns an array of map SRSs
getSrsInfo(<String> srsID)	Srs	Returns SRS info
getCredits	Array of Strings	Returns an array of map credits
getCurrentCredits	Array of Strings	Returns credits for the currently visible area
getCreditInfo(<String> creditID)	Credit	Returns credit info

Method for panning position

Method	Returns	Description
movePositionCoordsTo(<Position> position, <Number> azimuth, <Number> distance, <Number> azimuthCorrectionFactor)	Position	Returns the position with moved coordinates. Azimuth units are degrees. Distance units are meters. AzimuthCorrectionFactor sets how is azimuth corrected with changing longitude. Supported values are 0 (not applied) or 1 (applied)

Methods for Conversions

Method	Returns	Description
convertPositionViewMode(<Position> position, <String> mode)	Position	Returns the position in the desired view mode. Supported modes are: "obj","subj"
convertPositionHeightMode(<Position> position, <String> heightMode)	Position	Returns the position in the desired height mode. Supported modes are: "fix","float"
convertCoords(<String>; sourceSrs, <String>; destinationSrs, <Coords> coords)	Coords	Converts coordinates from source SRS to destination SRS. Coordinates have to be in fixed height mode.
convertCoordsFromNavToPhys(<Coords> coords, <String> heightMode)	Coords	Converts navigation coordinates to physical coordinates. "heightMode" tells in which height mode are the navigation coordinates. Supported height modes are: "fix","float"
convertCoordsFromNavToCanvas(<Coords> coords, <String> heightMode)	Coords	Converts navigation coordinates to canvas coordinates. Supported height modes are: "fix","float"
convertCoordsFromPhysToCanvas(<Coords> coords, <)	Coords	Converts physical coordinates to canvas coordinates.
convertCoordsFromNavToCameraSpace(<Coords> coords, <String> heightMode)	Coords	Converts navigation coordinates to camera coordinates. The camera coordinates are used for matrices in shaders. "heightMode" tells in which height mode are the navigation coordinates. Supported height modes are: "fix","float"
convertCoordsFromPhysToCameraSpace(<Coords> coords, <)	Coords	Converts physical coordinates to canvas coordinates. The camera coordinates are used for matrices in shaders.

Method for Measuring

Method	Returns	Description
getSurfaceHeight(<Coords> coords, <Number> precision)	[Number height, Bool precisionReached, Bool heightNotAccesible ]	Returns surface height at given coordinates. If the height reached desired precision then "precisionReached" element value is true. If "precisionReached" element value is false it means the needed data is not loaded yet. You need to keep calling this function at the desired coordinates until "precisionReached" is true. It may happen that height information for the given coordinates is not present at all. In that case the element "heightNotAccesible" is false.
getDistance(<Coords> coords, <Coords> coords2, <Bool> includingHeight)	[Number distance, Number azimuth]	Returns the shortest distance between the coordinates, and the azimuth from the first coordinate to the second coordinate. The parameter "includingHeight" sets whether coordinates heights will be taken into account for distance computation.
getNED(<Coords> coords)	Matrix	Returns the local space matrix for the given coordinates. The North, East, Direction vectors can be extracted from this matrix.
getHitCoords(<Number> screenX, <Number> screenY, <String> heightMode)	Coords	Returns navigation coordinates of the surface point lying underneath the screen point defined by the screen coordinates. Possible values for height mode are: "fix", "float". If no surface is present under the provided screen coordinates, null value is returned.
isPointInsideCameraFrustum(<Coords> coords)	Bool	Returns whether the point is visible in the camera frustum. The point is located by physical coordinates.
isBBoxInsideCameraFrustum(<Array of Coords> bbox)	Bool	Returns whether the axis aligned bounding box is visible in the camera frustum. BBox is defined by two physical coordinates. First coordinates represents BBox corner with minimal values and second represents corner with maximal values.

Methods for Accessing GPU Map Cache

Method	Returns	Description
getGpuCache()	GpuCache	Returns an interface to the GPU cache

GPUCache Methods for working with Cache Items

Method	Returns	Description
addItem(<Number> size, <Function> destructor)	CacheItem	Creates an item in the GPU cache. If the cache does not have enough space, 'destructor' is called.
removeItem(<CacheItem> item)	CacheItem	Removes 'item' from the GPU cache
itemUsed(<CacheItem> item)	CacheItem	Puts 'item' on top of the cache

Methods for generating trajectories

Method	Returns	Description
generateTrajectory(<Position> sourcePosition, <Position> destinationPosition, <TrajectoryOptions> options)	Array of Positions	Generates a trajectory from source position to destination position. Returns the trajectory as an array of Positions.

Trajectory Options

Option	Type	Default	Description
type	String	"auto"	Sets trajectory type. Supported types are: "auto", "direct", "ballistic", "pih [unsupported]"
maxHeight	Number	100000	Sets maximum trajectory height. This option is supported only in "ballistic" mode.
maxDuration	Number	10000	Sets maximum duration of flight in milliseconds.
samplePeriod	Number	10	The sample period in milliseconds. Sets density of samples of the generated trajectory.
height	Number	null	Sets height of flight. The height is determined automatically, but can be overridden by this option. This option is supported only in "ballistic" mode.

Camera Methods

Method	Returns	Description
getCameraInfo()	CameraInfo	Returns information about the currently used camera.

Content of Camera Info

Option	Type	Default	Description
projectionMatrix	Matrix	--	Projection matrix
viewMatrix	Matrix	--	View matrix
viewProjectionMatrix	Matrix	--	View-Projection matrix
position	Coords	--	Position of the camera in Physical Space
vector	Coords	--	Look vector of the camera in Physical Space

Render Slots Methods

The following methods allow working with render slots. By default, the map contains only one render slot with id "map" which renders the map. It is possible to add additional slots. These slots can render additional features over the rendered map using core rendering functions. Rendering slots form a stack. This stack is processed in sequential order.

Method	Returns	Description
addRenderSlot(<String> id, <Function> callback, <Bool> enabled)	this	Adds a render slot with provided id. Once the slot is about to be processed the callback is called. The callback is a one parameter function(renderChannel). The render channel specifies the purpose of rendering. Possible values are "base" or "hit". The "base" value means rendering to the user screen. The "hit" value means rendering to a texture with a special shader. The resulting hit texture is used by the method getHitCoords.
moveRenderSlotBefore(<String> whichId, <String> whereId)	this	Moves rendering slot identified by "whichId" before another slot identified by "whereId"
moveRenderSlotAfter(<String> whichId, <String> whereId)	this	Moves rendering slot identified by "whichId" after another slot identified by "whereId"
removeRenderSlot(<String> id)	this	Removes a rendering slot
setRenderSlotEnabled(<String> id, <Bool> state)	this	Enables or disables a rendering slot.
getRenderSlotEnabled(<String> id)	Bool	Returns the enable state of a rendering slot.

Geodata Creation

The following method creates geodata object which provides methods for adding vector features like points or lines. The geodata are based on VTS geodata file format. You can understand it a way that this javascript object builds internally geodata file based on your provided inputs. Each vector feature can be equipped by its id and properties. This id and properties can be returned by related events (geo-feature-click, geo-feature-hover, ..) or processed by geodata styles. Most powerful geodata feature is that all vector features can be styled by the geodata styles. You can think of it as a CSS styles for the vector features. By default is expected that features coordinates are in the navigation SRS, but you can define in which SRS are provided coordinates by optional SRS parameter. The feature coordinates can use two height modes: 'float' defines height above terrain or 'fix' which has no relation to the terrain. In case the 'float' heights are used then you have to call processHeights method before you can create free layer. Once are all features defined (and 'float' heights converted) then you can create free layer and add that layer to the map. The geodata are not very well suited for creating fluent animations but are very useful for static content and switching between various states. In case you are interested in fluent animations than you should look at render slots.

Method	Returns	Description
createGeodata()	Geodata	Returns Geodata object

Geodata Methods

Method	Returns	Description
createGroup(<String> id)	this	Creates group. All features added afterwards will be added to this group.
addPoint( Coords coords, <String> heightMode, <Object> properties, <String> id, <String> srs)	this	Adds point feature.
addPointArray( Array of Coords coords, <String> heightMode, <Object> properties, <String> id, <String> srs)	this	Adds point array feature.
addLineString( Array of Coords line, <String> heightMode, <Object> properties, <String> id, <String> srs)	this	Adds line string feature.
addLineStringArray( Array of Array of Coords lines, <String> heightMode, <Object> properties, <String> id, <String> srs)	this	Adds line string array feature.
processHeights(<String> heightSource, <Number> precision/lod, <Function> onProcessed)	null	This function converts all 'float' heights to 'fix' heigths. Once is conversion complete then onProcessed callback is called. Possible hegithSource values are: 'heightmap-by-precision', 'node-by-precision', 'heightmap-by-lod', 'node-by-lod'. Precision means size of sample in heightmap or metanode. Precision value is in meters.
extractGeometry( <String> featureId)	GedataGeometry	Returns geodata geomerty object. This object can be use for accessing information about feature geometry.
makeGeodata( <Number> resolution)	VTSGeodataJSON	Returns geodata object in interchangeable form. Resolution parameter is optional and represents maximum quantization range for features coordinates.
importGeodata( <object> geodataJson, <String> groupIdPrefix, <Bool> dontCreateGroups)	null	Imports features.
importGeodJson( <object> geoJson, <String> heightMode, <String> groupIdPrefix, <Bool> dontCreateGroups)	null	Imports features.
makeFreeLayer(<GeodataStyle> style, <Number> resolution)	FreeLayer	Returns free layer definition. Resolution parameter is optional and represents maximum quantization range for features coordinates.

Geodata Events

It is important to note that following events are generated only when 'click' an 'hover' methods called. More about these methods can be found there.

Event	Data content	Description
geo-feature-click	featureInfo	Called once user clicks on the feature. This event is generated only when feature layer style has property 'click-event : true'
geo-feature-hover	featureInfo	Called once user hovers over the feature. This event is generated only when feature layer style has property 'hover-event : true'
geo-feature-enter	featureInfo	Called once user starts hovering over the feature. This event is generated only when feature layer style has property 'hover-event : true'
geo-feature-leave	featureInfo	Called once user finishes hovering over the feature. This event is generated only when feature layer style has property 'hover-event : true'

Geodata Geometry

This object is used for accessing information about geodata feature geometry.

Method	Returns	Description
getType()	String	Returns type of the geometry. Possible value are: 'point', 'line''.
getElements(<Number> pathIndex)	Number	Returns number of the geometry elements (line segment, poines).
getRelationToCanvasPoint(<Number> elementIndex, <Number> screenX, <Number> screenY)	Object	Returns information about relation of screen coordinates (e.g. cursor) and geometry element.
getPathElement(<Number> elementIndex, <Number> pathIndex)	Coords/[Coords,Coords]	Returns geomtery element. In case of 'point' geometry it returns point coordinates. In case of 'line' geometry it return two coordinates [p1,p2]
getPathPoint(<Number> distance, <Number> pathIndex)	Coords	Returns point on the path. Distance on the path is in meters. This method can used only to 'line' geometries
getPathNED(<Number> distance, <Number> pathIndex)	Object	Returns NED on the path. Distance on the path is in meters. This method can used only to 'line' geometries
getPathLengthToElement(<Number> index, <Number> pathIndex)	Object	Returns information about distance to the line segment in meters and length of line segment itself.
getPathLength(<Number> pathIndex)	Number	Returns total length of the path in meters.
getPathsCount()	Number	Returns total number of paths.

Remaining Map Related Methods

Method	Returns	Description
click(<Number> screenX, <Number> screenY, <Object> state)	null	Tells the map to process click events on provided coordinates. The 'state' is optional variable which is returned with 'geo-feature-click' event.
hover(<Number> screenX, <Number> screenY, <Bool> persistent, <Object> state)	null	Tells the map to process hover events on provided coordinates. The 'persistent' option means that hover is processed internally on provided coordinates until is set differently. The 'state' is optional variable which is returned with 'geo-feature-hover', geo-feature-leave', geo-feature-enter' events.
redraw()	null	Forces the map to redraw.
setLoaderSuspended(<Bool> state)	this	Temporarily stops map loader activity or enables it again.
getLoaderSuspended()	Bool	Returns the map loader suspend status.

Map Events

Event	Data content	Description
map-loaded	null	Called once the map is loaded. From that moment map the interface is accessible.
map-unloaded	null	Called when the map is destroyed. From that moment the map interface is no longer accessible.
map-position-changed	<Position> position	Called when the map position is changed.
map-position-panned	null	Called when the map is panned
map-position-rotated	null	Called when the map is rotated
map-position-zoomed	null	Called when the map is zoomed
map-update	null	Called after the map is rendered

Position

The position is defined as an array of the following values:

Index	Type	Default	Description
0	String	"obj"	Type of view mode. Possible modes are: "obj", "subj".
1	Number	0	X coordinate in navigation SRS.
2	Number	0	Y coordinate in navigation SRS
3	String	"float"	Type of height mode. Possible modes are: "fix", "float".
4	Number	0	Z coordinate.
5	Number	0	Yaw component of orientation in NED based Euler angles.
6	Number	0	Pitch component of orientation in NED based Euler angles.
7	Number	0	Roll component of orientation in NED based Euler angles.
8	Number	400	Vertical extent of camera view, measured at the center of orbit in physical SRS units.
9	Number	90	Vertical FOV, measured in degrees.

View Modes:

Mode	Description
"obj"	XYZ coordinates represent the center of camera orbit. Orientation is measured at the center of orbit.
"subj"	XYZ coordinates represent the center of perspectivity. Orientation is measured at the center of perspectivity.

Height Modes:

Mode	Description
"fix"	Z coordinate is in navigation SRS.
"float"	Z coordinate represents AGL (Above Ground Level).

More information about positions will be provided in VTS Format Documentation.

You can set position directly in form of Array: map.setPosition(["obj",14.43624,50.08038,"float",0,10,-90,0,27308,55]);

Another way is set position in of Position object. This object is returned by map.getPosition method or cloned by from existing position by position.clone method. The Position object have following methods:

Methods

Method	Returns	Description
clone()	Position	Creates a copy of position.
isSame(<Position> position)	Bool	Returns whether the provided positions are the same.
setCoords(<Coords> coords)	Position	Sets position coordinates.
getCoords()	Coords	Returns position coordinates.
setHeight(<Number> height)	Position	Sets position height.
getHeight()	Number	Returns position height.
setOrientation(<Orietation> orientation)	Position	Sets position orientation.
getOrientation()	Orietation	Returns position orientation.
setViewExtent(<<Number> extent)	Position	Returns position view extent.
getViewExtent()	Number	Returns position view extent.
setFov(<Number> fov)	Position	Sets position FOV.
getFov()	Number	Returns position FOV.
getViewMode()	String	Returns position view mode. Possible values are: "obj", "subj"
getHeightMode()	String	Returns position height mode. Possible values are: "fix", "float"
toArray()	String	Returns position in array form

Definition of View

The Map View is an object with the following properties:

Property	Type	Default	Description
surfaces	Array of Strings	null	Surfaces used in the map view. Value is an object where property names represent which surfaces are visible. Property values are arrays with names of bound layers that will be used for the particular surface. A bound layer can be defined by a string id or by an object with a string property "id". Additionally, a bound layer defined by an object can contain the "alpha" property. Alpha is a number from zero to one, where zero means full transparency. Default alpha value is one (fully opaque). See examples below.
freeLayers	Array of Layers	null	Free layers used in map view Layer can be represented as a string or as an object with additional parameters.

Example of a view with one surface "town".

{
  surface: { "town": [] }
  freeLayers : {}
}

Example of a view with two surfaces "town" and "mountains".

{
  surface: { "town": [],
             "mountains": [] },
  freeLayers : {}
}

Example of a view with two surfaces "town" and "mountains". Additionally for the "mountains" surface the bound layer "ortophoto20015" is used.

{
  surface: { "town": [],
             "mountains": ["ortophoto20015"] },
  freeLayers : {}
}

Example of a view with two surfaces "town" and "mountains". Additionally for the "mountains" surface the bound layers "ortophoto20015" and "schema" are used. Bound layer "schema" is 50% transparent.

{
  surface: { "town": [],
             "mountains": [ "ortophoto20015",
                            {id: "schema", alpha: 0.5}] },
  freeLayers : {}
}

Definition of Surface

The Map Surface Info is an object with read only properties. The map can be composed of several surfaces like terrain or city. The API allows you to hide or show these surfaces by setting the Map View parameter.

Definition of BoundLayer

The Map BoundLayer Info is an object with read only properties. A bound layer defines geographic imagery to be mapped over a terrain surface. Each terrain surface can have more then one bound layer and bound layers can have various opacity levels. The API allows you to define bound layers for map surfaces by setting the Map View parameter.

Definition of FreeLayer

The Map FreeLayer Info is an object with read only properties. You can include free layers into the map. Free layers are independent of the main surface stack. There are several types of free layers:

• Monolithic Mesh - simple textured mesh with no tiles and resolution levels (LODs).
• Tiled Mesh - multi-resolution tiled map surface.
• Monolithic Geodata - non-tiled vector features in the map like points, lines, labels, etc., can be styled.
• Tiled Geodata - tiled vector data with multiple resolution levels. Similar to OpenStreet map data but in 3D. The API allows you hide or show these free layers by setting the Map View parameter.

Definition of Srs

The Map Srs Info is an object with read only properties. SRS stands for Spatial Reference System. Its definition is similar to Proj4 strings with some additional extensions for vertical coordinates.

Definition of Credit

The Map Credits Info is object with read only properties describing the credit.

Definition of Coords

The coords is an array of the following values [Number x,Number y,Number z].

Definition of Matrix

The 4x4 row major matrix (array of 16 numbers).

Definition of Credits

The object with read only properties which informs about credits for the currently displayed map.

Index	Type	Default	Description
imagery	Array of Strings	[]	Array of credit ids.
mapdata	Number	[]	Array of credit ids.