News Examples Documentation Download Buy Forum Contact

krpano XML Reference Version 1.22

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>
    <languages>
    <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.
  • object
    • Define a Javascript Object.
    • Note - Strings in the Object need to be quoted.
    • Example: attribute.object="{num:123, str:'hello'}"
  • array
    • Define a Javascript Array.
    • Note - Strings in the Array need to be quoted.
    • Example: attribute.array="[1,2,3,4,5]"
<xmlelement attribute="...any.value..."
            attribute.onchange="...code..."
            ...
            />
On-change actions for attributes

React on dynamic changes of an attribute. First the define the attribute itself, and then the attribute plus ".onchange" to execute custom code when the attribute gets changed.

Same as the dynamic onchange() action.

Examples
Restrict the value to be within 0.0 amd 1.0:
x="0.5"
x.onchange="x=clamp(x,0.0,1.0);"
React on changes:
design="default"
design.onchange="change_the_design();"
Do more complex things when some settings change:
<settings maps="false"
maps.onchange="if(maps, load_map(), remove_map() );"
...
<style name="stylename"
       attribute="value"
       attribute="link:..."
       attribute="relink:..."
       ...
       />
Usage:
<xmlelement ... style="stylename" ... />
<xmlelement ... style="link:stylename" ... />
<style> elements and the style attribute:

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

Every xml element can have a style attribute, which can be used in two ways:
  • style="stylename" ⇒ 'copy'
    When the xml element will be created, then first all attributes defined in the <style> element will be copied to it. And then as second step, the attributes that are actually defined at xml element itself will get set.
    That means it is possible to predefine some settings in the <style> element and then overwrite them later with the attributes defined directly at the element.
  • style="link:stylename" ⇒ 'link'
    Different to the normal 'style' attribute, where the values will be only copied, here all attributes defined in the <style> element will get linked to the current element.
    That means when a value inside the <style> changes, then automatically the value at the element will change too.
    Note - this works only for attributes that are defined in the <style> and not also at the element. When the element has the same attribute defined, the it will not get linked.
Several styles can be loaded at once by combining the style names by | characters.

Relinking Attributes (only when linking styles)
  • For style attributes there is also a special relink:... syntax.
  • When this is used, the linking will be 'forwarded' - that means the target element will get linked directly to given variable(s) instead of getting linked to the style.
  • With that it will be like when the linking attribute was directly defined at the target element.
  • This can be useful when using variables or expressions that are related to the variable scope of the target element.


For dynamically getting the attributes from a style, 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"
       />
<xmlelement attribute="link:variable" ... />
<xmlelement attribute="link:variable:expression" ... />
<xmlelement attribute="link:var1|var2:expression" ... />
<xmlelement attribute="link:event.NAME:expression" ... />
<xmlelement attribute="link:event.NAME1|event.NAME2:expression" ... />
When the value of a xml attribute starts with link: the value for the xml attribute will be linked to the value of an other variable or automatically be calculated using an expression when one or more other variables are changing or when certain events are triggered.

For dynamically creating links at runtime, the link() action can be used.
And for removing a 'link', the unlink() action can be used.

Notes:
  • The 'linking' only gets triggered when the 'to-linked' variables are actively changing (getting set to a new value). When the variable is a setter/getter and it changes its value internally, then these changes are not getting detected.
  • E.g. the fullscreen variable is such setter/getter: when setting it to true, the fullscreen-mode is getting requested - but this happens asynchronous and might even fail when the fullscreen mode is not supported or allowed. The actual value of the fullscreen variable changes only when the fullscreen mode is actually enabled and ready. In such cases, it would be possible to link to 'events' instead to get it working (see the examples below).
  • When linking to multiple variables or multiple events, these must be separated by | or , characters.
  • Use with care, there is no detection of 'circle-links'! That means when one variable is linked to an other, which is then again linked back to the source variable.

