JavaScript API

The player has an external API so it can be controlled with JavaScript.

The skin uses this exact API. Since the skin files are not minified, you can peek into a skin file to figure out how some things are done internally.

All the examples below use pano as the object. However, if you use JavaScript in the skin, you must use player as the object.

Using JavaScript in the Skin Editor

There are two ways of using JavaScript in the Skin Editor. The Code Element and the Go to URL Action. (Previously the Text Box was used and is now a legacy method.)

Code Element

The Code Element is a dedicated skin element for adding Javascript to the project.

Learn how to add code using the code element..

Go to URL Action

This lets you trigger JavaScript code by an action in the skin. For instance, add an action to a text element, set the source to Mouse Click, the action to Go to URL, and in the URL field add javascript: Your JavaScript code... or js: Your JavaScript code...

Like:

javascript: alert("Button clicked!");

Setup

pano.readConfigUrl(url: String, base: String="") Read the node/tour configuration from a url. The base parameter defines a different base path.

pano.readConfigUrlAsync(url: String, callback: Function, base: String="") Same as readConfigUrl but asynchronous.

pano.readConfigString(xml: String) Read the node/tour configuration from a string.

pano.readConfigXml(xml: Document) Read the node/tour configuration from a XML Document object.

pano.getBasePath() pano.setBasePath(path: String) Get/set the base path. The base path is added to relative file names and urls. This is useful, if the HTML file has a different base then the xml configuration file. Also note that the placeholder $(r) gets replaced by the player’s base path.

pano.setCrossOrigin(s: String) Set the crossorigin attribute for all external files like the config, images, tiles and embedded videos. The default is anonymous.

pano.destroy() Completely shut down the player: stops the render loop, releases GPU and media resources, and removes its listeners and DOM elements. Use this in single-page applications when the player is no longer needed. The instance cannot be reused afterwards.

skin.removeSkin() Remove the skin’s elements, styles, and listeners from the page. If you created a skin object, call this before pano.destroy().

Viewing direction

pano.getPan() Return the current pan angle.

pano.getPanN() Return a normalized current pan angle (between -180.0 and +180.0).

pano.getPanNorth() Return the current pan angle including the nodes north offset.

pano.setPan(angle_in_degrees: Number) Sets the current pan angle.

pano.setPanNorth(angle_in_degrees: Number) Sets the current pan angle, taking the nodes north offset into account.

pano.changePan(offset_in_degrees: Number) Change the current pan angle.

pano.getTilt() Returns the current tilt angle.

pano.setTilt(angle_in_degrees: Number) Sets the current tilt angle.

pano.changeTilt(offset_in_degrees: Number) Change the current tilt angle.

pano.getFov() Return the current Field of View, depending on the FoV mode.

pano.setFov(angle_in_degrees: Number) Set the current Field of View, depending on the FoV mode.

pano.changeFov(offset_in_degrees: Number) Change the current Field of View, depending on the FoV mode.

pano.getVFov() Return the current vertical Field of View.

pano.setVFov(angle_in_degrees: Number) Set the current vertical Field of View.

pano.getHFov() Return the current horizontal Field of View.

pano.getRoll() Return the current roll angle.

pano.setRoll(angle_in_degrees: Number) Set the current roll angle.

pano.setPanTilt(pan: Number, tilt: Number), pano.setPanTiltFov(pan: Number, tilt: Number, fov: Number)

Convenience Functions

pano.setProjection(v: Number), pano.getProjection():Number, pano.changeProjection(v: Number, speed: Number) To get or set the current projection. 4 – Rectilinear, 9 – Stereographic, 12 – Fisheye.

pano.setDefaultView() Sets the view to the default view.

pano.moveTo(pan: Number, tilt: Number, fov: Number, speed: Number, roll: Number, projection: Number); Move the view to a position.

pano.moveToDefaultView() Move the view to the default position.

pano.setInertia(value: Boolean) Enable inertia.

Limits

