Class vg.mapviewer.kiosk.Mapviewer

Class Detail

Field Detail

See:

vg.mapviewer.kiosk.Mapviewer#Camera

mapviewer.camera.rotation = mapviewer.cameraNorthRotation;

Since:

1.7.3

if (!mapviewer.isAccelerated) 
{
	mapviewer.camera.pitch = -90;
	mapviewer.camera.pitchManipulatorEnabled = false;
	// we can allow rotation.
	//mapviewer.camera.rotationManipulatorEnabled = false;
}

Method Detail

• {vg.mapviewer.kiosk.POI} addPOI(options)
  This method allow to add a POI Object in the scene. The POI is visible by default after creation.

  // For text that zooms in and out
  // which you could also control the visibility (with ramp functions)
  // use 'text' and 'url' fields
  // use onObjectMouseUp to get a callback on click
  selected_poi = mapviewer.addPOI({
      url: "test.png",
  	   text: 'The object "'+element.vg.id+'" has been clicked',
  	   position: {x: element.vg.position.x, y: element.vg.position.y, z: 10},
      id: 'mypoi',
      onObjectMouseUp: function() {alert('click');},
  	   scale: 6
  });

  // 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>
  ...
  selected_poi = mapviewer.addPOI({
  	   selector: '#test',
  	   position: {x: element.vg.position.x, y: element.vg.position.y, z: 10},
  });

  Parameters:

  {object} options

  {number} options.size Optional, Default: 64

  Used to control the size of the texture for the text. Not generally used, unless memory problems, zero not allowed.

  {string} options.text Optional, Default: ''

  The text to display above the POI. The use of options.text is mutually exclusive with options.url/options.seletor.

  {color string} options.color Optional, Default: '#ffffff'

  The text color, in hexadecimal. Used in conjunction with options.text.

  {string} options.family Optional, Default: 'Arial'

  The font type. Used in conjunction with options.text.

  {url} options.url Optional, Default: ''

  URL to an image to display. The use of options.url is mutually exclusive with options.text/options.seletor.

  {div id} options.selector Optional, Default: ''

  The div id (eg. '#test') to overlay at position. Use selector when you want something to be constant size and you can to control its style via CSS. The selector css display is set to visible (and 'none' when removed). The use of options.selector is mutually exclusive with options.url/options.text.

  {vector} options.position Optional, Default: {x:0.0, y:0.0, z:0.0}

  {vector} options.rotation Optional, Default: {x:0.0, y:0.0, z:0.0}

  {vector} options.alignment Optional, Default: {x:0.0, y:0.0}

  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}

  {vector} options.scale Optional, Default: {x:70.0, y:70.0, z:1.0}

  It only affects options.url and options.text

  {vector} options.icon_scale Optional, Default: {x:70.0, y:70.0, z:1.0}

  Used in conjunction with options.url

  {string} options.floor Optional, Default: currentFloorName

  The floor to add the POI.

  {number} options.visible Optional, Default: true

  If enabled, the POI will be visible directly after calling this method.

  {string} options.id Optional, Default: null

  Used to identify the POI. Should not be an already used id.

  {number} options.visibilityRampStartVisible Optional, Default: 2.0

  Only applicable if options.url or options.text exist.

  {number} options.visibilityRampFullyVisible Optional, Default: 5.0

  Only applicable if options.url or options.text exist.

  {number} options.visibilityRampStartInvisible Optional, Default: 3000.0

  Only applicable if options.url or options.text exist.

  {number} options.visibilityRampFullyInvisible Optional, Default: 5000.0

  Only applicable if options.url or options.text exist.

  {function(event|place orpoi)} options.onObjectMouseOver Optional, Default: global callback

  Only applicable if options.url or options.text AND options.id exist. This function gets called anytime the mouse moves over a surface (as opposed to just once when it enters). This is historic behavior which makes highlighting a single shop easier. It the mouse is over multiple POIs, it will receive multiple callbacks, with the farthest POIs being notified first.

  {function(event|place or poi)} options.onObjectMouseOut Optional, Default: global callback

  Only applicable if options.url or options.text AND options.id exist.

  {function(event|place or poi)} options.onObjectMouseUp Optional, Default: global callback

  Only applicable if options.url or options.text AND options.id exist.

  {bool} options.fixed Optional, Default: false

  When enabled the POI is shown at a fixed angle. The fixed angle is determined by options.angle and it forces the options.face2D to true. Useful for representing directional arrows, for example an arrow which points North. Used in conjunction with options.angle and options.url. Does not apply to options.selector.

  {number} options.angle Optional, Default: 0

  Angle in degrees with respect to map. Only applicable if used in conjunction with options.url OR options.text WITH options.fixed=true. 0 means horizontal, 90

  {number} options.width Optional, Default: -1

  Used with height to specify the box in which the text and icon will reside. If you use this option make sure to set .scale to {x:1,y:1,z:1}

  {number} options.height Optional, Default: -1

  Used with width to specify the box in which the text and icon will reside. If you use this option make sure to set .scale to {x:1,y:1,z:1}

  {bool} options.overlay Optional, Default: false

  When enabled the POI will be displayed over the other geometries.

  {bool} options.flip Optional, Default: false

  When enabled the POI will automatically flip so that it is easily readable from the current camera position. Only applicable if options.fixed=true and if options.angle does not exist.

  {bool} options.face2d Optional, Default: false

  When enabled the POI will lay flat on the ground. Otherwise the POI will always be camera facing (independent of the camera's pitch). Only applicable if options.fixed=false.

  Since:

  1.7.10 can options.alignment for .url

  Returns:

  {vg.mapviewer.kiosk.POI}
• {vg.mapviewer.kiosk.Path | false} addRoutingPath(options)
  This method allow to add a path to the scene. Note: all points should have the same .z otherwise the track may not be flat.

  Parameters:

  {object} options

  {points[]} options.points

  An Array of two or more local points (i.e. with values {x: number, y: number}) you can add an optionnal z key.

  {string} options.url Optional

  The url of an image to be used as a texture for the track.

  {number} options.speed Optional, Default: 1.0

  Speed can be zero for non animated tracks. Negative values for the texture (options.url) will move towards the beginning. If options.url is missing, default value is 0.

  {number} options.repeat Optional, Default: -1

  Determines how many times the texture should be repeated on the track. Value can't be 0. Negative values (-N), means N every thickness. Using positive values will most likely result in stretched textures.

  {number} options.segments Optional, Default: -1

  Total number of segments for the Path description. Higher values means finer detail and negative values means number of meters per segment. It is recommended to use negative numbers.

  {number} options.thickness Optional, Default: 2

  The thickness of the route, measured in meters. Can't be negative nor zero.

  {string} options.floor Optional, Default: currentFloorName

  The floor to ad the route to.

  {boolean} options.visible Optional, Default: true

  Determines whether the route is visible.

  {color} options.color Optional, Default: 0xffffff

  Can be a string or hexadecimal number

  {number} options.opacity Optional, Default: 1.0

  Determines the opacity of the route. Value between 0 and 1. Note: if using 0, better to make object invisible.

  {number} options.interpolationStart Optional, Default: 0.0

  if path should be drawn partially, this is a value between 0 and 1 (inclusive)

  {number} options.interpolationEnd Optional, Default: 1.0

  if path should be drawn partially, this is a value between 0 and 1 (inclusive), should be greater than options.interpolationStart

  {boolean} options.interpolationTextureLikeWindow Optional, Default: true

  if false, the texture (.url) at interpolationStart will be always the same (so it looks like a moving something), if true, the textures will be fixed on the path and the interpolation will look like a sliding window.

  Since:

  1.7.10 changed default of options.speed to 0.0., 1.7.11 added interpolationStart, interpolationEnd, interpolationTextureLikeWindow options

  Returns:

  {vg.mapviewer.kiosk.Path | false} a path or false.

  See:

  vg.mapviewer.kiosk.Mapviewer#convertLatLonToPoint
• {jQuery.Deferred Promise} changeFloor(targetFloorNumber, options)
  This method is called to change floor. The error function is called if a change floor animation is in progress.

  mapviewer.changeFloor(target_floor).done(function() { updateActiveFloorLabel(target_floor);});

  Parameters:

  {string} targetFloorNumber

  The floor to change to. If it is the same as the current floor, the done() function is called directly.

  {object} options Optional

  Additional options to change floor.

  {number} options.animationDuration Optional, Default: 500

  Duration of the change floor animation.

  Returns:

  {jQuery.Deferred Promise} where a done() or fail() callback can be added.
• {jQuery.Deferred Promise} computeRoute(pRouteRequest)
  Computes a route, use addRoutingPath() to add it once computed.

  Compute a route that only takes elevators (i.e. avoids stairs and escalators)
  mapviewer.computeRoute({
   src: "161",
   dst: "1",
   routingParameters: { excludedAttributes: [ "stairway", "escalators" ] },  // include this line for handicap routing.
  })
  .done(function(req,data) { ... })
  .fail(function(req) { ... });

  Compute a route with navigation, but minimal number of instructions
  mapviewer.computeRoute({
   src: "161",
   dst: "1",
   navigationParameters: { "modalityParameters": { "pedestrian" : { "straightAngleThreshold" : 180.0} } }
  })
  .done(function(req,data) { ... })
  .fail(function(req) { ... });

  Parameters:

  {object} pRouteRequest

  An object used containing the route being requested. It should also include callbacks for success and error.

  {string|RoutePosition} pRouteRequest.src

  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}

  {string|RoutePosition} pRouteRequest.dst

  The store id of the end point or position {"lat": x, "lon": y, "alt": z} or {"lat": x, "lon": y, "floor": floorname}

  {string} pRouteRequest.language Optional, Default: "en"

  Two letter language code for navigation instructions, currently only "en" (English) and "fr" (French) are supported.

  {object} pRouteRequest.routingParameters Optional

  Different routing parameters.

  {string} pRouteRequest.routingParameters.requestType Optional, Default: "fastest"

  "shortest" or "fastest".

  {array|string} pRouteRequest.routingParameters.excludedAttributes 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.

  {array|string} pRouteRequest.routingParameters.excludedModalities 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.

  {array|object} pRouteRequest.routingParameters.edgeTimeByAttributes 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"

  {boolean} pRouteRequest.computeNavigation Optional, Default: false

  If true, will also return navigation information.

  {object} pRouteRequest.navigationParameters Optional

  Different navigation parameters. Only taken into account if computeNavigation is true.

  {object} pRouteRequest.navigationParameters.modalityParameters Optional

  Associative array of modality => navigationParameter, where navigation parameters can be { "straightAngleThreshold" : angle}, by default { "shuttle": { "straightAngleThreshold" : 180.0, ""}}

  {function(pRouteRequest|pRouteData)} pRouteRequest.success Optional

  Deprecated, supported for backward compatibility, function called on success. pRouteData.status is either 200, 404, 500. Use .done()

  {function(pRouteRequest)} pRouteRequest.error Optional

  Deprecated, supported for backward compatibility, function called on error contacting routing server. Use .fail()

  Since:

  1.7.10 updated to handle off-line routing if the data has been published with this information (and getRoutingURL() return #javascript)

  Returns:

  {jQuery.Deferred Promise} 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.

  See:

  vg.mapviewer.kiosk.Mapviewer#addRoutingPath()

  MyRoute
• {localPoint} convertLatLonToPoint(pWGS84)
  Converts a lat/lon point to a local point. The local point can be used with vg.mapviewer.kiosk.Camera.goTo function or vg.mapviewer.kiosk.Mapviewer.addRoutingPath.

  Parameters:

  {WGS84} pWGS84

  The Lat/Long object to be converted { lat:, lon: }.

  Returns:

  {localPoint} The converted local point object { x:, y:, z:}. If the projection is invalid, the local point will be {x: 0, y: 0, z: 1, valid: false}.

  See:

  vg.mapviewer.kiosk.Mapviewer#addPOI

  vg.mapviewer.kiosk.Mapviewer#addRoutingPath

  vg.mapviewer.kiosk.Camera#goTo
• {WGS84} convertPointToLatLon(pPoint)
  Converts a local point to a lat/lon point.

  Parameters:

  {localPoint} pPoint

  The local point to be converted, { x:, y:, z:}

  Returns:

  {WGS84} The converted lat/lon point, { lat:, lon:}. The projection is invalid, the points will be {lat: 0, lon: 0, valid: false}
• {ScreenPoint} convertPointToScreen(local)
  Converts a local point to a screen coordinate. for example {x: .., y:.., optionally z} to a screen coordinate {left: ...,top: ...}

  Parameters:

  {pPoint} local

  point object { x:, y:, optionally z:}

  Since:

  1.7.11

  Returns:

  {ScreenPoint} object {left:, top: }, {left: 0, top: 0} being top left corner of map container
• {localPoint} convertScreenToPoint(pScreenPosition, optionalZ)
  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:

  {ScreenPosition} pScreenPosition

  The x/y of the pixel over the container, {x:0,y:0} being top left corner

  {number} optionalZ Optional, Default: 0

  height of the searched point

  Since:

  1.7.11

  Returns:

  {localPoint} The converted local point object { x:, y:, z:}. If the projection is invalid, the local point will be {x: 0, y: 0, z: 1, valid: false}.

  See:

  vg.mapviewer.kiosk.Camera#goTo
• {vg.mapviewer.kiosk.Place[]} getAllPlaces()
  This method retrieve ALL pickables elements. This is equivalent to calling getPlace() on all existing id's. If the id is not unique, the returned place is undefined, i.e. it could be different from what you would get on getPlace(id). This method also returns id's of objects added via addPOI. In general it can be called once, and the results cached on the page.

  Returns:

  {vg.mapviewer.kiosk.Place[]} placeObjects are indexed by their id and have the following members: floor, vg.id, vg.originalColor, and vg.position.
• {string} getCurrentFloor()
  Returns the current floor name.

  Returns:

  {string}
• {object} getFloors()
  Retrieve the floor objects.

  Since:

  1.7.10 added .heightMin and .heightMax to floor structure.

  Returns:

  {object} Array of floor objects which have attribute .name (string), .index (number) and if available .heightMin (number) and .heightMax (number)
• {vg.mapviewer.kiosk.Place|false} getPlace(id)
  This method retrieve a pickable element according to its ID.

  Parameters:

  {string} id

  the place id. e.g. "L250"

  Returns:

  {vg.mapviewer.kiosk.Place|false} The place object if it exists, false otherwise. placeObjects have the following members: vg.floor, vg.id and, vg.originalColor and vg.position.
• {Array|false} getRoutingAttributes()
  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

  Returns:

  {Array|false} an array of modality names or false if it does not support this operation or if getRoutingURL does not return '#javascript'

  See:

  vg.mapviewer.kiosk.Mapviewer#computeRoute

  vg.mapviewer.kiosk.Mapviewer#getRoutingURL
• {Array|false} getRoutingModalities()
  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

  Returns:

  {Array|false} an array of modality names or false if it does not support this operation or if getRoutingURL() does not return '#javascript'.

  See:

  vg.mapviewer.kiosk.Mapviewer#computeRoute

  vg.mapviewer.kiosk.Mapviewer#getRoutingURL
• {string|RoutePosition|false} getRoutingNode(placeOrPosition)
  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.

  // 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...
  }

  Parameters:

  {string|RoutePosition} placeOrPosition

  id (e.g. "129") of the start point or position {"lat": x, "lon": y, "alt": z} or {"lat": x, "lon": y, "floor": floorname}

  Since:

  1.7.10

  Returns:

  {string|RoutePosition|false} returns the same object as input, or false if it is not routable.

  See:

  vg.mapviewer.kiosk.Mapviewer#computeRoute

  vg.mapviewer.kiosk.Mapviewer#getRoutingURL