Examples
A simple link:
text="link:view.fov"
Link with formating the value using an expression:
text="link:view.fov:roundval(view.fov,2)"
Link with multiple variables:
text="link:view.hlookat,view.vlookat:'Lookat:'+roundval(view.hlookat,2)+'/'+roundval(view.vlookat,2)"
Link to events:
text="link:event.onfullscreen,event.onexitfullscreen:fullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen'"
Use linking for responsive design:
scale="link:stagewidth:stagewidth LT 400 ? 0.7 : 1.0"
<include url="..." />
The <include> elements - include other files:

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

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

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

These file-types can be included:
  • xml
    • Include other krpano xml files.
    • These xml files also need to have a root <krpano> element.
    • Note - for including xml content dynamically the includexml() and includexmlstring() actions can be used.
  • js
    • Include and execute Javascript files.
    • The Javascript code will be executed directly after the xml parsing.
    • The Javascript code will run within the krpano context and have direct access to all krpano objects and variables (same as in type="Javascript" <actions> elements).
    • Note - for including js files dynamically the loadjs() action can be used.
  • css
    • Include CSS stylesheet files.
    • This works the same as including a CSS file in the HTML file.
    • Note - CSS code can be also defined inline in <cssstyles> elements.

Examples
<include url="settings.xml" />
<include url="skin/skin.xml" />
<include url="%VIEWER%/plugins/depthmap_navigation.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.22.3"
        onstart=""
        basedir="%FIRSTXML%"
        bgcolor=""
        language="..."
        defaultlanguage="en"
        idletime="0.5"
        strict="false"
        usestrictjs="true"
        showerrors="true"
        logkey="true"
        debugmode="false"
        debugkeys="false"
        debugkeeplog="true"
        debugjsactions="false"
        debugjsplugins="false"
        deprecatedwarnings="true"
    >
    ...
</krpano>

Attribute nameVariable nameTypeDefault value
version xmlversion String "1.22.3"
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
language
systemlanguage
defaultlanguage
String
String
String


en
The language settings for using the translate() expression:
  • language
    • The current language code (in lower-case).
    • E.g. en for English, de for German, fr for French, etc.
    • By default this is the same as systemlanguage.
    • This language code is used to look up words in the <languages> translation tables when using the translate() expression.
  • systemlanguage
    • The language of the System / Browser.
    • Based on the Browsers navigator.language property, but it only uses the language code without the country code, and always in lower-case.
  • defaultlanguage
    • The fallback/default language to look for a specific word if that word is not available in <languages> translation tables in the current language.
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.
  • When clicking on INPUT or pressing SHIFT+logkey, an input-field will open for entering krpano actions or expressions.
    • This input-field also has these special commands:
    • clearlog - clear the current log.
    • clearhistory - clear the log and also the input-history.
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:
  • R - Enable or disable the autorotate mode.
  • C - Change the controlmode (moveto/drag).
  • T - 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 or expressions.
Variable nameTypeDefault value
debugkeeplog Boolean true
Keep/store the history of the log-input. That means the previous input in the debug input-field will be still there are reloading the page. The log will be stored only locally (in the Browsers localStorage memory) and so only in the current Browser and only for the current domain/origin.

Note - works only when the debugmode setting is also enabled.
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.

Available Image Settings (mixed for all types):
<image type="..."
       hfov="360.0" vfov="360.0" voffset="0.0"
       ox="0.0" oy="0.0" oz="0.0"
       objectsize="1000.0"
       crop=""
       stereo="false"
       stereolabels="1|2" stereoformat="TB" stereooffset="0.0"
       prealign="0|0|0"
       multiresthreshold="0.025"
       baseindex="1"
       tileoverlap="0"
       cubelabels="l|f|r|b|u|d"
       cubemapmode="false" cubemapsize="4096"
       frame="1" frames="1"
       >
    <TYPE ... 
        multires=""
        striporder="LFRBUD"
        mapping=""
        mjpegstream=""
        />
    ...
</image>


Image Settings for specific Pano-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,..."
          wraparound="false"
          />
</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="..." wraparound="false">
    <level tiledimagewidth="..." tiledimageheight="...">
        <sphere url="..._%v_%h.jpg" />
        <cylinder url="..._%v_%h.jpg" />
        <flat url="..._%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.
  • %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.


