VisioWeb2D 1.8.0

Class

vg.mapviewer.web2d.Mapviewer

new Mapviewer()

Main Visioglobe Web2D Viewer class. It allows the rendering Maps using tiles, thus being compatible with a large number of web browsers The user can change floors, highlight places, and animated the camera to go to a place, among other features.

Members

cameraNorthRotation :number|false

Tells you the rotation (in degrees) needed if you could align your map with the true north. If you wanted to display an arrow for a legend, you would display pointing to -mapviewer.cameraNorthRotation. This parameter is valid once the map is done initializing. Since Tiled maps cannot be rotate, you could use this property to draw a north arrow. IE8 NOTE: You cannot read or change this value.

isAccelerated :boolean

Exists for compatibility reasons it always returns false.

minimumDataSDKVersion :string

Used to determine if data is too old to be read by this SDK this is the minimum data version the SDK can read.
Since:
  • 1.7.15

revision :string

Internal revision of SDK.

sdkType :string

returns "web2d", to differentiate from VisioWeb
Since:
  • 1.7.15

version :string

Internal version of SDK.

Methods

addPOI(options) → {vg.mapviewer.web2d.POI}

This method allow to add a POI Object to map. The POI is visible by default after creation.
Note On low-end mobile devices displaying many POIs can reduce the map performance, test before deploying.
Parameters:
Name Type Description
options object
Properties
Name Type Attributes Default Description
url string <optional>
 URL to an image. This option is exclusive to options.text and options.selector
text string <optional>
 Text to display. This option is exclusive to options.url and options.selector Note This string will be placed inside a <div> UNESCAPED therefore care must be taken on what is placed inside this label. For example: options.text = '&lt;' will yield a text with: '<'. This is string is also not centered.
selector string <optional>
 Div id selector (eg. '#test') to overlay at position. Use the selector when you want overlay a DIV element above a given position. This selector should be already on the DOM and have a known width and height so it can be properly aligned. For example jQuery(options.selector).width()/height() should be non-zero. This option is exclusive with options.url and options.text.
position object <optional>
 {x:0.0, y:0.0} position in local coordinates, you can use mapviewer.camera.position to verify it.
floor string <optional>
 currentFloorName The floor the POI will be added to.
visible boolean <optional>
 true If enabled, the POI will be visible directly after calling this method.
alignment object <optional>
 {x:0.0, y:0.0} Controls alignment of options.selector. Valid values are between 1 and -1. With {x:1,y:1} being bottom left corner so the selector will be placed above and to the right of the given position. {x:-1,y:-1} being bottom right. If you want to align the bottom middle of your selector to be on the position, use {x: 0, y: 1.0}
width number <optional>
 32 used with width to specify the size of an icon, only applies if .url is valid
height number <optional>
 32 used with height to specify the size of an icon, only applies if .url is valid
onObjectMouseUp function <optional>
 function(event, Place or POI) This callback will be triggered when a Place or POI (with id) has been clicked. before calling this function, there will me a .trigger('mouseup',...), if any of those handlers returns false, this callback will not be called.
clickable bool <optional>
 true setting this to false prevents calling any callback over this POI: options.onObjectMouseOver, and global parameters.onObjectMouseOver, parameters.onObjectMouseOut, parameters.onObjectMouseUp. This is similar to VisioMove's VgPoint notifyPOISelectedOnClick. Does not apply to "selector" pois.
Since:
  • 1.7.17 if options.id exists, it will call the global onObjectMouseUp and trigger 'mouseup' on click. new option .clickable. documented options.visible.
Returns:
Type
vg.mapviewer.web2d.POI
Examples
// For text use the 'text' field.
var pos = mapviewer.camera.position;
selected_poi = mapviewer.addPOI({
    text: 'hello',
    position: pos
});
// For text use the 'url' field.
var pos = mapviewer.camera.position;
selected_poi = mapviewer.addPOI({
    url: '../media/test.png',
    position: pos,
    floor: "1",
    onObjectMouseUp: function() {alert('foo');}
});
// For constant size text with full css/html control
// use 'selector' which overlays a <div> over the map.
<div style="display: none;">
  <div id="test" style="font-weigth: bold; font-size: 24px; color: #fff; background: none;">
  </div>
</div>
...
var pos = mapviewer.convertLatLonToPoint( {lat: 48.78295439400996, lon: 2.222107906181293});
mapviewer.addPOI({selector: '#test', position: pos, alignment: {x:1,y:1}});

NOTE: currently there are many limitations with text and url POIs.

addPostRenderListener(listener())

adds a callback to be called at the end of dragging?.
Parameters:
Name Type Description
listener() function
Since:
  • 1.7.19 available via .on('redraw', function).
See:

addRoutingPath(options) → {vg.mapviewer.web2d.Path}

This method allow to add a path to the map.
Parameters:
Name Type Description
options object
Properties
Name Type Attributes Default Description
points Array.<object> An Array of local points (i.e. with values {x: number, y: number}) you can add an optional z key.
thickness number <optional>
 2.0 The thickness of the path, measured in number of pixels. Always constant size regardless of camera position and radius.
floor string <optional>
 currentFloorName The floor the path will be added to.
visible boolean <optional>
 true Determines whether the path is visible.
color string <optional>
 '0xff0000' The path color.
opacity number <optional>
 1.0 The path opacity.
See:
Returns:
Type
vg.mapviewer.web2d.Path
Example
var p0 =  {x: 0.505859375, y: 0.264404296875}
var p1 =  {x: 0.51708984375, y: 0.630615234375}
var path = mapviewer.addRoutingPath({
   points: [p0,p1],
   floor: "0",
   thickness: 4,
   opacity: 0.5,
   color: 0x00ff00
});

