PTViewer Documentation

By Tim Green,2014-03-30 10:58
8 views 0
PTViewer Documentation

    PTViewer Documentation

    Updated for Version 2.4

    October 18, 2001

    Helmut Dersch

    Technical University Furtwangen

    PTViewer is an open and free Panorama viewer. It is written in the Java language (v.1.0.4) and should run in any java-enabled browser. From Version 1.4, there is an additional Java-application which runs without any browser on Java 1.1 installations.

    Its main features are:

    ; Spherical and Cylindrical Panorama Playback: Horizontal field of view: 360?,

    Vertical field of view 0-180?.

    ; Playback of Quicktime VR panoramas (Cylinders and Cubes) and Object movies

    using PTMViewer extension.

    ; Display of rectilinear Images using optional PTZoom extension.

    ; Panning, tilting and zooming. Full navigation using either mouse or keyboard.

    ; High Quality bilinear rendering as found in better plug-in viewers, and

    unlike many other java viewers.

    ; Antialiasing for display of high resolution images.

    ; Image and window size only limited by system memory.

    ; Link any document to any point in the image using hotspots.

    ; Configurable Controls in Appletwindow.

    ; Complete VR-Tours in Browsers and Appletviewer.

    ; Scriptable via html/javascript and internal scripting system

    ; Tiny file size (<25kByte) for fast download.

    ; Package all files into one self-displaying tour using the Jar-utility.

    ; Display 3D-objects, Panorama Movies and animations using auxiliary helper

    applets included in the distribution.

    ; Supports fast downloading low resolution preview panoramas and high

    resolution zoomable features (ROI).

    ; Optional protection of panoramas and images by encryption. Download the latest version of PTViewer from this site


    PTViewer uses equirectangular panoramic images, which must cover 360? horizontally. Vertical coverage may be any value between 0? and 180?. In the equirectangular

    projection, both horizontal and vertical axis are proportional to the viewing angle. Therefor, a full spherical panorama has an aspect ratio of exactly 2:1. An example, which is taken from the Virtual tour of Marburg from this site is shown below:

    The "Pan", "Tilt" and "FOV" values which you can set to override the defaults, are easily deduced from the figure above. JPEG and GIF images are supported. Any size for the source panorama can be used, however, memory requirements for image decompression may be quite large for some java engines. Suitable images can be created using various commercial packages (LivePicture, iMove) or the free PanoTools software from this site.

    Cylindrical images as used in QTVR or other viewers have to be converted to the equirectangular projection, which can easily be accomplished using the free Panorama Tools from this site. Use the following procedure:

    Open the cylindrical image in Photoshop (or any other Graphics program with the Panorama Tools plug-in installed). The example below is such a cylindrical rendering of the scene above as might have been used for QTVR. It is converted to PSPhere/equirectangular format using the remap tool with the shown settings. Notice that the image gets smaller without loosing information. The saving are quite considerable in large vertical field of view images.