Settings 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 "0|0|0"
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.wraparound Boolean false
When enabled, flat images can horizontally wrap around.
  • The viewing position (view.hlookat) will also automatically wrap around and always be in the -hfov/2 to + hfov/2 range.
  • The hotspots will also wrap around and be centered around the current viewing position.

Note - works only with multi-resolution flat images where all multi-resolution levels are fully divisible by the tilesize!
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
4096/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.

Note - on iOS devices the default size is 2048. iOS is very sensitive to GPU memory usage and when hitting some limit, iOS Safari will crash the webpage. A lower setting here will reduce the memory need and better prevents crashes.
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.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.objectsize
Number
1000.0
Size of the internal 3D-Model of the pano-image.

When set to 0 or an invalid Number (e.g. by using the String "infinity") then the 3D-Model will be rendered infinity far away. This can be used for background panos that shouldn't move with the view.
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 nameTypeDefault value
image.hres
image.vres
int
int
0
0
The resolution / pixel-size of the pano-image.
When the pano is a multi-resolution image, then this is the size of the largest level.
Variable name (read only)TypeDefault value
image.hlookatmin
image.hlookatmax
image.vlookatmin
image.vlookatmax
Number
Number
Number
Number
-180.0
+180.0
-90.0
+90.0
The lookat range of the image.
Will be calculated automatically and depends on the image type and the hfov, vfov and voffset settings.
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 - when mapping a pano-image onto the 3D-Model and using rendermode=3dmodel, then the resolution can be limited by image.cubemapsize setting!

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.

Here a setting for using very large 3D-Models on mobile devices with limited memory:
<depthmap ... hittestmode.mobile.and.no-mobilevr="gpu" />
  • This enables the GPU-mode for mobile devices (to reduce the memory need),
  • but not for VR-headsets, which would be very slow in GPU-mode.
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.
    • Note - when mapping a pano-image onto the 3D-Model, then the resolution can be limited by the image.cubemapsize setting!
  • "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.

There is an example with an interactive helper tool for adjusting the depthmap-image mapping settings included: Depthmap-Image Helper 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 (the default) - limit the looking range and fov to be within the image limits.
  • lookat - limit the view lookat directly to within hlookatmin, hlookatmax, vlookatmin, vlookatmax. No automatic fov limit.
  • lookrange - limit the view lookat directly to within hlookatmin, hlookatmax, vlookatmin, vlookatmax and limit the fov to cover the whole full image.
  • range - limit the view and fov to fully inside the the hlookatmin, hlookatmax, vlookatmin, vlookatmax range.
  • fullrange - limit the view to be inside the the hlookatmin, hlookatmax, vlookatmin, vlookatmax range, but allow the fov zooming out to see the full image.
  • offrange - limit the view to be inside the the hlookatmin, hlookatmax, vlookatmin, vlookatmax range, but don't limit the fov.
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
-180.0
+180.0
-90.0
+90.0
The view looking ranges.
How they behave depends on the limitview setting.
When limitview is set to auto, these will be set automatically to the limits given by the pano-images fov-coverage.

Note - when 'hlookatmax-hlookatmin >= 360', then no horizontal limiting will be done.
Variable nameTypeDefault value
view.haschanged
Boolean
A boolean flag to check or set if the current view has been changed.
By setting it to true, this could be used to request a redraw in the next frame.
Variable nameTypeDefault value
view.pixelzoom
Number
The current zoom level relative to the size of the pano image.
A value of 1.0 means a 100% zoom of the source pixels.

Note - setting or getting this value works only when the pano image is loaded or its size information are available (that means after the onnewpano event).
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.syncto(otherview) Action
Copy the view settings from the view element from an other krpano viewer.
Could be used in onviewchange event to synchronize the pano view changes.
Note - the viewing range limits are not copied.

Parameters:
  • otherview - the view object from an other krpano viewer.
Function nameTypereturn
view.unproject(x, y, d, rotated) Action {x,y,z}
Unproject a 2D screen point to a 3D vector.

Parameters:
  • x, y - 2D screen position.
  • d - 3D distance to the point.
  • rotated - should be unprojected vector be rotated by the current viewing direction.
Return value:
  • A 3D point object with x,y,z properties.