animateValue(fromValue, toValue, options) → {false|Object}

Interpolates a value, calling the step function each time, and the complete function at the end. Internally it uses jQuery.animate, it exists for API compatibility with VisioWeb.
Parameters:
Name Type Description
fromValue number
toValue number
options object (they are very similar to jQuery.animate)
Properties
Name Type Attributes Description
duration number in milliseconds
step function <optional>
 called at every iteration, v goes from fromValue to toValue.
complete function <optional>
Since:
  • 1.7.19, updated documentation and added stop() function.
Returns:
Object if it started the animation.
Type
false | Object
Example
// animate the position of a POI
var poi_image = mapviewer.addPOI({
		url:'../media/test.png',
		position: {x:0.65, y:0.5, z:0}
});
mapviewer.animateValue(0.65,0.35, {
	duration: 2000, // 2 seconds
	step: function(value) {
        var position = poi_image.options('position');
        position.x = value;
		poi_image.options('position', position);
	},
	complete: function() {
		alert('animate completed');
	}
});
// you can't stop the animation in VisioWeb2D

changeFloor(targetFloorName) → {jQuery.Deferred.Promise}

This method is called to change floor.
Parameters:
Name Type Description
targetFloorName string floor to change to. If it is the same as the current floor, the onCompleted function is called directly.
Returns:
where a done() or fail() callback can be added.
Type
jQuery.Deferred.Promise
Examples
mapviewer.changeFloor(target_floor).done(function() { updateActiveFloorLabel(target_floor);});
// or using triggers
... before calling changeFloor
...
mapviewer.on('floorWillChange',function(ev) {
    // update UI
    console.log('floorWillChange from ' + ev.args.current + ' target ' + ev.args.target);
});
mapviewer.on('floorChanged',function(ev) {
    // update UI
    console.log('floorChanged from ' + ev.args.current + ' target ' + ev.args.target);
});

computeDistance(pStartPoint, pPointEnd) → {number}

Computes the distance in meters between two points.
Parameters:
Name Type Description
pStartPoint localPoint point containing .x, .y, and possibly .z
pPointEnd localPoint point containing .x, .y, and possibly .z
Since:
  • 1.7.18
See:
Returns:
distance in meters between the two points
Type
number

computeHeadingAngle(pPivotPoint, pPointStart, pPointEnd) → {number|false}

Computes the horizontal heading angle, in degrees, between pPointStart-pPivotPoint and pPointEnd-pPivotPoint. It will ignore any .z component.
Parameters:
Name Type Description
pPivotPoint localPoint The local pivot point
pPointStart localPoint The local start point
pPointEnd localPoint The local end point
Since:
  • 1.7.16
See:
Returns:
heading angle in degrees [0,360], values are "clockwise". It returns false if the distance between pPivotPoint and a point is 0.
Type
number | false
Examples
// Suppose you want to compute if mytargetposition is in front/left/right/behind of myposition relative to myheading
 var myposition = {x: 0.5, y: 0.5, z:0}
 var myheading = 10; // approx north... mapviewer.getPoint('kiosk01').headingInDegrees
 var mytargetposition = {x: 0.52, y: 0.52, z:0}; // or say 2nd position of instruction: mapviewer.convertLatLonToPoint(instruction.positions[1])
 var headingAngle = mapviewer.computeHeadingAngle(myposition, mapviewer.offsetPosition(myposition,myheading,0,10), mytargetposition);
 // then ... headingAngle > 315 or < 45, go forward; between 45 and 135 go right...
 // validate visually
 mapviewer.addPOI({position: myposition, text: 'O'})
 mapviewer.addPOI({position: mytargetposition, text: 'T'})
 mapviewer.addPOI({position: mapviewer.offsetPosition(myposition,myheading,0,10), text: 'i'})
 
// suppose you wanted to compute the heading between two lat/lon positions
 function computeHeading(startPosition,endPosition) {
   var startPoint = mapviewer.convertLatLonToPoint(startPosition);
   var endPoint = mapviewer.convertLatLonToPoint(endPosition);
   northPoint = mapviewer.offsetPosition(startPoint,0,0,10);
   return mapviewer.computeHeadingAngle(startPoint,northPoint,endPoint);
 }

computeRoute(pRouteRequest) → {jQuery.Deferred.Promise}

Computes a route, use addRoutingPath() to add it once computed.
Parameters:
Name Type Description
pRouteRequest object An object used containing the route being requested. It should also include callbacks for success and error.
Properties
Name Type Attributes Default Description
src string | RoutePosition The store id (e.g. "129") of the start point or position {"lat": x, "lon": y, "alt": z} or {"lat": x, "lon": y, "floor": floorname}
dst string | RoutePosition | Array The store id of the end point or position {"lat": x, "lon": y, "alt": z} or {"lat": x, "lon": y, "floor": floorname} or an array of those endpoints.
destinationOrder string <optional>
 'optimalFinishOnLast' How to interpret multiple destinations, applicable if .dst is anArray. Possible values 'inOrder', 'optimal', 'optimalFinishOnLast', 'closest' 'closest' will find the one destination that is shortest or fastest, use routeResult.destinationIndices array to determine which one.
language string <optional>
 "en" Two letter language code for navigation instructions, currently only "en" (English) and "fr" (French) are supported.
routingParameters object <optional>
 Different routing parameters.
Properties
Name Type Attributes Default Description
requestType string <optional>
 "fastest" "shortest" or "fastest".
excludedAttributes array | string <optional>
 Single atring or Array of strings of attributes to avoid. e.g. "stairway", "escalator", lift" or "stair". These parameters are case sensitive. The exact attribute name must be known in advanced and must be the same one that is on the Map.
