News Examples Documentation Download Buy Forum Contact

Documentation

Plugins

XML Extensions

Tools


Third Party Software
for krpano

krpano Actions / Scripting Reference Version 1.21

krpano has a small and simple dynamic scripting language. With it krpano can be customized in many ways. A command or function is called 'action' in krpano. It's possible to use existing actions and also to define new ones. The scripting language is dynamic and untyped by default, only some predefined variables are typed, but that is normally not relevant because inside the scripts all type conversions will be done automatically.

About this documentation

This documentation is about global krpano variables and objects, about the actions calling syntax and about all pre-defined krpano actions / functions.

Documentation topics:
For the documentation about the static xml code and object attributes have a look at the:
krpano XML Reference

krpano Global-Variables Reference

Version / Build information Screen information / settings Device informations Mouse / Keyboard / Touch-Gestures Timing / Random values State variables Math constants Keyboard / Button moving Multiresolution information Loading information XML / Scene Layers / Hotspots Programming / Debugging / Error handling

krpano Actions / Functions Reference

Programming logic / Flow control Math operators and functions Number / String formating Animations / Animated value changing Dynamic loading of other panos / tours Viewing animations / Camera control Automatic rotation Coordinate transformation Depthmap / 3D-Model information Request updates Dynamic adding or removing of screen elements Layer / Hotspot Actions Javascript Interfaces (krpano to Javascript calls) HTML/CSS Interfaces Javascript-only APIs (callable only from Javascript) Debugging

Syntax and Usage

Basic syntax
  • The krpano action code is list of commands.
  • Each command need to terminated with a semicolon at the end, except for the last one, there the semicolon is optional.
  • Whitespace characters or line-breaks between commands will be ignored.
  • Example:
    command1; command2;
    command3;
    ...
  • A command can be either a variable assignment:
    variable=expression;
    or an action call:
    action(parameters);

Variable assignments
  • Syntax:
    variable=expression;
  • With variable assignments new variables can be created or the value of exiting variables be changed.
  • The expression can be either a simple value or another variable or a more complex expression.
  • These variable assigment operatos are available:
    • = - just set/copy the value.
    • += - add the value.
    • -= - subtract the value.
    • *= - multiple the variable with the given value.
    • /= - divide the variable by the given value.
  • Examples:
    a = 1 + 2;  // a will be 3
    b = a + 3; // b will be 6
    trace(b); // output '6'
    b *= 2;
    trace(b); // output '12'
    str = "Hello: " + name;
    str = "hlookat=" + roundval(view.hlookat, 2);

Action calls
  • Syntax:
    action(parameters);
    action(parameter1, parameter2, parameter3);
    action(get(variable));  or  action(*variable);
    action(calc(expression));  or  action((expression));
    action('a quoted text, can contain with commas');
  • Where 'action' can be either:
    • the name of a built-in krpano action,
    • the name of an <action> element,
    • the name of a variable that contains krpano action code or
    • the name of a variable that refers to a Javascript function.
  • When passing more than one parameter, then the parameters need to be separated by commas.
  • Whitespace characters (like space, tab, new-lines) between parameters will be ignored.
  • Parameter value passing:
    • The parameters will be passed as they are written as text to the action.
    • When a parameter is a variable, then only the name of the variable will be passed - but not the value of the variable!
    • To pass the value of a variable get(variable) or *variable need to be used.
    • To pass more complex expressions calc(expression) or just (expression) can to be used as parameter.
    • Note - some actions might resolve variables automatically to their value!
  • To be able to use whitespace characters and commas inside a parameter value, the parameter must be enclosed by single ' or double quotes ".

Comments
  • Syntax:
    action(parameters);
    action(parameters); // this is a single-line comment
    action(parameters);
    /* a multi-line comment
    action(parameters); */

    action(parameters);
    <!-- a xml comment
    action(parameters); -->

    action(parameters);
  • There a single-line comments, starting from // to the next line-break.
  • Multi-line comments from /* to */.
  • And xml-comments from <!-- to -->. These comments work only when the related code was defined in a xml file, there they will get stripped away already during the xml-parsing.


Expressions

The expression syntax will be used in variable assignments, in if() checks, for the callwhen() action, in conditional loops (for, loop, asyncloop) and in the calc() action. It can be used to evaluate logical conditions, calculate mathematical expressions or to concatenate strings.