Function nameTypereturn
view.remapfovtype(fov,srctype,dstype,w,h) Action Number
Remaps a fov value from one fovtype to another.

Parameters:
  • fov - the fov value.
  • srctype - the fovtype of the given fov value.
  • dsttype - the fovtype to convert to.
  • w, h (optionally) - the size of fov area.
Return value:
  • The new fov value.
Function nameTypereturn
view.fovtoscale(fov,fovtype,w,h) Action Number
Convert a fov value (and its fovtype) to a linear scale factor.

Parameters:
  • fov - the fov value.
  • fovtype (optionally) - the fovtype of the given fov value.
  • w, h (optionally) - the size of fov area.
Return value:
  • A linear scale value.
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"
         hotspotvrzoom="true"
         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 kept rotated toward the viewers, just like distorted hotspots.
  • "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).

Note - see also the related hotspotvrzoom setting.
Variable nameTypeDefault value
display.hotspotvrzoom Boolean true
Define the appearance/scale of non-zooming and non-distorted hotspots in VR mode.

Possible settings:
  • true (the default) - the hotspots will change their size depending on the perspective, that means they will work mostly like distorted hotspots.
  • false - the hotspots will keep their size, regardless of the field-of-view or perspective.

Note - see also the related hotspotvrrendering setting.
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 and position defined by 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"
         zoomtocursor_fovlimit="360.0"
         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.zoomtocursor_fovlimit Number 360.0
Limit the zoomtocursor mode to panos that have a lower hfov.
This can be used to use the zoomtocursor mode automatically only on partial panos.
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 behavior 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();"
<languages>
The languages variable is a pre-defined, but by default empty krpano Array.
It can contain any custom attributes which are used by the translate() expression to look up words in the current language.

Example:
<languages name="en"
    enterfullscreen="Fullscreen"
    exitfullscreen="Exit Fullscreen"
    ...
    />
<languages name="de"
    enterfullscreen="Vollbild"
    exitfullscreen="Vollbild Modus Beenden"
    ...
    />
<languages name="fr"
    enterfullscreen="Plein écran"
    exitfullscreen="Quitter le plein écran"
    ...
    />

Translate the contextmenu fullscreen items:
<contextmenu 
    enterfs="link:translate(enterfullscreen)"
    exitfs="link:translate(exitfullscreen)"
    >

A fullscreen-button text that changes automatically based on the current language and the current fullscreen state:
text="link:event.onenterfullscreen,event.onexitfullscreen:fullscreen ? translate(exitfullscreen) : translate(enterfullscreen)"
<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.
  • There is one special <plugin> setting, which is only relevant for the xml parsing:
    <plugin api="NAME" ... />
    • When loading a krpano Javascript Plugin and defining an api attribute in the xml file, a global krpano plugin object with that name will be instantly created.
    • The plugin item element will get the same name as set in the api attribute.
    • This allows setting up links to that plugin using its short api name already during the xml parsing.
    • Example - when the plugin is defined like this:
      <plugin api="soundinterface" url="soundinterface.js" ... />
      It is possible to link to it using the api name:
      <layer ... height="link:soundinterface.volume,..." ...
      Instead of using the full plugin path:
      <layer ... height="link:plugin[soundinterface].volume,..." ...
<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=""
       cssstyle=""
       ☞ layering, flowing
       parent=""
       childorder="0"
       zorder="0"
       flowchildren=""
       flowchildrenexpand="false"
       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"
       ☞ foreground filters
       colorize="0xFFFFFF"
       colormatrix=""
       brightness="1.0"
       contrast="1.0"
       saturate="1.0"
       hue="0.0"
       invert="0.0"
       sepia="0.0"
       blur="0.0"
       dropshadow=""
       ☞ special layer type settings
       krpanobgcolor=""
       iframeurl=""
       html=""
       css=""
       htmlautosize="false"
       htmloverflow="hidden"
       htmllinkcolor="inherit"
       ☞ control events
       onover.addevent=""
       onhover.addevent=""
       onout.addevent=""
       ondown.addevent=""
       onup.addevent=""
       onclick.addevent=""
       onsingleclick.addevent=""
       ondoubleclick.addevent=""
       onwheel.addevent=""
       ontabindex.addevent=""
       onfocus.addevent=""
       onblur.addevent=""
       ☞ state events
       oncreate.addevent=""
       ondestroy.addevent=""
       onloaded.addevent=""
       onresize.addevent=""
       onlayout.addevent=""
       onaddchild.addevent=""
       onremovechild.addevent=""
       />