excludedModalities array | string <optional>
 Single string or Array of strings of modalities to avoid. e.g. "pedestrian" or "shuttle". These parameters are case sensitive. The exact modalities available must be known in advanced and must be the same on the map.
edgeTimeByAttributes array | object <optional>
 Single triplet or Array of triplet of the form {"attribute": X,"modality":Y,"time":seconds}. This will affect the computation if and only if requestType is "fastest"
remapResultingModality object <optional>
 Associative Array of source modality to target modality. {"travelator": "pedestrian", "vipline": "pedestrian"}. This will affect the resuling route, by replacing the source modality by the target modality. Neither the route result nor the navigation computation will not have any reference of the source modality, even if it was used for the route (it will be marked as being the target modality). This does not change the resulting length or duration.
computeNavigation boolean <optional>
 false If true, will also return navigation information.
navigationParameters object <optional>
 Different navigation parameters. Only taken into account if computeNavigation is true.
Properties
Name Type Attributes Default Description
modalityParameters object <optional>
 Associative array of modality => navigationParameter, where navigation parameters can be { "straightAngleThreshold" : angle}, by default is 7 degrees. { "nearPlacesThreshold" : distance}, by default is 20 meters, nearPlaces will be generated using this threshold. { "distanceFromCouloirThreshold" : distance}, deprecated, by default 2 meters, used by "original" algorithm. Deprecated as intersection algorithm is more predictable. { "minimumInstructionLength" : distance}, deprecated, by default 0 meters, used by "original" algorithm to reduce number of instructions. Deprecated as intersection algorithm is more predictable.
algorithm string <optional>
 'auto' by default 'auto', otherwise 'originalAlgorithm' or 'intersectionAlgorithm' 'auto' will use 'intersection' algorithm where the intersections are explcitly described by the map if the 'intersection' attribute exists on the map (see mapviewer.getRoutingAttributes()) otherwise it will use the 'original' algorithm.
firstNodeAsIntersection boolean <optional>
 false Treats the first node (not the start) of the first instruction after the start or a waypoint as an intersection, used to force the generation of an instruction turn right or left when you leave a POI.
mergeFloorChangeInstructions boolean <optional>
 false if true, it does not generate instructions to change floor, change modality, change layer, or you have arrived used to reduce the number of generated instructions.
success function <optional>
 Deprecated, supported for backward compatibility, function called on success. pRouteData.status is either 200, 404, 500. Use .done()
error function <optional>
 Deprecated, supported for backward compatibility, function called on error contacting routing server. Use .fail()
Since:
  • 1.7.19 updated firstNodeAsIntersection parameter to include first node after waypoint. Navigation instructions can have .attributes parameter including floor transition attributes for next edge: "stairway","escalator", and "lift"
See:
Returns:
where a done() or fail() callback can be added. fail() will be called if src/dst is missing or if dst === src, or if there is a problem accessing the server. The result attributes are shown in the example.
Type
jQuery.Deferred.Promise
Examples
Compute a route that only takes elevators (i.e. avoids stairs and escalators)
mapviewer.computeRoute({
 src: "161",
 dst: "1",
 // include this line for handicap routing.
 routingParameters: { excludedAttributes: [ "stairway", "escalators" ] },
})
.done(function(req,data) { ... })
.fail(function(req) { ... });
Compute a route with navigation, but minimal number of instructions
mapviewer.computeRoute({
 src: "161",
 dst: "1",
 computeNavigation: true,
 navigationParameters: {
    "firstNodeAsIntersection": true,
    "mergeFloorChangeInstructions": true,
    "modalityParameters": {
          "pedestrian" : { "straightAngleThreshold" : 180.0, "nearPlacesThreshold": 4} }
    }
 })
 .done(function(req,data) { ... })
 .fail(function(req) { ... });
The result will have the following attributes:
{
   "request": { computeRoute request parameters..."src": ... "dst": ... }
   "legs": [{
       "dataset": "B3-UL00",
       "modality": "pedestrian",
       "destinationIndex": 0,
       "points": [{
           "lat": 45.74095,
           "lon": 4.88094,
       }, ...],
       "height": 0 // in meters
   }],
 "destinationIndices": [0,1], // array of actual order the destinations are visited, will have length 1 for 'closest', and length will be >= 1 for all.
   "length": 35.10, // in meters
   "duration": 31.58, // in meters
   "status": 200, // 200 means success, 404 not found, 500 internal error
   "sdkVersion": "1.7.16",
   "routingServerVersion": "javascript",
   "navigation": {
       "route": { ... this same object, used for having access to route, and route.request, when looking at navigation}
       "instructions": [{
           "positions": [{
               "lat": 45.74095,
               "lon": 4.88094,
           },...],
           "position": {
               "lat": 45.74095,
               "lon": 4.88094,
           },
           "height": 0,
           "modality": "pedestrian",
           "dataset": "B3-UL00",
           "destinationIndex": 0, // useful if route had multiple destinations
           // but not visited in order.
           "time": 0, // in in seconds of the start of the instructions
           "length": 6.624, // in meters
           "duration": 5.96, // in seconds
           "maneuverType": "eVgManeuverTypeTurnRight", // see MyNavigation
           "nearPlaces": [{ // array of IDs/distance/angle from the end point of the instruction.
               "id": "B3-UL01-ID0071",
               "distance": 6.623932, // distance in meters from the
               "angle": 180
           }, ...],
           "actionAngle": 88, // angle of change of direction of the end of the instruction
           "totalTime": 31.58, // total time of the whole navigation
           "icon": "transit_instruction_turn_right.png" // see MyNavigation
		   ...
		   "attributes": ["lift"] // could also be "stairway", or "escalator"
       }, ...],
       "parameters": { // navigation parameters passed in.
           "modalityParameters": {
               "shuttle": {
                   "straightAngleThreshold": 180,
                   "distanceFromCouloirThreshold": 1000
               }
           },
           "algorithm": "auto",
           "mergeFloorChangeInstructions": true // reduce number of instructions:
          // e.g. avoid issuing single instruction to change floor.
       },
   }
}
// to find the closest ID (using routes, not bird-flight distance)
// like closest toilet
// you would need to create a destination array of all the toilet IDs
mapviewer.computeRoute({src: 'B2-UL0-ID0087', // could be the result of getRoutingNode()
                        dst: ['B4-UL05-ID0028','B4-UL05-ID0027','B4-UL05-ID0029'], // could be the result of getRoutingNode() use .id to find out place id.
                        destinationOrder: 'closest'})
                      .done(function(request,data){
                        console.log('closest id:'+request.dst[data.destinationIndices[0]].id);
                       });

