Publish to Website

The PTGui Viewer plugin can be used to publish a 360 degree or fully spherical panorama on a website. The plugin enables website visitors to 'look around' in the panorama by clicking and dragging with the mouse. For examples of such interactive panoramas see the Gallery on www.ptgui.com.

PTGui can generate all necessary files for publishing a panorama on a website in one click. The PTGui Viewer supports multiple technologies:
All modern web browsers (including smartphones and tablets) support either CSS3D or WebGL (or both). On older browsers the Flash plugin will usually be available. The appropriate technology is chosen automatically and transparently by the PTGui Viewer. You only need to publish your panorama once to make it viewable on nearly every computer, tablet or smartphone.

Usage

The panorama first should be stitched to an equirectangular image. Next the resulting panorama is converted using the Publish to Website tool. Finally the generated files need to be uploaded to the web server, for example through ftp.

Stitching the panorama

When stitching the panorama it's best to create the panorama in equirectangular projection; to do so click the button in the Panorama Editor. Adjust the field of view using the two sliders until the panorama fills the entire canvas. Do not use the yellow crop lines in the panorama editor: these cause asymmetrical cropping which is not supported by the PTGui Viewer.

Make a note of the horizontal field of view of the panorama: this is shown in the bottom status bar of the panorama editor window. For example if the status bar in the panorama editor displays '360° x 180° Equirectangular' then the horizontal field of view is 360 degrees. It is recommended to use the Publish to Website tool only for panoramas wider than 180 degrees: internally the panorama is converted to a full 360° x 180° representation; a lot of space is wasted if the viewable part of the panorama is only a small fraction.

Go to Create Panorama, choose 'Optimum Size' -> 'Maximum Size'. Then render the panorama in TIFF or JPEG format.

Converting for web display

After the panorama has been created select Tools -> Publish to Website... to open the conversion tool.

Click on Add Files to load the stitched panorama. Multiple panoramas can be converted in one go by adding them to the list. Use Remove if you need to remove a panorama from the list.

Set the Projection and Horizontal Field of View to match the properties of the panorama (i.e. equirectangular and the field of view noted above).

In the Output section specify the destination folder and file names of the generated files. The tool generates 15 .jpg tiles, one .htm file and two plugin files (PTGuiViewer.js and PTGuiViewer.swf). The .jpg and .htm files will be prefixed with the file name chosen in the Save as field. If Save to files with same names in the source folder is checked, the output files will be placed in the folder containing the source images, with a file name prefix identical to the source file name.

Files created shows a summary of the names of the files that will be generated.

Settings

Resolution: the combined size in megapixels of the generated .jpg tiles. Use Automatic to choose the optimum size at which no loss of quality occurs. Using a smaller size shortens the download time before the panorama is displayed fully, but also reduces the image quality. In Automatic setting the output panorama size is limited to 60 megapixels. This can be overridden by deselecting Automatic, but such large panoramas cannot reliably displayed on every computer.

iPad/iPhone/iPod size limit: the PTGui Viewer supports Apple mobile devices which have limited memory. If the panorama is too large (i.e. too many pixels) the Safari browser on the device runs out of memory and may shut down without warning. Therefore a separate size limit specifically for these devices can be set. In practise 4.5 megapixels is a safe limit.

JPEG quality: the quality level (0 .. 100) of the generated .jpg files. A lower number will result in lower quality but faster downloading.

Further, the Pan, Tilt and Field of View can be configured. For each parameter an initial value, a minimum and a maximum value can be set:

Pan sets and limits the horizontal viewing direction: 0 is the center of the panorama, -180 is the leftmost side and 180 is the rightmost side.

Tilt sets and limits the vertical viewing direction: 0 is the horizon, 90 the zenith and -90 the nadir.

Select Automatic to set the pan and tilt limits automatically, such that the visible area is limited to the boundaries of the panorama.

Field of View sets and limits the zoom: lower values zoom in, while higher values zoom out.

Auto rotate: if enabled, the panorama will start rotating as soon as it is diplayed. Visitors of your web page will imediately notice that it is a panorama and not a flat image. Speed sets the rotation speed in degrees per second. At 5 degrees per second a full rotation (360 degrees) will take 72 seconds. A positive speed setting will rotate the 'camera' to the right, negative will rotate in the opposite direction.

The auto rotation stops as soon as the user clicks in the panorama. If Resume after  is enabled, auto rotation will start again after the chosen time of inactvity.

Show Full Screen Button: by default a clickable Full Screen button will be shown in the top right corner. Clicking on it will switch to full screen display mode. Select Yes to show the fullscreen button or No to disallow full screen viewing.

Gyroscope Navigation: when enabled, on mobile devices the panorama can be navigated by rotating and tilting the device.

Create: you can choose to generate all required files, or only the .jpg tiles. Use the latter if the PTGui Viewer files are already on your web server and you are using custom HTML/PHP code to show your panoramas.

The tool will generate a basic HTML page for you. Enter the desired title of the web page at Web Page Title; this will be shown above the panorama and in the browser's title bar. At Description you may enter some text to be shown below the panorama.

Uploading to website

Finally all generated files (.jpg, .htm, PTGuiViewer.js and PTGuiViewer.swf) should be uploaded to your web server. Generally this is done via FTP, SFTP or SCP. Contact your web hosting company for more information on how to do this. After the files have been uploaded link to the uploaded .htm file to show the panorama.

Using custom templates

PTGui will generate a basic web page with a default layout. If you know how to edit html and css, you can customize the generated web page like any other html file. Alternatively a template can be used to customize the layout of the pages generated by the Publish to Website tool.

Select Use Custom Template to use your own template. Click on Browse and point to your own template file (.htm format). Or click on Create Template to create a new template file: this creates a copy of PTGui's default template, which you can customize.

The template is a regular .htm file with 3 custom tags in it:

{{TITLE}} - will be replaced by the value entered in the Web Page Title field
{{DESCRIPTION}} - replaced by the text entered in the Description field
{{PARAMS}} - parameters for the panorama viewer plugin

The viewer is embedded in the web page using Javascript commands; this code is best copied from the default template.

Local viewing

The PTGui Viewer is designed to be used on a website. While it is also possible to view the generated .htm file locally on your computer, web browsers and Flash have security restrictions preventing access to files stored on the hard disk of your computer.

If the PTGui Viewer cannot display a panorama due to Flash security restrictions it will show instructions for setting a security exception. Local Javascript is restricted as well in some browsers, which could cause the viewer not to be displayed at all when the files reside on your computer. These restrictions do not apply anymore once the panorama is uploaded to a website.