The xml structure for <hotspot> elements:
<hotspot name="..."
       ☞ basic settings
       type="image"
       url="..."
       keep="false"
       preload="false"
       style=""
       cssclass=""
       cssstyle=""
       ☞ 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"
       zoomscalebase="1.0"
       flying="0.0"
       scaleflying="true"
       camroll="true"
       ☞ special WebGL rendering settings
       renderer="auto"
       mipmapping="false"
       premultipliedalpha="false"
       depthbuffer="false"
       depthwrite="true"
       depthoffset="0"
       ☞ special effects (WebGL only)
       blendmode="normal"
       alphachannel="auto"
       alphahittest="0.0"
       stereo=""
       chromakey=""
       ☞ special HTML/CSS3D rendering 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"
       hittest="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=""
       ondown.addevent=""
       onup.addevent=""
       onclick.addevent=""
       onsingleclick.addevent=""
       ondoubleclick.addevent=""
       onwheel.addevent=""
       ontabindex.addevent=""
       onfocus.addevent=""
       onblur.addevent=""
       ☞ state events
       oncreate.addevent=""
       ondestroy.addevent=""
       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"
       ☞ special HTML/SVG rendering settings
       svglayer="below"
       ☞ user control
       enabled="true"
       capture="true"
       capturewheel="false"
       capturefocus="true"
       cursor="pointer"
       hittest="false"
       ☞ appearance
       visible="true"
       alpha="1.0"
       autoalpha="false"
       blending="true"
       ☞ control events
       onover.addevent=""
       onhover.addevent=""
       onout.addevent=""
       ondown.addevent=""
       onup.addevent=""
       onclick.addevent=""
       onsingleclick.addevent=""
       ondoubleclick.addevent=""
       onwheel.addevent=""
       ☞ state events
       oncreate.addevent=""
       ondestroy.addevent=""
       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:
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 layer/hotspot element.

Notes:
  • There are some name restrictions, please see the Name Notes for details!
  • The following names have either special meaning or are already in use and can't be used: STAGE, BGLAYER, OVERLAY, auto and null.
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.
    • CSS styles can be set by the css setting.
    • If the size of the layer should automatically fit the HTML content, enable the htmlautosize 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.
Layer / Hotspot AttributeTypeDefault value
cssstyle String
Directly set CSS styles to the element.

Note - some CSS styles might already be set or be used by other layer settings. And using styles that would change the position or size are not recommended, they could break the krpano controlled layout.
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.
  • If the layer is defined inside another layer in the xml, then the parent setting in the xml will be ignored. Instead, the parent setting will be automatically set to the name of the parent layer.
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
flowchildrenexpand Boolean false
Expand the flowing children elements to the parent size (in the non-flowing direction).
E.g. to give all vertical flowing elements the same width.

Note - this can't be used together with flowoverflow=true.
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?

* for type="html", type="iframe" or type="krpano" elements, the default is true!

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.
Hotspot AttributeTypeDefault value
hittest Boolean false
Use the hotspot for 3D-hit-testing (raycasting), e.g. when doing 3D-collision-tests or 3D-measurements.

Works only for distorted hotspots and for polygonal hotspots with WebGL rendering.
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 the 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.

The hotspot will get renamed (by adding "_blending" plus a unique number to its name) during the blending to avoid naming-conflicts with new added hotspots.

The isblending variable can be used to check if the hotspot is currently in this blending state.

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 Variable (read only)TypeDefault value
isblending Boolean false
A variable to check if the hotspot is currently used for the pano/scene-blending. That means this hotspot is going to be automatically removed once the blending is done.
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
svglayer String "below"
Define 'where' polygonal hotspots with renderer="svg" (non-WebGL) should be drawn.