convertLatLonToPoint(pWGS84) → {localPoint}

Converts a point { lat:, lon: } to a local point { x:, y:}. Note local points have range of [0,1] If the local point has a coordinate outside this range, it would be valid, but outside the map. the local point can be used with vg.mapviewer.web2d.Camera.goTo function or vg.mapviewer.web2d.Mapviewer.addRoutingPath. if the projection is invalid, the points will be {x: 0, y: 0, valid: false}
Parameters:
Name Type Description
pWGS84 WGS84
See:
Returns:
Type
localPoint
Example
mapviewer.convertLatLonToPoint( {lat: 48.78103089521526, lon: 2.220475972879528})
=>  {x: 0.4999999999937126, y: 0.5000000001176671}

convertPointToLatLon(pPoint) → {WGS84}

Converts a local point { x:, y: } to { lat:, lon:}. If the projection is invalid, the points will be {lat: 0, lon: 0, valid: false}
Parameters:
Name Type Description
pPoint localPoint
Returns:
Type
WGS84
Example
mapviewer.convertPointToLatLon( {x: 0.5, y: 0.5})
=>  {lat: 48.78103089521526, lon: 2.220475972879528}

convertPointToScreen(local) → {ScreenPoint}

Converts a local point to a screen coordinate. for example {x: .., y:..} to a screen coordinate {left: ...,top: ...}
Parameters:
Name Type Description
local pPoint point object { x:, y:}
Since:
  • 1.7.15
Returns:
object {left:, top: }, {left: 0, top: 0} being top left corner of map container
Type
ScreenPoint

convertScreenToPoint(pScreenPosition) → {localPoint}

Converts a pixel coordinate to a local point. For example {left: ..., top: ....} to {x: .., y:.., z: 0} To use this local point as a camera position for use with camera.goTo or camera.position, one needs to add a .radius
Parameters:
Name Type Description
pScreenPosition ScreenPosition The .left/.top of the pixel over the container, {left:0,top:0} being top left corner of the container
Since:
  • 1.7.15
See:
Returns:
The converted local point object { x:, y:}.
Type
localPoint
Example
// The camera position corresponds to what is on the center of the map container
 // Screen to point can give you the same result as the camera position
 // if you ask for the position of the center point
 mapviewer.convertScreenToPoint({left: jQuery('#container').width()*0.5, top: jQuery('#container').height()*0.5 })
 mapviewer.camera.position

getAllPlaces() → {Array.<vg.mapviewer.web2d.Place>}

This method retrieves all map elements including icons and anonymous objects.
Returns:
placeObjects are indexed by their id and have the following members: vg.floor, vg.id, vg.position and, vg.originalColor.
Type
Array.<vg.mapviewer.web2d.Place>
Example
var places = mapviewer.getAllPlaces();
for (var i in places) {
  var place = places[i];
  console.log(i + ' floor: '+ place.vg.floor + ' x: ' + place.vg.position.x + ' y: '+ place.vg.position.y);
}
=>
1 floor: 0 x: 0.5174714669769083 y: 0.25794685062655864
mapIcon02066 floor: 0 x: 0.4854098455666574 y: 0.20727326041037347
lift02 floor: 0 x: 0.5143540984984705 y: 0.6509336874168444
...

This is equivalent to calling getPlace() on all existing id's.

getCurrentFloor() → {string}

Returns the current floor name.
Since:
  • 1.7.17 if enabling floors individually via setEnabled(), then the result of this call is not valid.
Returns:
Type
string

getExtraData() → {Object|false}

Returns any extra data embedded in the map (e.g. venue layout).
Since:
  • 1.7.17
Returns:
returns any extra data embedded in the map (e.g. venue layout) or false otherwise
Type
Object | false

getFloors() → {object}

Retrieves list floor objects which has the public attribute name and index.
Since:
  • 1.7.10 added .heightMin and .heightMax to floor structure.
Returns:
Array of floor objects which have attribute .name (string), .index (number) and if available .heightMin (number) and .heightMax (number)
Type
object
Example
var floors = mapviewer.getFloors();
for (i in floors) {
   var floor = floors[i];
   console.log('name: '+ floor.name + ' index: '+floor.index);
}
=>
name: 0 index: 0 // the name could be RDC or any string.
name: 1 index: 1
name: 2 index: 2

getFootprint(id) → {object|false}

This method retrieve a footprint for an ID if it exists
Parameters:
Name Type Description
id string the place id. e.g. "L250"
Since:
  • 1.7.19 added .floor attribute to result.
See:
Returns:
object containting attributes .id, .floor, and .points: array of points
Type
object | false