pano.getViewerLimits():Object, pano.setViewerLimits(limits:Object) To retrieve or set the current viewer limits of the player. The limits object contains objects for ‘pan’ and ’tilt’. These objects in turn have values for ‘min’ and ‘max’. If you use the set function, you only need to provide the values you intend to change.

Here are example calls, to set viewer limits, and to reset the viewer to have no limits:

pano.setViewerLimits({
  pan: { min: -100, max: 100 },
  tilt: { min: -30, max: 70 },
});
pano.setViewerLimits({
  pan: { min: 0, max: 360 },
  tilt: { min: -90, max: 90 },
});

Auto Rotation and Animation

Auto Rotation

pano.setAutorotate(speed: Number, delay: Number, rth: Number) Set the autorotation parameters.

pano.startAutorotate(speed: Number, delay: Number, rth: Number) Start (and enable) autorotation.

pano.toggleAutorotate(speed: Number, delay: Number, rth: Number) Toggle autorotation.

pano.stopAutorotate() Stop (and disable) autorotation.

pano.pauseAutorotate() Pause autorotation. This will stop autorotation if it is currently active. It will not disable autorotation, so after the timeout it will start again.

pano.resumeAutorotate() Resume autorotation. This will start autorotation if it is currently enabled. It will not affect the ’enabled’ state.

pano.setAutorotateNodeFilter(tag: String) This tag specifies which nodes will be considered when autorotation automatically switches nodes.

pano.getIsAutorotating() If autorotation is currently running.

pano.startAnimation(animsequence: String) Play the given animation sequence. Always starts at the beginning of the sequence.

pano.resumeAnimation(animsequence: String) Play the given animation sequence. If the animation sequence was previously playing and interrupted by the user, it will continue from the point where it was interrupted.

View states

obj.getState():Number Get the number of the current view state.

obj.getStateTitle(index? :Number):String Returns the title of a view state. The index parameter is optional, if omitted it returns the title of the current view state.

obj.changeViewState(index :Number, speed :Number) Change to a different view state.

Media elements

pano.playSound(id: String) Start the sound with this media id.

pano.pauseSound(id: String) Pause the sound with this media id.

pano.playPauseSound(id: String, loop: Number) Toggle between play and pause the sound with this media id.

pano.playStopSound(id: String, loop: Number) Toggle between play and stop the sound with this media id.

pano.soundGetTime(id: String):Number, pano.soundSetTime(id: String, time: Number) To get/set the position of a currently playing sound.

pano.activateSound(id: String, state: Number) Pop out the image or video with id. state: 0 – hide, 1 – show, 2 – toggle.

pano.stopSound(id: String) Stop the sound with this media id.

pano.isPlaying(id: String):Boolean Check if this media element is currently playing.

pano.setVolume(id: String, volume: Number) Set the volume (between 0.0 and 1.0) for this element to a fixed value. The id main changes the global volume.

pano.changeVolume(id: String, volume: Number) Change the volume for this element. The id main changes the global volume.

pano.disableSoundLoading() Prevents loading of sound elements.

pano.setMediaVisibility(id: String) To change the visibility of a pinned image or video. 0 – hide, 1 – show, 2 – toggle.

pano.getMediaObject(id: String) Returns the source object of a specific pinned media element.

pano.changeLensflares(v: Number) To set the visibility of lens flares. 0 – show, 1 – hide, 2 – toggle.

Subtitles

pano.attachSubtitleTrack(id: String, options: Object) Attach a WebVTT subtitle track to the video with this media id. In the options object, you can set:

• url: the URL of the .vtt file (required)
• kind: subtitles (the default) or captions
• presentation: skin (the default; the cue text is provided through a skin variable) or native (the browser draws the cues on the video)
• variable: the name of the skin variable that receives the active cue text
• label: the track’s label
• srclang: the language code of the track file

pano.getSubtitleText(id: String):String Returns the currently active subtitle text of this media element.

pano.setSubtitlePresentation(id: String, presentation: String) Change how the subtitles are shown: native, skin, or off.