Available settings:
  • below (default) - all polygonal hotspots will be drawn into one shared SVG layer. That SVG layer that is below all other hotspots. The polygonal hotspots are sortable using zorder, but only together within this layer. Mixing the polygonal hotspots with other hotspots (image, video, ...) is not possible.
  • separate - With this setting, the hotspot can gets its own seperate SVG layer. With this, the hotspot will be sortable and mixable with other hotspots (using zorder).
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
alphahittest Number 0.0
Use the actual alpha value of the hotspot image for hit-testing.

When set to a value higher than 0.0, then the alpha-value from the pixel where the cursors hits the hotspot is compared to the alphahittest value - and when larger, the mouse-over will be detected as hit.

Works for images, textfields, videos - and supports also the alphachannel and chromakey settings.

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
premultipliedalpha Boolean false
Indicate that the colors of the image are 'pre-multiplied' with the alpha channel.

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.

Possible values:
  • lefttop top righttop
    left center right
    leftbottom bottom rightbottom
  • Or a relative point using the syntax: align="X|Y"
    • Where X and Y are relative values from 0.0 (left/top) to 1.0 (right/bottom) inside the element.
    • E.g. align="0.5|0.5" is the same as align="center".

* The default value:
  • For layers: lefttop
  • For hotspots: center

Note - on hotspots this setting has only an effect when using flying.
Layer / Hotspot AttributeTypeDefault value
edge String *
Edge position / anchor-point of the element.

Possible values:
  • null (the default) or an empty String
    • In this case the value from the align setting will be automatically used.
  • lefttop top righttop
    left center right
    leftbottom bottom rightbottom
  • Or a relative point using the syntax: edge="X|Y"
    • Where X and Y are relative values from 0.0 (left/top) to 1.0 (right/bottom) inside the element.
    • E.g. edge="0.5|0.5" is the same as edge="center".

* The default value:
  • For layers: null
  • 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'.
Hotspot AttributeTypeDefault value
camroll Boolean true
Should non-distorted hotspots be affected by view.camroll rotations?
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 and 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.
  • sizescale - like scale, but additionally also use width/height changes of images as scale-factor for children layers.

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 "sizescale".
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.
Hotspot AttributeTypeDefault value
zoomscalebase Number 1.0
This is an additional scale factor, but only for hotspots with zoom=true.

This could be used for hotspots on flat panos to adpot their size to the flat pano rendering (which is using a very small view fov), while keeping the same scale values as for zoom=false hotspots.
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).
Layer AttributeTypeDefault value
colorize
colormatrix
brightness
contrast
saturate
hue
invert
sepia
blur
dropshadow
int
String
Number
Number
Number
Number
Number
Number
Number
String
0xFFFFFF

1.0
1.0
1.0
0.0
0.0
0.0
0.0

Foreground Filters (CSS Filters)

Apply graphical effects such as blurring or color shifting to the element itself.

Syntax for colormatrix:
  • A 5x4 Matrix (20 values):
    colormatrix="r1 r2 r3 r4 r5
                 g1 g2 g3 g4 g5
                 b1 b2 b3 b4 b5
                 a1 a2 b3 a4 a5"
  • The color mixing:
    R' = r1*R + r2*G + r3*B + r4*A + r5
    G' = g1*R + g2*G + g3*B + g4*A + g5
    B' = b1*R + b2*G + b3*B + b4*A + b5
    A' = a1*R + a2*G + a3*B + a4*A + a5
  • Note - when colormatrix is set, colorize will not work!
    (colorize is internally a predefined colormatrix)

Syntax for dropshadow:
dropshadow="xoffset yoffset blur color alpha, ..."
  • 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 blurring).
  • color (optionally)
    The color of the shadow. The default is 0x000000 (black).
  • alpha (optionally)
    The alpha transparency of the shadow. The default is 1.0.
  • ... (optionally)
    Add another shadow (comma separated).
  • Note - a drop shadow is effectively a blurred, offset version of the input image's alpha mask, drawn in a specific color and composited below the image.
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.