getFootprints()

This method retrieves all footprints that are on the map. If there is no footprint data on the map, there will be no keys on the result.
Since:
  • 1.7.22
See:
Returns:
Object with keys being the IDs and each value being the footprint object containting attributes .id, .floor, and .points: array of points. You should not modify the result of this function

getPlace(id) → {vg.mapviewer.web2d.Place|false}

This method retrieves a map element according to its ID.
Parameters:
Name Type Description
id string the place id. e.g. "L250"
Returns:
the place object if it exists, false otherwise. placeObjects have the following attributes: vg.floor, vg.id, vg.position and, vg.originalColor.
Type
vg.mapviewer.web2d.Place | false
Example
var place = mapviewer.getPlace('1');
console.log(i + ' floor: '+ place.vg.floor + ' x: ' + place.vg.position.x + ' y: '+ place.vg.position.y);
=>
1 floor: 0 x: 0.5174714669769083 y: 0.25794685062655864

getPoi() → {Array.<POI>|undefined}

returns returns an Array of all POIs with that id have that id. This replaces the POI plugin: mapviewer.plugin('poi').getPoi(id) NOTE: in constrast to VisioWeb, The POIs in VisioWeb2D are only those created manually. They do not include the labels of places and icons on the original map (VisioWeb does), as these are not modifiable on VisioWeb2D.
Since:
  • 1.7.19 updated documentation.
Returns:
you should not modify this array.
Type
Array.<POI> | undefined

getPoint(id) → {object|false}

This method retrieve the point data associated with a POI ID if it exists. similar to VisioMove getPOIDescriptor.
Parameters:
Name Type Description
id string the place id. e.g. "L250"
Since:
  • 1.7.19 added .floor attribute to result.
See:
Returns:
point information object containing attributes: id, x, y, headingInDegrees, .height, and .floor.
Type
object | false

getPoints()

This method retrieves all point data that os on the map. If there is no point data on the map, there will be no keys on the result.
Since:
  • 1.7.22
See:
Returns:
Object with keys being the IDs and each value being the point object containting attributes: id, x, y, headingInDegrees, .height, and .floor. You should not modify the result of this function

getPois()

returns Object whose keys are all POIs that were created after the map is loaded. Since they can appear at multiple LODs NOTE: in constrast to VisioWeb, The POIs in VisioWeb2D are only those created manually. They do not include the labels of places and icons on the original map (VisioWeb does), as these are not modifiable on VisioWeb2D.
Since:
  • 1.7.19 updated documentation.
See:
Returns:
Object with keys being the POI IDs and each value being an array of POIs with that ID, you should not modify this array.

getRoutingAttributes() → {Array|false}

Returns all the routing attributes that are present in the routing database if available. Its result can be used as a parameter to computeRoute pRouteRequest.routingParameters.excludedAttributes It can return for example ["stairs","lift","access","virutal"], note that "virtual" and "access" are internal attributes, not to be used.
Since:
  • 1.7.10
See:
Returns:
an array of modality names or false if it does not support this operation or if getRoutingURL does not return '#javascript'
Type
Array | false

getRoutingModalities() → {Array|false}

Returns all the routing modalities that are present in the routing database if available, for example ["pedestrian","shuttle"] Can be used as a parameter to computeRoute pRouteRequest.routingParameters.excludedModalities
Since:
  • 1.7.10
See:
Returns:
an array of modality names or false if it does not support this operation or if getRoutingURL() does not return '#javascript'.
Type
Array | false

getRoutingNode(placeOrPosition, parametersopt) → {RouteNodeObject|false}

It can be used for example to determine if an ID or position is routable, if not, then one could disable a Returns non-false if the place or position is routable. The result of this function can be passed to computeRoute as pRouteRequest.src or pRouteRequest.dst. If the dataset does not support offline routing, i.e. getRoutingURL() is not equal to '#javascript' this function will presume the place and position is routable. In the future, this can include a hint to speed up the computeRoute. route button for that ID.
Parameters:
Name Type Attributes Default Description
placeOrPosition string | RoutePosition id (e.g. "129") of the start point or position {"lat": x, "lon": y, "alt": z} or {"lat": x, "lon": y, "floor": floorname} or {x:, y:, floor/alt:}
parameters RoutingNodeParameters <optional>
 {option: 'onEdge',threshold: 200} {option: 'anyNode'|'onEdge', distanceThreshold: N, excludeModalities: ['shuttle']}
Since:
  • 1.7.21 update doc about attributes get getting a routing node from a position.
See:
Returns:
returns a RouteNodeObject which can be used as a src or dst parameter to computeRoute, or false if it is not routable. It can be of the form {id: poiID, floor: string } if computed from a poiID or { position: inputPosition, routePosition: positionOnRoutingNetwork, floor: string } if computed from a position. The .id attribute can be used after computing a multi-point route to determine the poiID of the third destinatin: routePatameters.dst[2].id
Type
RouteNodeObject | false
Examples
// go from your current position to a shop L250
var cameraPosition = mapviewer.camera.position;
var cameraPositionLatLng = mapviewer.convertPointToLatLon({x: cameraPosition.x, y: cameraPosition.y });
var srcNode = mapviewer.getRoutingNode({lat: cameraPositionLatLng.lat,
                                                   lon: cameraPositionLatLng.lon,
                                                   floor: mapviewer.getCurrentFloor() });
var dstNode = mapviewer.getRoutingNode('L250');
if (srcNode !== false && dstNode !== false)
{
  mapviewer.computeRoute({
   src: srcNode,
   dst: dstNode,
  })
  .done(function(req,data) { ... })
  .fail(function(req) { ... });
} else {
  .. figure out if the error is on the srcNode or dstNode and inform the user...
}
// you can look at .floor, and .id if getting routing node from ID.
mapviewer.getRoutingNode('1')
  => { "id": "1", "floor": "0", "_hint": private }