Hotspots

pano.addHotspot(id: String, pan: Number, tilt: Number, div: DomElement) Add a DomElement as hotspot to the panorama.

pano.updateHotspot(id: String, pan: Number, tilt: Number) Update the hotspot position.

pano.removeHotspot(id: String) Remove a single hotspot.

pano.removeHotspots() Remove all hotspots.

pano.getPointHotspotIds():Array<String> Get all hotspot Ids as array of strings.

pano.getCurrentPointHotspots():Array<DomElement> Returns an array of all point hotspot divs.

pano.getHotspot(id: String):Object Get all the information of a hotspot as an object.

Example code:

var element = document.createElement("img");
element.setAttribute("src", "hsimage.png");
element.onclick = function () {
  pano.openNext("{node10}");
};
pano.addHotspot("myid", 0, 90, element);
console.log(pano.getPointHotspotIds());
pano.updateHotspot("myid", 0, -90);
console.log(pano.getHotspot("myid"));
pano.removeHotspot("myid");
console.log(pano.getPointHotspotIds());

pano.getPolygonMode():Number, pano.setPolygonMode(v: Number, toggle: Number) Gets or sets the current polygon mode. If toggle is 1, it toggles between Off and the mode v.

pano.showOnePolyHotspot(id: String), pano.hideOnePolyHotspot(id: String), pano.toggleOnePolyHotspot(id: String) To show/hide a specific polygon hotspot.

pano.changePolyHotspotColor(id: String, bgColor: Number, bgAlpha: Number, borderColor: Number, borderAlpha: Number) Sets the background and border color of a specific polygon hotspot. You can use an empty string for id, to target all polygon hotspots.

For example, for a red, semi-transparent polygon with a solid green border: player.changePolyHotspotColor("Poly01", 0xff0000, 0.5, 0x00ff00, 1);

Use a hexadecimal number for the color, prefixed with 0x. The alpha value is a number between and including 0 and 1.

pano.setPolyHotspotHandcursor(id: String, enable: Boolean) Toggles the hand cursor for a specific polygon hotspot. You can use an empty string for id, to target all polygon hotspots.

pano.getHotspotPropValue(nodeId: String, hsId: String, varname: String) To retrieve the value of a custom hotspot property, defined in the project.

pano.setHotspotPropValue(nodeId: String, hsId: String, varname: String, value: Any) To set the value of a custom hotspot property, defined in the project.

Virtual Tour

pano.getIsTour() If the project is a tour, or just a single panorama.

pano.getNodeIds():Array<String> Get a list of all node ids.

pano.getNodeUserdata(id: String):Object Get the user data for node id. If the id is empty the current node data is returned.

player.getNodeUserdataPropValue(id: String, varname: String) To retrieve the value of a custom user data property, defined in Pano2VR.

player.setNodeUserdataPropValue(id: String, varname: String, value: String) To set the value of a custom user data property, defined in Pano2VR.

pano.getNodeLatLng(id: String):Object Get the GPS data for node id. If the id is empty the current node data is returned.

pano.getNodeDistance(fromId: String, toId: String):Number Get the distance between 2 nodes (in meters), provided both nodes have GPS data.

pano.getNodeTitle(id: String):String Get the node title for node id. If the id is empty the current node data is returned.

pano.getCurrentNode():String Get the node id of the current node.

pano.getNextNode() Get the node id of the next node in the tour list. If the current node is the last node, the first node id is returned.

pano.getPrevNode() Get the node id of the previous node in the tour list. If the current node is the first node, the last node id is returned.

pano.getNodesWithTag(tag:String)::Array<String> Get an array of nodes that have a certain tag in their user data.

pano.nodeVisited(id:String):Boolean Returns true if the node has been visited. For the current node false is returned on the first visit.

pano.openNext(url:String,parameter:String) Open next panorama, if the url is in the from of {nodeid} it will change the node in the tour.

pano.getLastVisitedNode():String Return the id of the last visited node.