Additionally there are these special embedpano settings only for krpano layers:
  • contextmenu - true by default, when set to false, the krpano viewer in the layer can not have an independent contextmenu, instead the contextmenu of the outer viewer will appear.
  • fullscreen - true by default, when set to false, the krpano viewer in the layer can not switch itself to fullscreen mode.
  • stagescale - true by default, when set to false, the stagescale of the krpano viewer in the layer will be not synchronized with the parent krpano viewer.
  • asyncframeloop - false by default, when set to true, the krpano viewer in the layer will be not synchronized (same framerate, same timings) to the main krpano viewer.

Example (XML) - disable the contextmenu and the fullscreen mode support:
<layer ... 
    type="krpano" 
    krpanoembedsettings.object="{contextmenu:false, fullscreen:false}"
    />

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 the html layer.
Layer / Hotspot AttributeTypeDefault value
css String
CSS styles (direct styles, no CSS declarations) for the 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 AttributeTypeDefault value
htmllinkcolor String "inherit"
The default color of <a href="..."> links in textfields and HTML-layers.
  • The default is inherit, which means to use the text color from the parent element, which is typically the color that is set in the textfield.
  • The color here can be either an Integer color value, e.g. in hex-format like 0xFF0000, or a html-color name like red, or a html hex-color like #FF0000, or a html-color-function like rgb(255,0,0).
  • Note - to be able to set the link color by CSS classes, the value here must be set to an empty String!
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
readyBooleanfalse
A boolean variable that indicates that the element is 'ready' for layout. This is the case when the element either has a predefined size (using width, height or crop), or when the element is loaded and has a known size from the loaded image.
Hotspot VariableTypeDefault value
needredrawBooleanfalse
A boolean variable that indicates that the hotspots need to be redrawn.
Could be manually set to true to request a recalculation and a redraw of the hotspot.
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 VariableTypeDefault value
stopeventflow Boolean false
A dynamic setting to stop the current event flow.

It is always false by default and can be changed only in the onover or ondown events.

When set to true, the current event flow will be stopped and further elements will not receive this event.
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: These hitpoint information are only available for layers and for WebGL-rendered hotspots (not for CSS3D-rendered hotspots).
Hotspot Variables (read only)TypeDefault value
hit Object
An object with information about the current 3D hitpoint on the hotspot (the same hit object as from a raycast call).

The object should be only checked on direct interactions, e.g. in the ondown or onclick events.

