News Examples Documentation Download Buy Forum Contact

Documentation

Plugins

XML Extensions

Tools


Third Party Software
for krpano

krpano XML Reference Version 1.21

krpano uses simple xml text files for storing the settings for the krpano viewer. These files can be written or edited with any usual texteditor, but when writing the xml code, it is important that the xml-syntax-rules will be respected! These basic rules are the same for all xml files and not specific to krpano.

For more information about the basic xml syntax, please have a look here:
Basic XML Syntax Rules

About this documentation

This documentation is about the krpano xml structure, about all krpano xml elements, attributes and values and their mapping to their dynamic krpano variable names.

Documentation topics:
For the dynamic usage of the krpano variables and actions have a look at the:
krpano Actions / Scripting Reference

The krpano XML structure

Here a structured listing of all krpano xml elements: (click on an element to get more information)
<krpano>
    <include>
    <image>
      <preview>
      <cube>
      <cubestrip>
      <sphere>
      <cylinder>
      <flat>
      <fisheye>
      <depthmap>
    </image>
    <view>
    <area>
    <display>
    <control>
    <cursors>
    <autorotate>
    <plugin>
    <layer>
      <layer>
      ...
    </layer>
    <hotspot>
    <style>
    <events>
    <action>
    <contextmenu>
    <network>
    <memory>
    <security>
    <data>
    <cssstyles>
    <scene>
    <set>
    <if>
    <debug>
</krpano>
  • The root element of the xml file need to be the <krpano> element. All other elements must be placed inside this element.
  • All xml elements and attributes in the krpano xml are optionally and can be defined a several times and in any order. When the same element will be defined again two or more times, then the later/following declarations will overwrite the previous ones.
  • It's also possible to define additional <krpano> elements inside the root <krpano> element itself for declaring additional settings at the krpano scope.
  • The xml itself is just a transport-format - that means it will be only used to transport the data for the krpano viewer. When the xml will parsed, then the xml elements will be transformed/mapped into the krpano internal data structures. That means after parsing there is internally no xml anymore.

Special krpano XML elements and attributes

Some xml elements and attributes are handled in a special way in krpano. This special handling happens already during the xml loading and parsing.
<xmlelement name="..." ... />
The name attribute ⇒ defining Array elements:

When a xml element has a name attribute, then this element will be interpreted as element / item of an Array. The name of the Array is the name of the xml element itself. When no Array with that name already exists, it will be automatically created.
When the element / item already exists, then the attributes that were defined at the xml element will be still set and overwrite already existing values.

This means there can be several declarations of a xml element, but each element would need to have its own unique name for identification.

When using the value auto automatically an unique name will be generated.

Important notes about the name attribute:
  • Each name needs to begin with an alphabetic character!
  • That means using a number as name is not allowed!
  • When a name still begins with a numeric character, then the name will be interpreted as array index. This is okay for dynamic index-based access inside actions but not for defining the elements!
  • All names will get converted automatically to lower case to allow direct case insensitive access!
<xmlelement url="..." ... />
The url attribute:

When a xml attribute is named 'url' or begins or ends with 'url' (e.g. like 'videourl'), the value of the attribute will be interpreted as url / path to a resource.

When a relative path will be used as url value, then the path will be automatically adjusted to be relative to the xml file in which the url attribute was defined. That means relative paths in a xml will be always relative to the xml itself.
But note - when setting / changing the url attribute dynamically, then there is no automatic relation to the xml anymore!

To make the path relative to some special predefined paths, it's possible to use some of these placeholders in the url path:
  • %VIEWER% or %ROOT% or %SWFPATH%
    • Path to the folder of the main krpano viewer Javascript file.
    • Note - a custom viewer path could set by the basepath embedding setting.
  • %HTMLPATH%
    • Path to the folder of the html file.
  • %FIRSTXML%
    • Path to the folder of 'first' loaded xml file.
  • %CURRENTXML%
    • Path to the folder of 'current' loaded xml file.
  • %$VARIABLE%
    • Use the value of the given 'VARIABLE'.
    • This can be any krpano variable, but it need be defined before the xml or scene will be loaded, e.g. already in the html file during embedding (via initvars) or before loadpano(), loadscene() calls.

Beside of using file-paths, it's also possible to use Data-URLs as url value. Base64- and Plain-encoding are supported. That can be used to inline/embed files directly into the xml.
<xmlelement ... devices="...">
    <childrenelement ... />
    ...
</xmlelement>
<xmlelement attribute.devicecheck="..."
            ...
            />
Device Filters - define xml elements or xml attributes only for certain devices.

There are two possibilities:
  • Filter whole xml elements, including all children elements by adding a devices="..." attribute.
  • Define a xml attribute only for a certain device by adding a dot . character at the end of the attribute name and then the devices where it should be defined.

Syntax:
  • The value for a device check can be one or more of the device setting variables.
  • Several devices can be combined by using these logical operators:
    • .and. to check if all given device settings are matching.
    • .or. to check if one of the given devices settings is matching.
    • A no- prefix before a device name to check if the given setting is not set.
    • Resolving order: The AND checks will be resolved before the OR checks.

Notes:
  • For more complex checks the if attribute can be used as alternative.
  • These xml filters are for static xml code. Non-matching xml elements or xml attributes will get skipped during the xml parsing. For dynamic checking for a device use the device object and if() or calc() actions.

Examples
<layer name="layout" ... devices="normal"> 
    ... a layout for desktop and tablet devices ...
</layer>

<layer name="layout" ... devices="mobile">
    ... a layout for mobile devices ...
</layer>
<include url="iphone_fullscreen_swipe.xml" devices="iphone" />
<layer ... url="image.jpg" 
    scale.desktop="1.0"
    scale.tablet="0.75"
    scale.mobile="0.5"
    />
<layer name="enter_vr_button" ... devices="mobilevr" />
<layer name="enter_fullscreen_button" ...
    visible.fullscreensupport="true"
    visible.no-fullscreensupport="false"
    />
videourl.desktop="video-high-profile.mp4"
videourl.mobile.or.tablet="video-baseline-profile.mp4"
<xmlelement ... if="condition">
    <childrenelement ... />
    ...
</xmlelement>
The if attribute:

When a xml element has an if attribute, then the xml element and all its children elements will be only used when the given condition will be true.

When using variables in the if condition, then these variables need to be defined before (=above) the current xml element. Additionally there is one special case here - when using xml if checks on <include> elements, then the variables used in the if check, need to be defined before the current xml gets loaded. This could be done in the html file during embedding by using the initvars setting or in the xml before doing a loadpano() call.

Note - for conditionally parsing multiple xml elements, the <if> element can be used.

Examples
In the html file:
embedpano({..., initvars:{design:"flat"}, ...});
In the xml file:
<include url="design_default.xml" if="design == default" />
<include url="design_flat.xml"    if="design == flat"    />
<xmlelement attribute.typedef="..."
            ...
            />
Type definitions for attributes

When defining variables in the xml for 'non-predefined' object-structures like layers or hotspots, the values of these variables are always Strings by default (for 'predefined' objects the predefined variable-type will be used).

Normally the variable-type is not relevant because inside the actions type conversions will be done automatically when required, but sometimes it can be still helpful to be able to define the exact type of a variable.

And that's possible by adding a dot . character at the end of an attribute name and then there type for this variable.

Note - This is for static xml code - for defining variables with types dynamically at runtime the def() and set() actions can be used.

Available types:
  • bool
    • A boolean value, true or false.
  • number
    • A 64bit double precision floating point Number.
  • integer or int
    • An 32bit Integer value.
  • uint
    • An 32bit Unsigned Integer value.
    • Can be usefull for ARGB color values like 0xFFFFFFFF.
  • string (the default)
    • A text String.
<style name="stylename" attributes ... />
<xmlelement ... style="stylename" ... />
<style> elements and the style attributes:

The <style> element is a collection / storage element for any kind of attributes.

Every other xml element that has a name attribute can also have a style attribute. When the xml element will be first created, all attributes defined at the <style> element will be copied to the element itself. This will be done before the attributes that are defined at xml element itself will be applied.

That means it's possible to predefine some settings in the <style> element and then overwrite them later with the attributes defined directly at the element.

Several styles can be loaded at once by combining the style names by | characters.

For dynamically getting the attributes from a style at runtime, these actions can be used:
Examples
<style name="spotstyle" url="spotimage.png" />
<hotspot name="spot1" style="spotstyle" ... />
<hotspot name="spot2" style="spotstyle" ... />
<xmlelement attribute="get:variable" ... />
<xmlelement attribute="calc:expression" ... />
When the value of a xml attribute starts with get: or calc::

In this case the value for the xml attribute will get from an other variable or calculated using an expression.

The variables used in the get: or calc: need to be defined before (=above) the current xml element. Additionally there is one special case here - when using this on <include> elements, then the variables used there, need to be defined before the current xml gets loaded. This could be done in the html file during embedding by using the initvars setting or in the xml before doing a loadpano() call.

Examples
<settings width="100" height="50" />
...
<layer ...
       width="get:settings.width"
       height="calc:settings.height * 2"
       />
<include url="..." />
The <include> elements - include other xml files:

<include url="path/name.xml" />

The <include> elements will be resolved as first step during the xml loading. The requested include url file will be loaded and the content of the loaded xml will replace the <include> element in the current xml.

After all <include> elements are loaded and resolved, the viewer will start to parse the loaded xml data and map the informations from xml to the dynamic runtime data structures and objects.

For including xml content dynamically the includexml() and includexmlstring() actions can be used.

Examples
<include url="settings.xml" />
<include url="skin/skin.xml" />
<include url="%VIEWER%/global.xml" />


XML elements / attributes / values / variables

Here detail documentations about the krpano xml elements:
<krpano>
This is the root element of a krpano xml file.

All other XML elements must be defined inside it:
<krpano>
    ...
</krpano>

All variables that can be set by using the <krpano> element:
<krpano version="1.21.2"
        onstart=""
        basedir="%FIRSTXML%"
        bgcolor=""
        idletime="0.5"
        strict="false"
        usestrictjs="true"
        showerrors="true"
        logkey="true"
        debugmode="false"
        debugkeys="false"
        debugjsactions="false"
        debugjsplugins="false"
        deprecatedwarnings="true"
    >
    ...
</krpano>

Attribute nameVariable nameTypeDefault value
version xmlversion String "1.21.2"
Information about the krpano version that was used when creating the xml file.

It allows handling compatibility-related changes between different versions. Depending on the set version, the behavior of functions or the default values of settings might differ.
Variable nameType
onstart Action Event
The onstart event will be called directly at the start after the xml loading and parsing.
Variable nameTypeDefault value
basedir String "%FIRSTXML%"
The basedir setting defines the base directory for all following loadpano() action calls.

This can be a relative or an absolute path and it's also possible to use the url placeholders here.

The defaultvalue is %FIRSTXML% and that means that all relative xml paths of all following loadpano() action calls are relative to the first loaded xml file.
Variable nameTypeDefault value
bgcolor String
The viewer background color. That background color can be only seen before a pano image will be loaded or when using partial panos / flat images that are not covering the full view.
  • When set to a valid color number in hex format (e.g. "0xFFFFFF" for white), a background shape with that color will be rendered behind the pano.
  • When not set or set to an invalid value - no background shape will be used, and it behave like 'transparent' and shows the html page when using the bgcolor="transparent" embedding setting.
Variable nameTypeDefault value
idletime Number 0.5
The time in seconds without any user-interaction before calling the onidle event.
Variable nameTypeDefault value
strict Boolean false
Enable or disable the 'strict mode' of the expression parser.

When enabled variables will no longer 'automatically' resolve to their value inside expressions. This avoids accidentally mix-ups between variables and strings. Additionally some special backward-compatibility workarounds (like when comparing empty %N parameters) will be disabled.

See also here:
Strict / non-strict comparisons
Variable nameTypeDefault value
usestrictjs Boolean true
Use the Javascript Strict Mode.

