krpano XML Reference Version 1.20.11

Select Version:

• 1.22
• 1.21
• 1.20.11
• 1.20.10
• 1.20.9
• 1.20.8
• 1.20.7
• 1.20.6
• 1.20.5
• 1.20.4
• 1.20.2
• 1.20.1
• 1.20
• 1.19-pr16
• 1.19-pr15
• 1.19-pr14
• 1.19-pr13
• 1.19-pr12
• 1.18
• 1.17
• 1.16.9
• 1.0.8.15
• 1.0.8.14
• 1.0.8.12
• 1.0.7

• 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).
  

voffset = (vfov_min + vfov_max) / 2

vfov_min = -70
vfov_max = +20
voffset = (-70 + 20) / 2 = -25

vfov_min = -90
vfov_max = +90
voffset = (-90 + 90) / 2 = 0.0

<view limitview="off" />

crop="x-position|y-position|width|height"

prealign="X|Y|Z"

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

multires="512,2048x1024,4096x2048,8192x4096,16384x8192"

• stereoformat="TB" - Top/Bottom
• stereoformat="SBS" - Side-By-Side

<image stereo="true" stereolabels="1|2">
  <cube url="pano_%s_%t.jpg" />
</image>

<image stereo="true" stereoformat="TB">
  <sphere url="plugin:video" />
</image>

• "equi" or "equirectangular" - Equirectangular projection (the default).
• "lambert" - Lambert cylindrical equal-area projection.

• 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.

• 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.

• Basically all modern browsers except IE11 and MS Edge are supported, these browsers don't support MJPEG streams.

• 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.

• "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 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".

• "none" (default)
  • Render only the depthmap pano itself.
• "pano"
  • Render the depthmap pano and behind it the normal undistorted pano 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.

• 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 are defining the axis order and the signs (+ or -) before the value the direction of that axis.
• 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 center setting allows defining a custom center point of the 3D-Model (in units of the original and unscaled geometry). From that center the pano-image will be projected onto the 3D-geometry.

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

<area mode="border"
      left="0"
      top="0"
      right="0"
      bottom="0"
      cliplayers="true"
      />

• 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.

• 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.

• 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:

• 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.

• "natural" (the default) - the hotspots will be keep rotated toward the viewers eyes.
• "screenspace" - the hotspots will be keep rotated toward the device screen (same as in normal non-VR viewing, but in VR there is no flat screen and so screen orientated things are looking wrong).

• "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".

• 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.

• 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.

• true - When enabled (the default) a 'relative' mapping between the drag control input and the pano view movement will be used. This is less accurate but gives a better control feeling at larger field-of-views and when using fisheye distortions.
• false - When disabled an 'absolute' mapping between the drag control input and the pano view movement will be used. That means when dragging point A in the pano image to point B. the view will exactly follow that movement.

• true - When enabled (the default) a 'relative' mapping between the moveto control input and the pano view movement will be used. This is less accurate but gives a better control feeling at larger field-of-views and when using fisheye distortions.
• false - When disabled an 'absolute' mapping between the moveto control input and the pano view movement will be used.

• image or plugin
  • The defaults, they don't need to be set.
  • The type will be image when loading an image file (like jpg, png, svg, ...) and plugin when loading a krpano .js plugin file.
• container
  • Use the layer as container element for other layer elements.
  • The layer element needs to have width and height settings!
  • The container element is transparent by default, but a background color, border and shape can be defined by the bgcolor, bgalpha, bgborder, bgroundedge, bgshadow and bgcapture settings.
• text
  • Use this layer as textfield.
• krpano
  • Embed another krpano viewer inside the layer.
  • This is an optimized way for embedding and controlling other krpano instances.
  • The layer itself is also a container element and has also all the container element settings.
  • The embedded viewer need to be controlled by Actions or Javascript.
  • When the viewer is ready 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;
    }
    

• iframe
  • Embed an iframe (website) inside the layer.
  • The url of the iframe can be set by the iframeurl setting.
  • The layer itself is also a container element and has also all the container element settings.
  • When the iframe is ready the onloaded event will be called and the layer will contain a iframe variable that provides access to the iframe html-element.
• html
  • Embed raw/unparsed html-code inside the layer.
  • The html-code can be set by the html setting.
  • If the html content should be scrollable can be set by the htmlscrollbars setting.
  • The layer itself is also a container element and has also all the container element settings.
  • When the layer is ready 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"

url.flash="plugin.swf

url.html5="plugin.js

crop="x-position|y-position|width|height"

parent="name-of-the-other-layer"

parent="layer[name]"
parent="hotspot[name]"

• 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.

bgborder="widths color alpha"

• 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.
• color (optionally)
  The color of the border lines. The default is 0x000000 (black).
• alpha (optionally)
  Transparency / alpha of the border lines (0.0 to 1.0, default=1.0).

bgshadow="xoffset yoffset blur color alpha"

bgshadow="xoffset yoffset blur spread color alpha inset, ..."

• 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, HTML5 only)
  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, HTML5 only, 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, HTML5 only, optionally)
  Add another shadow (comma separated).

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

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

• image
  • The default - uses the url file as image.
• text
  • Use this hotspot as textfield.

url.flash="animatedhotspot.swf

url.html5="animatedhotspot.gif