Partial panoramaswith pan-range smaller than 360? and Flat Images can also be

    displayed. See the separate documentation for details.

    Image format may be JPEG (recommended for photographs) or GIF. To protect images against theft PTViewer images may be encrypted using the PTCrypt utility. There are

    various encryption options available, consult the PTCrypt documentation for details. Encrypted images are recognized by their extension (jpa, jpb, jpc,..) and can not be read by standard graphics programs. Using the stronger encryption features, they can't even be read by PTViewer if they are moved or copied from their original location.


    PTViewer is controlled by the html-file which sets the applet parameters. As a minimum, the size of the viewer window and the name of the image file have to be set. This section of the html file may then look like:



    The java code is contained in the file ptviewer.jar, which has to be placed in the

    same directory as the html-file, or you may provide a different path in the archive

    tag. Some viewers can not read jar files, and you have to provide the uncompressed class file instead.

    PTViewer may be used with these minimum controls. The file SimplePano.html in the distribution demonstrates this minimum functionality which is sufficient to view and navigate the panoramic images.

    PTViewer supports many more commands, which are all set by adding more PARAM-tags inside the APPLET tag. This is a list of options:

    ; file - The filename of the panoramic image. Alternatively, a panorama from

    a list specified using the pano0/1/2 tag can be loaded using the filename

    'ptviewer:Number' . Example: 'ptviewer:3' loads the panorama with list

    number 3.

    ; pwidth, pheight - Width and height of Panoramic image in pixel. By default,

    these parameter equal the width and height of the image specified in 'file'.

    Required only if regions of interest (ROI) are inserted later. See chapter


    ; roi0/1/2 - List of high resolution images to be inserted into the panorama

    as zoomable feature. For syntax and details see separate chapter below ; tilt - initial tilt angle (-90...90, default 0)

    ; pan - initial pan angle (-180...180, default 0)

    ; panmax - maximum pan angle ( 0...180, default none)

    ; panmin - minimum pan angle (0..-180, default none)

    ; fov - initial horizontal field of view (12...165, default 70) ; fovmin - minimum field of view (default 12)

    ; fovmax - maximum field of view (default 165)

    ; tiltmin - minimum tilt angle (-90 to 0, default -90 for spherical, or

    -vertical field of view for cylindrical panos)

    ; tiltmax - maximum tilt angle (90 to 0, default 90 for spherical,

    or vertical field of view for cylindrical panos)

    ; wait - Name of image (gif or jpeg) to be displayed during download. Specify

    path relative to html-document. This image is displayed centered in the

    applet window

    ; waittime - Minimum time to display the wait image, in Milliseconds (default

    0). This is useful if an animated gif-image is used, and the animation should

    finish before display of the panorama.

    ; auto - autorotation angle (-360...360, default 0) pan angle is incremented

    by that amount for each frame. Specify degrees, fractional values allowed. ; hotspot0,1,2,... - Alternative way to set hotspots, see next chapter ; shotspot0,1,2,...- Description of static hotspots, see next chapter ; maxarray - the maximum size for linear arrays on this machine (default 524288

    for Netscape). See the notes about large images.

    ; frame - An image to be displayed in front of the panorama window. This should

    be a gif or jpeg image. It will be inserted into the applet window aligned

    to the lower right edge. See the control buttons in Controls.html for an


    ; mousehs - Name of a user supplied javascript function which gets called

    everytime the mouse enters or leaves a hotspot. See example and notes on

    scripting below.

    ; getview - Name of a user supplied javascript function which gets called

    everytime the view (pan, tilt or field of view) changes. See example and notes

    on scripting below.

    ; bar_x - the x-coordinate of the upper left point of the progress bar (default


    ; bar_y - the y-coordinate of the upper left point of the progress bar (default


    ; bar_width - the width of the progress bar (default width/2). ; bar_height - the height of the progress bar (default 10 pixels). ; barcolor - the color of the progress bar (default dark gray). ; view_width - the width of the panorama viewer in pixels. Defaults to width

    of applet window.

    ; view_height - the height of the panorama viewer in pixels. Defaults o height

    of applet window.

    ; view_x - x-coordinate of upper left corner of the panorama viewer. (default


    ; view_y - y-coordinate of upper left corner of the panorama viewer. (default


    ; pano0,1,2,3 -List of panorama images for built-in controls. See next chapters

    for details.

    ; bgcolor - Hexadecimal integer specifying color of background ; hsimage - Name of hotspotimage describing masks for all hotspots. This image

    must have identical dimensions as the panoramic image. See chapter on

    hotspots below.

    ; sound0, sound1, sound2,... - Names of sound files to be used by the applet. ; quality - determines which of the two built-in pixel-interpolators are used

    for rendering the images: either the nearest-neighbor (nn, fast, low image

    quality) or the bilinear (bi, slow, high image quality) interpolator. The

    available options are 0 - always nn; 1 - nn for panning and autopanning, bi

    for stills; 2 - nn for panning, bi for stills and autopanning; 3 - always

    bi. (default 3).

    ; inits - Initialisation command which is executed after the panorama is loaded.

    This may be a ptviewer or javascript command, or a URL. The same syntax as

    in 'u' tags for hotspots should be used. The inits string may also link to

    a target inside a URL. In this case inits must contain the URL-string and

    the target string separated by a '*'-character, eg


    ; applet0, applet1,... - Applets to be loaded into ptviewer. Use this feature

    to load Panorama Movies, Objects or other helper applets.

    ; preload - Comma separated list of image files to be downloaded in the

    background. This is useful for VR-tours with many panoramic images. These

    are instantly available, without any download delay.

    ; cache - Set to 'false' if you want to disable PTViewer's internal RAM image

    cache (default: true). This may be required for very large tours which don't

    fit into RAM.

    ; cursor - Set to CROSSHAIR or MOVE to change the default arrow cursor. This

    change takes place only when the cursor is inside the applet window. ; loadAllRoi - set to "false" to disable download of all ROI-images at

    initialization time (default: true).

    ; grid_bgcolor - Hexadecimal integer specifying color of grid background

    (default white). This grid is displayed if tiled download is used, see chapter

    about ROI-images.

    ; grid_fgcolor - Hexadecimal integer specifying color of grid foreground

    (default black). This grid is displayed if tiled download is used, see chapter

    about ROI-images.

    mass - Inertia can be added to the viewer using a virtual mass (floating point

    parameter). This parameter influences the response of the viewer to

    directional changes. By default, this parameter is set to 0 turning off any

    delayed response. The useful and visible range of parameters for this option

    is ~10-30.

    ; antialias - Set this option to 'true' to turn on the Antialiasing feature.

    A series of scaled source images is created. Antialiasing is supported for

    equirectangular panoramas, QTVR panoramas (cylinders, cubes) and PTZoom

    images. For details see this example.

    ; oversampling - This floating point parameter is used with the antialias

    option above. It determines the maximum ratio of source resolution

    (pixel/degree) to screen resolution (pixel/degree). The default value is 1.5.

    Larger values cause more aliasing, while smaller values soften the view. ; order - This parameter is used with QTVR- files. It determines the order of

    the tiles (in the case of cylindrical panoramas), cubic-face images (in the

    case of cubic panoramas) or individual movie frames (in the case of object

    movies). If this order is non-standard, e.g. because the QTVR-file has been

    flattened, then this parameter should contain a comma separated list of

    numbers indicating the positions of the images. Example


    A list of panoramas can be defined using the pano0/1/2/3.. tag. This is required

    for use with the newPanoFromList() function. Using this feature PTViewer can be

    scripted without the need for a scriptable java-implementation. A panorama

    description consists of parameter tags similar to paramater tags in html pages. Each

    parameter tag is placed between braces. It consists of an identifier, followed by

    the equal sign ('=') followed by the value. The parameters have identical names as

    the above described tags, and are available except the view-related tags. An example pano tag:







     {hotspot0=x1141 y207 cff0000 n'Marburger Schloss' u'Controls.html'}

     {hotspot1=x311 y265 c00ff00 n'Pfarrkirche' u'Controls.html'} ">

    Please note that no quotes are used to enclose the parameters to the right side of the equations. Also, no spaces should be used on the left sides, since the simple parser used to read these parameters might get confused.

    Download feedback for the panoramic image is provided in two different formats depending on whether a 'wait'-image has been set. If not, then download feedback is provided by a message "Loading Image....X% complete" with X being the proper percentage. If a waitimage is specified, a progress bar is plotted inside the image. Size, location and color of this bar can be specified using the 'bar_..' tags. Download feedback indicates 80% when the image file has been loaded, and 100% after the image has been decompressed.


    Hotspots may be used to link other documents to specific points in the panoramic image. Hotspots are set using the 'hotspot' parameter in the APPLET tag. The active region of the hotspot may be specified in 4 different ways:

    1. Default (no specifications). A square region 24x24 pixels (in the viewer!)

    surrounding the x/y coordinate of the hotspot.

    2. Rectangular (specify a/b). A rectangular region (in the panoramic image!)

    limited by point x/y to the left and a/b to the right .

    3. Arbitrary shape (specify mask image m for each hotspot) The white regions

    of the mask image (in the panoramic image).

    4. Arbitrary shape (specify grayscale hotspot image hsimage, one for all

    hotspots, same size as panorama). The gray value of a pixel

    (0-254) determines the hotspot number it belongs to. 255 (white) means 'no

    hotspot'. This last method can not be mixed with the other three cases. Parameters in hotspot description lines and in other multi-parameter tags (static hotspots, ROI, etc) consist of an identifier, which is a single character, and its value. Parameters are separated by spaces, or, if they contain spaces, may be quoted by single quotes (') or any other letter, which is defined as quoting charcter by

    preceding it with the letter $. Example


    Each hotspot description consists of 4 mandatory parameters:

    ; xnumber or Xnumber- the x - coordinate of the hotspotlocation. 0 is left.

    x - absolute pixelcoordinate (0...width), X - relative pixelcoordinate

    (0...100), fractional values allowed.

    ; ynumber or Ynumber- the y - coordinate of the hotspotlocation. 0 is top.

    y - absolute pixelcoordinate (0...height), Y - relative pixelcoordinate

    (0...100), fractional values allowed.

    ; n'name' - the name of the hotspot displayed in the status line if the mouse

    moves over it. Must be enclosed with single quotes (').

    ; u'name' - the URL of the linked document relative to the html-document. Must

    be enclosed with single quotes ('). Instead of an URL, any of the ptviewer

    commands can be specified using the prefix "ptviewer:".

    The following are optional parameters:

    ; chexnumber - the RGB-color of the default hotspot marker. Specify as

    hexadecimal number RRGGBB. Default is red.

    ; i'name' - name of image to be displayed when hotspot is activated. Must be

    gif or jpeg, and will be shown centered at hotspot location. Instead of an

    image, any of the ptviewer commands can be specified. This command will be

    executed when the mouse enters the hotspot region. Example:

        i'ptviewer:PlaySound(0)' u'Controls.html' ">

    This hotspot plays the sound numbered 0 when the mouse enters. Hotspots

    executing commands are always of type popup and don't react to the showHS()

    command. If the 'e' parameter is specified, then 'i' specifies a text window,

    see below.

    ; t'name' - name of target in html-document specified with option u. ; m'name' - name of an image to be used as mask for shaping hotspots. Normal

    hotspots have square format and are 20x20 pixels large. To set other shapes,

    create a gif-image which is white at locations belonging to the hotspot. This

    image will be referenced with the upper left point being the x/y coordinate

    specified above. Hotspot markers appear centered in the image. Please see

    the streetlight example in the distribution.

    ; p - Specifying p (without parameter) makes this hotspots image pop up when

    the mouse moves over it, see the streetlight example.

    ; q - Specifying q (without parameter) makes this hotspot always visible. This

    may be used as floating logo.

    ; w - Specifying w ( for 'warped', without parameter) causes the specified image

    (see i-tag) to be inserted into the panorama image rather than into the viewer

    window. As a result, the image is blended and fixed to the background. See

    the roof of the building to the left in the example "Controls.html" which

    turns green when showing the hotspots. This feature works for permanent,

    popup and normal hotspots. The image will be inserted centered at the x/y

    coordinate. Please note that x/y = 0/0 refers to top left, while some graphics

    programs use the convention (1/1) for this point. The image must fit into

    the panoramic image and may not extend across the back seam. Hotspots using

    warped images are by default rectangular, ie the area of the image is active

    region of the hotspot, unless a separate mask image is specified.

    ; e - Specifying e (for text, without parameter) causes the specified image

    parameter (i-tag) to be interpreted as text message. This message is

    displayed in a rectangular window, with one corner being the hotspot. This

    corner is marked by a dot. The text window is positioned to fit into the viewer.

    Line breaks are marked by the character '|'. The c-parameter (see above) is

    used to specify the color of the text. Example:

        e ">

    ; a number or A number - the x-coordinate of the right edge of a rectangular

    hotspot. a - absolute pixelcoordinate (0...width), A - relative

    pixelcoordinate (0...100), fractional values allowed. If a or A is set, the

    active hotspot region is a rectangle with left coordinate x and right

    coordinate a. The hotspot marker image is shown centered. Please note, that

    a rectangle in the panoramic image is warped in the viewer window. If you

    need exact shapes, then use the m-tag for a masked hotspot.

    ; b number or B number - the y-coordinate of the right edge of a rectangular

    hotspot. b - absolute pixelcoordinate (0...height), B - relative

    pixelcoordinate (0...100), fractional values allowed. If b or B is set, the

    active hotspot region is a rectangle with left coordinate x and right

    coordinate a. One of b or y should be the top, the other coordinate is the

    bottom of the rectangle. The hotspot marker image is shown centered. Please

    note, that a rectangle in the panoramic image is warped in the viewer window.

    If you need exact shapes, then use the m-tag for a masked hotspot. Options may be specified in any order.

    These are examples for hotspot tags:

     Schloss' u'pano.html'">

         n'Pfarrkirche' u''" >

         n'Stairs' u'pano.html' ">

     n'Sky' u'pano.html' ">

         n'Entrance' u'javascript:test()' ">

         n'Center' u'panos.jpg' ">

         m'images/lmask.gif' p i'images/popup.gif' u'pano.html' ">

    Hotspots may be stacked. If one hotspot has identical x and y coordinates as another hotspot prior in the list, it is assumed to be identical. The mask of the prior hotspot will then be reused. If this hotspot gets activated by clicking the mouse, or moving the mouse over it, the appropriate actions of both hotspots are executed. Arbitrary many hotspots may be stacked at any position. The file 'Controls.html' of the distribution contains this example for a stacked hotspot:

         m'images/lmask.gif' i'ptviewer:PlaySound(0)' u'Controls.html' ">


    A common use for hotspot images is the tripod cap, ie a small logo at nadir position which covers the inevitable tripod head in full spherical panos. This logo usually links to the author of a panorama. See these examples which use normal, and warped

    hotspot images for this purpose.

Static Hotspots

    From Version 1.1. PTViewer supports static hotspots. These are static locations in the applet window which can be used like clickable image maps in html. The syntax to set these static hotspots is similar to the panorama hotspots. Note that all coordinates are absolute pixelcoordinates in the applet window. Static hotspots are set using the 'shotspotNumber' parameter in the APPLET tag. Each static hotspot

    description must consists of 5 mandatory parameters:

    ; xnumber - the left x - coordinate of the static hotspotlocation.

    ; ynumber -the top or bottom y - coordinate of the static hotspotlocation.

    ; anumber - the right x - coordinate of the static hotspotlocation.

    ; bnumber -the bottom or top y - coordinate of the static hotspotlocation.

    ; u'name' - the URL of the linked document relative to the html-document. Must

    be enclosed with single quotes ('). Instead of an URL, any of the ptviewer

    commands can be specified using the prefix "ptviewer:".

    The following are optional parameters:

Report this document

For any questions or suggestions please email