Pangea Software, Inc.

Panoramic Photography Services in the Austin, TX Area


PangeaVR Plug-in : Technical Info

Writing the HTML

This is a basic example of how to add HTML code to your web page that will send a .mov file to the PangeaVR plug-in for viewing:
<embed PLUGINSPAGE = "http://www.pangeasoft.net/pano/plugin/downloads.html" src="thepano.qtvr" type="graphics/pangeavr2" width="99%" height="90%">
The required parameters are:
src

This is the path to the panorama file that you want PangeaVR to display. This can be either a QuickTime movie or an equirectangular JPEG image.

IMPORTANT: If you're using JPEG source files, be sure you are using the new MIME Type: "graphics/pangeavr2" or else it could crash pre-2.0 versions of the PangeaVR plug-in!
width

The width of the image frame to display. Can either be a constant pixel value, or a percentage.
height

The height of the image frame to display. Can either be a constant pixel value, or a percentage.
PLUGINSPAGE This tells the web browser where to find the plug-in if it isn't already installed.
TYPE This is the MIME type of the PangeaVR plug-in. This is required to tell the browser what plug-in to use for this. NOTE: In version 2.0 the MIME type changed to graphics/pangeavr2. The old MIME type will still work on your existing pages, but all future pages must use the new MIME type. Using the old MIME type with the new equirectangular .jpeg files in 2.0 will cause older versions of Pangea VR to crash!

The optional parameters are:

CONTROLLER The default is TRUE. Set to FALSE if you don't want any controller bar to be displayed.
COMPRESSION The default is FALSE. Set this to true if you want to enable hardware texture compression. That this setting has no effect if the user's video hardware doesn't even support texture compression. See full details about texture compression below.
FOV Sets the initial camera FOV value in degrees. The default is 80 degrees, but you can specify values between 10 and 140 degrees in this parameter.
MAXFOV Sets the max FOV value the user can zoom to.
MINFOV Sets the minimum FOV value that the user can zoom to.
PAN Specifies the initial Pan angle. The default is 0.
TILT Specifies the initial Tilt angle. The default is 0 and the min/max is -90/+90
DRAGFRICTION The default is FALSE. When set to TRUE, if the user is dragging on the pano to rotate it, the pano will come to a stop if the mouse stops moving. When set to FALSE, the pano will continue to freely spin as the user holds down the mouse button even if the mouse isn't moving. As soon as they let go of the mouse button the friction will kick in to bring the pano spin to a halt. FALSE makes interaction a little closer to how the Quicktime player works.
MINTILT The default value is -90. This is the minimum degree angle that the camera can tilt down. Straight is -90, but you can go to even smaller numbers to allow the camera to be spun upside-down.
MAXTILT The default value is 90. This is the maximum angle in degrees that the camera can tilt up. Straight up is 90, but you can use even larger numbers to allow the camera to be spun upside-down.
TEXT Allows you to display a line of text at the bottom of the pano. This may be up to 255 ACSII characters long. Note: if the Helvetica font is not installed then no text will appear.
FONTSIZE This indicates the point size to display the font used in the TEXT parameter. The default value is 32 point.
AUTOPAN The pano will automatically pan until the user clicks on it. The input parameter is the degrees-per-second rotation value, and it can be + or -. So, a value of 10 would cause the pano to spin at a speed of 10º per second.
CACHE true/false if you want the panorama's file to be saved in the browser's cache for faster reloads. Your browser may already have a default preference setting for this, but this parameter will override it. Note, however, that some browsers won't cache large files.
THUMBNAIL This will display a thumbnail image while the pano is being loaded. The thumbnail file just be a JPEG. The value of this parameter is the filename of the thumbnail JPEG image. This file path is relative to the directory of the panorama file, so if your thumbnail is in the same directory as the pano file then you may have something like this: THUMBNAIL="mythumb.jpg" Or, if the file is in the pano's parent directory, then it could look like this: THUMBNAIL="../mythumb.jpg". The JPEG must be 512x512, 512x256, 256x256 or 256x128. Any other dimensions and it won't load! See additional notes below. NOTE: due to bugs in Mozilla, thumbnails are currently disabled on all browsers except Safari.
THUMBSCALE Sets the scaling factor of the thumbnail image. The default is 1.0.


Below is a sample panorama with the following HTML code:

<embed pluginspage="http://www.pangeasoft.net/pano/plugin/downloads.html" height="396" src="files/thepano.qtvr" type="application/pangeavr" width="560" COMPRESSION="true" CONTROLLER="true" FOV="70" PAN="45" TILT="45" DRAGFRICTION="true" TEXT="Guest Bedroom" FONTSIZE="20" THUMBNAIL="thumb.jpg">



About using Texture Compression

Compressing textures adds significant time to the loading of the panorama (over 7 seconds for a hi-rez file on a dual 2ghz G5, 15 seconds on a 1.25ghz Powerbook G4). The benefit to using compression, however, is that your pano images will retain their resolution when viewed on video cards with low VRAM. It also frees up some VRAM for other applications running concurrently.

This is a lossy compression, so the image quality does degrade. It is very noticable in smooth areas or dark gradients such as sky or flat walls. Detailed panos don't show the degredation much, so it's best to use it only on panos with lots of detail. Panos with very low detail or lots of sky may not look good with compression, so you should probably keep it turned off in those cases. This problem is very apparent in the example pano above where the dark walls have banding artifacts. This is definitely a worst-case example, so you should experiment with your own pano's to see what results you get.

Note that starting in version 1.1 of PangeaVR, the user has the option to override your compression settings in their PangeaVR Preferences dialog, but you should still set this to your desired setting since the default behavior of the plug-in is to use the HTML's compression setting.

Limits of the QTVR .mov files

1. PangeaVR only reads Cubic QTVR movie files. It won't work with any other format such as cylindrical.

2. Images in the .mov files must be JPEG. Any other format, such as TIFF or PNG may cause the plug-in to crash.

3. The headers must NOT be compressed. PangeaVR cannot parse header data that has been compressed.

4. Most of the testing has been done with .mov files which were created with Cubic Converter. Files created with other apps should work fine, but if you encounter issues, please let me know.

5. If your file is named with the .mov or .qt extension then the web browser will automatically use Quicktime to show the panorama if PangeaVR is not installed. You may or may not want this behavior. If you want the web browser to tell the visitor that they need the PangeaVR plug-in, then rename the file with a different extension, such as ".qtvr".


The images in your cubic QTVR files can be any size that you want. PangeaVR intelligently determines what the largest allowed image size is based on each visitor's video hardware specs. The COMPRESSION tag described above will help retain the original resolution at the cost of a longer load time. Generally speaking, however, your hi-rez QTVR .mov files should follow these rules for optimal load times:

1. Avoid tiled images. This only increases the .mov file size and increases load and decompression times. It does not add any benefit to PangeaVR.

2. Avoid fast-start tracks. These also just add to the .mov file size and are ignored by PangeaVR anyway.

3. Cube face images that are a power of 2 in size will load faster; such as: 512x512, 1024x1024, 2048x2048.

4. Since most 3D hardware only supports textures up to 2048x2048, having cube faces larger than that only causes PangeaVR to shrink them down. Additionally, anything larger than that really isn't going to make any visual difference since even a 23" Cinema Display at 1920x1200 resolution cannot show all those pixels when the FOV is set to a normal value. Higher resolutions only help when you zoom in a long way.

Limits of the Equirectangular JPEG files

1. The files must have the .jpg or .jpeg file extension (can be upper-case).

2. These must be full 360º x 180º equirectangular images. Partial panos will not work - they won't crash or anything, but they won't display properly.

3. PangeaVR chops the equirectangular images into 8 textures for OpenGL to use (4 across and 2 down). Generally, the maximum texture size that most 3D hardware can render is 2048x2048. Doing the math: 2048 * 4 = 8192 tells us that the largest practical pano resolution is 8192 x 4096. It takes a lot of VRAM to store that much pixel data, so not every computer will be able to display the pano at full resolution. Odds are the textures will get reduced just as they do when loading QuickTime movie files, however, equirectangular panos will usually render at higher resolutions that cubic QTVR panos. Not always, but usually - it depends on the amount of VRAM available and the size of the pano JPEG image.

Limits of the Thumbnail JPEG images

1. You should keep these thumbnail images as small in file size as possible so that they load very quickly. Try to keep them under 20k.

2. The files MUST be 512x512, 512x256, 256x256 or 256x128 in size. Any other size simply won't show up. It won't crash, but you won't see the thumbnail.

3. The JPEG filename is relative to the pano file's directory, so you do not need to specify a full path if the file is in the same directory as the pano. See example above.



To send feedback or get information: brian@pangeasoft.net

©2010 Pangea Software, Inc.