Skip to content

VTS Browser Map API

David Levinsky edited this page Aug 10, 2017 · 12 revisions

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

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.
You can’t perform that action at this time.