All Javascript code that will be directly called by krpano (e.g. in Javascript-Actions or by jscall, jsget, js:... or when loading Javascript files by loadjs() will use the Strict Mode when enabled.

This can help finding coding errors like undeclared variables, but therefore works slightly different in some cases and so can cause backward-compatibility problems when enabled.

If necessary the Javascript Strict Mode can be disabled globally here or individually per action[].usestrictjs.
Variable nameTypeDefault value
showerrors Boolean true
Set if the krpano output/log window should get opened automatically when an error happens to show the error message to the user.

Note - When using the Branding Free License the default value will be false.
Variable nameTypeDefault value
logkey Boolean true
Enable or disable the keyboard key that will show or hide the krpano output/log window.

The location on the keyboard - always the top-left most key below the ESC-key (independent of the keyboard-language or keyboard-mapping):

On Touch-devices there are no keys, therefore there the log-window can be opened by touching at the right-bottom corner of the viewer-window and swiping-up there.

Note - When using the Branding Free License the default value will be false.
Variable nameTypeDefault value
debugmode Boolean false
Enable or disable the special debug-mode.

When enabled:
  • Debug messages sent by plugins or the debug() and debugvar() actions will be shown, otherwise they will be ignored/skipped.
  • The versioninfo field of the contextmenu will be always displayed and can be clicked or touched to open or close the krpano output/log window.
  • Inside the krpano log there will be additional debug-buttons for entering commands, enabling special debug-keyboard-keys, visualizating layer- and hotspots-outlines and showing some hints about the pano image structure/tiles.
Variable nameTypeDefault value
debugkeys Boolean false
Enable or disable the special debug-keyboard-keys. These keys are only active when the debugmode setting is enabled and when the krpano log is currently opened.

The debug-keys:
  • A - Enable or disable the autorotate mode.
  • C - Change the controlmode (moveto/drag).
  • S - Enable or disable stereo rendering.
  • G - Enable or disable anaglyph rendering.
  • U - Unlock any fov and viewing-range limits.
  • P - Show or hide outlines or wireframes of the pano-image.
  • H - Show or hide outlines of hotspots elements.
  • L - Show or hide outlines of layer elements.
  • SHIFT+logkey - Open an input-field for entering krpano actions.
Variable nameTypeDefault value
debugjsactions Boolean false
Allow browser-debugging of type="Javascript" <action> code.
With that enabled, Javascript errors will not get captured by krpano and will be normally processed by the browser. This can help during development, e.g. for locating an error, but for normal usage this setting should be kept disabled!
Variable nameTypeDefault value
debugjsplugins Boolean false
Allow browser-debugging of Javascript-krpano-plugins.
With that enabled, Javascript errors will not get captured by krpano and will be normally processed by the browser. This can help during development, e.g. for locating an error, but for normal usage this setting should be kept disabled!
Variable nameTypeDefault value
deprecatedwarnings Boolean true
Show deprecated warnings when using actions that are outdated and might be not supported anymore in future versions.
<preview>
<image>
    <preview>
</image>
Define a low-resolution 'preview' image that will be displayed while loading the full-resolution image. This preview image should should be small (in filesize and image dimensions) to allow fast loading!

<preview type=""
         url="previewpano.jpg"
         striporder="LFRBUD"
         />

Note - the <preview> element can be defined inside the <image> element or outside it.
Variable nameTypeDefault value
preview.type String
Set the panoramic type of the preview image.

Possible settings:
  • empty, not set, the default - when not set, the type of the preview image will be detected automatically by its image-size and side-aspect (e.g. 2:1 = sphere, 1:6 = cubestrip, ...)
  • SPHERE - spherical pano image
  • CYLINDER - cylindrical pano image
  • CUBESTRIP - a 1x6, 6x1, 3x2 or 2x3 cubestrip image
  • grid(...) - generate a grid preview image
    grid(type,xsteps,ysteps,res,linecol,bgcol,pntcol)
    • Parameters:
      • type = SPHERE or CUBE (must be defined)
    • Optional parameters:
      • xsteps = horizontal distance between lines in pixels, default=64
      • ysteps = vertical distance between lines in pixels, default=64
      • res = resolution of gridimage, default=512
      • linecol = color of lines in hex-format (default=0x666666)
      • bgcol = background color (default=0x222222)
      • pntcol = color of points (default=same as linecol)

When the main <image> is a partial pano, then the preview pano will use automatically the same hfov / vfov / voffset settings.
Variable nameTypeDefault value
preview.url String
The url / path to the preview image.

This can be a spherical, cylindrical or a cubestrip (1x6, 6x1, 3x2 or 2x3) image.

When the main <image> is a partial pano, then the preview pano will use automatically the same hfov / vfov / voffset settings.
Variable nameTypeDefault value
preview.striporder String "LFRBUD"
Defines the order of the images in the cubestrip image.
Examples
Use an preview image:
<preview url="preview.jpg" />
Use a synthetic grid image as preview pano:
<preview type="grid(CUBE,16,16,512,0xCCCCCC,0xFFFFFF,0x999999);" />
<image>
With the <image> element the pano image will be defined.

Supported images types / panoramic formats by the viewer:
  • Cube
    • Six separate cube-face images.
    • Supports: Single-Resolution, Multi-Resolution, Stereo-Images, Depthmaps.
  • Cubestrip
    • One 'image-strip' with the six cube-faces images.
    • Supported arrangements: 1x6, 6x1, 2x3, 3x2.
    • The order of the cube-faces can be defined by the striporder setting.
    • Supports: Single-Resolution.
  • Sphere
    • A spherical / equirectangular panoramic image.
    • Partial panos are possible by using custom hfov, vfov and voffset settings.
    • Supports: Single-Resolution, Multi-Resolution, Stereo-Images, Video-Input, Depthmaps.
  • Cylinder
    • A cylindrical panorama image.
    • Partial panos are possible by using custom hfov, vfov and voffset settings.
    • Supports: Single-Resolution, Multi-Resolution, Stereo-Images, Video-Input.
  • Flat
    • A flat / rectilinear image.
    • With any field-of-view coverage from 1.0 (default) to ~170 degree.
    • Supports: Single-Resolution, Multi-Resolution, Stereo-Images, Video-Input.
  • Fisheye
    • An image or video shoot with fisheye lens.
    • Supports: Single-Resolution, Stereo-Images, Video-Input.

XML Syntaxes for the image types:

Cube

Single-Resolution Multi-Resolution (Short Syntax) Multi-Resolution (Long Syntax) Stereo-Images
Cube
<image>
    <cube url="pano_%s.jpg" />
</image>
Cube - Multi-Resolution (Short Syntax)
<image>
    <cube url="pano_%s_%l_%v_%h.jpg"
          multires="TILESIZE,LEVELSIZE1,LEVELSIZE2,..."
          />
</image>
  • Multi-resolution and tiled cube-face images.
  • The multires setting defines the tile-size and the sizes of all available resolution levels.
  • The 'short syntax' will be internally expanded into the 'long' one. That means for dynamically accessing the size information the 'long syntax' attributes can be used.
  • %s is the placeholder for the cube-side label.
  • %l is the placeholder for the current resolution level.
  • %h and %v are placeholders for the horizontal and vertical tile indicies.
Cube - Multi-Resolution Cube (Long Syntax)
<image tilesize="...">
    <level tiledimagewidth="..." tiledimageheight="...">
        <cube url="..._%s_%v_%h.jpg" />
    </level>
    <level ...>
        <cube ... />
    </level>
    ...
</image>
  • Multi-resolution and tiled cube-face images.
  • For each resolution a <level> element with the sizes for that level need to be defined.
  • %s is a placeholder for the cube-side label.
  • %h and %v are placeholders for the horizontal and vertical tile indicies.
Cube with Stereo-Images
<image stereo="true" stereolabels="1|2">
    <cube url="pano_%t_%s.jpg" />
</image>

Cubestrip

Default With custom order
Cubestrip
<image>
    <cubestrip url="pano.jpg" />
</image>
  • One single cube-strip image.
Cubestrip with custom order
<image prealign="0|0|0">
    <cubestrip url="pano.jpg" striporder="LFRBUD" />
</image>
  • For a custom cube-face image arrangement the striporder and prealign settings can be used. With both settings all possible arrangements are supported.

Sphere / Cylinder / Flat

Single-Res Partial-Pano Multi-Res (Short Syntax) Multi-Res (Long Syntax) Stereo-Images Video-Input
SphereCylinderFlat-Image
<image>
    <sphere url="pano.jpg" />
    <cylinder url="pano.jpg" />
    <flat url="pano.jpg" />
</image>
  • One spherical / equirectangular image.
  • Without hfov setting, a horizontal field of view of 360 degree is used.
  • One cylindrical image.
  • Without hfov setting, a horizontal field of view of 360 degree is used.
  • One flat / rectilinear image.
  • Without hfov setting, a horizontal field of view of 1.0 degree is used. This is used for a flat and undistorted viewing of the image.
  • Without vfov setting, the vertical field of view will be calculated automatically based on the image-size aspect-ratio (e.g. 2:1 for a 360:180 pano).
  • With the voffset setting, it's additionally possible to shift the image up or down. E.g. to correct the image center/horizon.
  • With the voffset setting, it's additionally possible to shift the image up or down. E.g. to correct the image center/horizon.
SphereCylinderFlat-Image - Partial-Pano
<image hfov="120" vfov="40" voffset="0">
    <sphere url="pano.jpg" />
    <cylinder url="pano.jpg" />
    <flat url="pano.jpg" />
</image>
  • Partial-pano support - works for Single- and Multi-Resolution, Stereo and Video.
  • Example syntax for a 120x40 degree partial pano.
SphereCylinderFlat-Image - Multi-Resolution (Short Syntax)
<image>
    <sphere url="pano_%l_%v_%h.jpg"
            multires="TILESIZE,LEVELSIZE1,LEVELSIZE2,..."
            />
    <cylinder url="pano_%l_%v_%h.jpg"
              multires="TILESIZE,LEVELSIZE1,LEVELSIZE2,..."
              />
    <flat url="pano_%l_%v_%h.jpg"
          multires="TILESIZE,LEVELSIZE1,LEVELSIZE2,..."
          />
</image>
  • Multi-resolution and tiled spherecylinderflat image.
  • The 'short syntax' will be internally expanded into the 'long' one. That means for dynamically accessing the size information the 'long syntax' attributes can be used.
  • %l is a placeholder for the current resolution level.
  • %h and %v are placeholders for the horizontal and vertical tile indicies.
SphereCylinderFlat-Image - Multi-Resolution (Long Syntax)
<image tilesize="...">
    <level tiledimagewidth="..." tiledimageheight="...">
        <sphere url="..._%s_%v_%h.jpg" />
        <cylinder url="..._%s_%v_%h.jpg" />
        <flat url="..._%s_%v_%h.jpg" />
    </level>
    <level ...>
        <sphere ... />
        <cylinder ... />
        <flat ... />
    </level>
    ...
</image>
  • Multi-resolution and tiled spherecylinderflat image.
  • For each resolution level a <level> element need to be defined.
  • %s is a placeholder for the cube-side label.
  • %h and %v are placeholders for the horizontal and vertical tile indicies.
SphereCylinderFlat-Image with Stereo-Images
For one file that contains both stereo images:
<image stereo="true" stereoformat="TB">
    <sphere url="pano.jpg" />
    <cylinder url="pano.jpg" />
    <flat url="pano.jpg" />
</image>

For separated left/right image files:
<image stereo="true" stereolabels="1|2">
    <sphere url="pano_%t.jpg" />
    <cylinder url="pano_%t.jpg" />
    <flat url="pano_%t.jpg" />
</image>

For Multi-Resolution:
<image stereo="true" stereolabels="1|2">
    <sphere url="pano_%t_%l_%v_%h.jpg"
            multires="TILESIZE,LEVELSIZE1,LEVELSIZE2,..."
            />
    <cylinder url="pano_%t_%l_%v_%h.jpg"
              multires="TILESIZE,LEVELSIZE1,LEVELSIZE2,..."
              />
    <flat url="pano_%t_%l_%v_%h.jpg"
          multires="TILESIZE,LEVELSIZE1,LEVELSIZE2,..."
          />
</image>
  • Stereo support - works for Single- and Multi-Resolution and Video
  • For one single stereo file the stereoformat setting need to be used to define the arrangement of the left or right images (Top-Bottom or Side-by-Side).
  • For multiple-files or Multi-Resolution the %t placeholder is used for referring to the stereo-side and defined by the stereolabels setting.
SphereCylinderFlat-Image with Video-Input
<image>
    <sphere url="plugin:video" />
    <cylinder url="plugin:video" />
    <flat url="plugin:video" />
</image>

<plugin name="video"
        url="videoplayer.js"
        videourl="video.mp4|video.webm"
        />
  • Use a video as panoramic-image.
  • The url value 'plugin:' needs to refer to a videoplayer plugin with the given name.

Fisheye

Normal Stereo-Images Video-Input
Fisheye Image
<image>
    <fisheye url="fisheye.jpg"
             fov="180.0"
             align="yaw|pitch|roll"
             crop="left|right|top|bottom"
             lenscp="a|b|c|d|e"
             />
</image>
  • Fisheye image support.
  • Directly use fisheye photos or videos.
  • For correctly straighten and aligning the fisheye image, it's necessary to know some parameters about it. A good tool for getting these parameters is PTGUI.
Fisheye Image with Stereo-Images
<image stereo="true" stereoformat="TB">
    <fisheye url="fisheye.jpg"
             fov="180.0"
             align="yaw|pitch|roll"
             crop="left|right|top|bottom"
             lenscp="a|b|c|d|e"
             />
</image>
  • Stereo support - works for images and videos.
  • The stereoformat setting need to be used to define the arrangement of the left or right images (Top-Bottom or Side-by-Side).
Fisheye Image with Video-Input
<image>
    <fisheye url="plugin:video" />
</image>

<plugin name="video"
        url="videoplayer.js"
        videourl="video.mp4|video.webm"
        />
  • Use a video as fisheye-image.
  • The url value 'plugin:' needs to refer to a videoplayer plugin with the given name.


Attribute details:
Variable nameTypeDefault value
image.type String
The type of the panorama image.

Available values (always in lower-case):
  • cube
    A cubical panoramic image - six images, one image per cube side.
  • cubestrip
    A cubical panoramic image as 'imagestrip' in one single image. Supported cubestrip formats are 6x1, 1x6, 3x2 or 2x3. The order of the cube-faces inside the image can be defined by the striporder setting.
  • sphere
    A spherical / equirectangular panoramic image.
    Partial panos are possible by using custom hfov, vfov and voffset settings.
  • cylinder
    A cylindrical panorama image.
    Partial panos are possible by using custom hfov, vfov and voffset settings.
  • flat
    A flat / rectilinear image.
    The default hfov is 1.0, which results in a non-distorted viewing of the image.
  • fisheye
    A fisheye-lens distorted image (details).
Variable nameTypeDefault value
image.hfov Number
Defines the horizontal field of view (hfov) of the pano image in degrees. The default value is 360 for all pano types except for flat panos, for flat panos the default is 1.0.

Note - when dynamically changing this setting (only possible for sphere, cylinder and flat panos), the updateobject() action need to be called to update the pano image.
Variable nameTypeDefault value
image.vfov Number
Defines the vertical field of view (vfov) of the pano image in degrees.
By default (when no value was set), this value will be calculated automatically by using the hfov, the type of the pano and the side aspect of the pano image.

Note - when dynamically changing this setting (only possible for sphere, cylinder and flat panos), the updateobject() action need to be called to update the pano image.
Variable nameTypeDefault value
image.voffset Number 0.0
Defines the vertical offset of the pano image in degrees.
By default the pano image will be vertically centered. This means the viewing range will be from -hfov/2 to +hfov/2 and from -vfov/2 to +vfov/2.
Now when using a partial pano image where the horizon is not in the middle of image (not at 0 degree), then this image will be displayed distorted.
The voffset can be used to shift the image up or down to center it correctly.

How to get the correct voffset value:
When the vertical from-to range of the pano image is known, then it can be calculated:
voffset = (vfov_min + vfov_max) / 2

e.g. for a 240x90 pano with the field of view from -70° (up) to +20° (down):
vfov_min = -70
vfov_max = +20
voffset = (-70 + 20) / 2 = -25
or see the result for a 360x180 pano with -90 to +90:
vfov_min = -90
vfov_max = +90
voffset = (-90 + 90) / 2 = 0.0

When the vertical range is unknown - just try out some values (negative and positive ones in the range from -90 to +90). Additionally it can be helpful here to set
<view limitview="off" />
in the xml to allow viewing the whole partial image without viewing limitations.

Note - when dynamically changing this setting (only possible for sphere, cylinder and flat panos), the updateobject() action need to be called to update the pano image.
Variable nameTypeDefault value
image.crop String
Crop / cut out a rectangular area of the source image or video.
Can be only used only with single images or videos, no tiled or multires images.

Syntax:
crop="x-position|y-position|width|height"
The values will be relative ones in the range 0.0 to 1.0.
Examples: to use the full image: 0.0|0.0|1.0|1.0, to use only the right half of the image: 0.5|0.0|0.5|1.0.

Note - using crop will not affect the automatic fov calculation, so the fov ranges might need to set manually.
Variable nameTypeDefault value
image.prealign String
With the prealign setting the pano image itself can be aligned / rotated.
This can be used to correct miss-aligned pano images.

The syntax:
prealign="X|Y|Z"
where X, Y, Z defines the rotation about these axis in degrees.

The prealign setting rotates only to the pano-image itself, but by using hotspot[name].prealign=true it would be possible to rotate certain hotspots as well.
Variable nameTypeDefault value
image.cube.multires
image.sphere.multires
image.cylinder.multires
image.flat.multires
String
String
String
String
Define the tile- and level-sizes (short syntax).

Syntax:
multires="TILESIZE,LEVELSIZE1,LEVELSIZE2,LEVELSIZE3,..."
  • TILESIZE
    • The first value in the multires settings.
    • Defines the default tilesize.
  • LEVELSIZE1, LEVELSIZE2, ...
    • Defines the size of a resolution level.
    • For cube images only one size is necessary:
      LEVELSIZE=CUBESIZE
      Optionally also with a custom tile-size for that level:
      LEVELSIZE=CUBESIZExTILESIZE
    • For sphere, cylinder and flat image a width- and height-size is necessary:
      LEVELSIZE=WIDTHxHEIGHT
      Optionally also with a custom tile-size for that level:
      LEVELSIZE=WIDTHxHEIGHTxTILESIZE
Example:
multires="512,2048x1024,4096x2048,8192x4096,16384x8192"
Variable nameTypeDefault value
image.multiresthreshold Number 0.025
The multiresthreshold value controls, depending on the fov/zoom, when to switch from one multi-resolution level to the next one. Suitable values are from -1.0 to +1.0.
Variable nameTypeDefault value
image.baseindex int 1
The index base (numbering start) for the tile- and level-indicies.
Used for generating the tile-filenames based on the placeholder.
Variable nameTypeDefault value
image.tilesize int
Define the tile-size for multires images (long syntax).
Variable nameTypeDefault value
image.tileoverlap int 0
Optionally for using custom tiles that have a tile-overlap-border around the tile-image.
Only supported for cubical images at the moment.
Variable nameTypeDefault value
image.cubelabels String "l|f|r|b|u|d"
The labels for the %s cube side url placeholder. The default labels are l|f|r|b|u|d (left, front, right, back, up, down).
Variable nameTypeDefault value
image.cubestrip.striporder String "LFRBUD"
Defines the order of the images in the cubestrip image.
Variable nameTypeDefault value
image.cubemapmode
image.cubemapsize
Boolean
int
false
2048
By default krpano uses internally for every tile an separate texture for rendering. When enabling the cubemapmode setting, internally only one large cubemap texture will be used and the tiles be rendered into it. On very draw-call limited systems, this can improve the rendering performance.

When using cubical depthmap panos with rendermode=3dmodel this rendering mode will be used too automatically (an internal requirement).

In this mode the maximum cube-size is limited to the given cubemapsize setting. Larger images will get automatically downscaled to that size.
Variable nameTypeDefault value
image.stereo
image.stereolabels
image.stereoformat
image.stereooffset
Boolean
String
String
Number
false
"1|2"
"TB"
0.0
Enables the usage of stereo images.

When using cube images, then the image urls should contain a %t placeholder. This placeholder will be replaced by the values from the stereolabels setting. For the left image the first value will be used and for the right image the second one.

For spherical or cylindrical images or videos it is possible to use 'frame-packed' stereo images. The stereoformat setting defines the packing order:
  • stereoformat="TB" - Top/Bottom
  • stereoformat="SBS" - Side-By-Side
Example - stereoscopic cube image:
<image stereo="true" stereolabels="1|2">
<cube url="pano_%s_%t.jpg" />
</image>
Example - stereoscopic panoramic video:
<image stereo="true" stereoformat="TB">
<sphere url="plugin:video" />
</image>

The stereooffset setting can be used to adjust/align the stereo images. Technically this rotates the left/right images horizontally apart or together by the given value in degrees.
Can be used to correct wrong-aligned stereo-images or to change the stereo-focal-plane.
Variable nameTypeDefault value
image.sphere.mapping String
Define the mapping / projection of the spherical input image.

Possible settings:
Variable nameTypeDefault value
image.fisheye.fov
image.fisheye.align
image.fisheye.crop
image.fisheye.lenscp
Number
String
String
String
180.0
"y|p|r"
"l|r|t|b"
"a|b|c|d|e"
Fisheye image support (WebGL only).

For correctly straighten and aligning the fisheye image, it's necessary to know some parameters about it. A good tool for getting these parameters is PTGUI.

Fisheye settings:
  • fov="180.0"
    • The field-of-view of the fisheye image (in degrees).
    • Related to the crop size.
    • Source: Can be directly taken from the PTGUI fov image parameter.
  • align="yaw|pitch|roll"
    • The aligment / rotation / leveling of the image (in degrees).
    • Source: Can be directly taken from the PTGUI image parameters.
      (e.g. use vertical-line control points to align / level the image)
  • crop="left|right|top|bottom"
    • The edges of the fisheye fov cropping circle (in pixels).
    • The circle relates to the fov size.
    • Source: Can be directly taken from the PTGUI crop settings.
  • lenscp="a|b|c|d|e"
    • The lens correction parameters.
    • Source: Can be directly taken from the PTGUI lens settings.

PTGUI Screenshots for getting the fisheye parameters:
Variable nameTypeDefault value
image.TYPE.mjpegstream String
MJPEG image streaming over HTTP support (WebGL only).

With this setting it's possible to use HTTP MJPEG video streams as source for the pano image. The supported images types are: <sphere>, <cylinder> and <flat> and <fisheye>.

The image url needs to point directly to to MJPEG stream source.

Possible settings:
  • true or auto - Automatic updating / refreshing:
    • During movement in the viewer pause the image updating for getting a smoother panning and zooming,
    • and when there is no movement and standing still constantly update the video image.
  • A number between 0.0 and 60.0
    • Manually set the update / refresh rate in frames-per-seconds.
    • The video image will be constantly updated with that rate, regardless if there is a movement or no movement in the viewer.

Browser support:
  • Basically all modern browsers except IE11 and MS Edge are supported, these browsers don't support MJPEG streams.
Variable nameTypeDefault value
image.ox
image.oy
image.oz
Number
Number
Number
0
0
0
A 3D offset / translation for the pano image. Can be used to place panos in 3D space.

For usage with depthmaps and animated 3D-transitions.

The pano will be viewed from its center (which means normal, undistorted viewing) when the view.tx/ty/tz coordinates are the same as the image.ox/oy/oz coordinates.
Variable nameTypeDefault value
image.frames
image.frame
int
int
1
1
Current frame and number of frames of the pano.

It's possible to use several frames for a pano image, there the %f placeholder must be used in the image urls. That placeholder will be replaced with the current set frame number.

When changing the frame number, the tiles from that frame will get loaded.
Variable nameTypeDefault value
image.loadstate int 0
The current loading state of the image:
  • 0 - not loaded.
  • 1 - currently loading.
  • 2 - the current view is fully filled with any content (preview pano, low-res tiles).
  • 3 - the current view is fully filled with the best resolution content for the current viewing-window size and current field-of-view.

See also the onviewloaded and onviewreloading events for more information about the current loading state of the current view.
Variable name (read only)TypeDefault value
image.level.count int 0
The count / number of all image level elements.
Variable nameTypeDefault value
level[#].tiledimagewidth level[#].tiledimageheight image.level[#].tiledimagewidth image.level[#].tiledimageheight int
int
The full / total size of the tiled image for this level.
Variable nameTypeDefault value
level[#].tilesize image.level[#].tilesize int
This setting will overrule the main image.tilesize setting for this level.
Variable nameTypeDefault value
level[#].aspreview image.level[#].aspreview Boolean false
Use this level as preview image.
This also forces the whole level to be fully loaded.

About the image url placeholders

Depending on the image type and the related settings, the url of the image should contain several placeholders to allow addressing the right image file.

These url placeholders are available:
  • for the cube side: %s ⇒ a placeholder for the cubelabels
  • for the horizontal tile index: %h, %x, %u or %c (all the same)
  • for the vertical tile index: %v, %y or %r (all the same)
  • for stereo images: %t ⇒ a placeholder for the stereolabels
  • for the current image frame: %fimage.frame
Each placeholder can be used a several times in the url - e.g. as part of the filename and also as part of the foldername.

Tile-index padding:

By inserting one or more 0 characters between the % character and the character of the tile-index placeholder, it's possible to define a custom padding for the numbers.
E.g. %h ⇒ 1,2,3,...,9,10,11, %0h ⇒ 01,02,03,...,09,10,11, %00h ⇒ 001,002,003,...,009,010,011.
<image ... ox="0" oy="0" oz="0">
    ...
    <depthmap>
</image>
Depthmap Support (Examples)

Add 3D depth to your panoramic images. For stereo-rendering with one-image, for VR-viewing, for 3D-transitions or even for walking around in 3D-space.

krpano supports two sources for the depthmap:
  • Depthmap-Images
    • That's are gray-scale images (e.g. in JPG or PNG format) where the gray-value represents the distance from the viewer.
    • The depthmap image need to be in spherical 360x180 projection. The pano image itself can use a different projection, like cubical.
    • The interpretation of the gray-value to the depth/distance can be controlled by the mapmode, offset, curve and scale settings.
    • Note: The browsers are supporting only a 8-bit color/grayscale resolution, even when the input image might be a 16-bit PNG image. So the depth accuracy is limited to 256 (=2^8) different depth-levels. For more accuracy a special 16- or 24-bit RGB-encoding could be used.
  • 3D-Models
    • Simple 3D-geometry-models (optionally also with texture-mapping).
    • The 3D-geometry will be either used to generate an internal depthmap image (with 24bit depth resolution, rendermode=depthmap) or used directly and the panoramic image projected onto it (rendermode=3dmodel).
    • krpano supports these 3D-file-formats:
      • STL files in ASCII format (.stl)
        • Geometry only.
      • DEPTH files (.depth).
        • A krpano-special format, like STL, but simplified and optimized for filesize and loading-performance.
        • Geometry only.
      • Wavefront OBJ files (.obj + .mtl)
        • Geometry with optional texture-mapping.
        • Multiple textures can be used with an additional .mtl material library file, referenced from the .obj file.
    • The STL, OBJ, MTL and DEPTH files can be optionally encrypted using the krpano tools to compress them and make them faster to load.
    • By default one unit in the 3D-Model represents one centimeter in krpano. This is especially important for the VR-usage so that everything looks in the right scale.

Note - the depthmapping-support is only available for <cube> (single- and multi-resolution) and <sphere> panos (single-resolution only)!


Syntax:
<depthmap url="..."
          texurl=""
          enabled="true"
          hittest="false"
          hittestmode="cpu"
          rendermode="auto"
          textured="auto"
          background="none"
          backgroundurl=""
          mapmode="1"
          offset="0.0"
          curve="1.0"
          scale="1.0"
          farscale="1.0"
          encoding="gray"
          axis="+x+y+z"
          cull="front"
          origin="0|0|0"
          align="0|0|0"
          subdiv=""
          />

Variable nameTypeDefault value
depthmap.url String
The path/url to the depthmap file. (see also the url notes)
Supported image file types: JPG, PNG and GIF.
Supported 3D-object file types: STL (.stl), Wavefront OBJ (.obj) and DEPTH (.depth).

When the server setup doesn't allow .stl, .obj or .depth file extensions, it would be possible to add for example '.txt' at the end, e.g. '.depth.txt'. or '.stl.txt'. krpano itself detects the file-type by analyzing the file content.
Variable nameTypeDefault value
depthmap.texurl String
The path/url to a texture image file. (see also the url notes)

Optionally - define a custom texture image for the 3D-model (.obj files only).

When not set, the .obj file can refer to a .mtl material library file to load one or more textures.
Variable nameTypeDefault value
depthmap.enabled Boolean true
Enable or disable the depthmap rendering mode.

Can be changed also anytime dynamically at runtime.
Variable nameTypeDefault value
depthmap.hittest
depthmap.hittestmode
Boolean
String
false
"cpu"
Should the Dethpmap / 3D-Model be used for hit-testing?

That means testing whether the mouse-pointer, a touch or a raycast-call hits the 3D-Model. This can be used when hotspots can lie behind the 3D-Model and should not be hit-able there.

Notes:
  • By default this is disabled for memory and performance reasons.
  • The screentodepth() and raycastdepth() actions work only when the hittest setting is enabled!
  • Hotspots that should interact and intersect with the Dethpmap or 3D-Model need to have the depthbuffer setting enabled.

The hittestmode setting defines how and where to do the testing:
  • cpu (default) - Do the hit-testing on the CPU. Therefore an internal hit-test-model that allows faster hit-testing will be generated. This needs some time at startup to generate and requires some memory, but then therefore the checking at runtime is very fast and with similar performance on all systems. The accuracy of the hit-test results is very high.
    Note - this mode only works for 3D-Models, for Depthmap-images the GPU mode is used automatically.
  • gpu - Do the hit-testing on the GPU. This requires no startup-setup and no extra memory and is generally fast and almost independent of the datasize of the 3D-Model, but it needs a readback/synchronizing between CPU and GPU and on some devices this can be quite slow and reduce noticeably the framerate, especially when doing multiple hit-tests per frame (e.g. when using raycasts calls). The hit-test results in the GPU case are not as accurate as in the CPU case: the distances have ~1cm accuracy and the normal-vectors/rotation-angles ~10 degree accuracy.
Variable nameTypeDefault value
depthmap.rendermode String "auto"
The rendermode setting defines how to use 3D-Models as Depthmap:
  • "depthmap"
    • The 3D-Model will be used to generate an internal depthmap image (with 24bit depth accuracy).
    • This is the fastest way to load the 3D-Model. The rendering performance will be always the same, regardless how detailed the 3D-geometry is, and there are no 'holes', everything will be connected/filled.
    • But as disadvantage it is not as accurate as when using the 3D-Model directly, and it's not possible to view the obscured parts of the 3D-geometry.
  • "3dmodel"
    • The 3D-Model will be used directly and the pano image projected onto it.
    • With very detailed 3D-Models and the default subdiv setting the loading and rendering of the 3D-Model can be slower compared to using "depthmap".
    • When the 3D-Model is textued, then this mode need to be used.
  • "auto"
    • Automatically select "depthmap" or "3dmodel" depending on the input file.
    • For images, .stl and .depth files the default setting from display.depthmaprendermode be will be used.
    • For .obj files, the setting "3dmodel" will be used.

Note - this setting can not be changed at runtime as it controls how the depthmap gets loaded and processed.
Variable nameTypeDefault value
depthmap.textured String "auto"
Should the 3D-Model use the texture-mapping stored in the file (only for .obj files).

Available settings:
  • true
    • Use the texture-mapping (when available).
  • false
    • Ignore the texture-mapping and map the pano-image onto the 3D-Model.
  • "auto" (default)
    • Automatically use the texture-mapping (when available) when either the texurl is set or when using the textures from a .mtl file (that means when no <cube> or <sphere> image for pano-depthmapping is defined).
Variable nameTypeDefault value
depthmap.background String "none"
Render something at the 'background' behind the 3D-Model, e.g. to fill empty / undefined areas from the 3D-Model.

Available settings:
  • "none" (default)
    • Render only the depthmap pano itself.
  • "pano"
    • Render the depthmap pano and behind it the normal undistorted pano image.

Works only when using a 3D-Model as depthmap and rendermode="3dmodel".
Variable nameTypeDefault value
depthmap.backgroundurl String
Use a separate pano image as 'background' behind the 3D-Model.

Currently only spherical (360x180) images are supported here.

Works only when using a 3D-Model as depthmap and rendermode="3dmodel".
Variable nameTypeDefault value
depthmap.mapmode int 1
The pixel-to-depth mapping modes for depthmap-images:
  • 1 - The depthmap-image pixel values are scaling an unit-sphere (default).
  • 2 - The depthmap-image pixel values are directly defining the distance.

For further fine-tuning the offset and curve settings can be used.
Variable nameTypeDefault value
depthmap.offset
depthmap.curve
Number
Number
0.0
1.0
Addtionally to mapmode these are very important settings a correct depthmap-images usage. The offset value defines the offset to the nearest depthmap value and the curve value an exponential curvature of the depthmap values.

The values to use depend how the depthmap image was created and mapped. Typical offset values for mapmode=1 are in the range 0.06 to 0.30.

Here a helper tool: depthmap_helpertool.xml (a xml to include) that allows playing interactively with depthmap-image mapping settings. Here an Example using that tool.
Variable nameTypeDefault value
depthmap.scale Number 1.0
Scale the depthmap 3D representation.

Invert the depth: for depthmap images that use black for near and white for far a negative scale value could be used to invert the depth.
Variable nameTypeDefault value
depthmap.farscale Number 1.0
This setting defines how far the 'background' should be away from the object foreground.
Only related to 3D-Models rendered with rendermode="depthmap".
Variable nameTypeDefault value
depthmap.encoding String "gray"
Set the encoding of the input depthmap image:
  • gray
    • The input is an image where the depth value is encoded with 8bit precision as grayscale image (the default).
  • rgb24
    • The input is an image where the depth value is encoded with 24bit precision as 3x8bit RGB image.
    • The bit/byte-encoding: Red is the most significant byte and Blue the least significant one.
    • Because the bits are distributed across several color channels, keeping the exacts bits during storage is very important. Therefore only loss-less image-compression file-formats (like PNG) can be used for such images.
    • Hint: to make the depthmap image-file smaller for faster loading, it would be possible to store only 16bit precision by zeroing the blue channel. Due the PNG image-compression the empty blue chancel will not take much file-space.
Variable nameTypeDefault value
depthmap.axis
depthmap.cull
depthmap.origin
depthmap.align
String
String
String
String
"+x+y+z"
"front"
"0|0|0"
"0|0|0"
Import settings for the 3D-Model.
  • With the axis setting the order and signs of the 3D-axes can be defined:
    • The order of the x,y,z values in the string defines the order of the axes.
    • The signs + or - before the value the direction of the axis.
    • Note - this must be set when loading and cannot be changed later!
  • The cull setting defines which 'side' of the 3D-Model should be visible:
    • front (the default) - the front-facing elements of the geometry are visible.
    • back - only the back-facing elements are visible.
    • twosided - both sides are visible.
  • The origin setting allows defining a custom origin/center point of the 3D-Model.
    • From that origin-point the pano-image will be projected onto the 3D-geometry.
    • The axis order and orientation will be the krpano one, but without depthmap.scale applied.
    • There is also the special setting image, where the origin will be automatically taken from the current image.ox/oy/oz position.
    • Note - this can be changed anytime with real-time rendering updates.
  • The align setting rotates the pano-image.
    • The setting defines the rotation-angles in degrees about these each axis.
    • Works like the image.prealign setting, but it rotates only the image, not the 3D-geometry.
    • There is also the special setting image, where align will automatically take the current image.prealign rotations.
    • Note - this can be changed anytime with real-time rendering updates.
Variable nameTypeDefault value
depthmap.subdiv Number
The subdiv setting controls the sub-division of the 3D-Model into smaller triangles.

The value of the setting defines the maximum length of a triangle edge that is allowed. That means lower values cause smaller and more triangles. That will be good for a more accurate display when using spherical images or optional view fisheye-distortions but also require more setup-time and rendering power.

Defaults: 14.25 on desktop devices, 17 on mobile and tablet devices.
To disable the sub-division, set the setting to 0.
Variable nameTypeDefault value
depthmap.bytesize
depthmap.buildtime
int
Number
Extra information for optimizing: the memory need of the internal 3D-Model data and the time in seconds to build it.
<view>
The view element contains the information about the current view.
In the xml it can be used to set the startup view settings.

The looking direction will be defined by the hlookat / vlookat attributes (=horizontal / vertical lookat), and the current field of view in the fov attribute. For viewing limits for partial panos, the limitview attribute can be used.

<view hlookat="0.0"
      vlookat="0.0"
      camroll="0.0"
      fovtype="VFOV"
      fov="90.0"
      hfov=""
      vfov=""
      dfov=""
      mfov=""
      sfov=""
      fovmin="1.0"
      fovmax="179.0"
      maxpixelzoom=""
      mfovratio="1.333333"
      distortion="0.0"
      distortionfovlink="0.5"
      stereographic="true"
      pannini="0.0"
      architectural="0.0"
      architecturalonlymiddle="true"
      longexposure="0.0"
      limitview="auto"
      hlookatmin=""
      hlookatmax=""
      vlookatmin=""
      vlookatmax=""
      rx="0" ry="0"
      tx="0" ty="0" tz="0"
      ox="0" oy="0" oz="0"
      />

Variable nameTypeDefault value
view.hlookat Number 0.0
The horizontal looking direction in spherical coordinates in degrees.

The typical range is from -180° to +180°. The value will not wrap around 360° but the view itself will. The value 0.0 points to the center of the pano image.
Variable nameTypeDefault value
view.vlookat Number 0.0
The veritcal looking direction in spherical coordinates in degrees.

The typical range is from -90° upward at the zenith down to +90° at the nadir.
Variable nameTypeDefault value
view.camroll Number 0.0
The roll / rotation of the view camera in degrees.
Variable nameTypeDefault value
view.fovtype String
Defines the type of the field of view that the fov value represents.
This is important when resizing the viewer window to decide what fov should change.

Possible settings:
  • VFOV - vertical field of view - based on the viewer window height.
  • HFOV - horizontal field of view - based on the viewer window width.
  • DFOV - diagonal field of view - based on the viewer window diagonal.
  • MFOV - maximum field of view - based either on the width or a mfovratio-scaled height, depending which size is larger.
  • SFOV - screen diagonal field of view - based on the total device screen diagonal, the viewer window size will not matter.

Default setting: on desktop devices VFOV, on mobile and tablet devices MFOV.
Variable nameTypeDefault value
view.fov Number 90.0
The current field of view in degrees - from almost 0.0 to 179.0.
Based on the fovtype setting.
Variable nameTypeDefault value
view.hfov
view.vfov
view.dfov
view.mfov
view.sfov
Number
Number
Number
Number
Number
Directly set or get the particular field-of-view based on the related fovtype.
The value will be converted to or converted from the view.fov value, the view.fovtype will not change.
Variable nameTypeDefault value
view.fovmin Number 1.0
The minimum fov value, this will limit the zooming into the pano.

Note - maxpixelzoom setting can be used instead!
Variable nameTypeDefault value
view.fovmax Number 179.0
The maximum fov value, this will limit zooming out of the pano.
Variable nameTypeDefault value
view.maxpixelzoom Number
The maximum pixel zoom factor of the pano image.

This will limit the fov automatically depending on the pano resolution and the current viewing window, e.g. 1.0 = limit to 100% zoom, no pixel scaling of the source image will be visible.

Note - when set, this setting will overrule the fovmin setting, the fovmin value will be dynamically updated in this case.
Variable nameTypeDefault value
view.mfovratio Number 1.333333
The size ratio for the maximum screen size calculation when using the fovtype=MFOV setting. By default the ratio of a 4:3 screen (4/3 = 1.333) will be used.
Variable nameTypeDefault value
view.distortion
view.fisheye (old name)
Number
Number
0.0
0.0
Fisheye distortion effect (0.0 - 1.0).

This value contolls the interpolation between the normal rectiliniear view and the distorted fisheye view.

0.0 = no distortion / rectiliniear
1.0 = full distortion

There are two fisheye modes:
- normal (view.stereographic="false")
- stereographic (view.stereographic="true")
Variable nameTypeDefault value
view.distortionfovlink
view.fisheyefovlink (old name)
Number
Number
0.5
0.5
The fov and fisheye distortion settings are linked together (e.g. when zooming in - the fisheye effect will be reduced). This setting controls the correlation link between these two values: (0.0 - 3.0), 0=linear correlation, 3=dynamic correlation.
Variable nameTypeDefault value
view.stereographic Boolean true
Enables/disables the stereographic fisheye projection.
The 'strongness' of the projection it is controlled by the fisheye setting. The stereographic projection allowes very interessting panorama views like the Little Planet Views.
Variable nameTypeDefault value
view.pannini Number 0.0
Apply a Pannini/Vedutismo projection (0.0 to 1.0).
The 'strongness' of the projection it is controlled by the fisheye setting.
Variable nameTypeDefault value
view.architectural Number 0.0
Architectural projection (0.0 - 1.0).
This value interpolates between the current projection (0.0) and the architectural projection mode (1.0).
Variable nameTypeDefault value
architecturalonlymiddle view.architecturalonlymiddle Boolean true
When enabled, the architectural projection will be only used in the 'middle' area of the view. When looking more up and down then the architectural projection will slowly switch back to normal projection.
Variable nameTypeDefault value
view.longexposure Number 0.0
Simulate a photography long-exposure / slow-shutter / motion-blur effect.
The value range is 0.0 (off) to 0.99 (extreme).
Variable nameTypeDefault value
view.limitview String auto
Limit the viewing range in the pano.

Possible values:
  • off - no limiting at all
  • auto - automatic limiting (default)
  • lookat - limit the lookat variables direct to "hlookatmin", "hlookatmax", "vlookatmin", "vlookatmax"
  • range - limit to the area set by "hlookatmin", "hlookatmax", "vlookatmin", "vlookatmax", allow viewing only INSIDE this range
  • fullrange - limit to the area set by "hlookatmin", "hlookatmax", "vlookatmin", "vlookatmax", but allow zooming out to see the whole image (usefull for FLAT panos!)
  • offrange - limit to the area set by "hlookatmin", "hlookatmax", "vlookatmin", "vlookatmax", but don't limit the zooming in any way.
Notes to "range", "fullrange" and "offrange":
when the "hlookatmin", "hlookatmax", "vlookatmin", "vlookatmax" values were not set, they will be automatically calculated from the size of the pano image.
Variable nameTypeDefault value
view.hlookatmin
view.hlookatmax
view.vlookatmin
view.vlookatmax
Number
Number
Number
Number
The minimum horizontal looking position in spherical coordinates (-180 .. +180).
The maximum horizontal looking position in spherical coordinates (-180 .. +180).
(When hlookatmax-hlookatmin=360 then no limiting will be done) The minimum vertical looking position in spherical coordinates (-90 .. +90).
The maximum vertical looking position in spherical coordinates (-90 .. +90).
Variable name (read only)TypeDefault value
view.hlookatrange
view.vlookatrange
Number
Number
The current maximum horizontal looking range (same as hlookatmax - hlookatmin).
The current maximum vertical looking range (same as vlookatmax - vlookatmin).
Variable nameTypeDefault value
view.rx
view.ry
Number
Number
0.0
0.0
An additional viewing rotation in screen-space (in degrees).
That means that rotation will be applied at the end of all other viewing transformations.

Can be used to implement a follow the mouse effect (example) that helps indicating that this is an interactive image.
Variable nameTypeDefault value
view.tx
view.ty
view.tz
Number
Number
Number
0.0
0.0
0.0
A 3D translation of the viewpoint.

For usage with depthmaps, 3D-viewpoint changes, WebVR position tracking and animated 3D-transitions.

The pano will be viewed from its center (which means normal, undistorted viewing) when the view.tx/ty/tz coordinates are the same as the image.ox/oy/oz coordinates.
Variable nameTypeDefault value
view.ox
view.oy
view.oz
Number
Number
Number
0.0
0.0
0.0
An additional 3D translation offset of the viewpoint. But the viewing rotation will be still from the non-offset point.

This can be used together with depthmaps to make a kind of 'dollhouse' effect.
Variable name (read only)TypeDefault value
view.ox_rotated
view.oy_rotated
view.oz_rotated
Number
Number
Number
The view.ox / view.oy / view.oz 3D translation offset, but inverse rotated by the current viewing rotation.
Variable name (read only)TypeDefault value
view.dir.x / y / z
view.dir.rx / ry / rz
view.dir.ux / uy / uz
Number
Number
Number
x,y,z - a 3D unit-vector that points into the current viewing direction.
rx,ry,rz - a 3D unit-vector that points to the right, based on the current viewing rotations.
ux,uy,uz - a 3D unit-vector that points upwards, based on the current viewing rotations.
Function nameTypereturn
view.resetlimits() Action
Resets the hlookatmin, hlookatmax, vlookatmin and vlookatmax values back to default (depending on the current pano and its size/fov).
Function nameTypereturn
view.update() Action
Updates and recalculates all view dependent variables (e.g. limit hlookat/vlookat/fov to the current defined limits). Can be used when requiring intermediate or updated values now and not after the next frame update.
Examples
Just set the looking direction and the field of view:
<view hlookat="0" vlookat="0" fov="80" />
Setup a 'little planet' view:
<view hlookat="0"
      vlookat="90"
      distortion="1.0"
      fov="150"
      fovmax="150"
      />
Good settings for viewing a flat pano:
<view hlookat="0"
      vlookat="0"
      maxpixelzoom="1.0"
      limitview="fullrange"
      />
<area>
Defines the area / window where in the pano image should be displayed.

There are two modes to define the area position and size:
  • either by defining the size and the position (mode=align).
  • or by defining padding borders (mode=border).

It's possible to change/adjust these settings dynamically in the onresize event. When there are changes of the area settings outside of the onresize event, then a onresize event will be called on the next screen refresh, to allow a reaction on the next area/window size.

Note - all <layer> elements will be placed inside this area by default. To place a <layer> element outside of that area, set the parent setting of the layer to "STAGE" or "OVERLAY".
Variable nameTypeDefault value
area.mode String "align"
Select the area positioning / sizing mode.

Possible settings: "align" or "border".

Align mode:
<area mode="align"
      align="lefttop"
      x="0"
      y="0"
      width="100%"
      height="100%"
      cliplayers="true"
      />

Border padding mode:
<area mode="border"
      left="0"
      top="0"
      right="0"
      bottom="0"
      cliplayers="true"
      />
Variable nameTypeDefault value
area.align String "lefttop"
Alignment / origin-point position of the area window on the screen.

Possible values: lefttop, left, leftbottom, top, center, bottom, righttop, right, rightbottom.
Variable nameTypeDefault value
area.x
area.y
String
String
"0"
"0"
The x / y distance from the align point to the area window (only for mode=align).
This can be either an absolute pixel values or a percent values that are relative to the screen width / height.
Variable nameTypeDefault value
area.width
area.height
String
String
"100%"
"100%"
The width / height of the area (only for mode=align).
This can be either an absolute pixel values or a percent values that are relative to the screen width / height.
Variable nameTypeDefault value
area.left
area.top
area.right
area.bottom
String
String
String
String
"0"
"0"
"0"
"0"
The distances from the left / top / right / bottom edges of the screen to the area window (only for mode=border).
This can be either an absolute pixel values or a percent values that are relative to the screen width / height.
Variable nameTypeDefault value
area.cliplayers Boolean true
Clip/cut off layers outside the area.

When disabled (set to false) layer elements outside the area will be visible. Could be used together with parent="OVERLAY" to place elements outside the area and with relative coordinates to the viewer-area.
Variable name (read only)TypeDefault value
area.pixelx
area.pixely
area.pixelwidth
area.pixelheight
int
int
int
int
The resulting area position (from left-top) and size in pixels (read-only).
Examples
A fixed size area in the center of screen:
<area align="center" width="640" height="480" />
Fixed size borders at top and bottom:
<area mode="border" top="10" bottom="100" />
Use only 75% of the available width:
<area width="75%" />
Some code to caluclate and set a fixed 16:9 aspect:
<events onresize="fixaspectresize(16,9);" />

<action name="fixaspectresize">
  div(aspect, %1, %2);
  mul(destwidth, stagewidth, aspect);
  copy(destheight, stagewidth);
  if(destwidth GT stagewidth,
      div(dwnscale, stagewidth, destwidth);
    ,
      set(dwnscale, 1.0);
    );
  mul(destwidth, dwnscale);
  mul(destheight, dwnscale);
  if(destheight GT stageheight,
      div(dwnscale, stageheight, destheight);
    ,
      set(dwnscale, 1.0);
    );
  mul(destwidth, dwnscale);
  mul(destheight, dwnscale);
  sub(destx, stagewidth, destwidth);
  sub(desty, stageheight, destheight);
  mul(destx, 0.5);
  mul(desty, 0.5);
  copy(area.x, destx);
  copy(area.y, desty);
  copy(area.width, destwidth);
  copy(area.height, destheight);
</action>
<display>
Display related settings.

<display autofullscreen="true"
         stereo="false"
         stereooverlap="0.0"
         stereoscale="1.0"
         stereoseparation="6.5"
         monoside="1"
         anaglyph="false"
         safearea="auto"
         mipmapping="auto"
         loadwhilemoving="auto"
         framebufferscale="1.0"
         hotspotvrrendering="natural"
         hotspotvrflying="500"
         hotspotworldscale="2.0"
         depthmaprendermode="depthmap"
         depthmapcachesize="3"
         depthbuffer="false"
         depthrange="0.1,100000"
         surfacesubdiv="100"
         nofullscreenfallback="true"
         wireframe="false"
         wirecolor="0x00FF00"
         chromesubpixelantialiasing="false"
         />

Variable nameTypeDefault value
display.autofullscreen Boolean true
Automatically switch to fullscreen mode when rotating the mobile device to landscape mode (Android only).
Variable nameTypeDefault value
display.stereo
display.stereooverlap
display.stereoscale
display.stereoseparation
Boolean
Number
Number
Number
false
0.0
1.0
6.5
Enable the side-by-side Stereo-rendering mode.

When the <image> is defined as stereo-image, then the left side will show the left image and the right side the right image. Without stereo-image both sides will show the same image.

The stereo-rendering mode can be used for VR displays. The WebVR plugin will enable this mode automatically when entering the VR mode.

The stereooverlap setting defines the overlapping of the left and right images: 0.0=no overlap, 1.0=full overlap.

The stereoscale setting defines the horizontal scaling:
  • For VR a setting of 1.0 should be used,
  • and for 3D-TV screens with 3D-HSBS-support a setting of 0.5 should be used.

The stereoseparation setting defines the distance between the eyes in cm. Only for non-VR usage, e.g. anaglyph-rendering or 3D-TV (in VR the distance defined by the headset will be used).
Variable nameTypeDefault value
display.monoside int 1
Define which side from stereo-images should be used for the normal monoscopic rendering: 1 = left, 2 = right.
Variable nameTypeDefault value
display.anaglyph Boolean false
Enable the 3D-Anaglyph (red/cyan) Stereo-rendering mode.
Variable nameTypeDefault value
display.safearea String auto
Set how the 'Safe-Area' of the device display should be handled (currently iOS only):
  • auto - All coordinates are relative to the safe-area (inside it).
  • h-only - Same as auto, but only the horizontal part of the safe-area will be respected, vertically the full display height will be used.
  • off - The safe-area will be ignored, all coordinates are relative to the full display area. Here the inset of the safe-area would need to managed manually via display.safearea_inset in the onresize event.
  • test:t r b l - set custom safearea-inset values to test/simulate the device support.

Notes:
  • To place a <layer> outside the safe-area use set the layer setting safearea=false.
  • In the html file there need to be also this <meta> setting in the html <head> element to be able to use the Safe-Area:
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, viewport-fit=cover">
  • The general safe-area support can be enabled or disabled in the embedding setting.
  • More information: krpano Forum Post

Comparison - without Safe-Area support (an iPhone with a Notch):
and with Safe-Area support (using safearea="h-only"), same Layout but more to see:
Variable nameTypeDefault value
display.safearea_inset Object null
When the display of the device has a 'safe-area' and the browser supports the safe-area-inset CSS variables, then this variable will be an Object with information about that safe-area. Otherwise it will be null.

When set, the Object has these member variables:
• l - left safe-area-inset
• t - top safe-area-inset
• r - right safe-area-inset
• b - bottom safe-area-inset
• x - offset from the left screen edge to the safearea
• y - offset from the top screen edge to the safearea
• w - the width of the safearea
• h - the height of the safearea
• sw - the total-width of the pano-display
• sh - the total-height of the pano-display

When the value of one of l,t,r,b variables is positive, then this is the safearea size outside of the krpano viewport. When it is negative, then the safearea is inside the viewport.

These values can change anytime when the device will be rotated, so they should be used only in the onresize event.
Variable nameTypeDefault value
display.mipmapping String "auto"
Define if mipmapping should be used when displaying panos with WebGL.
Mipmapping can give a better visual quality and reduce aliasing.
Technically mipmapping is only possible on images/tiles that have power-of-two sizes.

  • auto (default)
    Automatic mode - use mipmapping automatically when the witdh and height of a image or a tile are power-of-two sizes like 256px, 512px, 1024px, 2048px or 4096px.
  • force
    Force the usage of mipmapping - this will be done by automatically resizing the images to the next larger power-of-two size. Note - that resizing can reduce loading performance and increase memory usage.
  • off
    Never use mipmapping.
Mipmapping Screenshots:
Variable nameTypeDefault value
display.loadwhilemoving String
Control the tile reloading during movement (panning, zooming). The loading and adding of new tiles can interrupt smooth movements on slow devices.

  • true (default on Desktop)
    Always instantly load and add tiles.
  • auto (default on Mobile and Tablet)
    No reloading during direct on-the-screen user-interactions. Slightly delayed and scheduled reloading during movements without direct user-interaction (scripted lookto movements, autorotate, gyro, ...).
  • false
    No reloading during any movements. Reload only on halt.
Variable nameTypeDefault value
display.framebufferscale Number 1.0
Adjust / scale the size of the WebGL frame buffer.

A smaller number mean a lower resolution and fewer pixel to calculate. This could be used on slower mobile devices to increase the rendering performance.
Variable nameTypeDefault value
display.hotspotvrrendering String "natural"
Define the appearance of non-distorted hotspots in VR mode.

Possible settings:
  • "natural" (the default) - the hotspots will be keep rotated toward the viewers eyes.
  • "screenspace" - the hotspots will be keep rotated toward the device screen (same as in normal non-VR viewing, but in VR there is no flat screen and so screen orientated things are looking wrong).
Variable nameTypeDefault value
display.hotspotvrflying Number 500.0
The 3D- distance / depth for flying hotspots in VR.
Variable nameTypeDefault value
display.hotspotworldscale Number 2.0
A global scale factor for all hotspots.

By default the hotspot-sizes use a double unit scale (2x) compared to all the other krpano 3D coordinates. That's required of the initial definition of 1000 width/height units with 1000 depth units should result in 90 degree field-of-view coverage.

For using the same units for the hotspot-sizes and the 3D coordinates, then either the hotspotworldscale setting can be set to 1.0 or the individual hotspot scale to 0.5.
Variable nameTypeDefault value
display.depthmaprendermode String "depthmap"
Define the default rendering mode when using 3D-Models as depthmap.
Can be defined also individually per pano by the depthmap.rendermode setting.

Possible settings:
  • "depthmap"
    • The 3D-Model will be used to generate an internal depthmap image (with 24bit depth accuracy).
    • That's the fastest way to load the depthmap. The rendering performance is always the same, regardless how detailed the 3D-geometry is, and there are no 'holes', everything is connected/filled.
    • But as disadvantage it is not as accurate as when using the 3D-Model directly, and it's not possible to view content the obscured parts of the 3D-geometry.
  • "3dmodel"
    • The 3D-Model will be used directly and the pano image projected onto it.
    • With very detailed 3D-Models and the default subdiv setting the loading and rendering of the 3D-Model can be slower compared to using "depthmap".
Variable nameTypeDefault value
display.depthmapcachesize Number 3
The size of the depthmap-3D-Model cache in MB.

When loading 3D-Models their internal data-structures will be cached for re-usage. This can extremly speedup the loading when using the same 3D-Model for several panos.

Note - to be able to re-use a cached 3D-Model, the depthmap.axis, the depthmap.cull, the dethpmap.subdiv and the dethpmap.hittest/hittestmode settings need to be the same.
Variable nameTypeDefault value
display.depthbuffer Boolean false
Manually enable the use of the depth-buffer for rendering (when using Depthmap-panos this will be enabled automatically).

Using the depth-buffer would be neccesary when using hotspots with their depthbuffer setting enabled. When enabled the hotspots can intersect other hotspots or the depthmap-geometry in 3D-space.
Variable nameTypeDefault value
display.depthrange String 0.1,100000
Define the depth range in CM for rendering 3D content (like depthmapped-panos or 3D-Models or hotspots). Content outside this range will get clipped/cutted-off.

The unit for the range is centimeter.
The default range is from 1mm to 1km.
Variable name (read only)TypeDefault value
display.havedepthmap Boolean false
A state variable that reports if the current pano is using a depthmap.
Variable nameTypeDefault value
display.surfacesubdiv int 100
When rendering non-flat surfaces, e.g. spherical or cylindrical panos, fisheye-distorted panos or depthmapped-panos, krpano internally needs to subdivide the surface of the pano into many smaller parts for rendering.

This settings control how much the surface should be subdivided.

Large settings means more subdivision and so smaller parts and more accurate rendering but therefore also more processing-need and slower rendering. Smaller settings mean the opposite: fewer subdivision and less accuracy but therefore faster rendering.
Variable nameTypeDefault value
display.nofullscreenfallback Boolean true
Use a fallback solution when the browser/device doesn't support the HTML5 fullscreen-mode API (e.g. iOS). In this case krpano will try to make the pano html element covering the full webpage by modifying its CSS style (size and position).
But in some cases this can conflict with custom CSS styles, therefore it's possible to use this setting to disable that fallback.
Variable nameTypeDefault value
display.iphonefullscreen int 0
The state of the iPhone Safari-browser landscape fullscreen mode when the pano-webpage is covered or moved-out by the browsers url- and tab-bars.

Possible states (read-only):
  • 0: No need for a user-swipe gesture.
  • 1: The user would need to swipe-up to get into fullscreen mode.
  • 2: The user would need to swipe-down and then up to get into fullscreen mode.

Normally this is only a read-only state variable, but by setting this variable to -1 it would be possible to disable that fullscreen handling.

The events.oniphonefullscreen event will be sent when this state changes.
Variable nameTypeDefault value
display.wireframe Boolean false
Show the wireframe / polygons of the image-tiles and/or the internal 3D geometry.
Variable nameTypeDefault value
display.wirecolor int 0x00FF00
The color of the wireframe. The default is 0x00FF00 (green).
Variable nameTypeDefault value
display.chromesubpixelantialiasing Boolean false
Enable LCD subpixel antialising of texts in the Chrome browser (more details).
By default a gray-scale antialising is used.

Even when enabled the LCD subpixel antialising works only when the textfield has an opaque / non-transparent background color (bgalpha=1.0).

The setting is disabled by default to avoid an inconsistent text-display when some texts have a background and some not.
Variable name (read only)TypeDefault value
display.istransparent Boolean
Check if rendering with a transparent viewer background.
Variable name (read only)TypeDefault value
display.currentfps Number
The current average framerate.
Variable name (read only)TypeDefault value
display.refreshrate Number
The refreshrate of the display (e.g. typical values are 60, 30, 120).
It can be different to the framerate, depending on the rendering or cpu load.
Variable name (read only)TypeDefault value
display.frame int
The current frame number.
Variable name (read only)TypeDefault value
display.rframe int
The number of rendered/drawn frames.
Variable name (read only)TypeDefault value
display.viewerwidth
display.viewerheight
int
int
The current size of the krpano viewer in CSS pixels.
Variable name (read only)TypeDefault value
display.windowwidth
display.windowheight
int
int
The current size of the inner Browser window in CSS pixels.
Variable name (read only)TypeDefault value
display.screenwidth
display.screenheight
int
int
The total size of the device screen in CSS pixels.
Variable name (Javascript only)TypeDefault value
display.htmltarget
The HTML element where the krpano viewer is embedded.
Given by the target embedding setting in the html file.
Variable name (Javascript only)TypeDefault value
display.viewerlayer
The main HTML element of the krpano viewer.

Can be used to add custom HTML elements to krpano, which handle their user interaction theirself.
Variable name (Javascript only)TypeDefault value
display.controllayer
An inner HTML element of the krpano viewer, that handles the user-inputs (mouse, touch). Has the size given in the <area> settings.

Can be used to add custom HTML elements to krpano.
Variable name (Javascript only)TypeDefault value
display.customFullscreenElement undefined
Use a custom HTML element for the fullscreen mode.

When set, the given HTML element will be used as fullscreen-element when requesting the fullscreen mode. By default the krpano viewer element itself will be used.
This can be used to include custom HTML elements, that were put above, but hierarchically 'outside' the krpano viewer, also to the fullscreen mode.
Variable name (read only)TypeDefault value
display.layout.root
display.layout.stage
display.layout.bglayer
display.layout.overlay
display.layout.hotspots
Array
Array
Array
Array
Array
Arrays of 'root-level' layer elements: Can be used to browse hierarchically through all layer elements. Start with the elements in these Arrays and then use for each element the childobjects Arrays to browse further.
Function nameType
display.requestresize() Action
Request a resize of the viewer in the next frame.
Forces a resize calculation even if the actual viewer size hasn't changed.
Triggers also the onresize event.
Function nameType
display.layout.update() Action
Instantly process all changes and update the layout of all layer and hotspots elements.

Normally that processing will done automatically in the next frame, but when certain layout results (e.g. pixel positions and sizes) are required now, that recalculation can be forced by this call.
<control>
The mouse/touch and keyboard control settings.

<control mode="drag"
         ☞ drag control
         draginertia="0.1"
         dragfriction="0.9"
         ☞ moveto control
         movetoaccelerate="1.0"
         movetospeed="10.0"
         movetofriction="0.8"
         ☞ keyboard control
         keybaccelerate="0.5"
         keybspeed="10.0"
         keybfriction="0.9"
         keybinvert="false"
         keybfovchange="0.75"
         keycodesleft="37"
         keycodesright="39"
         keycodesup="38"
         keycodesdown="40"
         keycodesin=""
         keycodesout=""
         keydownrepeat="true"
         ☞ mouse control
         mousefovchange="1.0"
         zoomtocursor="false"
         zoomoutcursor="true"
         disablewheel="false"
         panomousebuttons="1"
         layermousebuttons="1"
         eventmousebuttons="7"
         ☞ touch control
         touchzoom="true"
         trackpadzoom="true"
         capturetouch="true"
         ☞ settings for all control modes
         usercontrol="all"
         fovspeed="3.0"
         fovfriction="0.9"
         frictionstop="0.01"
         invert="false"
         bouncinglimits="false"
         />
Variable nameTypeDefault value
control.mode String drag
Set the control mode.

Available settings:
  • drag - drag the pano image and the view will follow instantly.
  • follow - drag the pano image, but the view will follow smoothly delayed.
  • moveto - move the pano image constantly into the direction the user has dragged.
Variable nameTypeDefault value
control.draginertia Number 0.1
The inertia of the dragging control. The higher the value, the fewer the momentum of the view rotation when releasing the control. That setting applies to the drag and follow control modes.
Variable nameTypeDefault value
control.dragfriction Number 0.9
The friction of the view rotation momentum of the dragging control mode. The lower the value, the quicker the movement will stop. That setting applies to the drag and follow control modes.
Variable nameTypeDefault value
control.movetoaccelerate Number 1.0
The movement acceleration of the moveto control mode. The higher the value, the quicker the pano will start rotating.
Variable nameTypeDefault value
control.movetospeed Number 10.0
The maximum moving / rotating speed of the moveto control mode.
Variable nameTypeDefault value
control.movetofriction Number 0.8
The friction of the view rotation momentum of the moving control mode. The lower the value, the quicker the movement will stop.
Variable nameTypeDefault value
control.keybaccelerate Number 0.5
The acceleration of the keyboard / button controlled moving.
Variable nameTypeDefault value
control.keybspeed Number 10.0
The maximum moving speed of the keyboard / button controlled moving.
Variable nameTypeDefault value
control.keybfriction Number 0.9
The moving friction of the keyboard / button controlled moving.
Variable nameTypeDefault value
control.keybinvert Boolean false
Invert the keyboard / button up and down moves.
Variable nameTypeDefault value
control.keybfovchange Number 0.75
The keyboard / button fov (zoom) change in degrees (=zoom sensibility).
Variable nameTypeDefault value
control.keycodesleft String "37"
Keyboard keycodes for moving left (separated by commas).
Default="37" (arrow left)
Variable nameTypeDefault value
control.keycodesright String "39"
Keyboard keycodes for moving right (separated by commas).
Default="39" (arrow right)
Variable nameTypeDefault value
control.keycodesup String "38"
Keyboard keycodes for moving up (separated by commas).
Default="38" (arrow up)
Variable nameTypeDefault value
control.keycodesdown String "40"
Keyboard keycodes for moving down (separated by commas).
Default="40" (arrow down)
Variable nameTypeDefault value
control.keycodesin String
Keyboard keycodes for zooming-in (separated by commas).

Example: to allow zooming-in with the Shift-key, the A-key, and the Plus-key:
keycodesin="16,65,107"
Variable nameTypeDefault value
control.keycodesout String
Keyboard keycodes for zooming-out (separated by commas).

Example: to allow zooming-out with the CTRL-key, the Y/Z-keys, and the Minus-key:
keycodesout="17,89,90,109"
Variable nameTypeDefault value
control.keydownrepeat Boolean true
Enable or disable the auto-repeating of the onkeydown event when a key is hold down. The auto-repeating delay and repeating interval depends on the system keyboard settings.
Variable nameTypeDefault value
control.mousefovchange Number 1.0
The mouse-wheel fov (zoom) change in degrees (=mouse-wheel zoom sensibility).
Variable nameTypeDefault value
control.zoomtocursor Boolean false
When enabled and zooming in by the mouse-wheel the pano will zoom toward the position of the mouse cursor.
Variable nameTypeDefault value
control.zoomoutcursor Boolean true
When zoomtocursor and this setting are enabled and zooming out by the mouse-wheel the pano will zoom away from the position of the mouse cursor. Otherwise the pano will zoom away from the center of the screen.
Variable nameTypeDefault value
control.disablewheel Boolean false *
Disable mouse-wheel support.

Note - when the mouse-wheel support is disabled and the webpage is a 'non-full-height-webpage' then using the mouse-wheel might scroll the page.

* The default value depends on mwheel embedding setting.
Variable nameTypeDefault value
control.panomousebuttons
control.layermousebuttons
control.eventmousebuttons
int
int
int
1
1
7
Define which mouse buttons ...
The values for these settings are bit-flags with combinations of:
  • 1 - left mouse button
  • 2 - middle mouse button
  • 4 - right mouse button
Variable nameTypeDefault value
control.touchzoom Boolean true
Enable or disable the 2-finger zoom gesture.
Variable nameTypeDefault value
control.trackpadzoom Boolean true
Enable support for multi-touch-trackpad-gestures.

When doing a zoom-gesture on a trackpad, the browser translates this internally to a mouse-wheel event with the CTRL-key pressed (more details here).

And when the trackpadzoom setting is enabled, this case will be detected and mapped to a continuous zoom in the viewer. But a side-effect of this is that the mouse-wheel zooming behavoir is different when using a normal mouse-wheel and holding the CTRL-key.

So if mouse-wheel zooming while holding the CTRL-key should work normally, this setting would need to be disabled. But then also trackpad-zooming-gestures are not working correctly, so it is an individual trade off.
Variable nameTypeDefault value
control.capturetouch Boolean true *
Capture touch events.

Note - when disabled and the webpage is a 'non-full-height-webpage' then the touches might scroll the page.

* The default value depends on capturetouch embedding setting.
Variable nameTypeDefault value
control.usercontrol String all
User controls for changing the pano view:
  • all - all controls - mouse, touch and keyboard.
  • mouse - mouse and touch controls only (no keyboard).
  • keyb - keyboard control only (no mouse/touch).
  • off - no user control.
Variable nameTypeDefault value
control.fovspeed Number 3.0
The maximum fov change / zooming speed (for mouse-wheel and keyboard / button control).
Variable nameTypeDefault value
control.fovfriction Number 0.9
The friction of fov (zoom) changes.
Variable nameTypeDefault value
control.frictionstop Number 0.01
That setting is a relative factor that defines at what movement speed the movement should completly stop. The lower the value the smoother the movement will fade out.
Variable nameTypeDefault value
control.invert Boolean false
Invert the dragging / panning direction.
Variable nameTypeDefault value
control.bouncinglimits Boolean false
Bounce back when hitting the panning or zooming limits (drag control only).
Examples
Use the moveto control mode for desktop systems:
<control mode.desktop="moveto" />
Zoom toward the mouse cursor:
<control zoomtocursor="true" />
Allow zooming by keyboard:
<control keycodesin="16,65,107" keycodesout="17,89,90,109" />
<cursors>
Customize the mouse cursor.

By using the standard, dragging and moving settings it's possible to select CSS cursors for these states.


<cursors standard="default"
         dragging="move"
         moving="move"
         />
Variable nameTypeDefault value
cursors.standard
cursors.dragging
cursors.moving
String
String
String
default
move
move
Select the native CSS mouse cursor for the current state.
<autorotate>
Automatic rotation / moving / zooming when there is no user-interaction.

<autorotate enabled="false"
            waittime="1.5"
            accel="1.0"
            speed="10.0"
            horizon="0.0"
            tofov="off"
            oneroundrange="360.0"
            zoomslowdown="true"
            interruptionevents="userviewchange|layers|keyboard"
            />




Variable nameTypeDefault value
autorotate.enabled Boolean false
Enable / disable the automatic rotation.
Variable nameTypeDefault value
autorotate.waittime Number 1.5
The time in seconds to wait after the last user-interaction before starting the automatic rotation.
Variable nameTypeDefault value
autorotate.accel Number 1.0
The rotation acceleration in degrees/second.
Variable nameTypeDefault value
autorotate.speed Number 10.0
The maximum rotation speed in degrees/second.
Use a negative value for a rotation to left.
Variable nameTypeDefault value
autorotate.horizon Number 0.0
Move / rotate to the given horizon (0.0 = middle of the pano).
Set the value to "off" or any other non-number value to disable it.
Variable nameTypeDefault value
autorotate.tofov Number NaN
Zoom to the given field of view (fov).
Set it to "off" or any other non-number value to disable it.
Variable nameTypeDefault value
autorotate.oneroundrange Number 360.0
The degrees to automatically rotate before sending the onautorotateoneround event.
Variable nameTypeDefault value
autorotate.zoomslowdown Boolean true
Slow down the autorotation speed relative to the current zoom / field-of-view to get the same visual speed at all zoom distances.
Variable nameTypeDefault value
autorotate.interruptionevents String ...
Define which events will interrupt the autorotation (and also the onidle event).

The value can be a combination of the following strings (combined by | characters):
  • userviewchange
    • A change of the pano-view by the user via mouse or touch.
  • layers
    • An interaction with layer or hotspot elements.
  • keyboard
    • Any keyboard input.

The default is:
interruptionevents="userviewchange|layers|keyboard"
Variable name (read only)TypeDefault value
autorotate.isrotating Boolean false
Is the pano currently auto-rotating?
Variable name (read only)TypeDefault value
autorotate.ispaused Boolean false
Is the auto-rotating currently paused?
Function nameType
autorotate.start()Action
Enable and directly start the autorotation now (without autorotate.waittime).
Function nameType
autorotate.stop()Action
Stop the current autorotation and disable it.
Function nameType
autorotate.interrupt()Action
Stop/interrupt the current autorotation - same as an user interaction interrupt (and so will also interrupt the idletime for the onidle event).
The autorotation itself will kept enabled and will start again after waittime seconds without user interaction.
Function nameType
autorotate.pause()Action
Either pause the current autorotation, or when the autorotation is currently not running, then don't start it as long as it is paused.

E.g. could be used when the mouse hovers a hotspot to pause there.
Function nameType
autorotate.resume()Action
Resume a previously paused autorotation.
Examples
Just enable it (using the default settings):
<autorotate enabled="true" />
Enable it and set custom settings (like a rotation to left by a negative speed value):
<autorotate enabled="true"
            waittime="5.0"
            speed="-3.0"
            horizon="0.0"
            tofov="120.0"
            />
Interactively enable or disable the autorotation:
onclick="switch(autorotate.enabled);"
Enable and instantly start the autorotation:
onclick="autorotate.start();"
Pause when hovering an element and resume when leaving it:
onover="autorotate.pause();"
onout="autorotate.resume();"
<plugin>
About <plugin> elements:
  • The <plugin> and <layer> elements are the same elements.
  • Just two different names for the same thing.
  • It's anytime possible to use 'layer' or 'plugin' or inverse to address the same elements. In static xml code and also dynamic Action or Javascript code, it's always the same.
  • The term 'plugin' comes from older version where plugins were mainly intended to include external tools for further interactivity.
  • Today the element provides much more layout features, and so the newer term 'layer' describes its behavior better.
  • Therefore it would be recommend to use <plugin> only when including plugins that extend krpano with additional functionality (like the Soundinterface or WebVR plugins) and to use <layer> for all layout related elements.
<layer>
<hotspot>
The <layer> and <hotspot> elements are the main user-interface elements in krpano:
  • The layer elements are 2D-screen-space-based and can be used for all kind of layout elements. For including images, texts, buttons, videos, creating containers for other layers and also for adding special elements like embedding iframes, html-code and even other krpano viewers.
  • Hotspot elements are basically the same but in the pano-image/3D-space.
  • Additionally hotspots can be used for draw polygonal areas or lines.
  • The elements can be combined, ordered, stacked hierarchically either by using the parent setting or by defining further <layer> elements as xml-children-elements.
  • Technically layers are HTML-elements. Hotspots can be either HTML-elements or been drawn by WebGL, depending on the renderer setting and the type of the hotspot and if stereo-rendering is requiered.

Documentation Topics



The xml structure for <layer> elements:
<layer name="..."
       ☞ basic settings
       type="image"
       url="..."
       keep="false"
       preload="false"
       style=""
       cssclass=""
       ☞ layering, flowing
       parent=""
       childorder="0"
       zorder="0"
       flowchildren=""
       flow="true"
       flowexpand="false"
       flowoverflow="false"
       flowspacing=""
       childflowspacing="0"
       childmargin="0"
       enablechildren="true"
       scalechildren="true"
       maskchildren="false"
       ☞ user control
       enabled="true"
       capture="true"
       capturewheel="false"
       capturefocus="true"
       cursor="pointer"
       nativecontextmenu="false"
       tabindex=""
       ☞ appearance
       visible="true"
       alpha="1.0"
       autoalpha="false"
       ☞ position and size
       safearea="true"
       align="lefttop"	
       edge=""
       x="0"
       y="0"
       ox="0"
       oy="0"
       width=""
       height=""
       minwidth="0" maxwidth="0"
       minheight="0" maxheight="0"
       autowidth="" autoheight=""
       scalemode="scale"
       scale="1.0"
       scalex="1.0" scaley="1.0"
       rotate="0.0"
       gridfit="true"
       gpu="true"
       ☞ image cropping
       crop=""
       onovercrop=""
       ondowncrop=""
       scale9grid=""
       ☞ background, borders and shadows
       bg="true"
       bgcolor="0x000000"
       bgalpha="0.0"
       bgborder="0"
       bgbordermode="outside"
       bgborderblend="true"
       bgroundedge="0"
       bgshadow=""
       bgcapture="false"
       ☞ background filters
       bgbrightness="1.0"
       bgcontrast="1.0"
       bgsaturate="1.0"
       bghue="0.0"
       bginvert="0.0"
       bgsepia="0.0"
       bgblur="0.0"
       ☞ special layer type settings
       krpanobgcolor=""
       iframeurl=""
       html=""
       htmlautosize="false"
       htmloverflow="hidden"
       ☞ control events
       onover.addevent=""
       onhover.addevent=""
       onout.addevent=""
       onclick.addevent=""
       ondown.addevent=""
       onup.addevent=""
       onwheel.addevent=""
       ontabindex.addevent=""
       onfocus.addevent=""
       onblur.addevent=""
       ☞ state events
       onloaded.addevent=""
       onresize.addevent=""
       onlayout.addevent=""
       />


The xml structure for <hotspot> elements:
<hotspot name="..."
       ☞ basic settings
       type="image"
       url="..."
       keep="false"
       preload="false"
       style=""
       cssclass=""
       ☞ spherical position
       ath="0.0"
       atv="0.0"
       depth="1000.0"
       prealign="false"
       ☞ 3D position
       torigin="world"
       tx="0.0"
       ty="0.0"
       tz="0.0"
       ☞ 3D rotation
       rotationorder="yxz"
       rx="0.0"
       ry="0.0"
       rz="0.0"
       oref="2"
       inverserotation="false"
       twosided="false"
       ☞ 2D/3D appearance
       zoom="false"
       distorted="false"
       flying="0.0"
       scaleflying="true"
       ☞ special WebGL rendering settings
       renderer="auto"
       mipmapping="false"
       premultiplyalpha="false"
       depthbuffer="false"
       depthwrite="true"
       depthoffset="0"
       ☞ special effects (WebGL only)
       blendmode="normal"
       alphachannel="auto"
       stereo=""
       chromakey=""
       ☞ special CSS3D settings
       zorder2="1"
       ☞ layering, flowing
       parent=""
       childorder="0"
       zorder="0"
       childmargin="0"
       enablechildren="true"
       scalechildren="true"
       maskchildren="false"
       ☞ user control
       enabled="true"
       capture="true"
       capturewheel="false"
       capturefocus="true"
       cursor="pointer"
       nativecontextmenu="false"
       tabindex="false"
       ☞ appearance
       visible="true"
       alpha="1.0"
       autoalpha="false"
       blending="true"
       ☞ position and size
       edge="center"
       ox="0"
       oy="0"
       width=""
       height=""
       minwidth="0" maxwidth="0"
       minheight="0" maxheight="0"
       autowidth="" autoheight=""
       scalemode="scale"
       scale="1.0"
       scalex="1.0" scaley="1.0"
       rotate="0.0"
       gridfit="auto"
       ☞ image cropping
       crop=""
       onovercrop=""
       ondowncrop=""
       scale9grid=""
       ☞ background, borders and shadows
       bg="true"
       bgcolor="0x000000"
       bgalpha="0.0"
       bgborder="0"
       bgbordermode="outside"
       bgborderblend="true"
       bgroundedge="0"
       bgshadow=""
       bgcapture="false"
       ☞ control events
       onover.addevent=""
       onhover.addevent=""
       onout.addevent=""
       onclick.addevent=""
       ondown.addevent=""
       onup.addevent=""
       onwheel.addevent=""
       ontabindex.addevent=""
       onfocus.addevent=""
       onblur.addevent=""
       ☞ state events
       onloaded.addevent=""
       onresize.addevent=""
       onlayout.addevent=""
       />


The xml structure for polygonal <hotspot> elements:
<hotspot name="..."
       ☞ basic settings
       keep="false"
       style=""
       prealign="false"
       zorder="0"
       ☞ polygon type (filled area or line)
       polyline="false"
       ☞ polygon appearance
       fillcolor="0xAAAAAA"
       fillalpha="0.5"
       borderwidth="3.0"
       bordercolor="0xAAAAAA"
       borderalpha="1.0"
       bordergradient=""
       borderzoom="0.0"
       borderwidth3d="false"
       ☞ 3D position/rotation
       torigin="world"
       twosided="false"
       ☞ special WebGL rendering settings
       renderer="auto"
       depthbuffer="false"
       depthwrite="true"
       depthoffset="0"
       subdiv="false"
       borderhittest="false"
       ☞ special effects (WebGL only)
       blendmode="normal"
       ☞ user control
       enabled="true"
       capture="true"
       capturewheel="false"
       capturefocus="true"
       cursor="pointer"
       ☞ appearance
       visible="true"
       alpha="1.0"
       autoalpha="false"
       blending="true"
       ☞ control events
       onover.addevent=""
       onhover.addevent=""
       onout.addevent=""
       onclick.addevent=""
       ondown.addevent=""
       onup.addevent=""
       onwheel.addevent=""
       ☞ state events
       onloaded.addevent=""
>
    ☞ coordinates for spherical points:
    <point ath="..." atv="..." />
    <point ath="..." atv="..." />
    <point ath="..." atv="..." />
    ...
    ☞ coordinates for 3D hotspots (alternative to spherical):
    <point x="..." y="..." z="..."/ >
    <point x="..." y="..." z="..."/ >
    <point x="..." y="..." z="..."/ >
    ...
</hotspot>




Variables documentation: iscontainer
Global Variables (read only)TypeDefault value
layer.count
hotspot.count
int
int
0
0
The total count of all layer/plugin or hotspot elements.

Note - for traversing the elements hierarchically the display.layout Arrays can be used.
Layer / Hotspot AttributeTypeDefault value
name String
The name of the current layer/hotspot element.
Note - see also the Name Notes!
Layer / Hotspot Variable (read only)TypeDefault value
path String
The 'full path' for accessing / getting the element.
E.g. layer[NAME] or hotspot[NAME].
Layer / Hotspot Variable (read only)TypeDefault value
index int
The Array index of the current layer/hotspot element.
Layer Variable (read only)TypeDefault value
iscontainer Boolean false
A boolean read-only variable to check if the element is container element.
Layer / Hotspot Variable (read only)TypeDefault value
ishotspot Boolean false
A boolean read-only variable to check if the element is a hotspot or a layer.
Always false for layers, always true for hotspots.
Hotspot Variables (read only)TypeDefault value
ispoly
is3dpoly
Boolean
Boolean
false
false
State variables to check if the hotspot is a polygonal hotspot or even a 3D polygonal hotspot.
Layer / Hotspot AttributeTypeDefault value
type String "image"
Type of the layer/hotspot element.

Possible settings:
  • image or plugin or poly (default)
    • The defaults, these don't need to be set.
    • The type will be image when loading an image file (like jpg, png, svg, ...) or plugin when loading a krpano .js plugin file or poly when the hotspot is a polygonal hotspot.
  • container
    • Use the layer/hotspot as container element.
    • Typically to contain other layer elements, but can be also used as normal box.
    • When the layer has no width or height settings, it will automatically take a appropriate size to cover all children layers.
    • When the contiainer layer has no children layers, it needs to have width and height settings to get a size!
    • The container element is transparent by default, but a background color, border and shape can be defined by the bg, bgcolor, bgalpha, bgborder, bgroundedge and bgshadow settings.
    • By default it's possible to click through the container background. To disable that change the bgcapture setting to true.
    • When used as hotspot, only CSS 3D transform rendering is supported!
      That means no stereo/VR usage for this hotspot!
  • text
    • Use this layer/hotspot as textfield.
    • A textfield layer is an extended container layer and has the same basic settings as a container layer.
  • scrollarea (layer only)
    • Use this layer as scrollarea.
    • Can be only used as layer within a container layer.
  • iframe
    • Embed an iframe (website) inside the layer/hotspot.
    • The url of the iframe can be set by the iframeurl setting.
    • A iframe layer is an extended container layer and has the same basic settings as a container layer.
    • When the iframe is ready, then the onloaded event will be called and the layer will contain a iframe variable that provides access to the iframe html-element.
    • When used as hotspot, only CSS 3D transform rendering is supported!
      That means no stereo/VR usage for this hotspot!
  • html
    • Embed raw/unparsed html-code inside the layer/hotspot.
    • The html-code can be set by the html setting.
    • If the html content should be scrollable adjust the htmloverflow setting.
    • A html layer is an extended container layer and has the same basic settings as a container layer.
    • When used as hotspot, only CSS 3D transform rendering is supported!
      That means no stereo/VR usage for this hotspot!
    • When the layer is ready, then the onloaded event will be called and the layer will contain a htmlelement variable that provides access to the html-element.
    • Example - store html-code inside the xml as CDATA <data> element:
      <data name="test"><![CDATA[
        any html code...<br>
        ...
      ]]></data>
      and then load it by:
      html="get:data[test].content"
  • krpano
    • Embed another krpano viewer inside the layer/hotspot.
    • This is an optimized way for embedding and controlling other krpano instances.
    • A krpano layer is an extended container layer and has the same basic settings as a container layer.
    • The rendering background of the embedded krpano viewer is transparent by default. When transparency is not required, a custom background color can be set with the krpanobgcolor setting. Non-transparency is also better for rendering performance.
    • When used as hotspot, only CSS 3D transform rendering is supported!
      That means no stereo/VR usage for this hotspot!
    • For adding custom embedpano parameters, the krpanoembedsettings setting can be used (only by Javascript).
    • The embedded viewer need to be controlled by Actions or by Javascript.
    • When the viewer is ready, then the onloaded event will be called and the layer will contain a krpano variable that provides direct access to the krpano API of the embedded krpano viewer.
    • Example:
      <layer ...
        type="krpano"
        onloaded="krpano.actions.loadpano('test.xml');" 
        />
      
    • Javascript Example:
      var layer = krpano.addlayer();
      layer.type = "krpano";
      ...
      layer.onloaded = function()
      {
        layer.krpano.image.reset();
        layer.krpano.image.sphere = {url:"pano.jpg"};
        layer.krpano.events.onloadcomplete = function(){...};
        layer.krpano.actions.loadpanoimage();
        layer.krpano.view.fov = 120;
      }
      
Layer / Hotspot AttributeTypeDefault value
url String
The path/url to an image file. See also the url notes!

All image formats that the browser supports can be used.
Layer / Hotspot AttributeTypeDefault value
keep Boolean false
Should this element be kept or automatically removed when loading a new pano?
Settings: true or false (default).

This can be used to define a kind of 'global' elements that will be defined once and the stay there even when loading new stuff, or to define elements that should be 'local' only to the current pano/scene and automatically get removed when loading something else.
Layer / Hotspot AttributeTypeDefault value
preload Boolean false
Preload the url before loading the pano and before executing any actions. This can be used to force some element to be there and ready before everything else starts.

Note - the onloaded event doesn't work / can't be used when preloading is enabled!
Layer / Hotspot AttributeTypeDefault value
cssclass String
Assign CSS styles from one or more CSS classes to the element.
The setting is a space-separated list of CSS classes (same as in html).

Limitations when using the cssclass setting:
Note - for defining CSS styles/classes directly in the xml file, the <cssstyles> element can be used.
Hotspot AttributeTypeDefault value
renderer String "auto"
Select the renderer for displaying the hotspot.

Possible settings:
  • auto (default)
    • Automatically use WebGL for rendering the hotspot when:
      • the hotspot is an image- or video-hotspot,
      • the depthbuffer or chromakey settings are enabled,
      • the hotspot is a polygonal or poly-line hotspot
      • or when using stereo-rendering (WebVR).
    • Textfield-hotspots and other HTML-based hotspots will be automatically displayed as CSS-3D-transformed HTML element.
      • Advantages : For textfields this is faster and needs less memory than WebGL rendering, because the text don't need to be first manually rendered as image and then be uploaded to the GPU as WebGL-texture (two slow processes). Additionally all HTML/CSS styling features are available for the textfield in this case.
      • Disadvantages: WebGL-only features like depthbuffer (rendering the hotspots behind other 3D elements) are not available.
      • When stereo-rendering (WebVR) gets enabled, then the textfield hotspot will be automatically rendered using WebGL as long as stereo-rendering is enabled (stereo-rendering with HTML is not possible).
  • webgl
    • Always use WebGL to render the hotspot.
    • For image, video, textfield and polygonal-hotspots.
    • Exception: When a WebGL hotspot gets children layers attached, it will be automatically rendered as CSS-3D-transformed HTML element and no longer via WebGL!
  • html or css3d or svg (any value possible)
    • The hotspot will be displayed as CSS-3D-transformed HTML element (for images, videos, textfields) or as SVG-image (for polygonal hotspots).
Layer / Hotspot AttributeTypeDefault value
parent String
Assign the element to be a child element of an other layer or hotspot element.

Syntax:
  • Either set only the name of the layer that should be the parent:
    parent="name-of-the-other-layer"
  • Or set the 'full path' - that means the type and the name:
    parent="layer[name]"
    parent="hotspot[name]"
    That's required when a hotspot should be the parent element.

Beside of using other layers or hotspots there are these special parent settings:
  • parent="" or parent=null - no parent, the layer will be on the normal hierarchy level. The positions and sizes will be relative to the size of the <area>.
  • parent="STAGE" - place the layer outside the main krpano pano viewing and controlling context and this way also above the other layers and outside the <area>. The positions and sizes will be relative to the size of the total viewer area.
    This could be used for layers that should 'external' components like editor-controls.
  • parent="BGLAYER" - similar to STAGE but BEHIND the <area>. Could be used together with transparent background rendering to draw a background behind partial-panos or behind 3D-Models.
  • parent="OVERLAY" - place the layer on top over all other layers and outside the <area>. The positions and sizes will be relative to the size of the total viewer area. Depending on the area.cliplayers setting, the parts of the layers that are outside the <area> will be either visible or hidden.

Notes:
  • Layering is currently only supported for HTML/CSS elements.
  • That means only for layers and CSS3D-hotspots.
  • Because of this when using a WebGL-hotspot as parent, the hotspot automatically becomes a CSS3D-hotspot.
Layer / Hotspot AttributeTypeDefault value
childorder int 0
A setting to sort the children layers within a parent element. Any integer numbers can be used. Layers with higher numbers will above layers with lower numbers.

When changing this setting, then in the next processing loop all children elements of the parent element will get sorted by their given childorder values.

This order will affect the flowing- and draw/stacking-order.
Layer / Hotspot AttributeTypeDefault value
zorder int 0
A setting to change the draw/render-order. Any integer numbers can be used. Elements with higher numbers will above elements with lower numbers.

The layers can be only sorted within their parent-layer. Moving a children-layer out or above the parent layer is not possible.

Different to the childorder setting, this will only effect the draw-order, but not sort the elements within a parent and so have no effect on the flowing order of children elements.
Hotspot AttributeTypeDefault value
zorder2 int 1
A special setting for Safari / Apple-Webkit-based browsers.
These browsers have a special and unique behavior when rendering CSS 3D-elements, they are always rendering these elements with a 'z/depth-buffer' and ignoring the CSS-zindex.

The setting is only relevant for non-distorted CSS-rendered hotspots and only when mixing them with distorted CSS-rendered hotspots:
  • zorder2=0 - The hotspot is drawn BEHIND distorted hotspots.
  • zorder2=1 - The hotspot is drawn ABOVE distorted hotspots (default).
Layer / Hotspot AttributeTypeDefault value
flowchildren String ""
Enable an automatic flowing / ordering of children layers:
  • h - order all children elements with flow=true horizontally.
  • v - order all children elements with flow=true vertically.
  • "" or null - disabled.

Features:
  • Automatic positioning - the positions of the children layers will automatically adopt when the size of the layer or the sizes of the children layers changes.
  • Automatic sizing - when no layer width or height is given, the size of the layer will automatically adjust itself to the space needed by the children layers.
  • Automatic spacing - the spacing between the flowing children layers can be controlled by the childflowspacing and flowspacing settings.

Parent related settings: flowchildren, flowoverflow, childflowspacing, childmargin.
Child related settings: flow, flowexpand, flowspacing.
Layer AttributeTypeDefault value
flow Boolean true
Enable automatic flowing / ordering within the parent layer (has only an effect when the parent layer has the flowchildren setting enabled).

When enabled the layer position (the x and y settings) will be automatically calculated and updated depending on the other children layers within the parent.
Layer AttributeTypeDefault value
flowexpand Boolean false
When enabled the width or height of the layer (depending on the flowchildren setting of the parent layer) will automatically be adjusted to fit the remaining / available space within the parent layer. The parent layer need to have a given size for this (no auto / self-adjusting size of the parent).

When multiple layers have the flowexpand setting enabled, the available space will be divided proportionally based on their given width or height value (regardless if an absolute or percent value).
Layer AttributeTypeDefault value
flowoverflow Boolean false
Should children layers automatically 'overflow' to the next row or column when reaching the width or height of the parent layer.
Layer AttributesTypeDefault value
childflowspacing
flowspacing
String
String
"0"
""
Set the spacing / distances between flowing layers in pixels.

The childflowspacing is a setting at the parent and affects all children layers and the flowspacing setting is at the child to overwrite the parent childflowspacing setting and set an individual spacing. When flowspacing is set to "" or null, then the value from the parent layer's childflowspacing setting is used.

Syntax: 1 to 4 space-separated values:
flowspacing="allsides"
flowspacing="topbottom leftright"
flowspacing="top leftright bottom"
flowspacing="top right bottom left"

The spacing will be only between the flowing layers. For a spacing around all children layers the childmargin setting can be used.
Layer AttributeTypeDefault value
childmargin String "0"
Add a marging / space around all children layer elements in pixels. As a result, the space available for the children layers is correspondingly smaller.

Syntax: 1 to 4 space-separated values:
childmargin="allsides"
childmargin="topbottom leftright"
childmargin="top leftright bottom"
childmargin="top right bottom left"
Layer / Hotspot AttributeTypeDefault value
enablechildren Boolean true
Enable the children elements of the current element to be active.

When disabled the children elements will be inactive and don't receive any user events like clicks or touches.
Layer / Hotspot AttributeTypeDefault value
scalechildren Boolean true *
Should children layer elements also get scaled when the layer itself gets scaled.

Note - the default value depends on the version set in the xml! When the version is 1.21 or higher, then the default is true. For older versions the default is false.
Layer / Hotspot AttributeTypeDefault value
maskchildren Boolean false
When set to true then children elements that are outside the boundaries of the current element will be clipped / masked out.
Layer / Hotspot AttributeTypeDefault value
enabled Boolean true
Enables or disable the layer/hotspot.

When disabled the element will be inactive and don't receive any user events like clicks or touches.
Layer / Hotspot AttributeTypeDefault value
capture Boolean true
Capture the user events.

When disabled, elements below the current element will receive the user events too.
This could be used to click on an element and still be able to control the pano below it.
Layer / Hotspot AttributeTypeDefault value
capturewheel Boolean false
Should mouse-wheel events by captured by this element?

See also the onwheel event.
Layer / Hotspot AttributeTypeDefault value
capturefocus Boolean true
Capture the input/keyboard focus when clicking or touching on the element.
Layer / Hotspot AttributeTypeDefault value
cursor String "pointer"
Use a custom mouse cursor when hovering the element.

Any CSS cursor setting can be used, although the exact appearance and support depends on the browser and the system.

Common settings:
  • pointer - The typical mouse cursor when hovering clickable elements. On the most systems typically a Hand-cursor-icon. The default and indicates an interactive/clickable element.
  • default - The default system cursor, typically an Arrow-cursor-icon. Could be used for elements that shouldn't appear interactive/clickable.
Layer / Hotspot AttributeTypeDefault value
nativecontextmenu Boolean false
When enabled the browsers native/default contextmenu will appear when right-clicking (or long-touching) on the element.

Note - this works only when the capture setting is also set to true!
Layer / Hotspot AttributeTypeDefault value
tabindex Integer null
Make the layer sequentially focusable by using the Tab-key.
  • To enable, set a valid positive Integer value.
  • That Integer value also defines the order, in which the layers get focused.
  • To disable, set an invalid value, e.g. like null (the default) or an empty String.

When the focused layer gets activated by using the Enter-key, then either the ontabindex event will be triggered (only when it is set) - or the normal ondown (as long as holding the Enter key), onup and onclick (when releasing the Enter key) events.

When enabled (set to valid value), then the onfocus and onblur events will get triggered when the focus changes.
Layer / Hotspot AttributeTypeDefault value
visible Boolean true
Visibility of the element.

When set to false, the element will be not shown and also not be processed.
Layer / Hotspot AttributeTypeDefault value
alpha Number 1.0
Alpha transparency of the element: From 0.0 = fully transparent to 1.0 = fully visible.

Note - even when set to 0.0 - the element will be still there and interactive - to hide it completely set the visible setting to false!
Layer / Hotspot AttributeTypeDefault value
autoalpha Boolean false
Change the visible setting automatically depending on the alpha value.

When enabled the visible setting will be automatically set to false when alpha is 0.0 and back to true when alpha is greater then 0.0.

This could be used when tweening the alpha value and the element should automatically become inactive once fully transparent.
Hotspot AttributeTypeDefault value
blending Boolean true
Set if the hotspot should be rendered during pano/scene blending.

When disabled and keep is false, then the hotspot will get instantly removed when loading another pano. When enabled, the hotspot will be kept and still be rendered during the blending and then removed when the blending is done.

For hotspots that are getting constantly updated (even during blending) and are independent of the pano/scene, this setting can be disabled to avoid side-effects.
Hotspot AttributeTypeDefault value
blendmode String "normal"
Hotspot blending / mixing mode.

Supported settings with WebGL rendering:
  • normal - normal blending, just draw over the pixels below.
  • add - additive blending: add the pixel values from the background or the hotspots below with the ones from the current hotspot image.
Hotspot AttributeTypeDefault value
alphachannel String "auto"
Setup the alpha-channel / transparency-channel usage and source for the hotspot.
For images and videos.

Usage case: there is currently no browser-support for transparent videos, so as alternative a video with the alpha-channel as extra image on the right (Side-by-Side) or at the bottom (Top-Bottom) can be used.

Available settings:
  • auto - The default, disable alpha-channel-support for JPEG images and videos and enable alpha-channel-support for all other image-file-formats (PNG, GIF, ...).
  • inline - Always enable the alpha-channel-support, but the input-image or video would need to provide one.
  • SBS - The input is a Side-by-Side (SBS) image or video with a grayscale-alpha-channel on the right.
  • TB - The intput is a Top-Bottom (TB) image or video with a grayscale-alpha-channel on the bottom.
  • none - Always disable the alpha-channel-support, even when the input-image would contain one.

Note - The setting need to set once on loading the image/video, changing it later at runtime will not work.

Here an Example with using a SBS-image and TB-video.

Only available for WebGL rendering.
Hotspot AttributeTypeDefault value
chromakey String
With the chromakey setting a certain color in the hotspot image or video can be used as alpha / transparency mask. The typical usage would be Greenscreen or Bluescreen videos.

Syntax:
chromakey="color,threshold,smoothing"
  • color - the chroma key color as hex-color (e.g. 0x238E54).
  • threshold - the masking threshold / cut-off range (0.0 to ~1.0).
  • smoothing - the smoothing of the masking (0.0 to ~1.0).

Here an Example with a helper-tool for finding the correct parameters.

Only available for WebGL rendering.
Hotspot AttributeTypeDefault value
mipmapping Boolean false
Should the hotspot image get mip-mapped during rendering (to avoid aliasing when being rendered in a scaled-down format).

When enabled, this works only when the pixel-sizes (width and height) of the hotspot image are power-of-two sizes (e.g. 256, 512, 1024, ...).

Only available for WebGL rendering.
Hotspot AttributeTypeDefault value
premultiplyalpha Boolean false
Multiply the alpha channel of the hotspot image into the color channels.
Will be mapped to the WebGL UNPACK_PREMULTIPLY_ALPHA_WEBGL setting.

Only available for WebGL rendering.
Layer AttributeTypeDefault value
safearea Boolean true
Should the layer be relative to the safe-area of the display or to the full-display-area.
Layer / Hotspot AttributeTypeDefault value
align String *
Alignment position / origin-point of the element.
For hotspots this setting has only affect when using flying.

Possible values: lefttop, left, leftbottom, top, center, bottom, righttop, right, rightbottom.

* The default value:
  • For layers: "lefttop"
  • For hotspots: "center"
Layer / Hotspot AttributeTypeDefault value
edge String *
Edge position / anchor-point of the element.

Possible values: lefttop, left, leftbottom, top, center, bottom, righttop, right, rightbottom or no value (empty string or null).

* The default value:
  • For layers: null - and when set to null, then automatically the value from the align setting will be used.
  • For hotspots: "center"
Layer AttributeTypeDefault value
x
y
String
String
"0"
"0"
The x, y position / offset of the layer.
  • The distance from the align point to the edge point.
  • For right/bottom aligned elements, the offset will be measured from the right/bottom side. This way the same value can be used to get the same offset from each edge to the inner area.
  • This can be absolute pixel values or relative percent values: x% is relative to the parent- or screen-width, y% = relative to the parent- or screen-height.
Hotspot AttributesTypeDefault value
ath
atv
depth
Number
Number
Number
0.0
0.0
1000.0
Spherical coordinates in degrees and a depth-distance in cm to define the position of the hotspot in 3D-space.

For normal panos the depth value could be ignored, but for stereo- or 3D-panos it can be used to define an actual 3D-position. The larger the depth value, the farther away the hotspot is.

For VR/stereo-rendering there exists a special case: when the hotspot should be drawn at 'infinity' distance without any stereo-separation (like a normal, non-stereo, non-depthmapped pano image), then an 'invalid' Number value (e.g. a String) need be used as the depth value, e.g. depth="off".

As alternative for using ath/atv+depth to define the 3D-position, it is also possible to set depth to 0.0 and then use the tx/ty/tz settings for defining an XYZ-based 3D-position.
Hotspot AttributesTypeDefault value
prealign
Boolean false
Apply the image.prealign rotation also to the hotspot.
Layer / Hotspot AttributesTypeDefault value
ox
oy
oref
String
String
int
"0"
"0"
2
An additional x, y position offset.
  • These values will be added to the current position.
  • Will be added before applying the layer rotation.
  • These settings can have absolute pixel values or relative percent values: x% is relative to the layer-width, y% = relative to the layer-height).

The oref setting defines the reference for the offsets (distorted hotspots only):
  • 1 - apply the ox/oy translation before the hotspot rx/ry/rz rotation.
  • 2 - apply the ox/oy translation after the hotspot rx/ry/rz rotation.
Hotspot AttributeTypeDefault value
torigin String "world"
The hotspot translation origin - that means to what reference the tx/ty/tz translation is relative to.

Available settings:
  • "world"
    • The hotspot position is a 'global' / 'world' one.
    • That means the position will be always the same one, regardless of the pano-image-position or the view-position.
  • "image"
  • "view"
    • The hotspot position will be relative to the current view-position.
Hotspot AttributesTypeDefault value
tx
ty
tz
Number
Number
Number
0.0
0.0
0.0
Hotspot 3D translation offsets (will be added to the spherical ath/atv/depth position).

For directly using an absolute 3D position set the depth setting to 0.0!
Hotspot AttributeTypeDefault value
twosided Boolean true
Should the hotspot be visible from both sides (front and back).
Relates to hotspots with a 3D position and/or 3D rotations.
Hotspot AttributeTypeDefault value
flying Number 0.0
Let the hotspot 'fly' from its current pano/3D-position (0.0) to a screen-space-based position and projection (1.0).

The 'flying'-hotspot will get aligned at the given align position.

WebVR notes: in VR the the flying will always get aligned in the center, because there are no 'edges' or 'screen-borders' in VR.
Hotspot AttributeTypeDefault value
scaleflying Boolean true
Scale the hotspot from 'pano-space-size' to 'screen-space-size' when flying out.

WebVR notes: for VR usage it would be recommended to disable that setting, because in VR there is no real 'screen-space' or 'screen-size'.
Layer / Hotspot AttributeTypeDefault value
width
height
String
String
null
null
The size of the element:
  • This can be either an absolute pixel value or a relative (to the screenwidth or screenheight) percent value.
  • When not set, then the size will be determined automatically:
    • by using the size of the loaded image or video,
    • or by using the size of the text/content (for textfields/html-layers).
    • or by using the requiered space for flowing children layers (when using flowchildren=true).
  • Negative values - when using negative values as size, then the resulting size will be the size of the parent element (or the size of the stage when there is no parent) minus the given negative value.
  • Additionally it's possible to use the special value "prop" to scale an image via width or height by keeping it proportions (e.g. set width or height to a value and the other setting to "prop" - width="500" height="prop").
Layer / Hotspot AttributeTypeDefault value
autowidth
autoheight
Boolean
Boolean

Explicitly set if auto-sizing should be used,
or check if auto-sizing is currently used.
Layer / Hotspot AttributeTypeDefault value
minwidth
maxwidth
minheight
maxheight
Number
Number
Number
Number
0
0
0
0
Limit the resulting element size.

Only absolute pixel values are possible for these settings. When the value for a min/max setting is 0, it will be disabled/ignored. Dynamic changes of these settings will not trigger an instant update of the element.
Layer / Hotspot Variable (read only)TypeDefault value
loaderwidth
loaderheight
int
int
These variables contain the original unscaled pixel size of the loaded url image.
These information are first available after the onloaded event.
Layer / Hotspot Variables (read only)TypeDefault value
sourcewidth
sourceheight
int
int
These variables contain the original unscaled pixel size for the element.
This can be size of a cropped-image or the size from a container element.
These information are first available after the onloaded event.
Layer / Hotspot Variables (read only)TypeDefault value
pixelwidth
pixelheight
Number
Number
These variables contain the final pixel size of the element (within the scaling of its parent element).

Note - these values don't get updated immediately when changing any related variables, the update happens after a redraw (e.g. in the next frame) or when manually calling display.layout.update().
Layer Variables (read only)TypeDefault value
pixelx
pixely
Number
Number
These variables contain the final pixel position of the element (within the scaling of its parent element).

Note - these values don't get updated immediately when changing any related variables, the update happens after a redraw (e.g. in the next frame) or when manually calling display.layout.update().
Layer Variables (read only)TypeDefault value
stagex
stagey
Number
Number
Get the left-top pixel-position on the screen.

Note - these values don't get updated immediately when changing any related variables, the update happens after a redraw (e.g. in the next frame) or when manually calling display.layout.update().
Layer / Hotspot AttributeTypeDefault value
scalemode String "scale" *
Define the behavior of the scale settings:
  • scale - scale the element and its children (when scalechildren is enabled). In this case the borders, text-sizes, shadows and so on will become larger/smaller.
  • resize - instead of scaling, resize the element - similar to changing the width/height. With this setting all scale related elements will stay the same, only the area of the element will change.

Note - the default value depends on the version set in the xml! When the version is 1.21 or higher, then the default is "scale". For older xml files the default is "resize".
Layer / Hotspot AttributeTypeDefault value
scale
scalex
scaley
Number
Number
Number
1.0
1.0
1.0
Scaling of the element.
Use scale to set the scale for the x and y axis at once or scalex and scaley to set them individually.
Layer Variables (read only)TypeDefault value
childscalex
childscaley
Number
Number
The scaling that will get applied to children layer elements.

Depends on the combined scale and scalechildren settings from all parent layers.

Could be used e.g. via parentobject.childscalex to convert screen-based x/y coordinates or sizes to layer relative ones.
Hotspot AttributeTypeDefault value
zoom Boolean false
Change the size of the hotspot when zooming or keep a fixed/absolute size?
Hotspot AttributeTypeDefault value
distorted Boolean false
Should the hotspot image be distorted in the 3D space together with the current pano/viewing distortion. When distorted use the rotationorder and rx / ry / rz settings to rotate the hotspot in 3D space.

Note - When enabled, a size of 1000 pixels will be used as reference for pixel sizes. And this 1000 pixels are covering a field of view of 90 degrees in 3D space.
Layer / Hotspot AttributeTypeDefault value
rotate Number 0.0
Rotation of the element in degrees.
The rotation is done around the edge point.
Hotspot AttributeTypeDefault value
rotationorder String "yxz"
Define the order of the distorted hotspot 3D rx / ry / rz rotations.
Hotspot AttributeTypeDefault value
rx
ry
rz
Number
Number
Number
0.0
0.0
0.0
3D rotation for distorted hotspots in degrees over the X / Y / Z axes.
The order of the rotations can be defined by the rotationorder setting.
Hotspot AttributeTypeDefault value
inverserotation Boolean false
Inverses the rotation and the axis order of the rx / ry / rz settings.
Layer / Hotspot AttributeTypeDefault value
gridfit String *
Pixel-grid-fitting.

When enabled, the pixel positions and sizes will be rounded to the nearest full pixel coordinates. This can avoid a blurry displaying, especially when the coordinates, sizes or scales are not integer values.

Typically pixel-grid-fitting is recommended, but for smoother animations (especially zooming/scaling animations) it can be better to disable it.

Possible settings (*):
  • true (default for layers) - always fit to the pixel-grid.
  • false - no pixel-grid fitting.
  • "auto" (default for hotspots) - automatically use pixel-grid fitting when the zoom and distorted settings are disabled or when flying is set to 1.0.

Note - some browsers don't support sub-pixel-precise coordinates and therefore automatically do a kind of pixel-grid-fitting.
Layer AttributeTypeDefault value
gpu Boolean true
When enabled (the default) the resulting position on the screen will be set by CSS transforms. That should allow hardware-accelerated rendering and be also faster to calculate by the browser because this doesn't cause HTML layout changes.

When disabled, the resulting position will by set by CSS left/top absolute position settings. Rotation and scaling will be not supported in this case.
Hotspot AttributeTypeDefault value
stereo String
Define if the hotspot image is a stereoscopic image (WebGL only).

Possible settings:
  • no value - not a stereo image (default)
  • SBS - Side-by-Side image (left-half = left-eye image, right-half = right-eye image)
  • TB - Top-Bottom image (top-half = left-eye image, bottom-half = right-eye image)
Hotspot AttributesTypeDefault value
depthbuffer
depthwrite
Boolean
Boolean
false
true
depthbuffer - use the depth-buffer for the hotspot-rendering (WebGL only).

When enabled the hotspots can intersect with other hotspots (that also have depthbuffer=true) and the 3D-model/depthmap-geometry.

depthwrite - additionally to checking for the depth-intersection also write the resulting new depth of the hotspot to the depthbuffer. Can be used for decals that were rendered on top of something else but shouldn't change the depthbuffer itself.

Note - depth-buffered hotspot-rendering is only possible when using Depthmap-panos or enabling the display.depthbuffer setting.
Hotspot AttributesTypeDefault value
depthoffset
Number 0.0
Add an 'offset' to the rendering-depth.
This can be used to render a hotspot above (or behind) a 3D-model, even when they use the same 3D-space.
Layer / Hotspot AttributeTypeDefault value
crop
onovercrop
ondowncrop
String
String
String
Crop / cut out a rectangular area of the source image. Usefull to use only one single image for serval image elements.
onovercrop / ondowncrop - different crop areas for mouse over and mouse button down states.

Syntax:
crop="x-position|y-position|width|height"
Layer / Hotspot AttributeTypeDefault value
scale9grid String
Defines a grid in pixel coordinates that splits the image into 9 segments. And when scaling the element via the width / height values, the 'edge' segments will be kept unscaled and only the 'middle' segments will be scaled.

Syntax:
scale9grid="x-position|y-position|width|height|prescale*"
  • x/y-position - the start x/y pixel-position of the inner-box
  • width/height - the pixel-size of the inner-box
  • prescale - an optional scaling setting to pre-scale the base-image itself
Layer / Hotspot AttributeTypeDefault value
bg Boolean true
Use a background shape (only for containers and textfields).
Setting bg=false is the same as setting bgalpha to 0.0.
Layer / Hotspot AttributeTypeDefault value
bgcolor int 0x000000
Background color for containers and textfields.
Layer / Hotspot AttributeTypeDefault value
bgalpha Number 0.0 / 1.0
Alpha transparency of the background color.
The default it 0.0 for container layers and 1.0 for textfield layers.
Layer / Hotspot AttributeTypeDefault value
bgborder
bgbordermode
bgborderblend
String
String
Boolean
"0"
"outside"
true
Add borders around the element.

Syntax:
bgborder="widths color alpha style"

Parameters:
  • widths
    The border line-widths. This can be either just one size value for all sides or a comma separated list of values to define different widths for each side.
    There are four way to set the widths:
    • 1 value ⇒ use the same width for all sides.
    • 2 values: 1,2 ⇒ 1=Top&Bottom, 2=Left&Right width.
    • 3 values: 1,2,3 ⇒ 1=Top, 2=Left&Right, 3=Bottom width.
    • 4 values: 1,2,3,4 ⇒ 1=Top, 2=Right, 3=Bottom, 4=Left width.
    The default is 0, which means no border at all.
  • color (optionally)
    The color of the border lines. The default is 0x000000 (black).
  • alpha (optionally)
    Alpha transparency of the border lines (0.0 to 1.0), the default is 1.0.
  • style (optionally)
    The CSS border-style for the border line. This can be either just one value for all sides or a comma separated list of values to define different style for each side (same as for the widths). The default is solid.

Additional settings:
  • bgbordermode - where to add the border:
    • outside (default) - add the border to the outside of the layer. The layer will appear larger than its given width/height.
    • inside - add the border inside the layers given size.
  • bgborderblend - how to blend the border with the layer background:
    • true (default) - blend the border color/alpha with the background color/alpha. That basically means draw the border over the background.
    • false - the border color/alpha will be fully separate from the background color/alpha, no blending/mixing.
Layer / Hotspot AttributeTypeDefault value
bgroundedge String "0"
Define rounded edges for the element.
A value sets the edge rounding radius in pixels.

Four values can be set, one for each edge (separated by space characters). They are given in the order: top-left, top-right, bottom-right, bottom-left. If bottom-left is omitted, it is the same as top-right. If bottom-right is omitted, it is the same as top-left. If top-right is omitted, it is the same as top-left.
Layer / Hotspot AttributeTypeDefault value
bgshadow String
Add a shadow behind the element.

Basic Syntax (5 parameters):
bgshadow="xoffset yoffset blur color alpha"

Advanced Syntax (6 or more parameters):
bgshadow="xoffset yoffset blur spread color alpha inset, ..."

Parameters:
  • xoffset, yoffset
    The offset / distance of the shadow in pixels.
  • blur
    The blur radius / range in pixels - defines how strong the shadow will be blurred.
    0 = no blur ⇒ sharp edges.
  • spread (Advanced Syntax)
    Spreading of the shadow in pixels - expand (positive values) or shrink (negative values) the shadow.
  • color
    The color of the shadow.
  • alpha
    The alpha / transparency of the shadow.
  • inset (Advanced Syntax, optionally)
    When the text "inset" will be added as last parameter, then the shadow will be an inner shadow instead of an outer shadow.
  • ... (Advanced Syntax, optionally)
    Add another shadow (comma separated).
Layer / Hotspot AttributeTypeDefault value
bgcapture Boolean false
Capture user events on the background shape.

This would need to be enabled to make an container element itself active and clickable.
Layer AttributeTypeDefault value
bgbrightness
bgcontrast
bgsaturate
bghue
bginvert
bgsepia
bgblur
Number
Number
Number
Number
Number
Number
Number
1.0
1.0
1.0
0.0
0.0
0.0
0.0
Background Filters (CSS Backdrop Filters)

Apply graphical effects such as blurring or color shifting to the area behind the element. Because it applies to everything behind the element, to see the effect the background must be at least partially transparent (see bgalpha).
Hotspot AttributeTypeDefault value
polyline Boolean false
Draw a line-polygon instead a filled-polygon.
The start and end points will not be joined.
Hotspot AttributesTypeDefault value
fillcolor
fillalpha
int
Number
0xAAAAAA
0.5
The fill-color and alpha (transparency) of a polygonal hotspot area.
Hotspot AttributesTypeDefault value
borderwidth
bordercolor
borderalpha
Number
int
Number
3.0
0xAAAAAA
1.0
The width, the color and the alpha (transparency) of a polygonal hotspot border line.
Hotspot AttributeTypeDefault value
bordergradient String
Colorize the border with a gradient.

Syntax:
bordergradient="0xFFFF0000|0x0000FF00|0xFF0000FF|1.0"
  • Three colors (inner-side, middle, outer-side) in ARGB hex-format (0xAARRGGBB).
  • And an optional factor for curving the gradient, e.g. 1.0=a linear gradient, 2.0=cubic curve gradient, ...
Hotspot AttributeTypeDefault value
borderzoom Number 0.0
Should the borderwidth line zoom/scale when zooming in the pano?
  • When set to 0.0, no scaling appears on zooming.
  • With a value higher than 0.0, the line with scale on zooming and additionally get scaled by the given value.
Hotspot AttributeTypeDefault value
borderwidth3d Boolean false
Should the borderwidth change itself depending its the 3D-position.
Hotspot AttributeTypeDefault value
borderhittest Boolean false
Should the border line also be used for hit-testing?
By default this is disabled for performance reasons and should be only enabled for hotspots that especially need this.
Hotspot AttributeTypeDefault value
subdiv Boolean false
Enable or disable sub-division of the polygonal shape.
Sub-division will be necessary when using distorted projections (fisheye/stereographic views). Disabling can slightly improve the initial setup time for the hotspot when using very large polygons.
Hotspot AttributeTypeDefault value
point.count int 0
Number of polygon points.
Hotspot Point AttributesTypeDefault value
point[...].ath
point[...].atv
Number
Number
Spherical coordinates in degrees for a polygonal hotspot point.
Hotspot Point AttributesTypeDefault value
point[...].x
point[...].y
point[...].z
Number
Number
Number
3D coordinates for a 3D polygonal hotspot point.

Notes:
  • When x, y, z values will be set, the hotspot automatically becomes a 3D polygonal hotspot. Using the ath, atv values the same time is not possible.
  • For filled polygons (polyline=false) all points together should roughly form/define a flat plane in 3D space. The result will be in all cases a flat-plane, non-flat 3D-polygons are not supported.
Hotspot AttributesTypeDefault value
points
points3d
String
String
An alternative and shorter way to define the points for polygonal hotspots.

Spherical coordinates:
points="h,v,h,v,h,v,..."

3D coordinates for a 3D polygonal hotspots:
points3d="x,y,z,x,y,z,x,y,z,..."
Layer / Hotspot AttributeTypeDefault value
krpanobgcolor int
Set a background color as hex-color value (e.g. 0xFFFFFF for white) for an embedded krpano viewer (type=krpano).

By default (when this setting is not set) a transparent background is used.
But when transparency is not required, a background color should be set!
A non-transparent background allows faster rendering and requires fewer GPU memory. Additionally a non-transparent background allows using all pano-blending-modes.
Layer VariableTypeDefault value
krpanoembedsettings Object
An object with additional Embedding Parameters for embedded type=krpano layers.
Can be only used by Javascript.

Example (Javascript) - disable WebGL:
var layer = krpano.addlayer();
layer.type = "krpano";
layer.krpanoembedsettings = {webgl:false};
...
Layer / Hotspot Variable (read only)TypeDefault value
krpano Object null
The direct krpano API of a krpano layer.
Layer / Hotspot AttributeTypeDefault value
iframeurl String
The iframe url for an iframe layer.
Layer / Hotspot Variable (read only)TypeDefault value
iframe HTML-Element null
The iframe html-element of an iframe layer.
Layer / Hotspot AttributeTypeDefault value
html String
The raw html code string for a html layer.
Layer / Hotspot AttributeTypeDefault value
htmlautosize Boolean false
Should the layer automatically resize itself depending on the html content?
Layer / Hotspot AttributeTypeDefault value
htmloverflow String "hidden"
Html layer content overflow.

Settings:
  • "hidden" - overflowing content is hidden (the default).
  • "auto" - automatically show scroll-bars when the content is overflowing.
  • "scroll" - always show the scrollbars.
  • "xscroll" - always show the horizontal scrollbar.
  • "yscroll" - always show the vertical scrollbar.
  • "visible" - show the overflowing content.

Note - can be only used when htmlautosize is set to false.
Layer / Hotspot Variable (read only)TypeDefault value
htmlelement HTML Element
The html-element of a html layer.
Layer / Hotspot Variable (read only)TypeDefault value
rawEvent Event Object
The rawEvent Object provides access to the original Javascript Event that was sent by the browser when a certain event get triggered (for usage in Javascript code).

E.g. a layer onclick event could be caused by a Javascript mouseup Mouse-Event or by touchend or pointerup Touch-Events or even a WebXR select Event when triggered by a VR-conroller.

This could be used for checking additional properties, e.g. like if the shiftKey is currently also pressed when clicking somewhere.

Note - when there is no actual browser event, e.g. for 'synthetic' over/out events for WebGL hotspots, then the rawEvent object is set to null.
Layer / Hotspot Variable (read only)TypeDefault value
loading Boolean false
A boolean variable that indicates that the given url file is still loading.
Layer / Hotspot Variable (read only)TypeDefault value
loadedBooleanfalse
A boolean variable that indicates that the given url file has been loaded.
Layer / Hotspot Variable (read only)TypeDefault value
loadedurl String
The parsed full url of the currently loaded url file.
Layer / Hotspot Variable (read only)TypeDefault value
hovering Boolean false
Is the mouse cursor currently over the element?
Layer / Hotspot Variable (read only)TypeDefault value
pressed Boolean false
Was the mouse-button or the touch-screen pressed on the element and is still pressed?
Layer / Hotspot Variables (read only)TypeDefault value
hitx
hity
hitd
Number
Number
Number


The relative 'hit-point' of the mouse or touch-point inside the element when hovering or pressing it. The value range for hitx and hity is from 0.0 to 1.0 and from top-left to bottom-right.

The variable hitd is the 3D-distance from the hit-point to the screen (hotspots only).

Limitation: The hitpoint information are only available for layers and for WebGL-rendered hotspots (not for CSS3D-rendered hotspots).
Layer / Hotspot AttributeTypeDefault value
onoverAction Event
Actions / functions that will be called when the mouse moves over the element.
Layer / Hotspot AttributeTypeDefault value
onhoverAction Event
Actions / functions that will be called in intervals (once per frame) when the mouse stays over (hovers) the element.
Layer / Hotspot AttributeTypeDefault value
onoutAction Event
Actions / functions that will be called when the mouse moves out of the element.
Layer / Hotspot AttributeTypeDefault value
onclickAction Event
Actions / functions that will be called when there is a mouse click or touch on the element.
Layer / Hotspot AttributeTypeDefault value
ondownAction Event
Actions / functions that will be called when the mouse-button or the touch-screen will be pressed down on the element.
Layer / Hotspot AttributeTypeDefault value
onupAction Event
Actions / functions that will be called when the previously pressed mouse-button or touch-screen will be released.
Layer / Hotspot AttributeTypeDefault value
onwheelAction Event
Actions / functions that will be called when using the mouse-wheel over the element.

The delta of the mouse-wheel usage will be stored in the wheeldelta and wheeldelta_raw variables.

See also the capturewheel setting.
Layer / Hotspot AttributeTypeDefault value
ontabindexAction Event
This event will be called when layer has a tabindex setting, got focused by using the Tab-key and then the Enter-key is pressed.

When this event is not set, then the normal ondown (as long as holding the Enter key) and onup and onclick (when releasing the Enter key) events are called instead.
Layer / Hotspot AttributeTypeDefault value
onfocus
onblur
Action Event
Action Event
Actions / functions that will be called when the elements gets or loses the focus.
Only for elements that have a tabindex set or for editable-textfields.
Layer / Hotspot AttributeTypeDefault value
onloadedAction Event
Actions / functions that will be called when either the loading of the url is done or when the layer is ready for usage.
Layer / Hotspot AttributeTypeDefault value
onresizeAction Event
Actions / functions that will be called when the size of the element has been changed.
Layer AttributeTypeDefault value
onlayoutAction Event
Actions / functions that will be called when the layout (position, size, scale, ...) of the layer has been changed.
Layer / Hotspot Variable (read only)TypeDefault value
loaderHTML Imagenull
A HTML Image element.
Only when url is set to an image file and that image is loaded.
Layer / Hotspot Variable (read only)TypeDefault value
spriteHTML Elementnull
HTML DOM element (div) of the layer element.
Layer Variable (read only)TypeDefault value
parentobjectlayernull
A direct reference to the parent layer or hotspot object.
Only available when a parent setting is set.
Layer / Hotspot Variable (read only)TypeDefault value
childobjectsArray[]
A Value Array of layers that were added as children elements to this layer.
Add additional events
As xml attribute:
eventname.addevent="eventcode"
As dynamic call from actions:
layer[name].addevent(eventname, eventcode)
hotspot[name].addevent(eventname, eventcode)
Add additional events beside the normal ones.

This can be especially helpful when using <style> elements and defining independent events there. So it's possible to use the events from style and also the own ones.

Example - when clicking the layer both events will be called:
<style name="teststyle"
       ...
       onclick.addevent="trace('onclick from the style');"
       />

<layer name="test"
       style="teststyle"
       ...
       onclick="trace('onclick from the layer');"
       />

Action / Javascript usage:
When adding events dynamically, the eventcode can be either Action code or a Javascript function. Some events, like mouse or keyboard events, will provide the original Javascript Event object as rawEvent property and also as argument for the Javascript callback function.

Javascript example:
var layer = krpano.addlayer();
...
layer.addevent("onclick", function(event){ ... });
Layer / Hotspot FunctionType
removeevent(eventname, eventcode) Action
Remove an event listener.
Layer / Hotspot FunctionType
triggerevent(eventname) Action
Trigger and process the given event on the element (the direct assigned one and the ones added by addevent).

Parameter:
  • eventname
    • The name of the event, e.g. 'onclick'.
Return:
  • When called by Javascript, the function returns true or false, depending if the event was actually handled.
Layer / Hotspot FunctionType
loadstyle(styles)Action
Copy/load the attributes from one or more <style> elements.

Parameter:
  • styles
    • The name of a <style> element.
    • Several style names can be to combined by a | character.
Layer / Hotspot FunctionType
registercontentsize(width,height)Action
The registercontentsize action can be used to set / register the 'original / source / unscaled' size of the element.

For Javascript Plugins that want to draw custom stuff this function call is necessary to set the source size because Javascript Plugins don't have any information about their size by default.
Layer / Hotspot FunctionType
resetsize()Action
An action to set the width and height values back to the source size of the loaded image. This can be used after changing the url value to get the size of the new loaded image.
Layer FunctionType
changealign(align,edge)Action
An action to change the alignment and edge of a layer element without changing its current position. The x/y values will be recalculated to keep the current position.
Layer / Hotspot FunctionType
remove(removechildren*)Action
Removes the layer element.

Parameter:
  • removechildren (optionally)
    • true - remove also all children elements (default).
    • false - remove only the current element. The parent setting from all children elements will be automatically set to null in this case.

The same as a removelayer(name, true) call.
Hotspot FunctionType
p = hotspot.getcenter()Action
The function returns the center (in spherical coordinates) of a polygonal hotspot.
The returned object has x,y,z properties, where x ≘ ath, y ≘ atv and z ≅ fov.
Hotspot FunctionType
n = hotspot.getnormalvec()Action
The function returns the normal vector of the hotspot (only for distorted hotspots).
The returned object has x,y,z properties.
<events>
The krpano events - they can be used to call actions or functions when something particular happens.

There are these types of events:
  • The global krpano events
    These are the events that were defined in <events> elements without a name attribute. There can be always only one global event. When there is another <events> element in the xml with the same event actions defined, then the previously defined events were overwritten.
  • Independent local krpano events
    When an <events> element in the xml will be defined with a name attribute - then this will be an 'independent' events element. It can contain any of the events, but they will not overwrite the global events.
    These 'named' <events> elements have also a keep attribute (with the default value "false"). That means <events> elements without keep="true" will be automatically removed when an other pano/scene will be loaded.
  • Javascript event callbacks
    By using the events.addListener() and events.removeListener() functions it's also possible to use direct Javascript function callbacks.


Predefined events:
<events onenterfullscreen=""
        onexitfullscreen=""
        onxmlcomplete=""
        onpreviewcomplete=""
        onloadcomplete=""
        onblendstart=""
        onblendcomplete=""
        onnewpano=""
        onremovepano=""
        onnewscene=""
        onxmlerror=""
        onloaderror=""
        onkeydown=""
        onkeyup=""
        onclick=""
        onsingleclick=""
        ondoubleclick=""
        ondown=""
        onup=""
        onwheel=""
        ongesture=""
        oncontextmenu=""
        onidle=""
        onframe=""
        onviewchange=""
        onviewchanged=""
        onviewloaded=""
        onviewreloading=""
        onresize=""
        onframebufferresize=""
        ondisplaystereochange=""
        oncreateelement=""
        ondestroyelement=""
        onparentchange=""
        onlayoutgraphchanged=""
        onautorotatestart=""
        onautorotatestop=""
        onautorotateoneround=""
        onautorotatechange=""
        oniphonefullscreen=""
        gyro_onavailable=""
        gyro_onunavailable=""
        gyro_onenable=""
        gyro_ondisable=""
        webvr_onavailable=""
        webvr_onunavailable=""
        webvr_onunknowndevice=""
        webvr_onentervr=""
        webvr_onexitvr=""
        />


Local events: (by using 'named' <events> elements)
<events name="..." keep="false"
        ... any events ...
        />


Custom Events:
  • Additionally to the predefined events also customs events can be added, just by adding a custom attribute with the desired eventname
  • For dispatching them the events.dispatch('eventname') action can be called.
Variable nameTypeDefault value
events[...].name String
  • When a name attribute will be defined then this events element will be an independent local events element.
  • Without name attribute the global events were set.
Variable nameTypeDefault value
events[...].keep Boolean false
  • Should this named <events> element be kept or removed when loading a new pano or scene.
  • See also the notes in the loadpano() action.
Variable nameType
events.onenterfullscreen Action Event
  • This event will be called when switching to fullscreen mode.
Variable nameType
events.onexitfullscreen Action Event
  • This event will be called when switching back from the fullscreen mode to the normal window mode.
Variable nameType
events.onxmlcomplete Action Event
  • This event will be called when the loading of the xml file or the xml code of scene was completed.
  • After this event the user-control, the pano-viewing and the dynamic loading of the pano images will start.
Variable nameType
events.onpreviewcomplete Action Event
  • This event will be called when the loading of the preview image was completed.
Variable nameType
events.onloadcomplete Action Event
  • This event will be called when the loading of the pano image is done.
  • When using multi-resolution images, then this event will be called once when all parts for the current-view were loaded completely.
Variable nameType
events.onblendstart Action Event
  • This event will be called when the blending from one pano to the next one starts.
  • Additionally the blendtime variable will be set to the given value of the BLEND(blendtime) parameter in the preceding loadpano/loadscene/... call.
Variable nameType
events.onblendcomplete Action Event
  • This event will be called when the blending from one pano to the next is done.
Variable nameType
events.onnewpano Action Event
  • This event will be called when there is a new pano image and all information about it (type, imagesize, hfov, vfov) are available.
Variable nameType
events.onremovepano Action Event
  • This event will be called when the current pano will be removed (e.g. before a new pano will be loaded).
Variable nameType
events.onnewscene Action Event
  • This event will be called when a new scene will be loaded (similar to the onxmlcomplete event but only for scenes).
Variable nameType
events.onxmlerror
events.onloaderror
Action Event
Action Event
  • These events will be called on errors:
    • The onxmlerror event will be called on xml-loading or xml-parsing errors,
    • and the onloaderror event on image-loading errors (all kind of images: pano, layer or hotspot images).
  • When an event will be not set, then the default error processing will be done - that means a fatal-error on xml-errors and an error message in the krpano log on image-errors.
  • By using the onxmlerror event and some custom error handling, it would be still possible to continue using the viewer on an xml-error.
  • The error message will be stored in the lasterror variable.
Variable nameType
events.onkeydown Action Event
  • This event will be called when a key is pressed down.
  • They keycode of the pressed key will be stored in the keycode variable.
  • When a key will be hold pressed down, then the system automatically sends repeating onkeydown events. This could be optionally disabled with the control.keydownrepeat setting.
Variable nameType
events.onkeyup Action Event
  • This event will be called when a pressed key is released.
  • They keycode of the released key will be stored in the keycode variable.
Variable nameType
events.onclick Action Event
  • This event will be called when there was a mouse click in the pano.
Variable nameType
events.onsingleclick
events.ondoubleclick
Action Event
Action Event
  • Special events for single / double click detection.
  • Different to the normal onclick event (which will be fired instantly on every click) the onsingleclick event can be delayed a bit (up to ~400ms) because it checks if there might be a second click for detection as double-click.
  • There can be either:
    • One single-click event (delayed a bit compared to a normal onclick event).
    • Two single-click events - when the mouse was moved too far between the two clicks.
    • One double-click event - when there were two quick clicks and almost no mouse-movement between them.
  • The mouse.clickx and mouse.clicky variables are storing the coordinates of the mouse where the last click had happened.
  • Touch usage is also supported (e.g. 'tap' and 'double-tap').
Variable nameType
events.ondown Action Event
  • This event will be called when the mouse-button or the touch-screen will be pressed down in the pano view.
Variable nameType
events.onup Action Event
  • This event will be called when the previously pressed mouse-button or touch-screen was released.
Variable nameType
events.onwheel Action Event
  • This event will be called when the mouse-wheel was used or when the pano was zoomed by a touch zoom-gesture.
  • The delta of the mouse-wheel usage will be stored in the wheeldelta and wheeldelta_raw variables.
  • On touch devices there is no real mouse-wheel, but this event will be called too when using the 2-finger zooming gesture. The wheeldelta variables will be set to positive or negative values depending if zooming in or out. The wheeldelta_touchscale variable will provide more detailed information about the gesture zooming in this case.
Variable nameType
events.ongesture Action Event
  • This event will be called when doing a multi-touch gesture, like a scaling- or rotation-gesture with two-fingers.
  • Details about the event will be available in the gesture object.
  • Only available on multi-touch devices.
Variable nameType
events.oncontextmenu Action Event
  • This event will be called before the contextmenu will be opened and could be used to modify the contextmenu items (e.g. changing the caption or the onclick action) before displaying to match the current situation or need.
Variable nameType
events.onidle Action Event
Variable nameType
events.onframe Action Event
  • This event will be called once per frame (before layout-calculations and before the rendering) .
  • Note - use this event carefully, when doing too much stuff there it can affect the rendering/execution performance!
Variable nameType
events.onviewchange Action Event
  • This event will be called every time when the current view has been changed or when the pano will be rendered / redrawn.
  • The evaluation of the view settings and the applying of the viewing limitations settings is not done at this event. That means in this event it's still possible to make changes to the view before the final rendering.
  • Note - use this event carefully, when doing too much stuff there it can affect the rendering/execution performance!
Variable nameType
events.onviewchanged Action Event
  • This event will be called every time when the current view had been changed or when the pano had been rendered / redrawn.
  • Note - use this event carefully, when doing too much stuff there it can affect the rendering/execution performance!
Variable nameType
events.onviewloaded
events.onviewreloading
Action Event
Action Event
  • Events to check the state of loading for the current view.
  • The onviewloaded event will be called when all images/tiles that are required to fill the current view area with the best/optional resolution are loaded.
  • The onviewreloading event will be called when the view has changed and additional images/tiles need to be loaded and that loading has started.
Variable nameType
events.onresize Action Event
  • This event will be called when the size of the viewer (or the size of the area) has been changed.
  • Additionally the onresize event will be called every time when loading a new pano (e.g. to allow custom user-interface updates).
  • The new viewer size will be stored in the stagewidth and stageheight variables.
  • The size of the new area size will be available via the area.pixelwidth and area.pixelheight variables.
Variable nameType
events.onframebufferresize Action Event
  • In some cases only the size of the internal rendering framebuffer gets changed (e.g. when changing the framebufferscale setting or the oversampling setting in VR) - and in such case the normal onresize event might not be dispatched.
  • So this event will be called always when the size of the rendering framebuffer has been changed.
Variable nameType
events.ondisplaystereochange Action Event
  • This event will be called when the stereo rendering gets enabled or disabled.
Variable nameType
events.oncreateelement
events.ondestroyelement
Action Event
Action Event
  • These events will get called when a new layer or hotspot gets created or destroyed.
  • Can be used to automatically add custom properties and functions to new elements.
  • When calling Action code, the current element will be current scope and its properties are directly accessible.
  • When calling a Javascript function, the current element will be passed as argument.
Variable nameType
events.onparentchange Action Event
  • This event will get called when the parent of a layer gets changed.
  • When calling a Javascript function, the affected element will be passed as argument.
Variable nameType
events.onlayoutgraphchanged Action Event
  • Will be called when the layout-graph structure gets changed.
  • That means when adding or removing layers/hotspots or when changing the parent / childorder settings.
  • The event will be called only once per frame.
Variable nameType
events.onautorotatestart Action Event
  • This event will be called when when the automatic rotation starts.
  • E.g. when the autorotate.enabled setting is enabled and there was autorotate.waittime long no user interaction or when the autorotate.start() action was called.
  • It could be used to show a special kind of auto-tour-mode user-interface (or e.g. hide the normal user-interface).
Variable nameType
events.onautorotatestop Action Event
  • This event will be called when the automatic rotation stops.
  • Typically when the user interrupts the rotation or when the autorotation gets disabled or stopped.
  • It could be used to restore everything that was changed in onautorotatestart.
Variable nameType
events.onautorotateoneround Action Event
  • This event will be called when:
    • one 360 degree pan around (for 360x* panos, customizable),
    • or one left-right-pan for partial or flat panos was be made.
  • That could be used to switch to the next pano in the tour - e.g. for 'automatic tours'. This can look nice when using the KEEPMOVING flag to blend between the panos during the automatic rotation.
Variable nameType
events.onautorotatechange Action Event
  • This event will be called when the autorotate.enabled setting has been changed.
  • Could be used to update the state of the autorotate-button.
Variable nameType
events.oniphonefullscreen Action Event
  • This event will be called when the state of the iPhone Safari-browser landscape fullscreen mode has been changed.
  • Information about the current state are available by the display.iphonefullscreen variable.
<action>
With <action> elements it's possible to define krpano actions.
These actions are similar to functions or procedures in other scripting or programming languages.

The actions can be called from everywhere - from events, from other actions or also from external sources (Javascript, Plugins) via the call interface.

There are two kind of action types:
Normal krpano actions
<action name="..." scope="" args="" autorun="">
    action1();
    action2();
    ...
</action>
Inside a normal <action> element a sequence of krpano action calls can be placed. These action calls will be executed one after the other when the action gets called.

See here for the syntax and calling conventions of krpano actions:
The calling conventions of krpano actions / functions

Argument / Parameter passing / resolving

When calling an action it's possible to pass arguments / parameters to it.

For accessing the arguments / parameters there are two possibilities:
  1. by placeholder-replacing: (older version method)
    • To get the given parameters in the action code numeric placeholders in the form from %0 to %99 can be used.
    • Where %0 is the name of the action itself, %1 the first parameter, %2 the second parameter and so on.
    • These placeholders can be used anywhere and anyhow in the code.
    • Before the actual action code will be parsed and executed, all placeholders will be replaced by their parameter values.
    • When there will be no parameter for a given placeholder, the value 'null' will be used.
    • To use the % character in the action, %% need to be used.
  2. by argument-to-variable-mapping: (recommended, new)
    • For actions with a local scope an args attribute can be added to the <action> element. For example:
      <action ... args="var1, var2, var3">
    • In that args attribute variables names for the given action arguments / parameters can be defined (separated by commas).
    • Each action argument will be mapped to a new variable in the local scope with the name that was set in the args attribute.
    • These variables can be used normally like any other variables in the action code (e.g. read via get / calc / copy).
    • When there will be no action argument for a given variable, the value 'null' will be used for it.
    • Using the variable-mapping can be very useful when working with values that contain quote or comma characters. The normal placeholder-replacing can be problematic in such cases.
Note - it would be recommend to use the argument-to-variable-mapping where possible. Actions without %N placeholders can be internally cached, which makes the execution of further calls faster.


Javascript krpano actions
<action name="..." type="Javascript" autorun=""><![CDATA[
    ...
    Javascript code
    ...
]]></action>
With Javascript actions it's possible to use directly Javascript code for the action code. This can be faster for more complex things.

Inside a Javascript <action> these objects and functions are predefined:
  • krpano - the krpano Interface object.
  • args[] - an array with the passed arguments (args[0] = the name of the action, args[1] = first parameter, ...).
  • caller - the object of the <layer>, <plugin> or <hotspot> element that has called that action.
  • resolve(str) - a function for resolving / getting the value of a krpano variable/path. It works like the default krpano variable resolving - when the given variable/path exists, then the value will be returned, and when not, then the passed value will be returned as it is.
  • actions - an object for accessing the built-in native krpano actions (e.g. call actions.tween(...); to call the tween action);

By default errors in the Javascript-code will be captured by krpano and print to the krpano log. To be able to debug the Javascript-code the debugjsactions setting can be set to true, then krpano will not capture the error and the browser will report it.

Variable nameTypeDefault value
action[name].name String
Name of the action. (see the name notes)
When no name will be set, an automatic generated name will be used (e.g. could be used for autorun actions that will never be called directly).
Variable nameTypeDefault value
action[name].type String
The type of the krpano action:
Variable nameTypeDefault value
action[name].usestrictjs Boolean
Explicitly enable or disable the Javascript Strict Mode for this action.

When not set, the global usestrictjs setting is used as default.
Variable nameTypeDefault value
action[name].scope String
Define the scope for the new generated variables in the action:
  • global or not set (the default)
    • New variables will be added to the global variable scope.
    • Every other action or code will be able to use them as well.
    • This can be problematic when reusing variable names, especially when the variable type will differ between the usages.
  • local
    • New variables will be added to a local variable scope that exists only in the current action call.
    • When the action is done or calling other actions the local scope and all variables defined in it will be not available anymore.
    • The more complex an action is and the more temporary variables it is using, the more it makes sense to use a local scope for this action to avoid interfering problems with other actions.
  • localonly
    • Some as scope=local but with the difference that all access refers only to the local scope itself by default.
    • Access to the global scope will be only possible by the global object.
  • parent
    • Use the scope from the caller.
    • When the action that is calling the current action has a local scope, then this one can be used/accessed in the current action as well.
  • private:NAME
    • Define a private local scope for the action.
    • The scope will be refereed by a custom unique NAME.
    • This scope keeps alive between multiple action calls and can be shared across several actions.
    • Some as scope=localonly all access refers only to the local scope itself.

Notes:
  • global scope access - When searching for variables, first the local scope will be searched and then the global one. To be able to add variables to the global scope even when using a local scope or to directly access variables at the global scope there is the global object.
  • local scope access - To be able to ensure accessing the local scope (e.g. to define a local variable when there might be already a global variable with the same name) the current local scope is also available as local object in the action code. E.g. use def(local.i, integer, 0); to define a local integer variable named 'i'. For later access in the action code it will be enough to just use 'i' to address that variable.
  • deferred code - Actions that will call other code later (e.g. delayedcall, tween, asyncloop, ...) will use the same scope as in the current action in that code.
  • caller scope - code called from plugin / layer / hotspot events
    • For non-localscope actions:
      When an action (or any code) will be called from a plugin / layer / hotspot event, then the plugin / layer / hotspot object itself will be also available as scope for searching for variables. But only for accessing existing variables! New generated variables will be always added to the global scope.
    • For localscope actions:
      In localscope actions there is always the predefined local variable caller. When the action will be called from an plugin / layer / hotspot event (or by using callwith) then that caller variable will refer to that element. Otherwise the caller variable will be null.

Predefined variables in local scope actions:
  • actionname - The name of the current action.
  • args - A value-array of the arguments.
    • Access by: args[index].
    • Get the number or arguments by: args.length.
  • caller - The plugin / layer / hotspot object when called from there, otherwise null.
  • global - A reference to global scope.
  • local - A reference to the current local scope itself.
  • parentscope - A reference to the scope from the parent action, when there is no parent scope, this refers to the global scope.
Variable nameTypeDefault value
action[name].args String
Map the action arguments / parameters to local variables.
Requires the usage of local scope actions.

The args attribute should contains a list of variables names separated by commas.
For example:
<action name="test" scope="local" args="var1, var2, var3">
  showlog();
  trace('var1=',get(var1));
  trace('var2=',get(var2));
  trace('var3=',get(var3));
</action>
and when calling:
test(1.0, 'abc', get(version));
the trace output will be:
var=1.0
var2=abc
var3=1.21.2

The arguments are also available via an args value-array inside the action code.
Variable nameTypeDefault value
action[name].autorun String
Should the action run automatically on start.

Possible settings:
  • preinit - 'Pre-Initialize' - run this action at initialization before any other event or action (also before the onstart event). Will be called only ONCE.
  • onload - same as preinit, but will be called every time AGAIN when a new pano gets loaded.
  • onstart - run this action on startup (directly after the onstart event).
Variable nameTypeDefault value
action[name].protect Boolean false
When protect will be set to true, the action[name].content variable will be not accessible.

This could be to used to protect and hide the source of custom actions (e.g. when additionally defined in an encrypted xml file).
Variable nameTypeDefault value
action[name].secure Boolean false
When secure will be set to true, the action will be callable by the Javascript interface, even when the Javascript interface is disabled.

This makes it possible to implement custom and secure external interfaces.
Variable nameTypeDefault value
action[name].content String
The inner content of the <action> element. Can be also set or changed dynamically.
Variable name (read only)TypeDefault value
action.count int 0
The count / number of all <action> elements.


Note - when loading other xml files or scenes, all current defined actions remain unchanged unless they will be defined again and become overwritten this way.
Examples
Call an action on startup:
<krpano onstart="intro();">
  ...
  <action name="intro">
    lookat(0,0,90);
    wait(LOAD);
    lookto(120,10,110);
    lookto(-50,40,110);
    lookto(0,0,90);
  </action>
  ...
</krpano>
Call actions from hotspots and directly use the hotspot properties there:
<action name="overaction">
  tween(scale, 2.0);
  tween(alpha, 1.0);
</action>

<action name="outaction">
  tween(scale, 1.0);
  tween(alpha, 0.5);
</action>

<plugin name="pic1" ...
        onover="overaction();"
        onout="outaction();"
        />

<plugin name="pic2" ...
        onover="overaction();"
        onout="outaction();"
        />
Pass parameters to actions:
<action name="test">
  showlog();
  trace('parameter1=',%1);
  trace('parameter2=',%2);
  trace('fov=',%3);
</action>

<action name="parameterpassingtest">
  test('Test1', 'Test2', get(view.fov));
</action>
<contextmenu>
Customize the right click context menu:
  • Add user defined items...
  • Assign them to custom actions...
  • Re-order the 'krpano' item...

Basic syntax:
<contextmenu>
    <item caption="..." onclick="..." />
    <item caption="..." onclick="..." />
    ...
</contextmenu>

The syntax with all available settings:
<contextmenu versioninfo="true"
             fullscreen="false"
             enterfs="Fullscreen"
             exitfs="Exit Fullscreen"
             touch="true"
             customstyle=""
             >
    <item name="..."
          caption="..."
          enabled="true"
          visible="true"
          separator="false"
          showif=""
          onclick="..."
          />
    <item name="..."
          caption="..."
          onclick="..."
          />
    ...
</contextmenu>
Variable nameTypeDefault value
contextmenu.versioninfo Boolean true
Show version information about the krpano viewer and the Browser at the bottom of the context-menu.

When the debugmode setting is enabled, this item is clickable to open or close the krpano log. Additionally when the debugmode is enabled, the krpano version will be always shown, regardless if build with branding-free license or not.
Variable nameTypeDefault value
contextmenu.fullscreen Boolean false
Enable / disable the built-in / automatic "Fullscreen" / "Exit Fullscreen" item.

The krpano viewer will automatically hide the fullscreen-item when the Fullscreen-mode is not supported.
Variable nameTypeDefault value
contextmenu.enterfs
contextmenu.exitfs
String
String
"Fullscreen"
"Exit Fullscreen"
Set the enter / exit fullscreen mode captions for the automatic fullscreen item.
Variable nameTypeDefault value
contextmenu.touch Boolean true
Enable/disable the support of the contextmenu on touch devices.
Variable nameTypeDefault value
contextmenu.customstyle String
Define a custom style / look of the contextmenu.

Note - setting a custom contextmenu style will be only possible for touch devices by default. For desktop systems it will be necessary to have a Branding Free License.

Syntax:
customstyle="font|fontsize|lineheight|backgroundcolor|textcolor|disabled-textcolor|borderwidth|bordercolor|borderradius|shadow-x-offset|shadow-y-offset|shadow-blur-range|shadow-color|innerborder|innerbordercolor|padding-top|padding-bottom|seperator-margin|seperator-color|seperator-second-line-color|item-padding|item-borderwidth|item-bordercolor|item-borderradius|item-margin|item-hover-backgroundcolor|item-hover-bordercolor|item-hover-textcolor|item-text-left-margin|item-text-right-margin"
  1. font - a font-family name or 'default'.
  2. fontsize - a fontsize or 'default'.
  3. lineheight - the line-height in percent or 'default'.
  4. backgroundcolor - the background-color and the background-transparency.
  5. textcolor - the item text-color.
  6. disabled-textcolor - the text-color for disabled items.
  7. borderwidth - the width of the border in pixel.
  8. bordercolor - the color of the border.
  9. borderradius - the radius of the border edges in pixel.
  10. shadow-x-offset - the x-offset of the shadow.
  11. shadow-y-offset - the y-offset of the shadow.
  12. shadow-blur-range - the blur range of the shadow.
  13. shadow-color - the color and transparency of the shadow.
  14. innerborder - the width of the inner border in pixel.
  15. innerbordercolor - the color of the inner border.
  16. padding-top - the padding on top of all items.
  17. padding-bottom - the padding on bottom of all items.
  18. seperator-margin - the margin around the seperator.
  19. seperator-color - the color of the seperator line.
  20. seperator-second-line-color - either the color of a second seperator line (like a shadow) or 'none' for no second line.
  21. item-padding - the padding around the items.
  22. item-borderwidth - the width of the item border in pixel.
  23. item-bordercolor - the color of the item border.
  24. item-borderradius - the radius of the item border edges in pixel.
  25. item-margin - the margin around the items.
  26. item-hover-backgroundcolor - the background color when hovering/selecting the items.
  27. item-hover-bordercolor - the border color when hovering/selecting the items.
  28. item-hover-textcolor - the text color when hovering/selecting the items.
  29. item-text-left-margin - the left margin of the item text.
  30. item-text-right-margin - the right margin of the item text.
  31. backdrop-blur-radius - blur the background (optional, not supported by all browsers).
  32. outline-color - add a 1px-width outline (optional).

Colors and transparency
  • The format for all colors is 0xAARRGGBB.
  • 0xAA is the alpha transparency: 0x00 = fully opaque, 0xFF = fully transparent.

Customstyle Examples

The default contextmenu style for Windows, Linux, iOS and Android (demo):
<contextmenu customstyle="default|default|150%|0xFFFFFF|0x000000|0xBBBBBB|1|0xBBBBBB|0|2|2|8|0x66000000|0|0|2|2|5|0xE0E0E0|none|4|0|0|0|3|0xEEEEEE|0|0|18|12" />

The default contextmenu style for Mac OSX (demo):
<contextmenu customstyle="default|14|default|0xFFFFFF|0x000000|0xBBBBBB|0|0|5|2|2|8|0x66000000|0|0|1|4|5|0xEEEEEE|none|1|0|0|0|3|0xEEEEEE|0|0|20|12" />

A custom style example (demo):
<contextmenu customstyle="Helvetica|16|default|0x55000000|0xFFFFFF|0x555555|1|0xFFFFFF|8|0|0|8|0x44000000|0|0|4|4|6|0x555555|none|4|0|0|0|3|0xEEEEEE|0|0|12|12" />

Fake Windows 7 native look (demo):
<contextmenu customstyle="default|default|default|0xF0F0F0|0x000000|0xBBBBBB|1|0x979797|0|2|2|2|0x66000000|2|0xf5f5f5|0|4|4|0xE0E0E0|0xFFFFFF|3|1|0xF0F0F0|3|0|0xE8EEF6|0xAECFF7|0|18|12" />
Variable name (read only)TypeDefault value
contextmenu.item.count int 0
The count / number of all context menu items.
Variable nameTypeDefault value
contextmenu.item[].name String
The name of this item (see the name notes).
Variable nameTypeDefault value
contextmenu.item[].caption String
The caption of the item, this is the text that will be shown in the context menu.

Special captions:
  • KRPANO
    Can be used to place the "About krpano..." item there.
    When no KRPANO item will be defined in the xml, it will be added automatically as last item. This item can only be removed with the Branding Free License.
  • FULLSCREEN
    Can be used to place the automatic "Fullscreen" / "Exit Fullscreen" item there.
    When no FULLSCREEN item will be defined and contextmenu.fullscreen is set to "true", it will be added automatically as last item. The texts of this item can be changed with the enterfs / exitfs settings.

Caption formating / styling:
  • The contextmenu items can be formated with simple BB-code-formated HTML code (by using [ ] instead of < >).
Variable nameTypeDefault value
contextmenu.item[].enabled Boolean true
State of the item - enabled or disabled (grayed out)
Variable nameTypeDefault value
contextmenu.item[].visible Boolean true
Item visibility
Variable nameTypeDefault value
contextmenu.item[].separator String "false"
Should the current item separated by a line from other items.

Possible settings:
  • false - no separator.
  • true or above - show a separator line above the current item.
  • below - show a separator line below the current item.
  • both - show a separator line above and below the current item.

Duplicated separator lines will be automatically merged.
Variable nameTypeDefault value
contextmenu.item[].showif String
Show this item only when the given condition is true.

Example - to show an item only on full spherical panos:
<item ... showif="view.vlookatrange GE 180" />
Variable nameType
contextmenu.item[].onclick Action Event
Actions to call / execute on click / select.
<network>
Network / Loading settings.

These settings can have a major impact on the loading and rendering performance!
The default settings are a balance between slow and fast systems with a slight bias towards faster ones.

<network retrycount="2"
         cachesize="7"
         maxdownloads="20"
         maxrequests="9"
         maxdecodes="4"
         maxdecodetime_moving="12"
         maxdecodetime_still="28"
         />

Variable nameTypeDefault value
network.retrycount int 2
The number of automatic download retries on loading (server) errors before showing an error message.
Variable nameTypeDefault value
network.cachesize Number 7.0
The size of the internal cache buffer in MB for textual files (xml, js, stl, obj, ...).
Variable nameTypeDefault value
network.maxdownloads
network.maxrequests
network.maxdecodes
int
int
int
20
9
4
Settings for the loading / image-decoding performance:
  • maxdownloads - the maximum of parallel image/tile downloads.
    • Small values can unnecessarily reduce the download speed, and too high values can reduce the responsivity on quick viewing changes.
    • The right setting additionally also depends on the server performance and the network connection.
  • maxrequests - the maximum download-requests per frame.
    • How many new download requests can be made in one frame.
    • Like the maxdownloads setting, a balance between download speed and responsivity.
  • maxdecodes - the maximum of images/tiles to decode per frame.
    • How many images can be decoded in one frame.
    • Decoding images can be a heavy task for the system, and when too many images are decoded in the one frame, the frame-rate can drop down.
    • So this setting depends on the performance of the system (CPU and GPU) and on the size of the images/tiles - see the tilesize.
    • For more control and to avoid frame-drops when there are too many or too large images, there are additionally the maxdecodetime_moving and maxdecodetime_still settings.
Variable nameTypeDefault value
network.maxdecodetime_moving
network.maxdecodetime_still
Number
Number
12
28
More settings for the loading / image-decoding performance:
  • These settings define the maximum time (in ms) per frame spent decoding the images/tiles (all images together in the current frame).
  • One limit when there is no movement in the pano and one when moving. Because during moving the frame-rate should be as stable as possible and not get interrupted.
<memory>
Memory usage settings.

<memory maxmem="..." devices="..." />

Note - always use also a devices setting to change the default setting only for special cases and requirements!
Variable nameTypeDefault value
memory.maxmem int ...
Set the maximum memory usage for the decoded image tiles in MB. The calculation of the tile memory size in MB is done by: 'tile-image-width * tile-image-height * 4 / 1024 / 1024' (e.g. a 512x512px tile needs exactly 1 MB memory).

When the maxmem limit will be reached, the memory of currently not used (needed/visible) tiles will be freeed/returned.

Note - use this setting with care!
It can affect the performance and the browser stability.


The current default settings are:
  • Desktop: 150-750 MB (depending on the total screen size)
  • Mobile/Tablets: 200 MB (iOS, Android)
<security>
Security / Cross-Domain related settings.

<security cors="" />
Variable nameTypeDefault value
security.cors String
HTML5 CORS (Cross Origin Resource Sharing) Images.
Set the default value for the crossOrigin property for all images that will be loaded by the krpano viewer.

Allowed values are:
  • off - no CORS usage - the crossOrigin property will not be set.
  • anonymous or an empty string (=default) - CORS without credentials flag
  • use-credentials - CORS with credentials flag

For details about enabling CORS on the server please see here:
http://enable-cors.org/
http://enable-cors.org/server.html

Example:
If your Web-server is an Apache-server, the easiest way to enable CORS would be to put a .htaccess named file with the following content into the folder of the files that should be accessible:
Header set Access-Control-Allow-Origin "*"
<data>
A 'raw' data section. It can be used to store any kind of information or data. krpano will not parse its content. The whole content of the <data> element will be stored in the content property of the resulting data[name] object.

The content itself will be not parsed by krpano, but the xml syntax rules and several automatic xml-entity-resolving processes will still apply to it!
To avoid any kind of xml-syntax-parsing and xml-entity-resolving, put the whole data content inside <![CDATA[ and ]]> tags. This way all characters and xml-tags can be used without getting parsed.

Note - when loading an other xml file, all data tags remain unchanged unless they are defined again in the other xml, then they will be overwritten by the new ones.

<data name="...">
    ...
</data>

With CDATA to avoid xml-parsing:
<data name="..."><![CDATA[
    ...
]]></data>
Variable name (read only)TypeDefault value
data.count int 0
The count / number of all data elements.
Variable nameTypeDefault value
data[name].name int
The name of the data element (see the name notes).
When no name will be set, an automatic generated name will be used (e.g. could be used for data elements that will be accessed only via index (e.g. in a for loop) and never directly).
Variable name (read only)TypeDefault value
data[name].index int
The index of the data element.
Variable nameTypeDefault value
data[name].content String
The whole content of the <data> element as text string.
<cssstyles>
Define any CSS styles directly in the xml file.

This works the same like a .css file included in the html-file or a <style> element defined in the html-file <head> section.

The intended usage is for defining CSS styles/classes for using them in textfields or layers/containers with the cssclass settings.

Syntax:
<cssstyles>
    any CSS styles...
</cssstyles>


Notes:
  • The inner content of the <cssstyles> element will be not parsed by krpano, but because it is defined in a xml file, the xml syntax rules and the automatic xml-entity resolving will get applied to it!
  • To avoid any kind of xml-syntax-parsing and xml-entity-resolving, put the inner content into <![CDATA[ and ]]> tags. This way all characters and xml-tags can be used inside the content.
  • Example - with CDATA to avoid xml-parsing:
    <cssstyles><![CDATA[
        ...
    ]]></cssstyles>
<scene>
The scene elements are technically something like 'inline-xml' files.

They can be used to define the content of a full krpano xml file again inside the current xml file. It is like a external xml, but just inlined / embedded into the current xml.

The content of the scene element will not be parsed or used in any way, until loadscene() with the name of the scene will be called.

The typical usage would be to define several panos from a tour inside just one xml file.

When loading a new external xml file with the loadpano() action, then all currently defined scene elements will be removed.

It is possible to store any custom attributes at the <scene> element - the viewer itself will ignore them, but they can be used for custom actions.

<scene name="..." onstart="" autoload="false" ...>
    ...
</scene>
Variable name (read only)TypeDefault value
scene.count int 0
The count / number of all scene elements.
Variable nameTypeDefault value
scene[name].name String
The name of the scene element (see the name notes).
This is the name to be used when using the loadscene() action.
When no name will be set, an automatic generated name will be used (e.g. could be used for scene elements that will be accessed only via index (e.g. in a for loop) and never directly).
Variable name (read only)TypeDefault value
scene[name].index int
The index of the scene element (will be set automatically).
Variable nameType
scene[name].onstart Action Event
The "onstart" event - here any actions / functions that will be called "on start" of the pano/scene viewing can be defined.
Variable nameTypeDefault value
scene[name].autoload Boolean false
When set to true, this scene will get automatically loaded on start.
Only one scene can be 'auto-loaded', when several scenes have autoload=true set, then the last-defined-one will get loaded.
Variable nameTypeDefault value
scene[name].content String
The whole unparsed content of the <scene> element as text string.
<set>
Set / define a variable during the xml parsing.

This can be used to set or overwrite special variables, that weren't accessible due normal xml declarations.

<set var="..." val="..." />
Attribute nameType
var String
Any variable name or path.
Attribute nameType
val String
The value that will be set to the variable.
Can be any value, text or expression.
<if>
Parse a specific section of the XML only when a condition is met.
Similar to the if attribute, but for multiple xml elements.

Note - there is one limitation here: <include> elements are always loaded/included, even if the condition may be not met. That's because the include resolving is a separate initial process before the actual xml parsing!

<if check="condition">
    ... any other xml elements ...
</if>
Attribute nameType
check String
The condition / expression to check.
Variables used here need to be already defined.
<debug>
Trace / log something during the xml parsing.

Note - Debug messages will be only shown when the debugmode setting is enabled!

<debug trace="..." />
Attribute nameType
trace String
Any text, variable or expression.