The basic syntax is:
a OPERATOR b
  • Where the a or b terms can be either:
    • variables,
    • values,
    • strings (inside single-quotes ' or double-quotes "),
    • nested expressions (in parenthesis),
    • or inline functions.
  • The OPERATOR can be one of the operators listed below.
  • The resolving order depends on the operator, but withhin equivalent operators the resolving order is from left to right.
  • Use parenthesis / nesting for a custom resolving orders - e.g.:
    (a OPERATOR b) OPERATOR (c OPERATOR d)
  • Textual operators like AND or OR are only supported in UPPERCASE notation!

Comparison operators:
==is equal (non-strict)
!=is not equal (non-strict)
<  or  LTis lower than *
>  or  GTis greater than *
<=  or  LEis lower or equal than *
>=  or  GEis greater or equal than *
=== is equal (strict)
!==is not equal (strict)
Logical operators:
||  or  OR the left OR the right expression need to be true *
&&  or  ANDthe left AND the right expression need to be true *
!NOT operator - invert a boolean value
Type operator:
$variableForce using that variable as it is, skip any type detection / conversion (e.g. for Strings that contain a Number as value).
Ternary operators:
if ? then : elseTernary operator
Nesting operators:
( ... )Nesting operator
Mathematical operators:
+plus - add numbers or concatenate strings
-minus
*multiple
/divide
^power of
Binary operators:
<<  or  LSHTleft bit shift *
>>  or  RSHTright bit shift *
BORbitwise OR
BANDbitwise AND
XORbitwise XOR
* Note - due of xml syntax limitations, the usage of the characters <, >, & might be not possible (e.g. inside xml attributes or inside xml elements without CDATA tag). Therefore it's recommended to use the alternative syntax.

Inline functions:
isset(v) Returns true or false depending on if v is an already existing variable.
isvalue(v) Returns true or false depending on if v is an already existing variable and its value is not an empty string (whitespaces will be ignored).
isNaN(v) Returns true or false depending on if v is Not-a-Number.
int(v) Converts the given value to an Integer.
Returns 0 when the conversion was not possible.
number(v) Converts the given value to a Number.
Returns NaN (Not-a-Number) when the conversion was not possible.
string(v) Converts the given value to a String.
boolean(v) Converts the given value to a Boolean (true or false).
parseint(v) Parses the given value and converts all valid characters to an Integer. Returns 0 if the conversion was not possible.
parsefloat(v) Parses the given value and converts all valid characters to a Number. Returns NaN (Not-a-Number) if the conversion was not possible.
tolower(v) Converts the given value to a lower-case String.
toupper(v) Converts the given value to a upper-case String.
capitalize(v) Convert the first character of the String to upper-case and all other characters to lower-case.
fromcharcode(v) Returns a String created from the given character code.
charat(s,i) Returns the character from a String at the given index.
charcode(ch) Returns the character code for a character.
Could be used to check with keycode for a certain pressed characters.
charcodeat(s,i) Returns the character code from a String at the given index.
indexof(a,b) Returns the index of the String b inside a.
lastindexof(a,b) Returns the last index of the String b inside a.
contains(a,b) Returns true if the a contains the String b.
slice(s,a,b) Returns a part of the String s from index a to b.
substr(s,i,l) Returns a part of the String s from index i with length l.
trim(s) Returns a String with removed whitespaces around.
padleft(s,len,char)
padright(s,len,char)
Left or right align the String s by padding it with spaces or the specified char for the specified total length len.
replace(s,old,new) Replace in s all occurrences of the search-string old with the replacement-string new.
tohex(v) Returns a String with a hexadecimal converted value (low case, no prefix).
fromhex(s) Returns a Number from a parsed hexadecimal String (# and 0x prefixes are possible).
rgb(r,g,b) Returns a 32bit Integer-color-value build from the red, green, blue color values (0-255).
rgba(r,g,b,a) Returns 32bit Integer-color-value build from the red, green, blue color (0-255) and alpha (0.0-1.0) values.
escape(v) Returns a String in which certain characters have been replaced by a hexadecimal escape sequence.
unescape(v) Returns a String in which hexadecimal escape sequences are replaced with the character that it represents.
parsepath(s) Parses the given String for url-placeholders.
abs(v) Returns the absolute value of a number.
acos(v) Returns the arccosine of a number.
asin(v) Returns the arcsine of a number.
atan(v) Returns the arctangent of a number.
atan2(a,b) Returns the arctangent of the quotient of its arguments.
ceil(v) Returns the smallest integer greater than or equal to a number.
clamp(v,min,max) Limits/clamps the value to be between min and max.
cos(v) Returns the cosine of a number.
exp(v) Returns the exponential function of a number.
floor(v) Returns the largest integer less than or equal to a number.
log(v) Returns the natural logarithm (also ln) of a number.
max(...) Returns the largest of the given values.
min(...) Returns the smallest of the given values.
pow(a,b) Returns base to the exponent power.
round(v) Returns the value of a number rounded to the nearest integer.
roundval(v,dp) Returns a String of a number rounded to given decimal places (dp). When using -1 for dp, an automatic number of decimal places will be used, from 1 to 6, no trailing zeros.
sin(v) Returns the sine of a number.
sqrt(v) Returns the positive square root of a number.
tan(v) Returns the tangent of a number.

Strict / non-strict comparisons

When using non-strict comparisons (by using == or != when the strict mode setting is false) then it will be assumed that the given values are either variables or strings. That means when a variable with the given name exists, then the value of that variable will be used in the comparison. But when the variable doesn't exists, then the given name will be used as string.
In strict comparisons the strings must be explicitly marked by quotes. Variables will resolve either to their value or to null if they don't exists.


Arrays

Basic principles:
  • Every xml element with a name attribute is an element / item of an Array.
  • The name of the xml element is the name of the Array and the name attribute defines the name of the Array element / item.
  • An Array in krpano is always an Array of objects.
  • Such Array-item object can contain any kind of custom properties / attributes.
  • Arrays can be predefined or defined dynamically at runtime by setting an Array item value - when setting an item value the first time, then automatically an Array will be created.

Static XML Syntax: (when defining in the xml structure)
<array_name name="item_name" value="..." />

Dynamic Actions Syntax: (when accessing or setting at runtime)
array_name[item_name].value

Properties and Actions from Array objects:
  • count
    • Get the current number of items in the array.
    • An Array can be cleared by setting count to 0.
  • sortby(attribute, parameters)
    • Sort all array items by the value of the given attribute.
    • By default the sorting order will depend on the type of the attribute (e.g. 'numeric vs. string' sorting).
    • parameters (optionally) - a string that can contain one or more of the following values (e.g. separated by a pipe | character):
      • caseinsensitive - case insensitive string sorting.
      • descending - use a descending sorting order.
      • numeric - parse the values as numbers and sort accordingly.
  • createarrayitem(name or index)
    • Create / add a new array item.
  • removearrayitem(name or index)
    • Remove an array item.
    • The items following the removed item will rank / move up.

Default properties from Array-Item objects:
  • index
    • The 0-based index of the current Array-Item (read-only).
  • name
    • The name of the current Array-Item.
    • It's also possible to delete an Array-Item by setting its name to null.

Value-Arrays
Different to the normal krpano-Arrays there are also these special Value-Arrays:
  • Value-Arrays are simple Arrays with an integer index and a value.
  • Dynamically creating Value-Arrays is possible by def(test, array).
  • The access to the items is possible by array[index].
  • The current number of items in the Array can be get via array.length.
  • Value-Arrays are only available in actions code.
  • Internally these are native Arrays from Javascript. Their usage itself is the same in both cases.


Global Variables

All default global krpano variables:
Variable nametypedefault value
global
local
Object
Object
The global object allows directly accessing the global variable scope.
The usage of global can be necessary inside local- or layer/hotspot scope code to be able to access a global variable when a variable with the same name is already defined the current scope.

The local object is only available inside local-scope actions and allows directly accessing the current local variable scope. This can be used to ensure defining new variables at the local scope when there might be already global variables with the same names.
Variable name (read only)typedefault value
version String "1.21.2"
The krpano version string.
Variable name (read only)typedefault value
xmlversion String
The version setting from the xml.
When not set, this will be the same as the krpano version string.
Variable name (read only)typedefault value
build String "2023-12-11"
The krpano build date string in the format YYYY-MM-DD.
Variable name (read only)typedefault value
mouse.button int 0
Which mouse button was pressed or released:
  • 0 - left mouse button
  • 1 - middle mouse button
  • 2 - right mouse button
Variable name (read only)typedefault value
mouse.leftbutton
mouse.middlebutton
mouse.rightbutton
Boolean
Boolean
Boolean
false
false
false
Check which mouse button is currently pressed.

Example - control something with the right mouse button:
<events ondown="asyncloop(mouse.rightbutton, 
                  trace(mouse.dx,'/',mouse.dy);
                );" />
Variable name (read only)typedefault value
mouse.altkey
mouse.ctrlkey
mouse.shiftkey
Boolean
Boolean
Boolean
false
false
false
Check if the ALT, CTRL or SHIFT keys are pressed on the current mouse event.
Variable names (read only)typedefault value
mouse.x
mouse.y
mouse.dx
mouse.dy
mouse.stagex
mouse.stagey
mouse.screenx
mouse.screeny
mouse.downx
mouse.downy
mouse.clickx
mouse.clicky
int
int
int
int
int
int
int
int
int
int
int
int
The mouse position.

The mouse.x and mouse.y coordinates are relative to the left top edge of the area.

The mouse.dx and mouse.dy variables store the 'delta'-movement distance between the previous and the current frame.

The mouse.stagex and mouse.stagey coordinates are relative to the left top edge of the whole stage / window.

The mouse.screenx and mouse.screeny coordinates are the same as stagex/stagey but additionally also ignoring the safe-screen-area of the device.

The mouse.downx and mouse.downy variables store the position where the mouse button was last pressed down (for left and right buttons). The coordinates itself are relative to the left top edge of the area.

The mouse.clickx and mouse.clicky variables are special case ones - they store the position where the click from onsingleclick or ondoubleclick events had happend. The coordinates itself are relative to the left top edge of the area.
Variable names (read only)typedefault value
gesture.event
gesture.scale
gesture.deltascale
gesture.rotation
gesture.deltarotation
gesture.centerx
gesture.centery
gesture.dx
gesture.dy
gesture.touches
String
Number
Number
Number
Number
Number
Number
Number
Number
Array
Informations for the ongesture event:
Variable name (read only)typedefault value
keycode int 0
The keycode of the last pressed or released key.

The keycode value will be set in the onkeydown and onkeyup events.

Here a small code snippet to find out the keycode of the pressed key:
<events onkeydown="showlog(); trace('keycode=',keycode);" />
Check if the 'A' key got pressed:
<events onkeydown="if(keycode == charcode('A'), ...);" />
Variable names (read only)typedefault value
wheeldelta
wheeldelta_raw
wheeldelta_touchscale
int
Number
Number
0
Number.NaN
0.0
The roll-delta of the mouse wheel rotation.

These variables will be set in the onmousewheel event.

  • wheeldelta
    • The wheel roll delta as normalized value.
    • Typically +3 or -3 on the most systems.
  • wheeldelta_raw
    • The 'raw' unscaled and non-rounded delta values of the mouse wheel rotation. The normal wheeldelta values are limited to integer values and can be too inaccurate for some usages (plugins).
  • wheeldelta_touchscale
    • On touch devices there is no mouse-wheel, but the onmousewheel event will be also called on 2-finger zooming gestures.
    • The wheeldelta_touchscale variable will provide detailed information about the relative touch scale / zoom.
    • Note - only available on touch devices!
      On other devices the value will be always 0.0.
Variable nametypedefault value
fullscreen Boolean false
The fullscreen variable can be used to check or to change the current state of the fullscreen mode. When the variable will be changed, then also the fullscreen mode will be changed.

Example - switch to fullscreen mode:
onclick="set(fullscreen,true);"
Example - switch between fullscreen and windowed mode:
onclick="toggle(fullscreen);"

Notes:
  • Before using the fullscreen setting, it should be verified if the current browser / device actually supports the fullscreen mode. This can be done with the xml fullscreensupport devices setting and the device.fullscreensupport variable.
  • Due HTML5 security limitations the switching to the fullscreen mode will be only possible as reaction to an user input like a mouse click or a keypress! That means it's only possible switch to fullscreen mode in an onclick or onkeydown event!
  • When the HTML5 fullscreen mode is not supported by the browser (like on iOS), then the fullscreen setting will only change the size of the viewer html element to match the size of the full browser window. Due technical limitations this will not work from inside an <iframe> and can be problematic in nested html structures.
  • When trying to use the HTML5 fullscreen mode from within an <iframe>, it is necessary to add the allowfullscreen parameter to the <iframe> declaration. This tells the browser that this iframe is allowed to switch to Fullscreen mode.

    Example:
    <iframe ... allowfullscreen="true"></iframe>
Variable names (read only)typedefault value
stagewidth
stageheight
int
int
The sizes of the current viewer window in pixels.
Get the these sizes in the onresize event.
Variable nametypedefault value
stagescale Number 1.0
A global overall scaling setting.
The stagescale setting will scale all krpano elements and sizes.

By scaling all elements, the krpano stage-size (screen-size / resolution) itself will be scaled inversely by this value - e.g. a value of 0.5 will scale-down all elements by 50% while increasing the internal stage-sizes by 200% at the same time.

The default stagescale value depends on the device, the browser and the window.devicePixelRatio value.
Variable name (read only)typedefault value
browser.useragent
browser.platform
browser.location
browser.domain
browser.protocol
String
String
String
String
String
Information about the browser.
Variable name (read only)typedefault value
device.desktop
device.tablet
device.mobile
device.normal
Boolean
Boolean
Boolean
Boolean
Basic device type detection: desktop, tablet or mobile.
Note - only one of these three can be set to true!

The normal device is a combined setting and true for desktop and tablet devices. This can be used to apply the same to the 'larger' desktop and tablet devices and used as opposite to 'smaller' mobile devices.
Variable name (read only)typedefault value
device.mobilevr
Boolean
For detecting dedicated VR Browsers, that means Browsers that are itself also running in VR, e.g. the Oculus Browser or Firefox Reality for the Oculus Quest.
Variable name (read only)typedefault value
device.css3d
device.webgl
device.webgl2
Boolean
Boolean
Boolean
Detect the support of the basic 3D rendering technologies available in the Browser:
Note - see also the webgl embedding setting.
Variable name (read only)typedefault value
device.multiressupport
device.panovideosupport
device.depthmapsupport
device.fullscreensupport
Boolean
Boolean
Boolean
Boolean
Feature detection:
  • multiressupport - Is using multi-resolution images possible?
  • panovideosupport - Is using videos as panoramic image possible? Depends on WebGL and if using videos as texture is possible.
  • depthmapsupport - Is using 3D Depthmaps possible. Depends on certain WebGL features.
  • fullscreensupport - Is the HTML5 fullscreen mode be supported by the Browser and is it available? The availability inside iframes depends on the allowfullscreen setting!

All settings (except fullscreensupport, which depends on iOS and iframe restrictons) should be available on all modern devices and browsers. Only very old devices and browsers might fail here.
Variable name (read only)typedefault value
device.pixelratio
device.fractionalscaling
Number
Boolean
  • pixelratio - The physical pixels to CSS pixels ratio.
    Same as window.devicePixelRatio.
  • fractionalscaling - Is pixelratio a fractional value? Can be used to workaround layout problems on such devices or when using fractional page-zooms.
Variable name (read only)typedefault value
device.maxtexturesize
Number
The max. WebGL texture size (width or height in pixels) of the device.
Should be at least 2048.

This can be relevant for hotspot images. Larger images will get automatically down-scaled. To detect or avoid this case, this value can be checked.
Variable name (read only)typedefault value
device.touchsupport
Boolean
Detect if the browser technically provides touch-support - but that doesn't mean that there is be actually a touchscreen.
Variable name (read only)typedefault value
device.mouse
device.touch
Boolean
Boolean
Detect mouse and/or touch support.

Note - mouse and touch can be set at the same time when the device is supporting both (e.g. desktop devices with touch-screens).

Note - in recent browsers, it is no longer possible to detect if a desktop- or laptop-system has a touchscreen and touchsupport. In such case the device.touch value will be false, but touchsupport could be still available.
Variable name (read only)typedefault value
device.iframe
Boolean
Detect if inside an iframe.
Variable name (read only)typedefault value
device.ios
device.iosversion
device.iosdesktop
device.iphone
device.ipad
device.android
device.androidversion
device.windows
device.mac
device.linux
Boolean
Number
Boolean
Boolean
Boolean
Boolean
Number
Boolean
Boolean
Boolean
Device / System detection:
  • ios - Is an iOS device?
  • iosversion - The iOS version as Number.
  • iosdesktop - Use the iOS desktop mode?
  • iphone - Is an iPhone?
  • ipad - Is an iPad?
  • android - Is an Android device?
  • androidversion - The Android version as Number.
  • windows - Is a Windows system?
  • mac - Is a Mac OSX system?
  • linux - Is a Linux system?
Variable name (read only)typedefault value
device.chrome
device.chromeversion
device.firefox
device.firefoxversion
device.ie
device.ieversion
device.edge
device.newedge
device.safari
device.safariversion
Boolean
Number
Boolean
Number
Boolean
Number
Boolean
Boolean
Boolean
Number
Browser and Browser-version detection:
  • chrome - Is Chrome or a Chrome/Chromium-based browser?
  • chromeversion - The Chrome version as Number.
  • firefox - Is Firefox or a Gecko-based browser?
  • firefoxversion - The Firefox version as Number.
  • ie - Is the Interet-Explorer or the (old) Microsoft Edge browser?
  • ieversion - The Interet-Explorer or (old) Microsof Edge version as Number.
  • edge - Is the (old) Microsoft Edge browser?
  • newedge - Is the new Chrome-based Edge browser? The chrome and chromeversion settings will be also set in this case.
  • safari - Is the Safari browser?
  • safariversion - The Safari version as Number.
Variable name (read only)typedefault value
timertick Number
The timertick variable returns the number of milliseconds that have elapsed since the viewer has started (1000 milliseconds = 1 second).
Variable name (read only)typedefault value
lastuserinteraction Number
The timertick of the last user interaction.
Variable name (read only)typedefault value
blendtime Number 0.0
The time that was set in the BLEND(blendtime) parameter of the preceding loadpano/loadscene/load... call.
Variable name (read only)typedefault value
have3dtransition Boolean false
A variable to check if a 3D transition is currently active.
Variable name (read only)typedefault value
random Number 0.0 - 1.0
The random variable returns a random number in the range 0.0 to 1.0.

Example - how to get an integer random value in the range 1 - 10:
mul(val, random, 9);
add(val, 1);
roundval(val);
trace('random value=',val);
Variable namestypedefault value
hlookat_moveforce
vlookat_moveforce
fov_moveforce
Number
Number
Number
0.0
0.0
0.0
These variables can be used to set a force to move the view / the pano.
Their main usage is for keyboard or button movement control.

When they will be set to a value other than 0.0, the view will start slowly accelerating (controlled by control.keybaccelerate) and then move with a maximum speed (controlled by control.keybspeed) until they will be set back to 0.0, then the movement will slow down (controlled by control.keybfriction).
Variable name (read only)typedefault value
multireslevel int
The multireslevel variable returns the current multi-resolution level
(0 - image.level.count).
Variable nametypedefault value
lockmultireslevel String -1
Lock the automatic multi-resolution level selection to a fixed level.
Set lockmultireslevel to "current" to lock the level to the current level. To release the level locking set lockmultireslevel back to "-1".
Variable nametypedefault value
downloadlockedlevel Boolean false
When set to true, the currently locked level will be downloaded completely.
Variable nametypedefault value
progress.progress Number 0.0
The current loading progress as linear value from 0.0 to 1.0.

It could be used to create custom loading animations - e.g. use the onxmlcomplete event for starting the loading animation, and the onloadcomplete event for stopping it.
Variable nametypedefault value
network.viewerpath
network.htmlpath
network.firstxmlpath
network.currentxmlpath
String
String
String
String




Path to several locations (the path only, without filename):
  • viewerpath - Path to the krpano viewer file ⇒ %VIEWER% url-placeholder.
  • htmlpath - Path to html file ⇒ %HTMLPATH% url-placeholder.
  • firstxmlpath - Path to first loaded xml file ⇒ %FIRSTXML% url-placeholder.
  • currentxmlpath - Path to current xml file ⇒ %CURRENTXML% url-placeholder.
Variable name (read only)typedefault value
xml.url String
The xml.url variable contains the path/url of the currently loaded xml file.
When loading a scene or a xml-string the value of url will be null.
Variable name (read only)typedefault value
xml.content String
The xml.content variable contains the xml-content of the last loaded pano.
When a <scene> gets loaded or loadxml() be used, then the variable contains only the scene-xml-code or the given loadxml() xml-code.
Variable name (read only)typedefault value
xml.fileurl String
The xml.fileurl variable contains the path/url of the currently loaded xml file.
When loading a scene or a xml-string this value will not change.
Variable name (read only)typedefault value
xml.filecontent String
The xml.filecontent variable contains the content of the last loaded xml file.
The content will not change when loading a new pano via loadscene() or loadxml().
Variable name (read only)typedefault value
xml.scene String
The xml.scene variable contains the name of currently loaded scene.
Variable name (read only)typedefault value
xml.view Object
A backup of the values from the initial <view> element defined in the current xml or scene. E.g. get the initial view.hlookat value via xml.view.hlookat.

Note - only the values that were defined in the xml are stored here, no default values. That means before using a value from that object, it would be necessary to check if these variables actually exists - e.g. via if(xml.view.fov !== null, ...);.
Variable name (read only)typedefault value
hoveringelement Object null
The top-most element (layer or hotspot) where the mouse cursor is currently hovering over it. Or null when there is no element.
Variable name (read only)typedefault value
lasterror String
The lasterror variable contains the last error message when an error had happened. To get this variable the onloaderror event must be used.
Variable nametypedefault value
inlinefunctions Object
The inlinefunctions variable is a Javascript Object that stores all functions that are available as as Inline Functions inside krpano expressions.

With the object it is possible to extend krpano with additional inline functions by adding them to that object.

Example:
<action name="extendkrpano" type="Javascript" autorun="preinit">
  krpano.inlinefunctions.capitalize = function(s)
  {
    return s.charAt(0).toUpperCase() + s.slice(1);
  }
</action>

<action name="test" autorun="onstart">
  // Outputs: 'Test'
  trace(calc( capitalize('test') ));
</action>
Variable name (read only)typedefault value
actions.actioncaller Object
The layer or hotspot object that has called the current action / function.


Action Documentations

def(variable, type, value)
Define a new variable with a specific type and optionally set it to the given value.

When no value will be given and the variable already exists, then the variable with its current value will be converted to the given type.

Parameters:
  • variable
    • The variable name.
    • The variable will be created when it doesn't exists.
  • type
    • The type of the variable.
    • Available types:
      • boolean - true or false
      • number - a numeric value
      • integer or int - an integer value
      • uint - an unsigned integer value
      • string - text characters
      • object - an object with custom properties
      • array - a value-array
  • value (optionally)
    • The new value for this variable.
    • When no value will be given and the variable already exsits, then the variable with its current value will be converted to the given type.
    • When no value will be given and the variable doesn't exsits, then these the default values are used: boolean=false, number=NaN (Not a Number), integer=0, string=null.
    • When the type is object or array, no value can be set.
Examples
def(b, boolean, true);
def(n, number, 123.456);
def(s, string, 'text');
def(obj, object);
def(obj.x, number, 0.0);
def(obj.y, number, 0.0);
set(variable, value)
set(object, variable:type=value, variable:type=value, ...)
Set a variable to the a value.

The set() action was two calling / usage possibilities:
  • When called with two arguments:
    • This is a normal set of one variable to a value.
  • When called with three or more arguments:
    • This is a multiple-set of several variables at once.
    • Here the variables will be set or added to an object.
    • Optionally it will be also possible to specify the type of the variable.

Parameters:
  • object (optionally - for the three or more arguments call)
    • The object for the multiple set call - at this object the variables will be set.
    • When the object doesn't exists, it will be created.
    • To define variables at a specific scope, it would be e.g. possible to use the global or local objects here.
  • variable
    • The variable name.
    • The variable will be created when it doesn't exists.
  • type (optionally - for the three or more arguments call)
    • The type of the variable.
    • Available types:
      • boolean - true or false
      • number - a numeric value
      • integer or int - an integer value
      • uint - an unsigned integer value
      • string - text characters
  • value
    • The new value for this variable.
    • When the variable already exists, then the value will be converted to the type of that variable (when no explicit type was be defined).
    • Note - to get the value of other variables use the get(variable) or calc(expression) actions.
Examples
Normal set:
set(var1, 'hello');
set(var2, get(var1));
set(fullscreen, true);
set(layer[p1].visible, false);
set(hotspot[h1].scale, 2.5);
set(contextmenu.item[0].caption, 'hello item');
set(events.onxmlcomplete, null);
Multiple set:
set(layer[p1], visible=false, alpha=0.5);
set(hotspot[hs1],
    type='text',
    ath=0.0,
    atv=0.0,
    html='Test Text',
    css='text-align:center',
    bg=false
);
set(global,
    test='Test text',
    havesomething:boolean=true,
    var2:string=get(var1),
    value:number=calc(1 + 2*3)
);
action( get(variable), ... )  or  action( *variable, ... )
array[ get(variable) ]  or  array[ *variable ]
<xmlelement attribute="get:variable" ... />
Resolves the variable to its value.

The get(var) action is a special action that can be only used as parameter when calling other actions or when accessing array elements.

As shorter syntax also just *var can be used.

Parameters:
  • variable
    • Any variable.
    • When the variable doesn't exists, get() will return null.

Note - some actions are automatically trying to resolve their given parameters to their values. For these actions using get(var) would be not necessary.
Examples
set(dstvar, get(srcvar));
looktohotspot(get(name));
lookto(get(h), get(v), get(f));
showtext(get(msg));
tween(var,get(dstval));
set(pic, spot1);
set(hotspot[get(pic)].visible, false);
trace('xyz=', xyz, ' get(xyz)=', get(xyz));
txtadd(msg, 'fov=', get(view.fov));
calc(variable, expression);
action( calc(expression), ... )  or  action( (expression), ... )
array[ calc(expression) ]  or  array[ (expression) ]
<xmlelement attribute="calc:expression" ... />
Calculate / evaluate / resolve the expression to its value.

The calc(expression) action is a special action that can be only used as parameter when calling other actions or when accessing array elements.

As shorter syntax also just (expression) can be used.

Parameters:
  • variable
    • The variable where the result will be stored.
    • The variable will be created when it doesn't exists.
  • expression

Note: When using a calc(variable, expression) call in a 'callback' parameter (e.g. in an if or delayedcall action), make sure to terminate its call with a ';' to allow differing that call to 'calc(expression)' that would resolve the expression and pass only the result to the called action.
Examples
set(y_new, calc(y_old - offset1 + offset2));
set(animationtime, calc('%1' == 'instant' ? 0.0 : 0.5));
<layer url="calc:'%CURRENTXML%/skin/' + settings.image1" />
copy(destination, source, typeconversion)
The copy() action copies the content from one variable to the other one.

By default this is the same as: set(destination, get(source)).

Parameters:
  • destination
    • The destination variable.
    • When the variable doesn't exists, it will be created.
  • source
    • The source variable.
    • When the variable doesn't exists, null will be set to the destination variable.
  • typeconversion (optionally)
    • When set to true (the default):
      When both variables have different types, then the value of the source variable will be converted to the type of the destination variable.
    • When set to false:
      Copy the value and the type of the source variable to the destination variable.
Examples
copy(dstvar, srcvar);
copy(cur_hlookat, view.hlookat);
copy(layer[text].x, mouse.x);
copy(layer[text].y, mouse.y);
delete(variable, ...)
Delete and remove the given variables.

Parameters:
  • variables
    • Any variable name.
    • It's possible to delete several variables at once - just pass several variables names (separated by a comma).
Examples
set(tmp1, ...);
set(tmp2, ...);
... do something ...
delete(tmp1, tmp2);
2 or 3 parameter call:
if(condition, then-actions, else-actions)
4 or more parameter call:
if(
   condition, then-actions,
   else-if-condition, then-actions,
   else-if-condition, then-actions,
   ...
   else-actions
)
The if() action allows conditional execution of code.

Parameters:
  • condition
  • then-actions
    • The actions that will be executed when the evaluation of the condition will be true.
  • else-actions (optionally)
    • The actions that will be executed when the evaluation of the condition will be false.
Examples
if(fullscreen, fullscreensetup(), windowsetup() );
if(fullscreen, set(layer[controls].visible, false) );
if(i LT 10, loop(next) );
if(var === null, set(var,0));
if(hotspot[spot1] === null, trace(there is no spot1 hotspot));
if((varA GT 5) AND (varA LT 10),
    trace('varA is between 5 and 10')
  );
if(varA AND varB AND varC, trace('all vars are true') );
if(var1 GT var2,
    trace('condition is true');
    lookto(100,20,50);
  ,
    trace('condition is false');
    lookto(0,0,100);
  );
if(a*2+b GT (c+3)*1.5 OR teststring == '123', ...);
if(
    test == 1, trace('test is 1'),
    test == 2, trace('test is 2'),
    test == 3, trace('test is 3'),
    trace('test is someting else')
);
delayedcall(delay, actions)
delayedcall(id, delay, actions)
Calls / executes the given actions after a given time.

Parameters:
  • id (optionally)
    • An optional unique id for the delayedcall.
    • This id can be used to stop the delayedcall by calling stopdelayedcall(id).
  • delay
    • The number of seconds to wait before executing the actions.
  • actions
    • The actions to call after the delay.
Examples
delayedcall(5.0, hidelogo() );
delayedcall(10, looktohotspot(spot1);loadpano(pano2.xml); );
delayedcall(1, showtext('hello');       );
delayedcall(4, showtext('to the pano'); );
<action name="updatemousepos">
  copy(layer[cursor].x, mouse.x);
  copy(layer[cursor].y, mouse.y);
  delayedcall(0.02, updatemousepos() );
</action>
stopdelayedcall(id)
Stop the delayedcall with the given id.

Parameters:
  • id
    • The id of the delayedcall that should be stopped.
Examples
<events name="introimage_events"
        onnewpano="delayedcall(introimage, 5.0, hide_introimage() );"
        onremovepano="stopdelayedcall(introimage);"
        />
nexttick(actions)
Calls / executes the given actions in the next processing tick - that means after the current actions, but as soon as possible.

Parameters:
  • actions
    • The actions to call.
callwhen(condition, actions)
callwhen(id, condition, actions)
Calls the given actions when the condition is true or when it will become true.
When the condition is currently not true, then the callwhen() action will wait as long until the condition will become true.

Parameters:
  • id (optionally)
    • An optional unique id for the callwhen.
    • This id can be used to stop a waiting callwhen by calling stopcallwhen(id).
  • condition
    • A logical expression.
    • The callwhen() action will check this condition constantly every frame until it will become true.
  • actions
    • The actions to call when the condition is true.
    • Can be a krpano action-code string or a Javascript function.
Examples
callwhen(plugin[video].loaded, plugin[video].playvideo(...); );
callwhen(plugin[maps].loaded, plugin[maps].setcenter(...); );
stopcallwhen(id)
Stop a still waiting callwhen with the given id.

Parameters:
  • id
    • The id of the callwhen that should be stopped.
for(startactions, condition, nextactions, loopactions)
For loops.

First the startactions will be called, then the condition be checked and when it is true - then the loopactions will be called, then the nextactions and then it starts checking the condition and the loop again.

Parameters:
  • startactions
    • The actions that will be called / executed before the for loop starts.
  • condition
  • nextactions
    • The actions that will be called / executed after one loop (after the loopaction).
  • loopactions
    • The actions that will be repeatedly called / executed as long as the condition is true.
Examples
for(set(i,0), i LT 10, inc(i), trace('i=',i) );.
for(set(i,0), i LT layer.count, inc(i), 
  trace('layer[',i,'].name=',layer[get(i)].name);
);  
forall(array, itemvar, actions)
Loops through all elements of a krpano Array.

Parameters:
  • array
  • itemvar
    • Name of the variable that will contain the Array item in the actions code.
  • actions
    • The actions that will be called / executed for each item.
    • The current Array item will be available here as itemvar-named variable.
Examples
forall(scene, s, trace(s.name); );
forall(hotspot, h, h.visible=false; );
loop(condition, loopactions)
asyncloop(condition, loopactions, doneactions)
Javascript API - use a callback function:
krpano.actions.asyncloop(function(){ ...; return true; })
As long as the condition is true the loopactions will be called repeatedly.

The normal loop() action will continue with the following actions when the loop itself is done.

The asyncloop() will continue intermediately with the following actions and execute the loopactions once per frame. When the async looping is finally done, then the doneactions will be called.

For Javascript usage there is also a special API where a callback function can be used. This function will be called as long once per frame until the function returns false.

Parameters:
  • condition
    • A logical expression.
    • Or a Javascript function that returns true (=keep looping) or false (=stop looping).
  • loopactions
    • The actions or a Javascript function that will be repeatedly called / executed as long as the condition is true.
  • doneactions (optionally, asyncloop only)
    • The actions or a Javascript function that will be called when the condition becomes false and the looping stops.
Examples
ondown="asyncloop(pressed, layer[scrollarea].scrollby(+2,0) );"
onover="asyncloop(hovering, updatemousepos(), hideinfo() );"
asyncloop(true, framehandler() );
Javascript Example:
var hs = krpano.get("hotspot[spotname]");
hs.ondown = function(){
  krpano.actions.asyncloop(function(){
    if (hs.pressed) some_drag_hotspot_function(hs);
    return hs.pressed;
  });
};
renderloop(loopactions)
stoprenderloop()
Javascript API - use a callback function:
loopid = krpano.actions.renderloop(function(){ ...; return true; })
krpano.actions.stoprenderloop(loopid)
The renderloop() action will execute the loopactions once every frame.
To stop the loop the stoprenderloop() action need to be called inside the loopactions.

Parameters:
  • loopactions
    • The actions that will be repeatedly called / executed every frame.
    • Can be a krpano action-code string or a Javascript function that returns true (=keep looping) or false (=stop looping).
Examples
krpano-Action-Code Example:
renderloop(
    ... do something ...
    if(...done with rendering...,
      stoprenderloop();
    );
);
Javascript-Code Example:
krpano.actions.renderloop(function(){
    ... do something ...
    return done_with_rendering ? false : true;
});
setinterval(id, delay, actions)
clearinterval(id)
Calls / executes the given actions repeatedly with a delay time interval between them.

Parameters:
  • id (optionally)
    • An unique id for the interval.
    • This id can be used to stop the interval by calling clearinterval(id).
  • delay
    • The number of seconds to wait between the actions calls.
    • When using 0 as delay, the actions will be called once every frame.
  • actions
    • The actions to call every delay seconds.
Examples
setinterval(time, 1.0, 
    jsget(time, (new Date()).toLocaleTimeString(); );
    trace('time=',time);
  );
<events onkeydown="setinterval(get(keycode), 0.1, trace(keycode); );"
        onkeyup="clearinterval(get(keycode));"
        />
toggle(variable)
The toggle action toggles the value of the given (boolean) variable between true and false.

Parameters:
  • variable
    • The boolean variable that should be toggled.
Examples
toggle(fullscreen);
toggle(layer[button1].visible);
switch(variable)
switch(variable, value1, value2, ...)
The switch action switches the value of the given variable between / through several states. Every time when the switch action will be called the value will be switched / changed.

When only the variable itself without value parameters will be given, then the variable will be switched between true and false.

When there are two or more values given as parameters, then the variable will switch through all the values (starting from the current value and then to right and then starting over again at the end).

Parameters:
  • variable
    • The variable that should be switched / changed.
  • value1, value2, ... (optionally)
    • The switch-through values for this variable.
Examples
switch(fullscreen);
switch(layer[button1].visible);
switch(layer[button1].alpha, 1.0, 0.5);
switch(layer[child].parent, button1, button2, button3);
switch(destpos, -100, 0, +100); tween(y,get(destpos));
break()
  • Break / stop the execution of action calls from the current flow and the also the action calls from one nesting level up (e.g. when called inside an if() call then also the flow outside that if will be stopped).
  • When used inside a for() or loop() loop, the break() call will also stop that loop.
exitcall()
  • Directly exit / stop the current actions 'call'.
  • A 'call' is either a call to an <action> or the calling of a variable that contains action code or the calling of action code from events.
callwith(caller, actions)
Call krpano action code with using a specific plugin / layer or hotspot element as caller. This can be used for direct property access or to simulate event calls on these elements.

Parameters:
  • caller
    • The element that should be used as caller.
    • Can be only a <plugin> / <layer> or <hotspot> element.
  • actions
    • Any krpano action code.
    • The code will be executed in the 'context' of the caller - that means 'direct' access to its properties.
Examples
callwith(layer[test], onclick);
callwith(layer[test], trace('test pos=',x,'/',y); );
callwith(layer[test], tween(alpha, 0.0); );
scope(scope, actions)
Call krpano action code within a specific scope.

Parameters:
  • scope
    • The scope for the actions code.
    • Available scopes:
      • global
      • local
      • localonly
      • parent
      • private:NAME
      Details about the scopes here: actions scope.
  • actions
    • Any krpano action code.
Examples
scope(localonly, for(set(i,0), i LT 10, inc(i), trace(i)); );
scope(private:my_xml_plugin, trace(internal_var); );
parentscopeset(variable, value)
Set a variable to the a value - like a set() call - but in the scope of the parent action.
This could be used to return / pass back a result from an inner local scope action to an outer one.

Parameters:
  • variable
    • The variable name.
    • The variable will be created when it doesn't exists.
  • value
    • The new value for this variable.
    • When the variable already exists, then the value will be converted to the type of that variable.
linkeventscope(element)
Link the current local scope to the events of the given element.

When an event of that element (e.g. onclick) will be called, then the same scope will be used in the event code. By default events are always using the global scope.

Note - when having linked to a scope, it is necessary to use caller to address the element scope itself!

Parameters:
  • element
    • A layer or hotspot element.
Examples
<action ... scope="local">
  set(localvar, 123);
  addhotspot(auto,hs);
  ...
  linkeventscope(hs);
  set(hs.onclick, trace('localvar=',get(localvar)); );
</action>
assignstyle(elementname, styles)
Copy the attributes from one or more <style> elements to a custom element.

Parameters:
  • elementname
    • The name of the element where the style attributes should be copied to.
      E.g. layer[test] or myelement[name].
  • styles
    • The name of a <style> element.
    • Several style names can be to combined by a | character.
Examples
assignstyle(layer[test], 'teststyle');
assignstyle(layer[test], 'style1|style2');
copyattributes(destobject, srcobject)
Copy all attributes from one object to another one.

Note - the parameters of the copyattributes() action need to be the objects, not the names/paths of the objects! That means it might be necessary to use the get() action to resolve the names/paths.

Parameters:
  • destobject
    • The destination object - the object where the attributes will be copied to. Existing attributes will be overwritten.
  • srcobject
    • The source object - all attributes from that object will be copied to the destination object.
Examples
copyattributes(get(layer[test]), get(style[style1]));
events.dispatch(eventname, instantly)
Dispatches / calls the given event from all <events> elements.

Parameters:
  • eventname
    • The name of the event.
  • instantly (optionally)
    • A Boolean setting (true or false, false by default).
    • When set to true, the events will be called and executed instantly, when not set or set to false, the events will be called after the current actions calls.
Examples
<events name="events1" myevent="trace(events1...);" />
<events name="events2" myevent="trace(events2...);" />
...
events.dispatch(myevent);
focus()
Javascript API:
krpano.focus()
Give the input focus to the current krpano viewer.
releasefocus()
Javascript API:
krpano.releasefocus()
Remove the input focus from the current viewer.
That will also stop any movement frictions, release pressed keyboard-keys and close an open contextmenu.
add(variable, valueA, valueB)
sub(variable, valueA, valueB)
mul(variable, valueA, valueB)
div(variable, valueA, valueB)
mod(variable, valueA, valueB)
pow(variable, valueA, valueB)
Actions for mathematical calculations.
These actions can be used with 2 or 3 parameters:

  • with 2 parameters:
    • add(dst,val1)  ⇒  dst = dst + val1 (like +=)
    • sub(dst,val1)  ⇒  dst = dst - val1 (like -=)
    • mul(dst,val1)  ⇒  dst = dst * val1 (like *=)
    • div(dst,val1)  ⇒  dst = dst / val1 (like /=)
    • mod(dst,val1)  ⇒  dst = dst % val1 (modulate)
    • pow(dst,val1)  ⇒  dst = dst ^ val1
  • with 3 parameters:
    • add(dst,val1,val2)  ⇒  dst = val1 + val2
    • sub(dst,val1,val2)  ⇒  dst = val1 - val2
    • mul(dst,val1,val2)  ⇒  dst = val1 * val2
    • div(dst,val1,val2)  ⇒  dst = val1 / val2
    • mod(dst,val1,val2)  ⇒  dst = val1 % val2 (modulate)
    • pow(dst,val1,val2)  ⇒  dst = val1 ^ val2

Note - val1 and val2 can be values or variables. When val1 or val2 is a variable then automatically the content of the variable will be used!

Parameters:
  • variable
    • The variable where the result of the calculation will be stored.
    • When the variable doesn't exists, it will be created.
  • valueA / valueB (optionally)
    • The values or variables for the calculation.
Examples
set(val, 1);
add(val, 1);
trace('val should be 2: val=',val);
mul(doublewidth, width, 2.0);
mul(scale, 0.5);
div(result, vala, valb);
add(dst,rotate,360); tween(rotate,get(dst),5);
add(xpos, mouse.x, mouse_x_offset);
sub(destx, stagewidth,  destwidth);
div(aspect,16,9);
mod(cur_hlookat,cur_hlookat,360);
pow(sqrt,val,0.5);
inc(variable, byvalue, max, min)
dec(variable, byvalue, min, max)
These actions increase or decrease variable (with saturation or limiting).

Parameters:
  • variable
    • The variable to increase or decrease.
  • byvalue (optionally)
    • Increase or decrease the variable by this value.
    • When not set, the variable will be increased or decreased by 1.
  • max / min (optionally)
    • Defines maximum and minimum values.
    • When one limit will be reached then the value will be set back to the other limit value. This can be used to let the varibale either wrap around a defined range or to clip at at specific limit (with min=max).

Note - The inc() and dec() actions will convert the variable type to 'integer'!
Examples
inc(i);
inc(frame,1,get(lastframe),0);
inc(ypos,30);
inc(view.hlookat, 2, 90, 90);
clamp(variable, min, max)
Limit the value of the variable to be between the given min and max values.

Parameters:
  • variable
    • The variable to clamp / to limit.
  • min
    • The minimum value - when value of the variable is below that value, it will be set to this min value.
  • max
    • The maximum value - when value of the variable is above that value, it will be set to this max value.
Examples
clamp(percent, 0, 100);
screentolayer(bar, mouse.stagex,mouse.stagey, lx,ly);
div(fill, lx, layer[bar].pixelwidth);
mul(fill, 100);
clamp(fill, 0, 100);
txtadd(layer[barfill].width, get(fill), '%');
Math.*
The Math object provides constants and actions for mathematical calculations.

The most Math actions can be called in two ways - either by just passing the name of the variable - then variable will be used as parameter and the result of the calculation will be stored back to the variable, or by specifying an additionally parameter where the result should be stored.

roundval(variable, decimalplaces)
roundval(destinationvariable, variable, decimalplaces)
Rounds the value of the variable to given decimal places.

Note - the variable will be a string internally after rounding!

Parameters:
  • destinationvariable (optionally)
    • The variable where the result will be stored.
    • Only when called with 3 parameters!
  • variable
    • The variable to be rounded.
    • When called with 1 or 2 parameters, the result will be stored also in that variable.
  • decimalplaces (optionally)
    • The number of decimal places - 0 when not set.
    • Negative values work like positive ones, except that trailing zeros are automatically removed (except for a least one zero after the comma dot).
Examples
roundval(val);
roundval(val, 2);
roundval(val, 123.0, 6);   // ⇒ "123.000000"
roundval(val, 123.0, -6);  // ⇒ "123.0"
roundval(hlookat_print, view.hlookat, 2);
tohex(variable, prefix, length)
tohex(destinationvariable, variable, prefix, length)
Convert the content of the given variable to a hexadecimal string.
Can be used to create html/css color strings.

Parameters:
  • destinationvariable (optionally)
    • The variable where the result will be stored.
    • Only when called with 4 parameters!
  • variable
    • The variable to be converted to a hexadecimal string.
    • When called with less than 4 parameters, the result will be stored also in that variable.
  • prefix (optionally)
    • A prefix (like '0x' or '#') for the string.
  • length (optionally)
    • A fixed length for the result.
Examples
tohex(color,'#',6);
set(color, ...an_external_integer_input...);
tohex(color,'#',6);
txtadd(layer[text1].css,'color:',get(color),';');
tolower(variable)
toupper(variable)
tolower(destinationvariable, sourcevariable)
toupper(destinationvariable, sourcevariable)
Convert the content of the given variable to a lower or upper case.

Parameters:
  • destinationvariable (optionally)
    • The variable where the case conversion result will be stored.
    • Only when called with 2 parameters!
  • variable / sourcevariable
    • The variable to be converted to a lower or upper case.
txtadd(destination, txt1, txt2, txt3, ...)
The txtadd action can be used to add/connect several texts / values together.
The action can be used with 2 or more parameters. When using only two parameters (destination and a text) then the text will be added to current value of the destination variable.

Parameters:
  • destination
    • The destination variable where the connected text will be stored.
    • The variable will be created when it doesn't exists.
  • txt1, txt2, txt3, ... (optionally)
    • The texts that will be connected together.
    • When using only one txt parameter then this text will be added to the content of current destination variable.
    • Note - when the content of a variable should be used - then the get() action must be used to resolve the variable!
Examples
txtadd(picfilename,'%CURRENTXML%/pic_',get(pic),'.jpg');
txtadd(crop,'0|',get(ypos),'|333|285');
txtadd(pname, 'thumbbar_image_', get(i));
txtadd(layer[text].html,'[p]',get(data[txt1].content),'[/p]');
txtadd(msg,get(view.fovtype),'=',get(fov),'Ā°');
subtxt(dstvar, srcvar, startpos, len)
The subtxt action extracts a part of an other text.

Parameters:
  • dstvar
    • The destination variable where the extracted text will be stored.
    • The variable will be created when it doesn't exists.
  • srcvar
    • The variable or text with the source text.
  • startpos
    • The starting position from where the text should be extracted.
  • len
    • The length of the text to extract.
indexoftxt(index, txt, searchtxt, startindex)
The indexoftxt action gives the position of the first occurrence of the 'searchtxt' value in the 'txt' string.

Parameters:
  • index
    • A variable that will store the index of first occurrence of 'searchtxt'.
    • Or -1 if 'searchtxt' never occurs.
    • The variable will be created when it doesn't exists.
  • txt
    • The text in which it should be searched.
  • searchtxt
    • The text to searched for.
  • startindex (optionally)
    • The starting startindex / position where to start searching for the text (0 by default).
txtreplace(var, searchtext, replacetext)
txtreplace(dstvar, srcvar, searchtext, replacetext)
The txtreplace action searches in 'var/srcvar' for all occurrences of 'searchtext' and replaces them with 'replacetext'.

Parameters:
  • var / srcvar / dstvar
    • The variable where to search for (var, srcvar) and where the result will be stored (var, dstvar).
    • The variable will be created when it doesn't exists.
  • searchtxt
    • The text that should be searched for.
  • replacetext
    • The text that will replace the 'searchtxt' occurrences.
txtsplit(string, separator, resultingarray)
txtsplit(string, separator, var1, var2, ...)
Splits the given 'string' by the given 'separator'.

Parameters:
  • string
    • The string to split, can be either a text or a variable.
  • separator
    • The separator character or string.
  • resultingarray (when calling the txtsplit() action with 3 arguments)
    • Name of a krpano Array variable that will contain the split parts as 'value' properties.
  • var1, var2, ... (when calling the txtsplit() action with 4 or more arguments)
    • The results of the spliting will be directly assigned to the given variables.
    • When using null as variable, that value will ignored/skipped (could be used to extract only some specific values).
Examples
Split into separate variables:
txtsplit('1|2|3', '|', a, b, c);
trace('a=',get(a), ' b=',get(b), ' c=',get(c));
Result:
a=1 b=2 c=3
Split into an array:
txtsplit('x|y|z', '|', arr);
for(set(i,0), i LT arr.count, inc(i),
trace('arr[',get(i),'].value=',arr[get(i)].value);
);
Result:
arr[0].value=x
arr[1].value=y
arr[2].value=z
txtjoin(var, separator, array)
txtjoin(var, separator, var1, var2, ...)
Join / concate all of the elements in the given array or the given variables and inserts the specified separator string between them.

Parameters:
  • var
    • The variable where the result will be stored.
    • The variable will be created when it doesn't exists.
  • separator
    • The separator character or string that will be insert between the elements.
  • array (when calling the txtjoin() action with 3 arguments)
  • var1, var2, ... (when calling the txtjoin() action with 4 or more arguments)
    • The variables or values to join.
Examples
Split into separate variables, modify and then join again:
txtsplit(image.prealign, '|', rx, ry, rz);
add(ry,90);
txtjoin(image.prealign, '|', rx, ry, rz);
Split into an array, modify and rejoin:
txtsplit('1|2|3', '|', arr);
for(set(i,0), i LT arr.count, inc(i), mul(arr[get(i)].value,2); );
txtjoin(test, '|', arr);
trace(test);
Result:
2|4|6
fromcharcode(var, charcode)
The fromcharcode action converts the given character code to a string and stores in the given variable.

Parameters:
  • var
    • The variable where to store the character.
    • The variable will be created when it doesn't exists.
  • charcode
    • The Unicode character code as number.
escape(var)
escape(var, text)
unescape(var)
unescape(var, text)
The escape and unescape actions are escaping the content of the given variable or the given text and then storing the result in the given variable.

Parameters:
  • var
    • Without text parameter - the variable which will be escaped/unescaped.
    • With text parameter - the variable where the escaped/unescaped text will be stored.
  • text (optionally)
    • The text that that will be escaped/unescaped.
tween(variable, value, time, tweentype, donecall, updatecall)
The tween action can be used for a time-controlled animation / change of a variable.
The action will dynamically change the current value of the variable to the given value.

Color support: When tweening a variable with a name that contains the word 'color', then the values will be automatically interpreted as 32bit ARGB colors and each color channel will be processed individually.

Multiple variable support: It is possible to tween several variables together at once. Therefore specify several variables, values and tweentypes separated by | characters. When several variables were specified, but only one value and/or only one tweentype, then all variables will tween to the same value and/or use the same tweentype. The time and the done- and updatecalls will be always the same for all given variables.

Parameters:
  • variable
    • The variable that should be changed.
    • Use the | character to specify several variables.
    • When the variable name contains the word 'color', then process the variable value as 32bit ARGB color value.
  • value
    • The destination value for this variable.
    • When tweening percent values - add a '%' character to the value.
    • Use the | character to specify several values for several variables.
    • Note - to tween to the value of another variable use the get() action to get the value of the other variable!
  • time (optionally)
    • The time in seconds for the change from the current value to the destination value (0.5 seconds by default).
    • Instead of using a fixed time for the change it is possible to define the maximum moving distance for the value and a time for that distance (not supported when tweening multiple variables). This allows to use a short time for a short distance and long time for a long distance.
      This can be done by using the distance function:
      • distance(maxdistance,maxtime)
        • maxdistance - the maximum distance between the start and the destination value
        • maxtime - the time in seconds for this maximum distance

  • tweentype (optionally)
    • The tweening / interpolation type (easeOutQuad by default).
    • See here for all available tween types: tweentypes.
  • donecall (optionally)
    • The action commands that should be executed when the tween is done and the destination value has been reached.
    • Instead of normal actions, it is also possible to use the special keyword WAIT here. In this case the user interface and the execution of the following actions will be blocked until the destination value has been reached. The oninterrupt action can be used to make this action interruptable by the user.
  • updatecall (optionally)
    • These action will be called every time (=every frame!) when the value will be updated / changed!
    • WARNING - use with care! When heavly used this can reduce the framerate!

Some information about the origin of the name "tween" - Wikipedia about Tweening.
Examples
tween(scale,2);
tween(rotate,90);
tween(width,50%);
onover="tween(alpha,0.7,distance(0.3,0.2));"
onout="tween(alpha,1.0,distance(0.3,0.2));"
set(alpha,0);
set(visible,true);
tween(alpha, 1.0 ,0.3);
tween(layer[logo].width, get(destwidth));
set(layer[image].enabled,false);
tween(layer[image].alpha,0.0,0.5,default,removeplugin(image));
set(view.stereographic,true);
tween(view.vlookat, 90.0, 2.0);				
tween(view.fisheye, 1.0, 2.0);
tween(view.fov, 150.0, 2.0);
stoptween(variable, ...)
The stoptween action stops a currently running tween action.

Parameters:
  • variable
    • The name of the variable which is currently tweening and should be stopped.
  • ... variable, variable, ... (optionally)
    • Addtional variables that should stop tweening.
Examples
ondown="tween(layer[text].y, 10, distance(400,0.7), linear);"
onup="stoptween(layer[text].y);"
tweentypes
All available tween types for the tween action:
linear
easeinquad
easeoutquad
easeinoutquad
easeinback
easeoutback
easeinoutback
easeincubic
easeoutcubic
easeinquart
easeoutquart
easeinquint
easeoutquint
easeinsine
easeoutsine
easeinexpo
easeoutexpo
easeincirc
easeoutcirc
easeinbounce
easeoutbounce
easeoutinquad
easeinoutcubic
easeoutincubic
easeinoutquart
easeoutinquart
easeinoutquint
easeoutinquint
easeinoutsine
easeoutinsine
easeoutinexpo
easeinoutexpo
easeinoutcirc
easeoutincirc
easeinoutbounce
easeoutinbounce
set3dtransition(ref, dx,dy,dz, mblur, hlookatoffset, delay, time, tweentype)
set3dtransition(ref, h,v,d, mblur, hlookatoffset, delay, time, tweentype)
Setup a 3D-transition between panos.
  • A movement in 3D space with optional motion-blurring.
  • Need to be called before a loadpano/loadscene/load... call.
  • Works for normal 'non-3D' panos and for Depthmapped / 3D-Model panos.
  • The 3D transition will start automatically once the new pano is loaded and ready.
  • When set and during the 3D transition is running, the have3dtransition variable will be true.

Parameters:
  • ref and dx, dy, dz or h, v, d
    • The reference for the given 3D coordinates:
    • ref="image" (default)
      • For panos without Depthmapping or a 3D-Model the dx, dy, dz values are defining the 3D moving direction. The length of the 3D direction vector defines the zooming distance and should be typically between 500 and 1000.
      • For panos with Depthmapping or a 3D-Model the dx, dy, dz values are a relative offset to the image 3D position of the next pano.
    • ref="world"
      • The dx, dy, dz values are defining an absolute 3D world position.
      • Only for Depthmapped / 3D-Model panos.
    • ref="sphere"
      • The h, v, d values are defining a spherical position as direction and a distance (1000.0 by default) for zooming.
      • Only for panos without Depthmapping or a 3D-Model.
  • mblur (optionally)
    • Strengh of the motion blur effect: 0.0 to 0.9.
    • The default is 0.5.
  • hlookatoffset (optionally)
    • An optional offset for the horizontal looking direction (view.hlookat).
    • Can be used when the panos are not aligned together (different Norths).
    • The default is 0.0.
  • delay (optionally)
    • An optional delay in seconds before starting with the 3D-transition.
    • By default or when set to 0.0, the 3D-transition starts together with the pano-blending.
  • time (optionally)
    • An optional duration time in seconds for the 3D-transition.
    • By default or when set to 0.0, the time will be automatically the same that will be set in the BLEND(blendtime) parameter.
  • tweentype (optionally)
Examples
<hotspot ... onclick="scene3dtransition('scene2');" />

<action name="scene3dtransition" scope="local" args="newscene">
    set3dtransition("sphere", caller.ath,0);
    loadscene(get(newscene), null, MERGE, BLEND(0.5) );
</action>
loadpano(xmlpath, vars, flags, blend, loaddone)
loadscene(scenename, vars, flags, blend, loaddone)
loadpanoscene(xmlpath, scenename, vars, flags, blend, loaddone)
loadpanoimage(flags, blend, loaddone)
loadxml(xmlstring, vars, flags, blend, loaddone)
Actions to load a new panos:
Examples

Note - only the layer, plugin, hotspot and event elements with keep="true" will be kept when loading new panos!

Parameters:
  • xmlpath (for loadpano)
    • The path/url of the new pano xml file to be loaded (use null for none).
    • When a relative path will be used then the file will be loaded from the basedir folder, which is %FIRSTXML% by default. That means that the paths in all loadpano calls are relative to the first loaded xml file.
  • xmlstring (for loadxml)
    • The content of a xml file as string / text to be loaded (should be escaped).
  • scenename (for loadscene)
    • The name of the <scene> element that should to be loaded.
  • vars (optionally)
    • Custom variables to set (use null for none).
    • These variables will be set after parsing / resolving the xml but before starting to load the pano images. This way these variables can be used either to overwrite settings from the xml or to set addtional ones.
    • Variables can be defined as var1=val1 pairs separated by &amp;.
  • flags (optionally)
    • Addtional flags for loading (use null for none).
    • Several flags can be combined by a | character.
    • Available flags:
      • MERGE (the recommended flag)
        • Merges all settings from the current and the next pano.
        • If there are layers, plugins or hotspots in the new panorama with the same name as the kept ones, the new elements will not be loaded.
        • This is the recommended setting for virtual tours.
      • PRELOAD
        • Preload the full resolution of the next pano for the current viewing range before blending to it.
        • Without that flag the blending will start as soon ANY content (e.g. the preview-pano, low-res tiles, ...) has fully filled the view.
        • Without PRELOAD flag the switching from one pano to the next pano can be much faster, so this flag should be only used in certain cases.
      • KEEPIMAGE
        • Keep the current pano-image.
        • Ignores the <image> element from the next pano.
      • KEEPVIEW
        • Keep the current view settings.
        • Except the viewing range limitations as they are more related to the pano image.
      • KEEPMOVING
        • Keep the current view and allow moving during the blending.
      • KEEPLIMITS
        • Keep the current view limitations.
        • Without that flag, the current viewing limits will be reset when loading a new pano.
      • KEEPLOOKAT
      • KEEP3D
      • KEEPSCENES
        • Keep the current scenes (loadpano only).
      • KEEPPLUGINS
        • Keep the current loaded layers / plugins.
      • KEEPHOTSPOTS
        • Keep the current loaded hotspots.
      • NOPREVIEW
        • Skip / ignore the <preview> element of the new pano.
      • REMOVESCENES
        • Remove all current scenes.
      • IGNOREKEEP
        • Ignore the keep="true" setting and remove also these elements.
      • IMAGEONLY
        • Load only the pano-image (and the preview).
        • Can not be used with the loadpanoscene() action.
      • IMAGEANDVIEW
        • Load only the pano-image (and the preview) and the view settings.
        • Can not be used with the loadpanoscene() action.
      • RESET
        • Resets the krpano viewer before loading the new pano.
        • Removes all current layers, hotspots, actions, events and animations/timers, even when defined with keep=true.
        • Set everything back to default except: custom global stored variables and the current area, display, control, network, memory and security settings.
  • blend (optionally)
    • Blend / Crossfade to next pano image / Transition Animation
    • Available blending modes:
      NOBLEND
      No blending, just switch directly to the next panorama (the default).

      BLEND(time, tweentype)
      Blend / Crossfade from current panorama to next one.
      This is also the fallback mode when the selected mode is not supported!

      Parameters:
      • time - The blending time in seconds (default=2.0).
      • tweentype - The blending curve / motion shape, type of the blending animation (default=easeInCubic) - see tweentypes.

      (WebGL only)COLORBLEND(time, color, tweentype)
      Blend to a color and then from that color to the next panorama.

      Parameters:
      • time - The blending time in seconds (default=2.0).
      • color - The in-between color in hex format (default=0x000000 = black).
      • tweentype - The blending curve / motion shape, type of the blending animation (default=easeOutSine) - see tweentypes.

      (WebGL only)LIGHTBLEND(time, color, colorscale, tweentype)
      Add or subtract a color and then cross-fade to the next panorama.

      Parameters:
      • time - The blending time in seconds (default=2.0).
      • color - The color to add in hex format (default=0xFFFFFF = white).
      • colorscale - The scaling factor of the color, use negative values for subtracting (default=2.0).
      • tweentype - The blending curve / motion shape, type of the blending animation (default=easeInCubic) - see tweentypes.

      (WebGL only)SLIDEBLEND(time, angle, smooth, tweentype)
      A slide animation between the current and the next panorama.

      Parameters:
      • time - The blending time in seconds (default=2.0).
      • angle - The angle / direction of the slide in degrees (default=0.0).
      • smooth - The smoothing / blurring of the transition line (0.0 to 1.0, default=0.2).
      • tweentype - The blending curve / motion shape, type of the blending animation (default=linear) - see tweentypes.

      (WebGL only)OPENBLEND(time, shape, smooth, zoom, tweentype)
      An opening animation between the current and the next panorama.

      Parameters:
      • time - The blending time in seconds (default=2.0).
      • shape - A factor that defines the opening shape (-1.0 to +1.0) - 0.0=circle opening, -1.0=vertical opening, +1.0=horizontal opening (default=0.0).
      • smooth - The smoothing / blurring of the transition line (0.0 to 1.0, default=0.2).
      • zoom - Additionally zoom-out the old panorama (0.0 to 1.0, default=0.0).
      • tweentype - The blending curve / motion shape, type of the blending animation (default=linear) - see tweentypes.

      (WebGL only)ZOOMBLEND(time, zoom, tweentype)
      ZOOMBLEND(time, zoom, x, y, tweentype)
      Zoom into the current view and cross-fade to the next panorama.

      Parameters:
      • time - The blending time in seconds (default=2.0).
      • zoom - The zoom factor (default=2.0).
      • x, y - The zoom center (0.0 to 1.0, default=0.5).
      • tweentype - The blending curve / motion shape, type of the blending animation (default=easeInOutSine) - see tweentypes.

      DEMO: Pano Blending Demo

      Note - When the selected blending mode will be not supported, e.g. when using a transparent background or when using a 'WebGL only' mode and only CSS3D is available, then automatically the BLEND() mode will be used instead.
  • loaddone (optionally)
    • Actions code or a Javascript function to call when the loading is done.
Examples
loadpano
loadpano(pano2.xml);
loadpano(pano2.xml, null, MERGE, BLEND(1));
loadscene
loadscene(scene1);
loadscene(scene1, null, MERGE, BLEND(1));
loadxml
loadxml('<krpano><image><sphere url="pano.jpg"/></image></krpano>');
loadxml(get(data[xml].content), null, KEEPALL);
loadpanoimage (Action Code)
image.reset();
set(image.sphere.url, 'pano.jpg');
set(image.hfov, 100);
loadpanoimage();
loadpanoimage (Javascript Code)
krpano.image.reset();
krpano.image.flat = {
  url : "tile_%l_%v_%h.jpg",
  multires : "512,1024x512,2048x1024,4096x2048"
};
krpano.actions.loadpanoimage('MERGE','BLEND(0.5)',function()
{
  console.log('load call done');
});
image.reset(options)
Resets the <image> element back to default.

Should be used before a loadpanoimage() call to create an new image object. When the image object is already used for rendering a pano, then calling loadpanoimage() will fail with an error.

Parameters:
  • options (optionally)
    • When options is set to copy then all basic settings from the current <image> element are copied to the new one.
includexml(url, loaddone)
includexmlstring(string, loaddone)
Dynamically load and add xml content.

This will not change any current elements or trigger any events.
Only <actions> with autorun="preinit" will get called.
If the xml contains <image> elements, then they will be skipped.

Parameters:
  • url
    • The url of the xml file to load and include.
  • string
    • The xml code to include as string.
  • loaddone (optionally)
    • Actions code or a Javascript function to call when the loading is done.
loadjs(url, loaddone, loaderror)
Dynamically load and execute Javascript code.

The Javascript code will run within the krpano context and have direct access to all krpano objects and variables - same as type="Javascript" actions.

Parameters:
  • url
    • The url of the js file to load and execute.
    • Different to Javascript files loaded directly by the browser (using <script> in the html code), these js files can be encrypted using the krpano tools.
    • Optionally it is also possible to load several js files at once. For this the urls need to be separated by a pipe | character. The file loading will be done in parallel but the resulting Javascript code execution will be done when all files are loaded and in the same order as the files were requested. Example:
      loadjs('file1.js|file2.js|file3.js');
      When called directly from Javascript it is also possible to pass the files as Array:
      krpano.actions.loadjs(['file1.js','file2.js','file3.js']);
  • loaddone (optionally)
    • Actions code or a Javascript function to call when the loading is done.
  • loaderror (optionally)
    • Actions code or a Javascript function to call when the loading failed.
openurl(url, target)
Open an url / link.

Parameters:
  • url
    • The url to open.
  • target (optionally)
    • The target where the url should be opened.
    • Possible settings:
      • _blank - open the url in a new window (the default)
      • _self - open the url in the current frame in the current window
      • _parent - open the url in the parent of the current frame
      • _top - open the url in the top-level frame in the current window
Examples
openurl('https://krpano.com',_self);
openurl('help.html');
lookat(h, v, fov, distortion, architectural, pannini)
Look at this panorama position.

Parameters:
  • h
    • The horizontal looking direction (view.hlookat) in spherical coordinates in degrees (-180 to +180).
  • v
    • The vertical looking direction (view.vlookat) in spherical coordinates in degrees (-90 to +90).
  • fov (optionally)
    • The field of view (view.fov) in degrees (0 - 179).
  • distortion (optionally)
  • architectural (optionally)
  • pannini (optionally)
Examples
lookat(0,0);
lookat(0,0,90);
loadpano(pano.xml);
lookat(45.1, -20.2, 110.0);
lookto(h, v, fov, motiontype, shortestway, nonblocking, donecall)
looktohotspot(hotspotname, fov, motiontype, shortestway)
moveto(h, v, motiontype)
zoomto(fov, motiontype)
Move the view from current looking position to the given position.

Note - the user-interface and all following actions are blocked during the movement (except the nonblocking parameter of the lookto call is true). That means the next action will be only executed when the current lookto action has been finished.
To allow the user to interrupt the movement and the blocked user interface and to take control again, the oninterrupt() action can be used.


Parameters:
  • h
    • Horizontal destination looking direction (-180 to +180, wraparound possible).
  • v
    • Vertical destination looking direction (-90 to +90).
  • hotspotname (for looktohotspot, optionally)
    • The name of the hotspot.
    • This will be use the hotspot position (ath/atv) as destination position.
    • When no name will be defined and looktohotspot() will be called from a hotspot element then that hotspot itself will be used.
  • fov (optionally)
    • The destination fov (0 to 179).
    • The looktohotspot action will use automatically the size of the hotspot as destination fov when the fov was not set. The other actions keep the current fov when not set.
  • motiontype (optionally)
    • The type of the motion.
    • Possible settings:
      • linear(speed) - a linear motion
        • speed = moving speed in degrees/second
      • smooth(accel,break,maxspeed) - accelerated smooth movement (=default)
        • accel = acceleration in degrees/secondĀ² (default=720)
        • break = negative acceleration in degrees/secondĀ² (default=-720)
        • maxspeed = maximum moving speed in degrees/second (default=720)
      • tween(tweentype,time) - tween animation curve
        • tweentype = one of the tween types
        • time = time in seconds for the movement
  • shortestway (optionally)
    • The use the shortest possible way from the current to the destination position.
    • Possible settings: true or false (default=true).
  • nonblocking (optionally, lookto only)
    • When set to true, then the lookto action will not wait for completing the movement before continue executing the the following actions. The user-interface will also be not blocked.
    • When the lookto movement is done then the donecall action will be called (when defined).
    • To stop/interrupt a non-blocking lookto, the stoplookto() action can be anytime called.
  • donecall (optionally, lookto only, only when nonblocking is true)
    • This action will be called when the nonblocking lookto movement is done.
Examples
moveto(100.0,5,linear(10));
zoomto(130,smooth());
lookto(33,-22,30,smooth(100,50,20));
looktohotspot(hotspot1);
looktohotspot(hotspot2, 40);
looktohotspot(hotspot3, 25, smooth(100,50,20));
looktohotspot(get(name));
adjusthlookat(desthlookat)
Adjusts the view.hlookat value for manual tweening.
It fixes the 360 wrap around for the shortest way to desthlookat.

Parameters:
  • desthlookat
    • The intended destination hlookat value.
    • When desthlookat is the name of a variable, then automatically the value of that variable will be used.
    • The current view.hlookat variable will be adjusted (without changing the current view) to be next to this value.
Examples
adjusthlookat(140);
tween(view.hlookat, 140);
adjust360(source_ath, target_ath)
Adjusts the source_ath variable to be shortest 360-horizontal-around way to target_ath variable.

Parameters:
  • source_ath
    • The source/start ath value.
    • source_ath needs to be the name of a variable.
  • target_ath
    • The intended target/destination ath value.
    • When desthlookat is the name of a variable, then automatically the value of that variable will be used.
Examples
Move a hotspot to the current horizontal viewing position:
adjust360(hotspot[test].ath, view.hlookat);
tween(hotspot[test].ath, get(view.hlookat), 1.0);
getlooktodistance(result, toH, toV, fromH, fromV)
Get the spherical distance between the fromH / fromV and toH / toV lookto points (in degrees). The result will be always between 0.0 and 180.0 (more than 180 degree distance is not possible on a sphere).

Parameters:
  • result
    • The name of the variable where the distance value will be stored.
    • The variable will be created when it doesn't exists.
    • When calling this function directly by Javascript, the result parameter can be null, the result will be returned as Javascript return value in this case.
  • toH
    • Horizontal looking-to position (-180 to +180, wraparound possible).
    • Can be a variable name or a value.
  • toV
    • Vertical looking-to position (-90 to +90).
    • Can be a variable name or a value.
  • fromH (optionally)
    • Horizontal looking-from position (-180 to +180, wraparound possible).
    • Can be a variable name or a value.
    • When not defined, the current horizontal looking direction (view.hlookat) will be used by default.
  • fromV (optionally)
    • Vertical looking-from position (-90 to +90).
    • Can be a variable name or a value.
    • When not defined, the current vertical looking direction (view.vlookat) will be used by default.
stoplookto()
Stop a non-blocking lookto() action.
stopmovements()
Instantly stop all user-driven (by mouse, keyboard or touch) panning and zooming movements.
wait(parameter)
Wait a number of seconds or wait for an event.

Note - The user interface and all following actions will be blocked during the waiting. That means the next action in the current call will be executed when the current wait action is done. The oninterrupt action can be used to make this action interruptable by the user.

Parameters:
  • parameter
    • any number - this the time the action will wait in seconds
    • LOAD - wait until loading is finished
    • BLEND - wait until loading and blending are finished
Examples
oninterrupt(break);
lookto(150,30,70);
wait(3);
lookto(242,0,150);
lookto(280,-10,50);
wait(3);
loadpano(pano2.xml,null,MERGE,BLEND(2));
lookat(100,50,5);
wait(BLEND);
lookto(100,50,150);
oninterrupt(actions)
This action can be used before calling actions that are blocking the user interface (like wait, lookto, looktohotspot, moveto, zoomto or tween with WAIT as donecall).
When any of these actions will get interrupted by the user (e.g. by a click) then the these actions will be stopped and the given actions be called.

Parameters:
  • actions
    • The action commands to call on a user interrupt.
    • Addtionally there is a special command possible here:
      break - this will just break the current actions.
Examples
oninterrupt(break);
lookto(150,30,70);
wait(3);
lookto(242,0,150);
lookto(280,-10,50);
wait(3);
oninterrupt( trace(user interrupt); );
lookto(0,0,90);			
lookto(90,0,90);
lookto(180,0,90);
lookto(270,0,90);
lookto(0,0,90);
screentosphere(x,y, h,v)
spheretoscreen(h,v, x,y, stereoside)
Javascript API:
p = krpano.actions.screentosphere(x,y)
p = krpano.actions.spheretoscreen(h,v, stereoside)
Actions for converting between screen and spherical coordinates.

The screentosphere action will convert the x/y variables to the h/v variables and the spheretoscreen action the h/v variables to the x/y variables.

Parameters:
  • x / y - Screen coordinates in pixels from the left top edge.
  • h / v - Spherical coordinates in degrees.
  • stereoside (optionally)
      For stereo rendering - define to which screen side the coordinates should be mapped. Possible settings: l for the left side or r for right side or not-set/undefined for normal non-stereo screen coordinates.
Javascript Return:
  • p - An object with x, y properties.
Spheretoscreen Notes:
  • When the given spherical coordinates can't be converted to screen coordinates, e.g. when 'behind' the screen, then the resulting values will be NaN (Not-a-Number). The Javascript call will return null in this case.
Examples
screentosphere(mouse.x, mouse.y, toh, tov);
screentolayer(layer, screenx,screeny, layerx,layery)
layertoscreen(layer, layerx,layery, screenx,screeny)
Javascript API:
p = krpano.actions.screentolayer(layer, screenx,screeny)
p = krpano.actions.layertoscreen(layer, layerx,layery)
Actions for converting between screen/stage and relative <layer> coordinates.

Parameters:
  • layer - The name of the <layer> element or the <layer> element itself.
  • screenx / screenx - Screen/stage coordinates in pixels from the left top edge.
  • layerx / layery - Layer coordinates from the left top layer edge.
Javascript Return:
  • p - An object with x, y properties.
Notes:
  • The screen /stage coordinates are based on the krpano coordinate system (from left-top 0 / 0 to right-bottom stagewidth / stageheight).
  • The layer coordinates will be scaled when scalechildren is enabled.
  • Rotated layers are not supported!
Examples
screentolayer(bar, mouse.stagex,mouse.stagey, lx,ly);
div(fill, lx, layer[bar].pixelwidth);
mul(fill, 100);
clamp(fill, 0, 100);
txtadd(layer[barfill].width, get(fill), '%');
spheretospace(h,v,depth, x,y,z)
spacetosphere(x,y,z, h,v,depth)
Javascript API:
p = krpano.actions.spheretospace(h,v,depth)
p = krpano.actions.spacetosphere(x,y,z)
Actions for converting between spherical and XYZ 3D space coordinates.

Parameters:
  • h / v - Spherical coordinates in degrees.
  • depth - Distance from spherical center (1000.0 by default).
  • x / y / z - 3D space coordinates.
Javascript Return:
  • spheretospace: p - An object with x, y, z properties.
  • spacetosphere: p - An object with h, v, depth properties.
Examples
Convert the hotspot position from spherical to space coordinates:
spheretospace(ath,atv,depth, tx,ty,tz);
set(ath,0);
set(atv,0);
set(depth,0);
and back:
spacetosphere(tx,ty,tz, ath,atv,depth);
set(tx,0);
set(ty,0);
set(tz,0);
remapfovtype(fov, srcfovtype, dstfovtype, width, height)
Remap a fov value from one fovtype to another.

When changing the viewing fovtype and at the same time, remapping the viewing fov, then the resulting pano zoom will keep the same.

Parameters:
  • fov
    • A variable with the fov value that should be changed.
    • The result will be stored in the same variable.
  • srcfovtype
    • The current fovtype.
    • Can be: HFOV, VFOV, DFOV or MFOV.
  • dstfovtype
    • The new fovtype.
    • Can be: HFOV, VFOV, DFOV or MFOV.
  • width (optionally)
    • The width of the fov area/frame in pixels.
    • By default the current screen/area size will be used.
  • height (optionally)
    • The height of the fov area/frame in pixels.
    • By default the current screen/area size will be used.
Examples
set(view.fovtype, HFOV);
set(view.fov, 90);
...
set(view.fovtype, VFOV);
remapfovtype(view.fov, HFOV, VFOV);
screentodepth(sx,sy, hit)
raycastdepth(x,y,z, dx,dy,dz, hit)
Javascript API:
hit = krpano.actions.screentodepth(sx,sy)
hit = krpano.actions.raycastdepth(x,y,z, dx,dy,dz)
Get information from the Depthmap / 3D-Model.

Either from a point on the screen or from any point in 3D-space.
Works by finding the hit/intersection-point between a ray and the depthmap / 3D-model surface.

Note - the depthmap.hittest setting need to be enabled!

Parameters:
  • sx / sy (screentodepth)
    • Screen coordinates in pixels from the left top edge.
  • x / y / z (raycastdepth)
  • dx / dy / dz (raycastdepth)
  • hit
    • An object with several properties about the result.
    • When there is no depth/3d-information at the requested point, it will be null.
    • Properties:
      • d - distance/depth from the screen to the point.
      • x,y,z - the worldspace x,y,z 3D coordinates of the hit-point (in cm).
      • nx,ny,nz - the normal vector of the hit-surface.
      • rx,ry,rz - rotation angles in degree that match the hit-surface (in "zxy" rotation-order - note - that's not the default one for hotspots).
    • Note - the performance and accuracy of the results depends on the the depthmap.hittestmode settings.
    • Javascript usage notes: when called by Javascript the hit object will be returned directly, no parameter for a krpano variable need to be passed.
Examples
Get the distance to the next wall/surface in front of the viewer:
raycastdepth(view.tx, view.ty, view.tz, view.dir.x, view.dir.y, view.dir.z, hit);
if(hit,
  trace('distance to wall:', hit.d, 'cm');
);
Place a hotspot on the surface of a Depthmap / 3D-Model:
screentodepth(mouse.x, mouse.y, hit);
if(hit,
  copy(hs.tx, hit.x);
  copy(hs.ty, hit.y);
  copy(hs.tz, hit.z);
  copy(hs.rx, hit.rx);
  copy(hs.ry, hit.ry);
  copy(hs.rz, hit.rz);
);
showtext(text, textstyle)
Deprecated - use the new and extended showtext.xml plugin instead!
updateobject()
Updates / rebuilds the internal 3D model of the pano object.

This must be called when dynamically changing of the image.hfov, image.vfov or image.voffset settings.
Examples
set(image.hfov,1);
updateobject();
invalidatescreen()
  • Request a redraw.
  • Can be used when changing settings that don't cause a redraw by its own.
addlayer(name, varname)
addplugin(name, varname)
addhotspot(name, varname, renderer)
Javascript API:
layer = krpano.addlayer(name)
plugin = krpano.addplugin(name)
hotspot = krpano.addhotspot(name, renderer)
Dynamically create and add a new layer, plugin or hotspot element.

Parameters:
  • name
    • Name of the new layer/plugin or hotspot element.
    • When no name is given or auto is used as name, then an automatic-generated name will be used.
    • When there is already an element with the given name, no new element will be created, instead the current one will be returned.
  • varname (optionally)
    • Create a variable with the given name linked to the new added element.
  • renderer (optionally)
    • Set the hotspot renderer setting directly on creation.
    • This can avoid the temporary unnecessary and creation of a HTML element (for CSS3D-hotspots) when actually a WebGL-hotspot is desired.
Javascript Return:
  • The new added element.
Notes:
  • Layers and plugins are the same, just different names.
Examples
addlayer(button);
set(layer[button].url,button.jpg);
set(layer[button].align,bottom);
set(layer[button].x,10);
set(layer[button].y,20);
set(layer[button].onhover,showtext('hovering the new button'));
set(layer[button].onclick, removelayer(button) );
addhotspot(newspot);
set(hotspot[newspot].url,spot.png);
set(hotspot[newspot].ath,150);
set(hotspot[newspot].atv,30);
set(hotspot[newspot].scale,0.7);
set(hotspot[newspot].zoom,true);
set(hotspot[newspot].onclick, removehotspot(newspot) );
addhotspot(polyspot);
set(hotspot[polyspot].fillalpha, 0.25);
set(hotspot[polyspot].borderalpha, 0.50);
set(hotspot[polyspot].onclick, removehotspot(polyspot) );
set(hotspot[polyspot].point[0].ath,-10);
set(hotspot[polyspot].point[0].atv,-10);
set(hotspot[polyspot].point[1].ath,-10);
set(hotspot[polyspot].point[1].atv,+10);
set(hotspot[polyspot].point[2].ath,+10);
set(hotspot[polyspot].point[2].atv,+10);
set(hotspot[polyspot].point[3].ath,+10);
set(hotspot[polyspot].point[3].atv,-10);
addlayer('background_layer', bg);
bg.loadstyle('design1');
set(bg.bgcolor, 0x777777);
removelayer(name, removechildren)
removeplugin(name, removechildren)
removehotspot(name)
Javascript API:
krpano.removelayer(name, removechildren)
krpano.removeplugin(name, removechildren)
krpano.removehotspot(name)
Dynamically remove and destroy a layer, plugin or hotspot element.

Parameters:
  • name
    • Name of the layer/plugin or hotspot element that should be removed.
  • removechildren (optionally)
    • When set to true, all children elements will be removed too.

Alternatively also the remove() function of the element itself can be used, e.g.:
layer[name].remove()
hotspot[name].remove()
js( JavascriptFunction(parameters) )
Call a Javascript function.

The parameters will be parsed by krpano before calling the Javascript function. Use get(var) or calc(expression) in the parameters to access krpano variables.
Examples
Code in the .html or .js file:
function test(p1, p2, p3)
{
  alert(p1 + ": " + p2 + " / " + p3);
}
Code in the xml file:
js( test('Lookat', get(view.hlookat), get(view.vlookat)) );
jscall( ...any Javascript code... )
Directly call any kind of Javascript code.

Inside the Javascript code these objects are available for a two-way communication:
  • krpano
    • The krpano Interface object (allows additionally also direct Javascript access to all whole krpano structure and all functions there).
  • caller - the object of the <layer>, <plugin> or <hotspot> element that has called that action.
Examples
Change the style of a html element:
jscall('document.getElementById("test").style.display="none";');
Use the calc() action to build the Javascript call and pass krpano variables:
jscall(calc('console.log("krpano version: ' + version + '")'));
Go back to the previous webpage:
jscall('history.back()');
jsget(variable, ...Javascript code... )
Get the value of a Javascript variable or the return value of a Javascript function.

Inside the Javascript code these objects are available for a two-way communication:
  • krpano
    • The krpano Interface object (allows additionally also direct Javascript access to all whole krpano structure and all functions there).
  • caller - the object of the <layer>, <plugin> or <hotspot> element that has called that action.

Parameters:
  • variable
    • The name of krpano variable where the returned value will be stored.
    • The variable will be created when it doesn't exist.
Examples
Get the address of the current webpage:
jsget(ret, 'location.href');
trace('location=', get(ret));
Let the user enter something:
jsget(passwort, 'prompt("Enter Password")');
if(password == 'hidden', ...);
Get the current date in the format YYYY-MM-DD:
jsget(date, 'new Date().toISOString().slice(0,10);');
trace('date=', get(date));
event="js: ...any Javascript code..."
Directly call any kind of Javascript code from events (or code defined in variables).
When a called action code string starts with js: it will be considered to be Javascript code.

Inside the Javascript code these objects are available for a two-way communication:
  • krpano
    • The krpano Interface object (allows additionally also direct Javascript access to all whole krpano structure and all functions there).
  • caller - the object of the <layer>, <plugin> or <hotspot> element that has called that action.
Examples
onclick="js:alert(caller.path);"
onclick="js:krpano.actions.lookto(0,0);"
addcssstyles(styles)
Dynamically add CSS styles.

Parameter:
  • styles
    • A string with CSS styles/classes.
Javascript API:
krpano.events.addListener(eventname, callback, once)
krpano.events.removeListener(eventname, callback)
Add or remove Javascript listeners / callback-functions for any krpano events.

Parameters:
  • eventname
    • The name of any krpano event, e.g. "onclick" for the onclick event.
  • callback
    • The Javascript function to be called on the given event.
    • Some events, like mouse or keyboard events, will provide an Event object as parameter.
  • once (optionally)
    • When set to "once", call the callback function only once and then automatically remove the event listener.
showlog(state, position)
Show or hide the trace output log.

Parameters:
  • state (optionally)
    • true - Show the log window (default).
    • false - Hide the log window.
    • toggle - Show or hide the log window depending on the current state.
  • position (optionally)
    • top - Show the log at the top of the viewer window.
    • bottom - Show the log at the bottom of the viewer window (default).
debugvar(varname)
Show / trace details (value and type) about a variable in the output log.
When the variable is an object, then also all object properties will be shown.

Notes:
  • Debug messages will be only shown when the debugmode setting is enabled.
  • Consider enabling the consolelog setting in the html file to see these messages also in the browser console.
  • Doing many traces is affecting the rendering performance! Especially avoid constantly tracing messages every frame!
debug(...)
trace(...)
warning(...)
error(...)
Traces texts or the content of variables to the output log.

  • debug() will trace DEBUG: messages.
    These messages will be only shown when the debugmode setting is enabled.
  • trace() will trace INFO: messages.
  • warning() will trace WARNING: messages.
  • error() will trace ERROR: messages and additionally also open the log (only when showerrors is enabled).

Parameters:
  • ...
    • Any text or variable.
    • When passing a variable, then that variable will be automatically resolved to its value.
  • Special parameter values:
    • [HTML] ...
      When the text starts with [HTML] then the following text can be HTML-code, but where the < and > characters need to be replaced with [ and ].
    • [OW] ...
      The line will be 'overwriteable' - that means the next trace will overwrite / replace that line.
    • [CLEARLOG]
      Clears the log.
    • [MAXLINES=NN]
      Defines the maximum lines to log, the default is 200.

Notes:
  • Debug messages will be only shown when the debugmode setting is enabled.
  • Consider enabling the consolelog setting in the html file to see these messages also in the browser console.
  • Doing many traces is affecting the rendering performance! Especially avoid constantly tracing messages every frame!
Examples
trace('view.maxpixelzoom=', view.maxpixelzoom);
<events onkeydown="trace('keycode=',keycode);" />
onresize="trace('size=',stagewidth,'x',stageheight);"
onclick="trace('mouse clicked at ', mouse.x, ' / ', mouse.y);"
trace('xyz=',xyz,' get(xyz)=',get(xyz));
fatalerror(errormessage)
Show an error message and stop the user interaction.

Parameters:
  • errormessage
    • The error message to show.