The Adobe PDF-format for Acrobat and Acrobat Reader can be displayed on almost any computer. The availability is better than that of all other techniques used for display of VR-content like Java, Javascript, Quicktime etc. PDF offers some limited interactive possibilities which I have tried to employ in this PDF-Panoramaviewer.
PDFPanorama converts panoramas and objectmovies into PDF-files. As in Javascript-based panorama-viewers (and any object-viewers) the panorama is displayed as navigatable sequence of still-images. Panoramas tend to result in quite large files, suitable mainly for CDs, whereas object-movies retain their size. Interactivity is provided by
To avoid yet another syntax and make authoring as simple as possible, I have adopted the PTViewer-format. Ideally, PDFPanorama reads HTML-files, extracts embedded PTViewer-panoramas (the <APPLET> tag) and converts them on the fly into a format suitable for Acrobat-Reader, eg the necessary extracted views are generated automatically, hotspots are calculated and positioned, etc. A small but useful subset of PTViewer-commands is parsed and understood, so that conversion should be simple. In reality, there are a few incompatibilities which are described in the documentation below. Nevertheless, complete navigatable tours with arbitrary many panoramas in one file are feasible, and displayable on any Acrobat-equipped computer (ie no java/javascript/Quicktime or other plugin is required).
Three examples are posted as demonstration. It is advisable to adjust Acrobat to 100% Zoom-level for best image quality although any value should work.
Installation:
Only the Windows platform is supported. However, the included sources make the program portable to almost any system.
Two steps are required:
PDFPanorama is now ready to work. It is best to first
try, repeat and study the example Monument Valley from my website.
See the documentation below for more details.
Compiling PDFPanorama:
To build the program, you need the sources included in the package, plus the pdflibrary pdflib .Depending on the operating system, you may also need to get some standard utility files like getopt.c etc. The Makefile of the distribution is written for the Mingw(gnu-c) installation, and can be edited for other compilers.
Using PDFPanorama
PDFPanorama may be invoked in two ways:
Converting PTViewer-Panoramas
In the following some familiarity with PTViewer is assumed. It should be emphasized again, that PDFPanorama does not require Java, Javascript or any other plug-in, even though it uses similar commands as PTViewer. Only Adobe Acrobat is required to display and view the final panorama.
This is an applet-tag from a HTML-page, which can be processed by PDFPanorama. It is the source file for the Monument Valley example:
<APPLET archive=ptviewer.jar code=ptviewer.class name=ptviewer width=300 height=240> <PARAM name=shotspot0 value=" x90 y226 a120 b240 u'ptviewer:panDown()' "> <PARAM name=shotspot1 value=" x120 y226 a150 b240 u'ptviewer:panUp()' "> <PARAM name=shotspot2 value=" x150 y226 a180 b240 u'ptviewer:panLeft()' "> <PARAM name=shotspot3 value=" x180 y226 a210 b240 u'ptviewer:panRight()' "> <PARAM name=pan value=-10> <PARAM name=tiltmax value=30> <PARAM name=frame value="Control.gif"> <PARAM name=file value="Monp.jpg"> </APPLET>PDFPanorama generates a PDF-file using the image size set by width and height. The views are extracted from the image "Monp.jpg" given by the file-tag. The default pan-angle is set to -10, and another image named "Control.gif" is loaded and inserted, containing buttons for navigation. These buttons are linked to four static hotspots using the shotspot tags. Such a control panel is optional in PTViewer, but required in PDFPanorama since there is no other way of navigating the world.
The following tags are parsed and understood by PDFPanorama. Please consult the PTViewer documentation for their exact meaning:
file, pan, frame, width, height, tiltmax,
view_width, view_height, view_x, view_y,
fov, hotspot#, shotspot#, pano#
Static hotspots (shotspot) are specified using
these commands:
x, y, a, b
- Coordinates
u'Command'
- Action
Command may be one of the following:
ptviewer:panLeft() - pan one frame to the left
ptviewer:panRight() - pan one frame to the right
ptviewer:panUp() - tilt one frame up
ptviewer:panDown() - tilt one frame down
ptviewer:newPanoFromList(num) - Load Panorama num from List
http://any_address - Open Weblink
Dynamic hotspots (hotspot) are specified similarly:
x, y
- Absolute Pixel Coordinates
X, Y
- Relative Coordinates
(0...100)
n'Note'
- The Note will be displayed
as PDF-annotation floating
at the hotspot position
u'Command'
- Action, same as for static
hotspots
Panorama lists (pano) can be specified for multi-image
tours.
The syntax is identical to that of PTViewer, e.g. one
valid entry in a list could be
<PARAM name=pano0 value="{file=schloss1.JPG}
{auto=0.5}
{pan=20}
{fov=80}
{fovmax=130}
{fovmin=25}
{hsimage=schloss1HS.gif}
{hotspot0=X18.4 Y45.7 n'Court Yard' u'ptviewer:newPanoFromList(2)'}
{hotspot1=X52.6 Y63.4 n'Pfarrkirche' u'ptviewer:newPanoFromList(3)'}
{hotspot2=X40 Y57 n'Market Place' u'ptviewer:newPanoFromList(6)'}
{hotspot3=X82.7 Y53.8 n'Road' u'ptviewer:newPanoFromList(1)'}">
{hotspot4=X90.7 Y20.8 n'Home of Author' u'http://www.fh-furtwangen.de'}">
The entries auto,fovmax,fovmin and hsimage
are ignored, everything else works as in PTViewer. This example is taken
from Marburg.html, the source for the Virtual tour of Marburg above.
Converting PTViewer-Objects
Objectmovies in PTViewer are handled by the extension
PTObject.class with a special syntax. The same syntax works for pdfpanorama.
Example:
<APPLET archive=ptviewer.jar code=ptviewer.class width=320 height=225 name=ptviewer>
<PARAM name=inits value="ptviewer:startApplet(0)">
<PARAM name=frame value="Control.png">
<PARAM name=shotspot0 value=" x0 y200 a160 b225 u'ptviewer:panLeft()' ">
<PARAM name=shotspot1 value=" x160 y200 a320 b225 u'ptviewer:panRight()' ">
<PARAM name=shotspot2 value=" x200 y0 a320 b21 u'http://www.fh-furtwangen.de' ">
<PARAM name=view_height value=200>
<PARAM name=applet0 value="{code=ptobject.class}
{file=Result.jpg}
{nhor=18}
{nver=1}">
</APPLET>
This is the source for the example Renault
above.
The two static hotspots for navigation are like the ones
in the last example. Objects are declared using the applet#-tag
together with {code=ptobject.class}. The following tags may then
be used to further specify the object movie:
file, nhor, nver
nhor and nver override the settings in
"x" and "y" when starting from the commandline. Currently, only single
row objects (nver = y = 1) work correctly.
Problems with GIF-Images
Acrobat and/or the pdflib used in PDFPanorama have problems with many types of GIF-images specifically those with palettes having less than 128 colours. Therefor, GIF-images which perfectly work in PTViewer often do not work in PDFPanorama. This is indicated by an error-message "Could not read Image .." when starting the program. A workaround is converting GIFs to PNG-Format. These are supported by the Acrobat software, and they also offer transparency as well as lossless compression, which both is needed for buttons and controls. Unfortunately, Java and hence PTViewer on the other hand do not support the PNG-format. Therefor two sets of control images are sometimes required, one in GIF-format for PTViewer, and one in PNG-format for PDF-files.
Extensions to the PTViewer-format
PTViewer works with stitched equirectangular panoramic images. PDFPanorama extracts the required partial views from this panoramic image during conversion. It may be that no equirectangular image exists, but just a sequence of equally spaced source photographs of the scene. It would be tedious to first stitch the images, and then have PDFPanorama extract the views back. Instead, these series of photographs may be directly used as source images.
This is accomplished by giving names to the images containing
numbers starting with 0, eg image0.jpg, image1.jpg, image2.jpg,
... without leading 0! These images should be ordered from left to right
in rows starting with the horizontal row, then moving up until vertically
up, and then the remaining steps below horizon.
Example: We have 5 rows (tilt = -90°,-45°,0°,
45°, 90°) with 10 images each. These should be numbered
tilt=0°
image0 ... image9
tilt=45°
image10 ...image19
tilt=90°
image20 ...image29
tilt=-45° image30
...image39
tilt=-90° image40
...image49
Then specify the file tag in the HTML-source file
to be "image#.jpg", ie the sign '#' instead of the numbers. pdfpanorama
then inserts the appropriate numbers, and loads the corresponding images.
The same applies to objectmovies: For PTViewer, these
are long movie-like stripes, which have to be assembled from individual
images. For PDFPanorama these individual images can be used directly
using the syntax descibed above.
License:
The program PDFPanorama implements the excellent library package pdflib by Thomas Merz together with routines of my previous VR-related work. "pdflib" is covered by the so-called "Aladdin Free Public License", and so is this program "PDFPanorama". The text of this license is included in this package. To quote the most important phrase for most users "Functional use (running) of the Program is not restricted...", i.e. you may freely create panoramas and object movies using this program, be it for private or commercial use. Restrictions apply if you want to distribute copies of this software or modified copies or derived software, please read the license text carefully. The terms are more restrictive than the well-known GNU-license applicable to my other software.
This package includes the sources required to build PDFPanorama, actually only those not readily available. Modfying and/or distributing these sources is also covered by the Aladdin Free Public License.
Finally, as always: BECAUSE THE PROGRAM IS LICENSED FREE
OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM.
1999-2003 © Helmut Dersch der@fh-furtwangen.de