pano.setTransition(v: Object) Set the transition parameters when moving between panoramas:

• type: cut, crossdissolve, etc.
• before: the before effect (0 – none; 2 – zoomin)
• after: the after effect (0 – none; 2 – zoomin; 3 – zoomout; 4 – flyin)
• transitiontime: the transition time
• waitfortransition: – if the after effect should wait for the transition to finish
• zoomedfov: the fov to zoom to if zoomin is selected
• zoomspeed: the speed used if zoomin is selected
• dipcolor: the color to use if diptocolor is the chosen type
• softedge: if is soft edge is used for the transition type

pano.getZoomCenterCursor(), pano.setZoomCenterCursor(value:Boolean) Get/set the zoom value at the cursor.

To reveal the zoom value in a text box in the skin, add a Mouse Click with a Set Value action and the following as the value: javascript: player.getZoomCenterCursor().

Fullscreen

The method names speak for themselves.

pano.setFullscreen(flag:Boolean)

pano.enterFullscreen()

pano.exitFullscreen()

pano.toggleFullscreen()

pano.getIsFullscreen()

Video panorama

pano.videoPanoPlay(), pano.videoPanoStop(), pano.videoPanoPause() Play/Stop/Pause the video panorama.

pano.getVideoPanoTime():Number, pano.setVideoPanoTime(t:Number) Get/set the current time for the play head of the video panorama.

pano.getVideoPanoObject():DomVideoElement Get a reference to the DOM video element.

pano.setVideoPanoSource(v) Set the source object for the video panorama.

VR

pano.enterVR():boolean To enter VR mode.

pano.exitVR():boolean To exit VR mode.

pano.toggleVR():boolean To toggle VR mode.

pano.isInVR():boolean Returns true if the player is currently in VR mode.

pano.hasVR():boolean Returns true if the device supports VR mode.

3D Models

pano.is3dModel():Boolean Returns true if the current node is a 3D model.

pano.get3dModelType():Number The type of the current node’s 3D model. 0 – no model, 1 – mesh model, 2 – Gaussian splat.

pano.playModelAnimation(animationName: string, loops: number) Plays an animation of the model with the given name. loops is the number of times the animation should loop, 0 meaning loop indefinitely.

pano.stopActiveModelAnimation() Stops the currently running animation.

pano.playPauseActiveModelAnimation() Plays or pauses the currently running animation.

pano.getModelAnimationAction(animationName: string) Returns the three.js AnimationAction object of the animation with the given name.

pano.getCameraMode():Number, pano.setCameraMode(mode: Number, keepPosition: Boolean=true) Get or set the camera mode in a 3D model. 0 – Panorama, 1 – Walk, 2 – Fly, 16 – Orbit, 17 – Fly Over.

pano.setCameraView(options: Object) Move the camera in a 3D model. The options object can contain, among others: mode (the camera mode), pan, tilt, fov, lookAt (a point in model space), target (the id of a camera point to move to), usePath (move along the node links), delay, and timingFunction.

pano.get3dCameraPoints(type?: String):Array<Object> Returns the camera points of the current 3D model. Pass a type to filter the result: node, waypoint, clusterpoint, or targetcamera.

pano.alignedWith3dModel():Boolean Returns true if the current panorama node has a camera position in a 3D model of the tour.

pano.set3dMaterialSide(side: String) Set which side of the model’s faces is rendered: FromFile, FrontSide, BackSide, or DoubleSide.

pano.raycastModel(x: Number, y: Number):Object Finds what lies under a point of the viewer, given in pixels from the top left, in the 3D model of the current node, or in the model a panorama node is aligned with. When something is hit, the result contains hit (the three.js intersection, with point, object, and distance), normal, and modelPoint, the point in the model’s own coordinates. When nothing is hit, it contains no hit. Without a model, an empty array is returned. The pointer events below carry the x and y this function takes.

pano.getThree():Object Returns the three.js library the player uses, so you can create your own objects with it.

