HD View properties & XML Reference


HD View is a control that exposes a set of properties and events (callbacks) in order to interface with the host web page or application.

The following table outlines the control’s Javascript callback functions. 

Event

Description

onRotate(f,y,p)

(float, float, float) Called with the field of view (horizontal), yaw (y axis rotation), and pitch (x axis rotation) every time the rotation is changed by the UI. Only applies to cylindrical/spherical panoramas.

onTranslate(z,x,y)

(float, float, float) Called with the zoom (horizontal), x center (x axis translation), and y center (y axis translation) every time the translation is changed by the UI. Only applies to perspective panoramas.

onPanMode(n)

(int) Called when the pan mode is changed by the UI.

onToneMode(n)

(int) Called when the tone mode is changed by the UI.

onProjMode(n)

(int) Called when the projection mode is changed by the UI.

onFullScreen(b)

(bool) Called when full screen mode is changed by the UI.

The following table outlines the control’s properties.        

Property

Description

FileName

The source file.  An XML file describing the source, or, a string containing the XML source.  The XML format is described below.

BackgroundColor

(int) The RGB background color for the control’s window.

ForegroundColor

(int) The RGB foreground color for the control’s window, used for text etc.

PanMode

(int) panning mode: 0 = grab-and-drag (as in Virtual Earth), 1 = velocity interface (as in QTVR)

ToneMode

(int) tone mapping mode: 0 = none, 1 = linear, 2 = curve

ProjMode

(int) projection mode: 0 = default (perspective blending out to spherical), 1 = fisheye

FullScreen

(bool) full screen: false = default window, true = full screen window

ShowToolbar

(bool) show toolbar: true = show toolbar icons, false = no toolbar icons (keyboard still works)

Cylindrical or Spherical only properties:

Yaw

(float) set/get world rotation about the y-axis in degrees (centered at 180 if horizontal, 90 if vertical)

Pitch

(float) set/get world rotation about the x-axis in degrees (centered at 90 if horizontal, 180 if vertical)

FOV

(float) set/get horizontal field of view in degrees

Perspective only properties:

XCtr

(float) set/get image center along the x-axis (as fraction of image width; 0.5 for no translation)

YCtr

(float) set/get image center along the y-axis (as fraction of image height; 0.5 for no translation)

Zoom

(float) set/get zoom factor (as multiple; 1.0 for no zoom)

FileName may be an XML description, or an image file.  The XML description is useful for tiled image sets or by images that need the parameters exposed in the XML schema.  An example XML file follows.

	<?xml version="1.0" encoding="utf-8" ?>
	<root>
		<imageset
			url="{image.zip}image_files/l_{l}/c_{c}/tile_{r}.jpg"
			levels="9"
			width="20000"
			height="10000"
			tileWidth="256"
			tileHeight="256"
			tileOverlap="1"
			projection="cylindrical"
			phiMin="45"
			phiMax="135"
			thetaMin="120"
			thetaMax="240"
			rollPitchYaw="r p y"
			maxZoom="2"
			maxFOV="90"
			subRect="left top right bottom"
			alphaBlend="false"
			isLowerLeftOrigin="false"
			areTilesPadded="false"
		</imageset>
	</root>
	
imageset Attribute

Description

url Can specify a filename directly or a set of tiles. For the non tiled case this is simply the image name. A set of tiles can optionally be read out of a single .zip archive rather than a directory tree.

For the tiled case the tile name will be formed by replacing the {l} with the level number, the {c} with the tile column and the last {r} with the tile row (assuming the counts start at 0; use {L}, {C}, and/or {R} for counts that start at 1).

{image.zip} indicates that the subsequent portions of the path are potentially stored in a zip archive.  For local file system access HDView will first check if the archive file exists - if it does then it will retrieve the tiles from the archive named within the brackets.   On http or ftp accesses this directive is ignored and the tiles can't be stored in an archive.  If a multi-part zip is selected then this is indicated as {image.part4.zip}, HDView interprets this as the tiles are potentially distributed in 5 zip files image image.part0.zip through image.part4.zip.

{g} can be used to describe tilegroups stored in the Zoomify format, e.g. TileGroup{g}/{l}-{c}-{r}.jpg
levels The number of levels in the multi-resolution tile set. 0 is the coarsest level, levels – 1 is the maximum or finest level.
width Width of the image at its maximum (largest) level
height Height of the image at its maximum (largest) level
tileWidth Width of each tile (currently must be same as tileHeight). Defaults to 256.
tileHeight Height of each tile (currently must be same as tileWidth). Defaults to 256.
tileOverlap Pixel overlap of each tile to prevent seams between tiles. Defaults to 0.
projection Describes the projection. The default value is perspectiveValid values are:
  • perspective – projection onto a plane
  • cylindrical – projection onto a cylinder
  • cylindricalTransverse – projection onto a vertical or transverse cylinder
  • spherical – projection onto a sphere
  • sphericalTransverse – projection onto a vertical or transverse sphere.
phiMin Min vertical extent in degrees (centered around 90 if non-transverse or 180 otherwise)
phiMax Max vertical extent in degrees (centered around 90 if non-transverse or 180 otherwise)
thetaMin Min horizontal extent in degrees (centered around 180 if non-transverse or 90 otherwise)
thetaMax Max horizontal extent in degrees (centered around 180 if non-transverse or 90 otherwise)
rollPitchYaw "r p y" specify Euler angles that are applied to adjust the view. Useful if the roll angle of a panorama needs to be adjusted.  The default value is "0 0 0".
maxZoom The size in pixels a single pixel is mapped to at maximum zoom.  The default value is 2.
maxFOV  The largest field of view allowed.  Use this so to prevent users from zooming out too far.  The default value is 360.
subRect "left top right bottom" specify a region of the image to view. In some cases tiling programs will output padded or black tiles, this tag tells the viewer to only display an interior rect.
alphaBlend Can take values "true" or "false".  The default value is "false".  Enables alpha blending. The background area of stitched panoramas often has alpha of 0, so enabling alpha blending can prevent it being displayed.
areTilesPadded Can take values "true" or "false".  The default value is "false".  In the description below extreme tiles means the right-most tiles and the bottom-most ones for isLowerLeftOrigin="false" or the top-most ones for isLowerLeftOrigin="true"

false - The extreme tiles of the image are not padded to a tileWidth/tileHeight.  Instead they are exactly trimmed to width/height.

true - Extreme tiles are padded with black such that they have tileWidth/tileHeight dimensions
isLowerLeftOrigin Can take values "true" or "false".  The default value is "false"

false - Tile row numbering {r},{R} starts at top of image and increases down the image

true - Tile row numbering {r},{R} starts at bottom of image and increases up the image