// you can look at .floor, .position (position used for the search), and .routePosition (position on routing network) if getting routing node from position.
mapviewer.getRoutingNode({x: 0.5, y: 0.5, alt: 0 })
  => { "floor": "0", "position": { x: 0.5, y: 0.5, z: 0}, "routePosition": { x: 0.21, y: 0.32, z: 0 },  "_hint": private }

getRoutingURL() → {string}

This method is used to retrieve the routing URL: If the returned URL is '#javascript' it means there is routing data embedded in map data and routing will be computed in javascript without accessing the network If it returns a URL, it means that route computations will be done by a server If it returns empty string, it means routing is not possible and mapviewer.computeRoute() will fail. For local maps without off-line routing, you must call setRoutingURL with the right URL to service the route computations.
Since:
  • 1.7.10 for datasets that support off-line routing, returns #javascript
See:
Returns:
The routing server URL.
Type
string

getViewpointFromPositions(options)

Computes a viewpoint (camera position: .x, .y, .radius) which centers the point on the padded viewport. This method preserves the camera altitude (or zoom) when only 1 position is provided.
Parameters:
Name Type Description
options object
Properties
Name Type Attributes Default Description
points Array local positions containing .x and .y, and optionally .z
top number <optional>
 0 top padding in pixels
bottom number <optional>
 0 bottom padding in pixels
left number <optional>
 0 left padding in pixels
right number <optional>
 0 right padding in pixels
Since:
  • 1.7.10