pano.getThreeGroup(group?: Boolean|String):Object Returns a three.js group that the player draws together with the panorama or model. Objects you add to it are shown in the tour. Without a parameter, the group belongs to the current node and is emptied when the node changes. Pass true or global for a group that stays across all nodes.

Miscellaneous

pano.getIsLoading() Check if the panorama is still loading.

pano.getIsLoaded() Check if the panorama is loaded completely.

pano.getPercentLoaded():Number How much of the panorama is loaded (a number between 0.0 and 1.0).

pano.getIsTileLoading() Check if multi-resolution tiles are currently being loaded.

pano.getIsReady():Boolean Returns true once the current node is completely shown: its images, tiles, 3D model, and video are loaded, and no transition is running. See also the ready event.

pano.transitionRunning():Boolean Returns true while a transition between two nodes is running.

pano.getLastInteraction():Number The time of the last real input by the visitor, a click, a touch, a key press, or a VR controller trigger, in milliseconds as returned by Date.getTime(). Autorotation, animations, and calls to this API do not change it. Until the first input, it is the time the tour was loaded.

pano.setLocked(value: Boolean) Disable all interaction with the panorama.

pano.setLockedMouse(value: Boolean) Disable mouse interaction with the panorama.

pano.setLockedKeyboard(value: Boolean) Disable keyboard interaction with the panorama.

pano.setLockedWheel(value: Boolean) Disable mouse wheel interaction with the panorama.

pano.getPositionAngles(x: Number, y: Number):Object Returns an object with the pan and tilt values for a given screen position.

pano.getPositionRawAngles(x: Number, y: Number):Object Same as getPositionAngles but the current position of the panorama is ignored, so the angles are as if pan=0 and tilt=0.

pano.setMargins(l: Number, t: Number, r: Number, b: Number) Lets you define margins around the player that you would normally define in the skin editor.

pano.setMargins(params:Object) Also lets you set margins around the player, like the function above, but gives you more options. The params object can contain (but does not have to contain all):

• left, top, right, bottom: each an object, containing value and unit, where unit should be either px or %.
• transition: an object containing duration and delay in milliseconds, and timingfunction. Supported values for timingfunction are: linear, ease, ease-in, ease-out, ease-in-out, step-end.

Example:

pano.setMargins({
  left: { value: 30, unit: "%" },
  transition: { duration: 500, timingfunction: "ease" },
});

pano.getViewerSize():Object Returns an object containing the ‘width’ and ‘height’ of the panorama player.

pano.getViewMode():Number, pano.changeViewMode(v: Number) Gets or sets the current view mode. 0 – Continuous Mode, 1 – Drag Mode, 2 – Toggle.

pano.updatePanorama() Repaint the panorama.

pano.isTouching() If the panorama player is currently being touched on a mobile device.

pano.getMouseOverPanorama():Boolean Returns true while the mouse is over the panorama itself, and not over a skin element. See also the mouseoverpanoramachanged event.

pano.getIsMobile() If the player is currently running on a mobile browser.

pano.getGyroAvailable():Boolean If the gyroscope is available on the current device.

pano.getUseGyro(), pano.setUseGyro(v:Boolean, useRoll:Boolean) If the gyroscope is used on a mobile device.

pano.getOS():Number The operating system the player is currently running on. 0 – Unknown, 1 – Windows, 2 – Mac, 3 – Linux, 4 – iOS, 5 – Android

pano.getBrowser():Number The browser the player is currently running in. 0 – Unknown, 1 – Chrome, 2 – Firefox, 3 – Safari, 4 – Edge, 5 – IE ,6 – Meta Quest Browser

pano.getBrowserTheme():Number The theme of the browser the player is currently running in. 0 – Light Theme, 1 – Dark Theme

pano.setOverrideCursor(cursor: String) Set the type of mouse cursor. See here for a list of cursors types.

Performance

pano.getPerformance():Object, pano.setPerformance(options: Object) To retrieve or change performance-related player settings. If you use the set function, you only need to provide the values you intend to change:

• maxTileCount: the maximum number of multi-resolution tiles kept in memory
• maxDownloads: the maximum number of parallel tile downloads
• nodeCacheSize: the number of nodes kept in the node cache, -1 for automatic
• prefetch: enable or disable prefetching of neighboring nodes
• asyncTileDecode: enable or disable asynchronous tile decoding
• msaa: enable or disable anti-aliasing (MSAA)
• resolutionScale: scale factor for the render resolution
• resolutionScaleNearest: use nearest-neighbor scaling for the render resolution
• vrResolutionScale: scale factor for the render resolution in VR (0 to 2)
• vrFoveation: foveation level in VR (-1 to 1)
• tileServerNames: an array of tile server names used for the tile-server placeholder

pano.releaseNodeResources(id: String):Boolean Frees the images and GPU memory the player still keeps for a panorama node visited earlier. The node loads again when it is opened next. Returns false, and keeps the resources, for the current node, for a node that is part of a running transition, and for 3D model nodes.

Skin Variables

pano.getVariableValue(varName: String):Any, pano.setVariableValue(varName: String, varValue: Any) To access skin variables.

pano.setVariableOptions(varName: String, options: Object):Boolean In the options object, you can set:

• keep: when set to true, the variable is stored in a browser cookie, and will be updated from there when the project is opened again later
• cookiePath: the cookie path
• cookieExpireDays: a number, specifying how many days until the cookie expires

Returns true if successful.

pano.setSuperCookie(superCookieName: String, options: Object) In the options object, you can set:

• cookiePath: the cookie path
• cookieExpireDays: a number, specifying how many days until the cookie expires

Once a super cookie is defined, and you later set a variable to be stored in a cookie (with the setVariableOptions() function), this variable will not be stored in a separate cookie, but all such variables will be collected and stored in the one super cookie. This allows you to omit the 50 cookies per domain limit.

Maps and Floor Plans

pano.getMapsContainingNode(id: String):Array<String> Returns a list of map ids (floorplans) the given node is located on.

pano.getMapIDs():Array<String> Returns a list of all map ids (maps and floor plans) in the project.

pano.getFloorplanIDs():Array<String> Returns a list of all floor plan ids in the project.

pano.hasMap():Boolean Returns true if the project has at least one map.

pano.hasFloorplan():Boolean Returns true if the project has at least one floor plan.

pano.getFirstMap():String Returns the id of the first map in the project.

pano.getFirstFloorplan():String Returns the id of the first floor plan in the project.

pano.getMapDetails(id:String):Object Returns an object containing all the data of a certain map or floor plan. The special ids _firstmap and _firstfloorplan refer to the first map or floor plan of a project.

Translations

pano.getLanguage():String Returns the code of the language currently used by the player (like ’en’ or ’en-US’).

pano.setLanguage(langCode:String) Tells the player which language to use.

Player Events

The player provides an event system where events are triggered at certain points. You can also register your own functions to those events.

pano.addListener(eventName:String, listener:Function)

pano.on(eventName:String, listener:Function)

Example code:

pano.on("changenode", function () {
  alert("Node changed!");
});

pano.removeEventListener(eventName:String, listener:Function) To remove a previously registered function from a certain event.

pano.triggerEvent(eventName:String) To manually trigger a certain event.

A list of available events:

The four pointer events playerclick, playerdblclick, playerdown, and playerup carry the point they happened at twice: pan and tilt are the viewing angles, and x and y are the same point in pixels from the top left of the viewer. The pixel pair is what raycastModel and getPositionAngles take, so you can ask what was clicked on without tracking the pointer yourself. That matters on a touch device, where there is no mouse position to fall back on:

pano.on("playerclick", function (e) {
  var ray = pano.raycastModel(e.x, e.y);
  if (ray.hit) console.log("clicked on", ray.modelPoint);
});

See also…

• Code Element

• HTML Template

• Web Output Properties

• Skin Editor