• {string} getRoutingURL()
  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

  Returns:

  {string} The routing server URL.

  See:

  vg.mapviewer.kiosk.Mapviewer#computeRoute

  vg.mapviewer.kiosk.Mapviewer#setRoutingURL
• getViewpointFromPositions(options)
  Computes a viewpoint (camera position: .x, .y, .radius) which centers the point on the padded viewport. If there is only one position (options.points.length == 1), this method preserves the current camera altitude and orientation.

  // 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);

  Parameters:

  {object} options

  {Array positions} options.points

  local positions containing .x and .y, and optionally .z

  {number} options.top Optional, Default: 0

  top padding in pixels

  {number} options.bottom Optional, Default: 0

  bottom padding in pixels

  {number} options.left Optional, Default: 0

  left padding in pixels

  {number} options.right Optional, Default: 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)
• {boolean} highlight(place, color)
  Set a place color (as highlight, ie temporarly).

  Parameters:

  {vg.mapviewer.kiosk.Place} place

  placeObject returned by getPlace()

  {color} color

  Highlight color in hexadecimal, e.g. 0x00ff00, results are non predictable (usually black) if a non-hexadecimal value is given.

  Returns:

  {boolean} Returns true if a place was successfully highlighted.
• {jQuery.Deferred Promise} initialize(mapDiv, parameters)
  This method is called to load and initialize a Mapviewer object

  Parameters:

  {DOM} mapDiv

  The DOM element where the Mapviewer will render itself. It is used to obtain the size of the map.

  {object} parameters

  A parameter object supporting the following values:

  {string} parameters.path Optional

  The path to the map file. e.g. .g. '../data.bundles/mapname/map.svg' or '//mapmanager.visioglobe.com/public/xxxhashxxx/content/map.svg'. You must either supply this parameter or .mapContentString

  {string} parameters.initialFloorName Optional

  Name of initial floor. If it does not exist or invalid, it will use first floor on map.

  {function(event|place or poi)} parameters.onObjectMouseOver Optional

  This callback will be triggered when the mouse is going over a placeObject. This function gets called anytime the mouse moves over a surface (as opposed to just once when it enters). This is historic behavior which makes highlighting a single shop easier. It the mouse is over multiple places, it will receive multiple callbacks, with the farthest POIs being notified first.

  {function(event|place or poi)} parameters.onObjectMouseOut Optional

  This callback will be triggered when the mouse leaves a placeObject. For performance reasons, this event will be triggered whenever there is a mouse move event

  {function(event|place or poi)} parameters.onObjectMouseUp Optional

  This callback will be triggered when a placeObject has been clicked.

  {boolean} parameters.antialias Optional, Default: true

  Use antialiased renderer, only relevant when renderType = 'webgl'.

  {string} parameters.logoPosition Optional, Default: 'TOP_RIGHT'

  Indicates the Visioglobe logo location within the mapDiv, supported values include: 'TOP_LEFT', 'TOP_RIGHT', 'BOTTOM_LEFT', and 'BOTTOM_RIGHT'.

  {string} parameters.mapContentString 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.

  {string} parameters.mapContentDirectory Optional

  advanced: when loading mapContentString this specifies the directory for the resources.

  {boolean} parameters.bugWP81 Optional, Default: false

  work around for bug on WP 8.1 version 8.10.12393.890

  Returns:

  {jQuery.Deferred Promise} Where a .done() or .fail(failresult) callback can be added, failresult.message will have more information on the cause of the failure.