Properties:
  • d - distance/depth from the screen to the point.
  • x,y,z - the worldspace x,y,z 3D coordinates of the hit-point (in cm).
  • nx,ny,nz - the normal vector of the hit-surface.
  • rx,ry,rz - rotation angles (in degrees) that match the hit-surface (in "zxy" rotation-order - note: that's not the default one for hotspots).

Note: These hitpoint information are only available for WebGL-rendered hotspots and only when hittest is enabled.
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
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
onclickAction Event
Actions / functions that will be called when there is a mouse click or touch on the element.
Layer / Hotspot AttributeTypeDefault value
onsingleclick
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 (~300ms) 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 time between the two clicks was too long or when the mouse was moved too far.
    • 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').
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
oncreate
ondestroy
Action Event
Action Event
Actions / functions that will be called when the element will be created or destroyed.
Could be used for initializing or cleaning up.
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 AttributeTypeDefault value
onaddchild
onremovechild
Action Event
Action Event
Actions / functions that will be called when children layer elements will be added or removed.

When assigning a Javascript function, the first argument is the parent layer and the second the child layer that was added or removed:
function(parent, child){ ... }
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
linkstyle(styles)Action
Link 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.
Layer / Hotspot FunctionType
z = element.getchildzorder("min" or "max")Action
Get the smallest ("min") or the largest ("max") zorder value from the children elements.

This could be used to put a certain element below or above all current elements.
Layer / Hotspot FunctionType
xmlstring = element.getxml(settings)Action
Generates a XML String representation of the element.

Parameter: settings (optionally) - an Object with the following properties:
  • defaults - include also the attributes that have their default value (true or false, false by default).
  • children - include also the children elements (true or false, false by default).
  • multiline - write each attribute to a separate line (true or false, false by default).
  • preindentation - the initial indentation, "" by default.
  • indentation - the indentation for children elements, "\t" (a tab) by default.
  • accuracy - the maximum accuracy for Numbers, 6 by default.
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=""
        onremovescene=""
        onxmlerror=""
        onloaderror=""
        onkeydown=""
        onkeyup=""
        onclick=""
        onsingleclick=""
        ondoubleclick=""
        ondown=""
        onup=""
        onwheel=""
        ongesture=""
        oncontextmenu=""
        onidle=""
        onidleend=""
        onframe=""
        onviewchange=""
        onviewrender=""
        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.onremovescene Action Event
  • This event will be called when a scene will be left (similar to the onremovepano 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 (~300ms) 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 time between the two clicks was too long or when the mouse was moved too far.
    • 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.onidleend Action Event
  • This event will be called when the idling, the time without user-interaction ends.
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 need to be rendered / redrawn.
  • At this event, no view-related updates, like applying viewing limitations or calculating the direction vectors or rotation matrices, are done yet.
  • That means in this event, it's still possible to make any 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.onviewrender Action Event
  • This event will be called every time when the current view will be rendered / redrawn.
  • At this event, all view-related updates and calculations are done. Changing any view settings is not possible here.
  • 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.

The <action> elements are typically defined at the xml root level, but it is also possible to define them inside <layer> and <hotspot> elements. In this case, these actions are only callable from that layer/hotspot element and its children elements.

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" args="" 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.
  • All arguments from the args setting as variables.
  • 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 (for krpano-code and for Javascript actions). Requires the usage of local scope actions (krpano-code actions only).

The args attribute should contains a list of variables names separated by commas.
For example (Actions code):
<action name="test" scope="local" args="var1, var2, var3">
  showlog();
  trace('var1=',get(var1));
  trace('var2=',get(var2));
  trace('var3=',get(var3));
</action>
For example (Javascript code):
<action name="test" type="js" args="var1, var2, var3">
  console.log('var1=',var1);
  console.log('var2=',var2);
  console.log('var3=',var3);
</action>
When calling:
test(1.0, 'abc', get(version));
the output will be:
var=1.0
var2=abc
var3=1.22.3

Note - the arguments are also available via an args 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).

Note - the automatic running of "onstart" actions can be also controlled by the NOAUTORUN load-flag and the includexml() / includexmlstrings() actions!
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 / long-touch context menu:
  • Add user defined items...
  • Assign them to custom actions...
  • Re-order the 'krpano' item...
  • Style usind CSS...

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"
             customcssclasses=""
             >
    <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.customcssclasses String
Define a custom style / look for the contextmenu.

Note - for setting a custom contextmenu style it will be necessary to have also a Branding Free License! For testing reasons, it is possible to change the style when the krpano viewer is not registered or when using the krpano viewer locally.

Syntax:
customcssclasses="contextmenu|item|separator"
  • Here 3 custom CSS class-names need to be set.
  • One for the contextmenu container box, one for the items and one for the separator.
  • The item CSS classes should handle the :hover state.
  • Disabled items will have a disabled attribute set.
  • The CSS classes can be defined either in html/css files or also in the xml file using the <cssstyles> element.

Example: Custom Contextmenu
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 / events:
  • The contextmenu items can be formated with simple BBCode encoded HTML code (by using [ ] instead of < >).
  • It's possible to use HTML-links with krpano:... or event:... as link-target to call krpano actions or js:... to call Javascript code.
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-Origin related settings.

<security cors=""
          cors_sameorigin="false"
          />
Variable nameTypeDefault value
security.cors String
HTML5 CORS (Cross Origin Resource Sharing) Settings.

  • Set the default value for the crossOrigin property for all images that will be loaded by the krpano viewer.
  • When using use-credentials then additionally also the withCredentials setting will be enabled for loading text-files (xml, js, ...).
  • Because this setting affects the loading of files, it is possible to set it also already during embedding using the cors embedding parameter.

Allowed values:
  • 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 "*"
Variable nameTypeDefault value
security.cors_sameorigin Boolean false
Should the CORS setting also be applied when loading files from the same origin?

Normally this setting should be not enabled! Enabling can be even contra-productive, as it can make it necessary to load certain files twice.

This setting should be only enabled when doing HTTP redirections from the current origin to another 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.