Returns:
camera position object (Attributes .x, .y and .radius) or false if input position not valid (missing x and y)
Examples
// suppose you have a transparent overlay menu overlaps 200 pixels the right of the map.
// getViewpointFromPosition can be used to compute a viewpoint such that certain positions
// do not "land" on margin areas.
var viewpoint = mapviewer.getViewpointFromPositions({
 points: [{x: ..., y: ..., z: ...}],
 top: 10,
 bottom: 10,
 left: 10,
 right: 200
);
mapviewer.camera.position = viewpoint;
// Suppose you want to recenter the camera because you have a 200 pixel status bar on the bottom of the map
var viewpoint_options = { points: [mapviewer.camera.position], bottom: 200};
mapviewer.camera.position = mapviewer.getViewpointFromPosition(viewpoint_options);

highlight(place, color, optionsopt) → {boolean}

Set a place color (as highlight, ie temporarly).
Parameters:
Name Type Attributes Description
place vg.mapviewer.web2d.Place placeObject returned by getPlace()
color string highlight color in hexadecimal, e.g. 0x00ff00. Results are non predictable (usually black) if a non-hexadecimal value is given.
options <optional>
Properties
Name Type Attributes Default Description
opacity <optional>
 1.0 Opacity of the highlight
Returns:
true if a place was highlighted.
Type
boolean
Example
mapviewer.highlight(mapviewer.getPlace('161'),0x00FF00, {opacity: 0.5})

initialize(mapDiv, parameters) → {jQuery.Deferred.Promise}

This method is called to load and initialize a Mapviewer object.
Parameters:
Name Type Description
mapDiv DOM is the DOM element where the Mapviewer will render itself; it must be already in the DOM and have attribute id! It is used to obtain the size of the map. IE8 Note if there are UI elements over the mapDiv, make sure they have a z-index CSS attribute, e.g. z-index: 100.
parameters object a parameter map supporting the following values:
Properties
Name Type Attributes Default Description
path string path to map file. e.g. '../data.bundles/mapname/map.tiles.json' or '//mapmanager.visioglobe.com/public/xxxhashxxx/content/map.tiles.json', You must either supply this parameter or .mapContentString
initialFloorName string <optional>
 name of initial floor. If it does not exist or invalid, it will use first floor on map.
onObjectMouseUp function <optional>
 this callback will be triggered when click.
onObjectMouseOver function <optional>
 this callback will be triggered when the mouse is going over on object. Important, this callback will be ignored if .enableMouseOver is false. Avoid adding this callback if you know the webpage is on a mobile or touch only device because its existence can reduce the performance of the map.
enableObjectMouseOver bool <optional>
 depends This value is false on devices that should not have a mouse (for performance and optimization reasons), true otherwise. You can set it to true, if you want to receive mouseOver events on certain devices (that have both mouse and touch). We guess if a devices would never have a mouse by testing navigator.userAgent with (/android|webos|iphone|ipad|ipod|blackberry|iemobile|opera mini/)
onObjectMouseOut function <optional>
 this callback will be triggered when the mouse leaves an object. Important, this callback will be ignored if .enableMouseOut is false. Avoid adding this callback if you know the webpage is on a mobile or touch only device because its existence can reduce the performance of the map.
enableObjectMouseOut bool <optional>
 depends This value is false on devices that should not have a mouse (for performance and optimization reasons), true otherwise. You can set it to true, if you want to receive mouseOut events on certain devices (that have both mouse and touch).
forceHasPointerEvents bool <optional>
 automatic forces the use or disuse of CSS pointer events. This influences label centering mechanism. It is false for IE8, IE9, IE10 (see http://caniuse.com/pointer-events) Without CSS pointer events, the labels cannot be centered properly AND have proper event listeners.
mapContentString string <optional>
 advanced: content of map file as a string, to be used when you want to use your own mechanism to load the map file. Cannot be used at the same time as parameters.path.
mapContentDirectory string <optional>
 advanced: when loading mapContentString this specifies the directory for the resources.
useJSONP bool <optional>
 false forces the use JSONP, this is kept only in version 1.7.15 for backward compatibility. If the map is hosted on different domain, make sure the server is setup with CORS Headers. For IE8/IE9 compatibility, it uses XDomainRequest for ajax requests on IE8/IE9.
Since:
  • 1.7.19 notifications initializeCompleted and initializeFailed are sticky, any registration via .on will always receive them.
See:
  • vg.mapviewer.web2d.Mapviewer.prototype#trigger
Returns:
where a done() or fail(failresult) callback can be added, failresult.message will have more information on the cause of the failure. progress() can also be added, it will receive some updates as the map is processed.
Type
jQuery.Deferred.Promise
Example
<div id="mapdisplay" style="width: 640px; height: 480px"/>
...
var mapURL = "../data.bundles/visioglobe_generic_tiles/map.tiles.json"; // given to you by Visioglobe
mapviewer_parameters = {
  path: mapURL,
  initialFloorName: "1",
  onObjectMouseUp: function (event, element){alert('clicked on '+element.vg.id);}
}
mapviewer = new vg.mapviewer.web2d.Mapviewer();
mapviewer.initialize(jQuery('#mapdisplay')[0], mapviewer_parameters)
.done(function() { mapviewer.start(); })
.fail(function(result) { if (result !== undefined && result.message !== undefined) { console.error(result.message);}  })
.progress(function(percentage) { });

off(type, handleropt) → {boolean}

similar to jQuery off, used to remove event listeners
Parameters:
Name Type Attributes Description
type string of event ex: 'routeComputed' or list of events separated by spaces 'floorChanged floorWillChange'
handler function <optional>
 handler to remove, if no handler, it will remove all events for that type.
Since:
  • 1.7.14
See:
Returns:
true if it removed any handler.
Type
boolean

offsetPosition(pPoint, pHeadingInDegrees, pPitchInDegrees, pDistanceInMeters) → {localPoint}

Offsets a position with a distance in meters given a direction.
Parameters:
Name Type Description
pPoint localPoint The local point to start from, { x:, y:, z:}
pHeadingInDegrees number heading in degrees, 0 is North
pPitchInDegrees number pitch in degrees, 0 is horizontal, -90 is downward
pDistanceInMeters number distance in meters to move the point
Since:
  • 1.7.16
See:
Returns:
the start point moved pDistanceMeters in a given heading and pitch
Type
localPoint

on(type, handler)

similar to jQuery on, used to add event listeners. You can listen to the mapviewer defined events, or you can listen to your own (for which you will have to trigger them). Currently: 'routeComputed','floorChanged','floorWillChange', 'resize', 'mouseup', 'initializeCompleted', 'initializedFailed', and 'redraw' If the handler returns false, other subsequent handlers will not be called.
Parameters:
Name Type Description
type string of event ex: 'routeComputed' or list of events separated by spaces, e.g. 'floorChanged floorWillChange'
handler function event object will contain .type,, .args is an object
Since:
  • 1.7.19 added 'redraw'
See:
Examples
mapviewer.on('floorWillChange',function(ev) {
	// update UI
	console.log('floorWillChange');
	// returning false would stop the floor from changing
});
mapviewer.on('floorChanged',function(ev) {
	// update UI
	console.log('floorChanged' + ev.args.current + ' target ' + ev.args.target);
});
// You need to add this in order for the resize trigger to work.
jQuery(window).resize(function(event) {
	mapviewer.resize(jQuery('#container').width(), jQuery('#container').height());
});

mapviewer.on('resize', function(ev) {
  console.log('new map dimension: '+ev.args.mapWidth+ 'x'+ev.args.mapHeight);
});

once(type, handler)

similar to jQuery once, used to add event listeners that will only be executed once, and automatically removed after execution. If the handler returns false, other subsequent handlers will not be called.
Parameters:
Name Type Description
type string of event ex: 'routeComputed' or list of events separated by spaces, e.g. 'floorChanged floorWillChange'
handler function event object will contain .type a string, .args is an object
Since:
  • 1.7.22
See:
Example
mapviewer.once('initializeCompleted',function(ev) {
		// update UI
		console.log('initializeCompleted');
		// by using once, this function will be removed after first execution.
	});

	// setup some event that will cause a redraw, and wait for redraw
	mapviewer.once('redraw',function(ev) {
		// update UI
		console.log('redraw just happened');
	});

queryNearPlaces(position, parametersopt) → {Array}

finds all the places that are near a position within a certain threshold. uses the position.alt or position.floor to figure out what layer to search on
Parameters:
Name Type Attributes Description
position position | point {"lat": lat, "lon": lon, "alt": z} or point {"x": x, "y": y, "floor": floorname}. If using .floor, it will only search in a particular floor. If using .alt, it will search on all layers that are at that altitude.
parameters object <optional>
Properties
Name Type Attributes Default Description
distanceThreshold number <optional>
 10 by default it will only look at places (access points) within 10 meters of the given position.
heading number <optional>
 0 by default the heading will be north (in degrees, values from 0 to 360)
Since:
  • 1.7.18
Returns:
of {.id: placeid, .angle: heading angle between inputParameter.heading/position and the place, .distance: in meters}, sorted by distance.
Type
Array
Examples
//var positionAlt0 = {lon: 4.8835509, lat: 45.7399682, alt: 0.0};
 //var positionFloor = {lon: 4.8835509, lat: 45.7399682, floor: "B2-UL02"};
var parameters = { heading: mapviewer.camera.heading, threshold: 10};
var position = mapviewer.camera.position; // will set .x and .y
position.floor = mapviewer.getCurrentFloor()

var nearPlaces = mapviewer.queryNearPlaces(position, parameters);
if (nearPlaces.length > 0)
{
    var nearPlace = nearPlaces[0];
    console.log('the closest place is '+nearPlace.id + ' at distance '+nearPlace.distance + ' angle: '+nearPlace.angle);
}
// find places near start of instruction, assuming current instruction is in var instruction

// suppose you wanted to compute the heading between two lat/lon positions
function computeHeading(startPosition,endPosition) {
  var startPoint = mapviewer.convertLatLonToPoint(startPosition);
  var endPoint = mapviewer.convertLatLonToPoint(endPosition);
  northPoint = mapviewer.offsetPosition(startPoint,0,0,10);
  return mapviewer.computeHeadingAngle(startPoint,northPoint,endPoint);
}
var position = instruction.position; // this will set .lat and .lon
position.floor = instruction.dataset;
var parameters = {heading: computeHeading(instruction.positions[0], instruction.positions[1]), threshold: 20};
var nearPlaces = mapviewer.queryNearPlaces(position, parameters);
for (var i in nearPlaces)
{
  var nearPlace = nearPlaces[i];
  console.log('the closest place is '+nearPlace.id + ' at distance '+nearPlace.distance + ' angle: '+nearPlace.angle);
}

removeHighlight(place(s)) → {boolean}

Removes the highlight from a placeObject, thus returning the place to its original color.
Parameters:
Name Type Description
place(s) vg.mapviewer.web2d.Place | Array.<vg.mapviewer.web2d.Place> returned by getPlace()
Returns:
true if a highlight was removed.
Type
boolean
Example
mapviewer.removeHighlight(mapviewer.getPlace('161'))

removePostRenderListener(listener(mapviewer))

removes a callback
Parameters:
Name Type Description
listener(mapviewer) function
Since:
  • 1.7.19 returns true if listener will be removed.
See:
Returns:
true if a listener will be remove. It will remove at most one listener

requestRedraw()

Triggers the calling of the postRenderListener's
Since:
  • 1.7.19
See:

resize(width, height)

Resize map. The container should have been resized beforehand. If percentage size must be used, then it is the integrator's responsibility to call the resize() function at every resize. Note: when resizing the amount of visible map will change as the camera will not move.
Parameters:
Name Type Description
width number The maps width
height number The maps height
Since:
  • 1.7.19 resize trigger notification is sticky.
Example
jQuery(window).resize(function(event) {
	mapviewer.resize(jQuery('#container').width(), jQuery('#container').height());
});
mapviewer.on('resize', function(ev) {
  console.log('new map dimension: '+ev.args.mapWidth+ 'x'+ev.args.mapHeight);
});

setPlaceIcon(id, url, optionsopt)

places an icon over a place. (eg ../media/test.png) The default width and height comes from the CSS class .vg-setplaceicon.
Parameters:
Name Type Attributes Description
id string the place id e.g. "L250"
url string | object the icon URL. the icon URL must be in the same domain as the viewer, Otherwise the browser security restrictions will prevent it from loading. It can also be an object with .url attribute and possibly .visibilityRampStartInvisible, .width, and/or .height
options object <optional>
Properties
Name Type Attributes Default Description
visibilityRampStartInvisible number <optional>
 specifies at which camera.position.radius elements should be visible. default value shows the icon on the last two zoom levels.
width number <optional>
 CSS .vg-setplaceicon for example '64', do not put 'px'
height number <optional>
 CSS .vg-setplaceicon for example '64', do not put 'px'
Since:
  • 1.7.19 can take second parameter as options directly, to be compatible with VisioWeb

setPlaceName(id, label, optionsopt)

Set a name over a place. You can use the CSS class .vg-setplacename to control the style of the text.
Note On low-end mobile devices displaying many place names can reduce the map performance.
Known Limitation Place names are not centered on browsers that do not support CSS pointer events.
Parameters:
Name Type Attributes Description
id string the place id e.g. "L250"
label string | object the place name that must be displayed, or object containing .text attribute Note This string passed will be placed inside a UNESCAPED therefore care must be taken on what is placed inside this label. For example: setPlaceName(myid,'&lt;') will place a label with: '<'. If you wanted to add line breaks you could do setPlaceName(myid,text.replace(/ /g,'<br>'))
options object <optional>
Properties
Name Type Attributes Description
visibilityRampStartInvisible number <optional>
 specifies at which camera.position.radius elements should be visible. default value shows the text on the last two zoom levels. If you wanted to be displayed only at the last zoom level, you could use mapviewer.camera.minRadius
Since:
  • 1.7.19 can take second parameter as options directly, to be compatible with VisioWeb
Example
mapviewer.setPlaceName('114','Big Store');
 jQuery('.vg-setplacename').css('font-size','18px');

mapviewer.setPlaceName('L250', { text: 'Zara',
								 visibilityRampStartInvisible: 400 // this is the only option processed by VisioWeb2D.
							 });
  NOTE: you can do this runtime as a test, but this should be done on a CSS file.
  the labels will be created on demand (eg floor change) thus the style of labels
  on other floors will not change with this method if the floor has not been loaded

setRoutingURL(url)

This method is used to set a specific routing URL to this viewer.
Parameters:
Name Type Description
url string the routing server base URL.

start()

Exists for compatibility reasons.

trigger(type, args)

trigger an event type. It will execute all triggers ordered by type, stopping if any handler returns exactly false
Parameters:
Name Type Description
type string of event ex: 'routeComputed' or list of events separated by spaces 'floorChanged floorWillChange'
args anything as a function of event type
Since:
  • 1.7.17 stops if any handler returns false
See:
Returns:
false if any handler returned false