• {boolean} removeHighlight(place(s))
  Removes the highlight from a placeObject, thus returning the place to its original color.

  Parameters:

  {vg.mapviewer.kiosk.Place|vg.mapviewer.three.Place[]} place(s)

  returned by getPlace()

  Returns:

  {boolean} Returns true if a highlight was successfully removed.
• resize(width, height)
  Resize map. The container should have been resized beforehand. Avoid using "width: 50%" as this allows the container to change size. If percentage size must be used, then it is the integrator's responsibility to call the resize() function at every resize.

  Parameters:

  {number} width

  The maps width

  {number} height

  The maps height
• setPlaceIcon(id, url)
  Set a place icon. The icon will have a fixed orientation except when the camera "switches" sides, at which point the icon will be flipped (the orientation changes 180 degrees).

  Parameters:

  {string} id

  The place id e.g. "L250"

  {string} url

  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.
• setPlaceName(id, label)
  Set a place name by updating all of its labels. All labels (text) will be updated. If an icon shares the same ID and label is not empty it will be ignored. The label will have a fixed orientation except when the camera "switches" sides, at which point the label is flipped (the orientation changes 180 degrees).
  NOTE: on IE10 this function is very expensive. Avoid rendering all the labels.

  Parameters:

  {string} id

  The place id e.g. "L250"

  {string} label

  The place name to be displayed.
• setRoutingURL(url)
  This method is used to set a specific routing URL to this viewer.

  Parameters:

  {string} url

  The routing server base URL.
• start()
  This method must be called when the HTML document is loaded in order to start the rendering. Should be called as late as possible to minimize unneccessary screen refreshes.