Download PhotoWarp 2.5

PhotoWarp 2.5
User's Guide
Welcome!
Welcome to PhotoWarp 2.5! PhotoWarp is a simple-to-use yet powerful tool for generating
panoramic images. PhotoWarp unwarps images from one-shot optics, cylindrical and spherical
images, and QuickTime VR cylinders. It generates panoramas for QuickTime VR, Flash, PTViewer
or Zoom Viewer, as well as cylindrical or spherical images and thumbnails. Finally, PhotoWarp
creates customizable web pages for presenting your panoramas.
You'll be up and running with PhotoWarp in just a few minutes. To get started right away, read the
Installation and Quick Start chapters. For more in-depth coverage of PhotoWarp's advanced features,
this document will be your guide.
Table Of Contents
1. Installation
1. Mac OS X installation
2. Windows installation
3. Setup Assistant
2. Quick Start
1. A quick tour of PhotoWarp
2. Unwarping your next panorama
3. Jobs
1.
2.
3.
4.
5.
Job window
Source pane
Format pane
Unwarping
Output pane
1.
2.
3.
4.
5.
One-shot images
Cylindrical and spherical images
QuickTime VR cylinders
Constraints
Notes
4. Sources
5. Formats
1. Supported output formats
2. Output format settings
6. Templates
1. Job templates
2. Format templates
7. Additional Features
1.
2.
3.
4.
Inspector / Details window
Preview window
Unwarp log
Preferences
8. Web Scripts
1. Web script format
2. Included web scripts
3. Creating web scripts
A. Web Script Reference
1. Job description variables
2. Prefix functions
B. Version History
1. PhotoWarp 2.5
2. PhotoWarp 2.0
3. PhotoWarp 1.0
C. Credits and Acknowledgements
Installation
This chapter discusses the installation and first use of PhotoWarp on your computer. The PhotoWarp
CD includes all the software you need to use PhotoWarp on either a Mac OS X-based computer or a
Windows-based computer.
The installation process is different on the Mac and the PC, so skip ahead to the section appropriate
for your computer.
Macintosh Installation
Windows Installation
Macintosh Installation
Before installing PhotoWarp, make sure your computer meets these system requirements:
Mac OS X version 10.2.7 or higher
QuickTime 6.5 or above (included)
128 MB RAM (256 MB recommended)
100 MB available hard drive space (10 MB for application, plus space for images)
1024 x 768 display or larger
Install QuickTime
PhotoWarp requires QuickTime 6.5 or above to operate. Installers for QuickTime 6.5 are contained
on the PhotoWarp CD in the "QuickTime 6 Installers" folder. Alternately, you can download the
latest version of QuickTime for free from Apple's web site:
http://www.apple.com/quicktime/download/
Install PhotoWarp
Now we're ready to install PhotoWarp itself. Double-click on the "PhotoWarp 2.5" disk image on the
CD. In the folder that appears, simply drag the PhotoWarp icon to your Applications folder, or
anywhere you would prefer to install the application.
Continue now to the Setup Assistant.
Windows Installation
Before installing PhotoWarp, make sure your computer meets these system requirements:
Windows 98, ME, 2000, XP or above
Microsoft .NET framework (included on CD)
QuickTime 6.5 or above (included on CD)
True color (32 bit / millions of colors) display
128 MB RAM (256 MB recommended)
100 MB available hard drive space (10 MB for application, plus images)
1024 x 768 display or larger
Install the Microsoft .Net Framework
First, we need to install the .Net Framework, a set of support libraries which PhotoWarp uses. Rightclick on the PhotoWarp CD icon in Windows Explorer, then click on "Install .Net" in the menu.
Windows 98 users will need to restart after installing .Net before continuing.
Install QuickTime
PhotoWarp requires QuickTime 6 or above to operate. Installers for QuickTime 6.5 are contained on
the PhotoWarp CD in the "QuickTime 6 Installers" folder. Alternately, you can download the latest
version of QuickTime for free from Apple's web site: http://www.apple.com/quicktime/download/
To install QuickTime, right-click on the PhotoWarp CD icon in Windows Explorer, then click on
"Install QuickTime". Follow the installation instructions that appear. Once QuickTime is installed,
move on to Step 3 below.
Install PhotoWarp
Finally, we're ready to install PhotoWarp itself. Once again, right-click on the PhotoWarp CD icon,
and choose "Install PhotoWarp".
Continue now to the Setup Assistant.
Setup Assistant
Running PhotoWarp for the first time
We recommend that you connect to the Internet before running PhotoWarp the first time.
PhotoWarp includes an automatic update feature that will download software updates from our web
server.
The first time you use PhotoWarp, an assistant will be presented to guide you through the initial
setup of the application. You will need your license key to begin using PhotoWarp. The license key
can be found on the product packaging for CD installations, or in your order confirmation email (if
you purchased PhotoWarp online).
Setup Assistant window showing License Key screen
Settings
PhotoWarp requires certain settings to unwarp images properly. Choose the type of one-shot optic
you intend to use most frequently here. This will be the default source format for images dropped
onto a PhotoWarp job. You can always change the format for a source after loading, and you can
change the default in Preferences later on, if necessary.
Settings screen, shown with additional 360 One options
If you choose "360 One VR" as your default source format, you can also choose the mounting kit
used for the optic. This information is used to provide more accurate geometry when unwarping.
Choose your mounting kit or camera from the "Mounting Kit" list, or type in a distance manually if
you are using an SLR bracket or custom mount.
Register PhotoWarp
Next, you will be asked to provide contact information to register PhotoWarp with EyeSee360. The
form may have information from your address book already present. Enter as much or as little
information as you are comfortable with. You will be able to choose if you want to transmit the
information on the next screen.
Why should I register?
Registering your software allows us to service you more effectively. If at any time you need to
contact us for technical support, upgrade information or to find a lost serial number or user name, we
can retrieve your information more easily.
EyeSee360 may contact you to notify you of new products and important software updates, or to
inquire about your experience with PhotoWarp. We do not share your contact information with any
third parties.
Registration screen
Once you've completed the contact information, click "Next". To submit your registration
information over the Internet, click the "Send Registration" button. If you don't want to register,
click "Skip."
EyeSee360 Forum
EyeSee360's web site provides a free forum for the user community to share experiences with
PhotoWarp. EyeSee360's support and development team actively participate on the forum and will
promptly answer your support questions. As a convenience, you can register for the forum now
through PhotoWarp.
Forum signup screen
Note:
If you already have an account on the forum through the web site, you can re-enter your account
information here to allow PhotoWarp to keep record of it. This may be used in the future for
additional services.
If you aren't interested in the forum, just click "Skip."
Choose a user name for your account. Your user name will appear on forum posts and will be your
identity online. Your email address is required for account validation and to send private emails from
the Forum. The address itself never appears on the web site, so it can't be harvested by "spammers."
You will also require a password that is used to log in to your account on the web site. A password
must be at least 3 characters in length and should be kept a secret. Enter your password again to
verify.
Click "Join Now" to register online for the forum. A message will be displayed to indicate if your
account was created successfully, or if you need to choose a different user name or password.
Click "Next" to finish up.
Finish
You have completed the initial setup of PhotoWarp. Click "Finish" and you're ready to go!
Quick Start
A quick tour of PhotoWarp
Once you've installed PhotoWarp and followed the setup assistant, you're ready to unwarp images.
You should have some one-shot images handy to continue.
PhotoWarp should now have an empty "job" window visible. If for some reason a job window isn't
visible, choose "File → New Job" to open one.
Empty job window
The process PhotoWarp uses to convert one-shot images into interactive panoramas is called
Unwarping. Unwarping combines the steps of changing the geometric projection of an image,
applying various image filters, and exporting to one or more panoramic file formats for presentation.
1. Add a Source Image
Let's begin by unwarping a single image. Select the image file you want to process. You can do this
on Windows through an Explorer window by selecting the image file icon. On a Mac, select the file
icons in the Finder, or select thumbnails in iPhoto for the image. Drag the image onto the PhotoWarp
job window. Alternately, you can choose "Source → Add Source..." to choose image files from an
open dialog.
You should see the image displayed in the main pane of the job window. The image is overlaid with
a target mask, and the mirror is outlined with a solid target line.
Job window with source
2. Position the Mask
If the target line doesn't outline the mirror correctly, you can reposition it by clicking and dragging in
the center of the outline. To change the diameter of the line, click and drag on the line itself.
3. Check the Preview
Choose "View → Preview" to reveal the Preview window. This shows a low-resolution preview of
the unwarped image.
Preview window
Click and drag inside the preview image to look around. If you find a certain view appealing, click
the "Save" button to use it as the default view (the view first shown when your panorama is
displayed).
4. Choose Output Formats
Click on the "Format" button to switch to the Format pane. Icons for the current output formats are
shown in the tray at the bottom of the window.
Format pane
For this exercise, we'd like to generate a QuickTime VR movie and a simple web page for the
panorama. A QuickTime VR format is already present in the tray, so we need to add a Web Script
output for the web page.
Choose "Format → Add Format → Web Script" to add the Web Script format to the job. A new
Web Script icon appears in the tray.
5. Unwarp
We don't need to change any settings here to get the output we want. To unwarp, just click the large
"Unwarp" button. A save dialog will appear. Enter a name for your panorama, then click "Save".
The job will begin to unwarp. You will see the image as it unwarps in the main pane.
Unwarping the job
6. Review Results
In a few moments, unwarping will finish and the Output pane will show. Here you can review the
results by clicking on the output icons in the tray.
Output pane with web page
Congratulations! You've unwarped your first image. To unwarp more images, you can simply drag
more images onto the job window, then click "Unwarp" again.
Unwarping your next panorama
Let's look at what steps you will take to unwarp other panoramas.
Once you've chosen the formats that you like to use, most of the hard work is done. If you have more
images to unwarp, just follow the following steps:
Unwarping images in 5 easy steps:
1.
2.
3.
4.
5.
Create a new job, if necessary.
Drag in source image file(s).
Choose the default view for each source (optional).
Click "Unwarp".
Review your results.
As you can see, PhotoWarp is very straightforward to set up and use, and stays out of your way
when you just have some images to unwarp.
In the next few chapters, we will examine PhotoWarp's features in more depth.
Jobs
The Job Window
When you first open PhotoWarp, you will be presented with a new, empty Job window:
Parts of the Job window
Jobs are the documents PhotoWarp works with. You can save and open PhotoWarp Jobs just like
text documents. This can be useful to save all the settings you used for a set of panoramas for later
reference, or to make corrections and adjustments later on.
The main pane is used to display the active image or settings being manipulated.
The tray displays icons and information that represents content in the main pane.
The pane switcher is used to switch between the Source, Format and Output panes of the Job
window.
The Unwarp button causes PhotoWarp to process the job by unwarping source images into output
files.
The Job window is switched between three major display panes using the pane switcher. The source
pane is used to display source images and manipulate the settings used on the image. The format
pane determines the kinds of files generated by PhotoWarp and the settings that control them. After
unwarping the job, the output pane shows the output files created by PhotoWarp.
Source Pane
The source pane displays the currently selected source image in the job. Here, you set up an image
for unwarping.
Source images are added to a job in one of two ways. You can use the "Source → Add Source..."
menu item to select image files in a standard open dialog. Alternately, you can simply drag image
file icons onto the job window. Here, a single image file has been dragged onto the Job window:
Source pane with an image
The Tray displays the name of the source and its type. Here, the input image has been determined to
be a 360 One VR image. You can change this easily by selecting a different source template from
the popup menu. You can choose between one-shot formats, cylindrical or spherical images.
QuickTime VR cylinders can also be used as a source, and are automatically recognized by
PhotoWarp.
PhotoWarp also displays a proxy for the current image file on the left of the pane switcher. You can
drag this icon to another application to open the image, where you can modify it if necessary. If you
right-click on the proxy, a contextual menu will allow you to reveal the original file, or choose an
application to open the file (Mac OS X only).
You can manually change settings for the source by using the Source Settings pane. Click the
"Settings..." button in the tray to reveal the settings pane. You can customize the constraints for
display, adjust some additional source type settings, and add notes for sources that can be reflected in
web scripts.
Source settings panel
PhotoWarp supports batch processing. This allows you to add several source image files to the job at
once. When unwarping the job, all the source files will be unwarped. To use batch processing, just
drag several files (all at once or in groups) onto the job window. When two or more sources are
connected to the job, the source list will open (you can also manually open the source list from the
"Source → Show List" menu):
Source list for a batch job
You can switch to a particular source by clicking its name in the source list. The image will appear
in the source pane and you can adjust the mirror position or source settings as necessary. You can
also switch between sources using the next/previous arrows above the Unwarp button.
The name of the source is used as the base of the output files PhotoWarp generates when unwarping
that source. By default source are named based on the file name of the image. You can rename
sources to your liking. Double-click on a name in the source list to edit. The filename associated
with the source will not be changed. You can also change the name of the current source from the
source tray.
Usually images taken with a digital camera have unattractive names like "DSCxxxx.JPG". If you have
a batch of source files like this, you can rename them all at once by clicking the Rename All... button
in the source drawer (or by selecting the "Source → Rename All..." menu). The Rename Sources
panel will appear:
Rename sources panel
You can choose a meaningful base name for all the images (e.g. "Vacation"). A serial number will
be added after this name. You can force a certain number of leading zeroes on names (e.g. "Vacation
001") to make sorting easier. Also, you can preserve the number in the original file name for
convenience. Click Rename to rename all the sources.
Two columns of status indicators appear next to the names of sources. These icons allow you to
view at a glance the result of target detection or unwarping for that source.
The Mirror Detection column shows an icon indicating the confidence in finding the mirror in each
source. You will see the following icons if target detection is being used:
- Mirror was detected with high confidence
- Mirror detection may have given an incorrect result. Check and correct if necessary.
- Mirror detection failed or performed poorly. Manually locate the mirror to fix.
The Unwarp Status column shows icons indicating the result of unwarping the given source. Nothing
will appear here until the first time you unwarp a job. The following icons are used:
- The source and all its formats were unwarped successfully.
- An error occurred while unwarping this source. Check the log file for a description of the
problem and how to fix it.
Format Pane
A PhotoWarp job (when unwarped) will create files for each output format from each source in the
job. Each different viewer or image has its own output format. QuickTime VR, Zoom Viewer, and
thumbnail image are examples of output formats.
The Format Pane shows the output formats that are applied to the job. The Tray displays icons for
each output format. Clicking an icon in the tray will display options for that format in the main pane:
Format pane
Tabs will appear in the main pane with various options that apply to the format:
General — Settings that apply to any image output. This includes the resolution (a percentage of
the source) and filename prefix and suffix.
Compression - The compression codec (e.g. JPEG, TIFF), quality and target file size to use when
compressing the output.
Image - Options to adjust or enhance unwarped images.
Web Script - Settings to generate a custom HTML web page that embeds the panorama created
from the source.
QTVR - Settings specific to QuickTime VR movies, such as fast start previews.
The name of each format (displayed below its icon) can be edited by double-clicking.
You can change the formats for a given job using the format tray. To add a new format, select an
item from the "Format → Add Format" menu. A new format will be created based on your selection.
You can remove a format by selecting it in the tray and choosing "Format → Remove Format", or by
pressing "Delete".
Unwarping
Once you have added the sources and formats you want for your job, you can begin processing by
clicking the Unwarp button. If you have a single source in your job, you will be prompted for a file
name. This name will be the base for the output files generated. For example, if you saved "My
Panorama", you might see output files called "My Panorama.mov", "My Panorama.html", or "My
Panorama-thumb.jpg"). Enter a name and click "Save". If you have multiple sources, you are asked
to choose a folder to save unwarped files. Navigate to the folder you want for your output files, and
click "Choose".
If any files in the destination folder conflict with files that PhotoWarp will generate, a panel will be
presented listing each of the files that may be replaced:
Replace files warning dialog
You can choose to move all the affected files to a new sub-folder (called "Moved Files"), or just
replace the listed files. If you want to choose a different unwarp folder, or rename your sources to
avoid the conflict, choose "Cancel" and fix the problem yourself.
PhotoWarp will display a progress bar while it unwarps the source images, along with an animated
display of the current output file as it is generated. You will also see an estimate of the time
remaining to unwarp the job.
Job unwarping
You can cancel the job at any time if you see a problem with the results. Just click "Cancel", and go
back to make changes to correct the problem. After clicking Unwarp, the job will continue near
where it left off.
Tip:
You can unwarp just the selected source files by choosing "File → Unwarp Selection".
Output Pane
When the job has been completely unwarped, the progress bar and animated unwarp display will
disappear, and the output pane will be shown.
Output pane showing web page
The tray will show each of the files created for the selected source. Click on any of these icons to see
the resulting file. You can double-click on a file icon to open it in an appropriate application (such
as QuickTime Player for .mov files, or your web browser for .html files).
You can drag the file icons in the tray just like icons in the Finder or Windows Explorer. You might
drag a JPEG file onto Photoshop for some touch-up work, drag an HTML file onto BBEdit to
manipulate the web page generated by PhotoWarp, or drag a movie into an email message to send it
to someone.
Sources
PhotoWarp accepts several different types of images and panoramic media as sources, which can be
unwarped into any of PhotoWarp's output formats. In this chapter we will discuss the source types
supported by PhotoWarp.
Important Notice:
Do not use PhotoWarp to decode copyrighted materials without the author's permission. Copyright
infringement is illegal.
One-Shot Images
The most common source format for most users is a one-shot image source. This is a standard image
file (TIFF, JPEG, etc.) photographed with a one-shot optical attachment. These images are
sometimes referred to as "donuts" because of their characteristic shape.
PhotoWarp can interpret one-shot images from the most popular optics available commercially.
These optics include:
Kaidan™ 360 One VR®
0-360™ Lens
BeHere® TotalView®
Remote Reality® OneShot360®
Egg Solution® Egg 360°
PhotoWarp assumes that images are one-shot sources if they have an aspect ratio (pixel width / pixel
height) of 3:2 or less, which is typical of most standard cameras. You can also manually select a
one-shot format by selecting it from the source format popup menu.
One-shot images
Important:
Each of the one-shot source types is calibrated specifically for that optic design. Using the wrong
one-shot format for an image will result in a distorted output image. You can choose the default
format for one-shot images from Preferences → Source → Default Source Type.
A solid target line indicates the edge of the mirror. A colored mask shows the area of the image that
will be cropped from the output.
Tip:
Adjust the color of the mask by choosing "Source → Mask Color..." Use the color panel to select the
color and opacity. Results are shown immediately.
PhotoWarp uses a target detection technique to automatically center for the target. Target detection
is performed automatically when one-shot source images are added to a job. While target detection
is running on an image, the target line pulsates until the target has been detected. Once finished, the
line will change to one of several colors depending upon the confidence of the match:
Green - High confidence
Yellow - Medium confidence
Red - Low confidence
Note:
The position of the target may change slightly as images in a batch are processed. PhotoWarp
automatically groups source images in a batch to apply the best results to the entire group.
Target detection works best on properly framed one-shot images with good lighting. "Properly
framed" images have the mirror fill the frame vertically, without cropping the mirror.
Images zoomed too far in, properly framed, and zoomed too far out.
The target mask can be dragged around manually to indicate the proper location of the mirror in the
image. Start dragging the mask at any time; it isn't necessary to wait for the target to be detected.
The target line will turn black to indicate a custom selection. Dragging on the line itself will change
its diameter. You can use the arrow keys to position the mask precisely, and the < and > keys or the
mouse scroll wheel to adjust the diameter.
A view knob appears on the image which denotes the center of the view of any generated panorama
files. Click and drag on this knob to change the initial viewing angle for generated panoramas. A
horizon line appears while dragging as a guide. The knob will "stick" to the horizon while dragging.
Use the [ and ] keys to rotate the view knob from the keyboard.
Directly opposite the view knob, the split line indicates where cylindrical and spherical images will
be split. The part of the image on one side of this line will make the left of the cylindrical image,
and the other will end up on the right side.
Settings
Click on the "Settings..." button to show additional settings for one-shot images. Choose the
"Source" tab in the pane that appears, if it's not shown.
Settings pane for 360 One VR.
"Shooting Direction" provides for images where the camera is shot down onto the optic (e.g., when
resting the optic on a table). This will flip the resulting panorama so it appears correctly.
"Target Selection" reflects the use of target detection on this image. "Automatic" uses the detected
position for the target. Manual is used to override this value. The detected location can be restored
after dragging the target by clicking "Automatic".
"Mirror Distance" appears for 360 One VR images. You can enter the distance in millimeters
between the tip of the mirror and the focal point of the camera to unwarp images with more accurate
geometry. This value is set automatically from your preferences (or the setup assistant), so you only
need to change this if your camera setup has changed.
The "Apply to All" button is useful to apply the same settings to all the images in a job at once.
Position the target for any source image. Then click on the "Apply to All" button under "Target
Selection". The remaining 360 One VR sources in the job will turn off target detection and set the
same position as the current source.
Cylindrical and spherical images
PhotoWarp accepts panoramic images using cylindrical or spherical (equirectangular) projections as
well. These might have been generated by another program (perhaps a stitching program, or an
image generated by a rotating slit device), or by PhotoWarp itself as the result of a previously
unwarped source.
Images that are very wide (greater than 3:2 aspect ratio) are assumed to have a cylindrical projection.
If the aspect ratio is exactly 2:1, the image is assumed to be a full spherical panorama. Additionally,
PhotoWarp identifies TIFF and JPEG images generated by PhotoWarp 2 automatically, along with
the appropriate settings.
Spherical source image
With either of these source types, a horizon line appears over the image. This line denotes a tilt angle
of 0 degrees in the image. This line appears on or slightly above the horizon of the image. Drag the
horizon line to align with an object at the same height as the mirror in the original shot. This is
important to ensure the resulting panorama will not be distorted when unwarping. With cylindrical or
spherical images generated by PhotoWarp, the proper position is extracted from the file itself.
Like other sources, the view knob will appear on top of the horizon line to indicate the initial view of
resulting panoramas. Drag this knob to choose an appropriate initial view.
Settings
Normally the pan range for a cylindrical or spherical input image is from 0 to 360 degrees. For
partial panoramas, set these numbers appropriately.
Tilt settings allow the lower and upper tilt bounds to be specified explicitly. These are set
graphically by dragging the horizon line, but for precise settings or for non-square pixels, values can
be entered numerically in the Source tab.
Note:
The pan and tilt range shown under the Source settings tab are different than the ranges shown in the
View tab. In the Source tab, you are specifying the geometry of the image. In the View tab, you are
effectively cropping the source to the desired constraints
Vertical cylinders are rotated for display in PhotoWarp to appear normally. If an image appears
rotated, toggle the orientation setting so it appears correctly. The orientation setting appears only for
cylindrical images, not spherical.
QuickTime VR cylinders
PhotoWarp also accepts cylindrical QuickTime VR movies as a source. These sources will appear
similarly to a cylindrical image source, but all the parameters are encoded within the movie.
PhotoWarp can read both horizontal and vertical VRs that use QTVR 2.0 encoding. Some very old
panoramas that use the QTVR 1.0 encoding cannot be read.
QuickTime VR cylinder sources can be useful to convert a collection of QuickTime VR movies for
other viewers; for instance, to provide a Java version of the panorama for display.
Tip:
Whenever possible, use the original image as a source rather than a QuickTime VR. QuickTime VRs
are typically compressed for delivery. Unwarping will degrade image quality further when recompressed by PhotoWarp.
Like the cylindrical image source, a view knob appears on top of the image to allow selection of the
initial view for generated panoramas. Drag the knob to choose a suitable view.
Settings
No settings can be changed on a QuickTime VR panorama since all the important details are
encoded within the movie. The Settings pane displays the pan and tilt constraints defined by the
panorama for reference.
View Constraints
You can customize the pan, tilt and field-of-view constraints for a source in the Settings panel. Click
the "Settings..." button in the source tray, then switch to the "View" tab:
Constraints tab
View controls
The numerical values for the default view are shown first. The values will change if you use the view
knob or the preview window to adjust the view.
Auto Rotate will cause the panorama to rotate automatically when it is first viewed and sitting idle.
You can control the direction and rate of this rotation by dragging the "Auto Rotate" slider to that
direction. If the preview window is visible, you will see the view rotate at the selected rate.
Clicking "Apply to All" will copy the default view or auto rotate settings to the other sources in the
job, replacing their current settings.
Constraint controls
The range of allowable pan, tilt, and field-of-view values is indicated here. The number in the left
box is the minimum value, the maximum is on the right. There is a checkbox next to each of these
fields to allow that value to be edited. If the box is unchecked, PhotoWarp will automatically
calculate the appropriate value for that constraint.
Note:
Constraints limit the portion of the panoramic image the viewer can see. Limits that appear in the
Settings pane control the geometry of the image, and should not be changed to limit the view.
Constraints are analogous to cropping the image.
Clicking "Apply to All" will copy the customized constraints to the other sources in the job.
Notes
Also available in the source settings is the Notes tab. Text annotations can be recorded for each
source in a job. Annotations are recorded within the meta data of output files, but are most often
used when creating web pages with Web Scripts.
Annotations tab
The Author is typically the photographer of this panorama. As a convenience, the Author field is
applied to every source in the job.
Similarly, Copyright is the copyright statement to be displayed along with the panorama. It also is
applied to all sources in the job.
Comments are usually intended for taking personal notes about the source, e.g. conditions at the
shoot, touch-ups to perform, etc. They are recorded with the source but typically aren't displayed to
the viewer.
The Description is typically listed with the panorama in generated web pages. This can be as simple
as a caption, or a more detailed discussion of the scene.
Formats
PhotoWarp supports a variety of output formats to present panoramas to a viewer. As part of its
batch processing capability, a PhotoWarp job may contain any number of formats. Each format will
generate its own set of files as appropriate for that viewer.
Supported Output Formats
The following output formats are supported by PhotoWarp 2:
QuickTime VR
QuickTime VR is a component of Apple's QuickTime media platform, which can be
viewed on any Mac or Windows computer with the free QuickTime plugin installed.
QuickTime VR was one of the earliest panoramic image viewers available, and is
one of the most common. "QTVR" is known for high quality display and the ability to use advanced
QuickTime features to combine panoramas with other types of media, such as video or Flash.
QuickTime VR cylinders are the most common format of QuickTime used on the web, and is a good
fit for the field-of-view produced by a 360 One VR. The "QTVR Cylinder" format in PhotoWarp
produces QuickTime VR panoramas that are ready to distribute over the web or on CD. QuickTime
must be installed on the viewing computer to see the panorama. If a user without QuickTime
encounters this on a web page, they can be prompted to automatically download and install
QuickTime on their computer.
Tip:
You can use auto-fallback in a Web Script to show a FlashVR or Java panorama if QuickTime is
unavailable.
QuickTime VR Cubic is a variant of QuickTime VR. QuickTime versions 5.0 and higher include full
support for Cubic VRs, while earlier versions of QuickTime will display a slightly distorted version
of the panorama for compatibility. Instead of a cylindrical projection for image data, six faces of a
cube are used to produce an image map. This is useful mainly when a fully immersive panorama is
required, granting the ability to look straight up or down. Note that one-shot sources cannot image
the area below the camera or behind the mirror, so you cannot look all the way up or down in only
one shot.
Either QuickTime VR format generates a single ".mov" file that can be played back in any
application that supports QuickTime. This makes QuickTime VR a good choice for e-mailing
panoramas, since only a single file is needed.
For more information:
QuickTime web site: http://www.apple.com/quicktime/
FlashVR
FlashVR provides a perspective-corrected panorama viewer in Flash. The Macromedia Flash
player 6 has wide availability on all platforms, and provides a good alternative to viewers
without QuickTime or a Java virtual machine installed. PhotoWarp includes a license for the
basic version of the FlashVR Framework that can be uploaded to any web site.
The FlashVR output format generates a "pano.swf" file for each panorama. "flashvr.swf" is the
FlashVR viewer itself. The panorama can only be displayed properly with a web script.
Note:
This version of FlashVR does not provide support for hot spots or customized preloading screens.
You can purchase a version of the FlashVR Framework with these capabilities from the FlashVR web
site.
For more information:
FlashVR Framework web site: http://www.flashvr.de/
Zoom Viewer
Zoom Viewer is a common Java-based panoramic image viewer produced by iseemedia
(formerly known as MGI). Java-based viewers do not require any special plugins to be
installed on a user's computer. A Java virtual machine must be present and activated in the
browser in order to view such a panorama. Zoom is an increasingly popular format for real estate
web sites in particular, and is often used as a plugin-free alternative to QuickTime.
The Zoom Viewer format creates a cylindrical JPEG image and an ".ivr" file that contains display
information. "panoapplet.jar" is the Zoom viewer itself. The panorama can only be displayed
properly with a web script.
For more information:
iseemedia web site: http://www.iseemedia.com/
EyeSee360 is not affiliated with iseemedia.
PTViewer
PTViewer is a component of the open source Panorama Tools, created by Prof. Helmut
Dersch. PTViewer is a Java-based viewer that is a popular alternative viewer. A Java virtual
machine must be present and activated in the browser in order to view such a panorama.
PTViewer offers a similar user experience to QuickTime without requiring a download.
The PTViewer format creates a spherical JPEG image. "ptviewer.jar" is PTViewer itself. The
panorama can only be displayed properly with a web script.
For more information:
Panorama Tools web site: http://webuser.fh-furtwangen.de/~dersch/
Cylindrical or Spherical image
These formats are used to generate plain image files from PhotoWarp. This can be
useful, for example, to edit unwarped imagery in a third-party application such as
Adobe Photoshop prior to delivery. PhotoWarp encodes the proper unwarping
parameters in these files, so once edited they can be easily converted to their final format by passing
the same file back into PhotoWarp as a source.
Note:
If you will be unwarping an image to an image file for editing, be sure to save in a lossless file
format such as TIFF or PNG. This will prevent generational loss when the image is re-compressed
for viewing.
These two projections may also be useful to use raw projected images in a viewer not supported
natively by PhotoWarp, or in computer graphics applications such as 3D environment maps.
Cube face images
This format generates six plain image files, one for each face of a cube. Each cube face
image is suffixed with an initial for its direction, N, S, E, W (for North, South, East and
West) and T, B (for Top and Bottom). This format is useful for post-processing cube faces in
a separate application, e.g. to produce a full cubic panorama. Third-party tools can be used to reassemble the images into a QuickTime VR Cube.
Thumbnail
A thumbnail is simply a small image file of pre-defined dimensions. They are used most
commonly on web sites listing several panoramas to provide a preview of the full resolution
pano. Web script outputs can create thumbnail pages like this automatically.
Thumbnail outputs can use a standard cylindrical projection, or a spherical or perspective projection
depending upon the look desired. Thumbnails can actually be created with any dimensions, so this
format can be used as a convenient way to make image files of a particular size.
Tip:
A perspective thumbnail will show the initial view of the panorama identically to any viewer. You
can use this as a "preview" or "click-thru" image by setting the same dimensions as your panorama
viewer and choosing the Perspective projection.
Web Script
Web Scripts are a special output format used to create web pages for output panoramas.
Web Scripts can be added, removed and named just like any other format, but instead of
producing a panoramic image, text files (typically web pages) are generated instead based on
the other formats present in the job.
Web Scripts are discussed in detail in Chapter 9: Web Scripts.
Output Format Settings
Output formats offer a range of setting for the size, appearance and behavior of panoramas. The
settings are grouped into common categories, often shared by several formats. Each category appears
in its own tab in the window.
General Settings
General settings for images, viewer formats
Resolution
Resolution determines the number of pixels in generated images. Resolution is expressed in pixels
per degree (px/º), a natural unit of resolution for panoramic images. At 100% resolution, the output
panorama will have about the same resolution as the source image. At less than 100%, PhotoWarp
will produce smaller images. Resolutions above 100% add pixels to the output by interpolating the
image, which may be useful to preserve detail when post-processing image files. Normally, you will
choose an output resolution of 100% for optimal results.
Note:
Setting the resolution slider above 100% does not add detail to the output image; it only adds pixels.
PhotoWarp cannot restore details that were not captured in the source.
Dimensions
Dimensions are the physical pixel size of a generated image file. Dimensions cannot be changed
directly except for thumbnails. To change dimensions of an image, adjust the Resolution slider.
Display Size
Applies to interactive panorama viewers, such as QuickTime VR, Zoom Viewer or PTViewer. This
is the size of the window in which the panorama will be displayed. Display size is not related to the
resolution of the image. Click the arrow next to the text field to choose from preselected display
sizes. Three sizes (240 x 180, 320 x 240, and 480 x 360) are in a 4:3 aspect ratio, typical for most
digital pictures. Another three sizes (300 x 200, 375 x 250, 450 x 300) are in a wide aspect ratio of
3:2, which is typical of 35mm film slides. Alternately, you can choose your own display size by
clicking in the text field and typing the dimensions you like.
Tip:
PhotoWarp is not restricted to the display sizes listed here. To choose your own dimensions, click in
the text box and type any size you like, "800 x 600" for instance. Press Return and the dimensions
will be accepted.
File Type
For cylindrical and spherical image files, there is a choice for the file type to generate. Typically
JPEG will be chosen for web delivery. For uncompressed files, you can also save as a TIFF or PSD
(Photoshop) file. Other formats are available as well.
Tip:
If a source image has 16 bits per channel, choosing a TIFF file type can preserve the 16 bits per
channel when processing. The "Allow 16 bit per channel processing" preference must also be enabled.
This is useful if you plan to post-process images from PhotoWarp.
Filename
Controls the name of files generated by the output format. Filenames are generated as follows:
Prefix + Source Name + Suffix + Extension
Prefix and suffix are the values which appear here. You can type any prefix and/or suffix you like to
alter the name of the output file. You cannot use certain characters that are not permitted in
filenames (such as '/', '\', and others). Also, files generated by an output format cannot conflict with
those of other output formats. If this occurs, a dialog will appear prior to unwarping, allowing
prefixes to be changed so they no longer conflict.
The source name is the name typed into the Save dialog box when unwarping (for single sources), or
the name shown in the Source list.
The file extension is set appropriately by the output format, and may not be changed.
Compression Settings
Compression settings
Compression
Only shown for QuickTime VR formats. Compression determines the particular codec used to
compress the VR image. Typically, "Photo - JPEG" works well and offers the best compatibility.
QuickTime offers many other compression formats that can be used as well. Some codecs include
Sorenson for higher compression ratios; PNG, TIFF and others for lossless compression, and several
others. Certain codecs that may be available are incompatible with QuickTime VR; these are not
normally displayed in PhotoWarp.
Quality
Determines the quality of the compressed image. The exact behavior depends on the compression
setting. There is a trade-off between quality and file size, so increasing the quality setting will result
in a larger file.
Target File Size
By checking "Target File Size" and entering a value (in kilobytes) into the field, PhotoWarp will
attempt to produce a file of the specified size. This is accomplished by reducing the Quality setting
until the desired size is reached. If the initial Quality setting produces a file smaller than requested,
this setting will have no effect. If the minimum quality setting produces a file larger than requested,
the minimum quality setting will be used.
File Size vs. Resolution
If generated panoramas display annoying compression artifacts, settings should be adjusted to remove
them. Increasing the target file size will reduce the presence of artifacts. To produce very small files,
consider lowering the resolution in the General settings to reduce pixel count.
Image Settings
Image settings
Note:
Image settings are not available for QTVR Cubic or Cube face outputs, as the image filters do not
work consistently across multiple images.
Auto Levels
"Auto Levels" performs identically to the Adobe Photoshop function of the same name. The contrast
of the image is stretched to fill the entire range from black to white. This results in an overall
improvement in contrast and often brighter colors.
Sharpen Image
Enabling "Sharpen Image" will perform an unsharp mask filter on the unwarped image, prior to
compression. This can be useful to reduce softness in images without needing third party programs.
The "Amount" slider controls the level of sharpening to perform.
Thumbnail Settings
Thumbnail settings
Thumbnails are small images used primarily for web index pages to look at several panoramas at a
glance. They may also be used for preview images, or to create an image file with precise
dimensions. Thumbnails are always saved as JPEG image files.
Projection
"Projection" determines the appearance of the thumbnail image, which can be a traditional
cylindrical or spherical projection, or a perspective projection of the default view. Using the
perspective projection, you can create a "Preview" image, for example, that is identical to the default
view of the interactive panorama.
Dimensions
Unlike image formats, thumbnails can have their dimensions specified explicitly. With a cylindrical
or spherical projection, the full panorama will be stretched to fit into the specified dimensions.
QTVR Settings
QTVR settings
Based on Movie
Based on Movie is a simple solution to using features of QuickTime that are not supported natively
by PhotoWarp. A movie selected with the "Choose..." button will be copied and used as a basis for
the QuickTime VR file produced.
For example, to create a QTVR with a "watermark" overlay, just select a movie with the desired
watermark in-place. The non-QuickTime VR related tracks in the movie will be copied into the
output, which results in all movies generated by PhotoWarp having the watermark. Similarly, this
can be used to copy wired sprite tracks or skins.
Note:
In PhotoWarp 2.0, Based on Movie was frequently used to add an auto-rotate sprite to the movie to
allow the panorama to rotate automatically. This capability is supported directly from the Source
Settings pane in PhotoWarp 2.5. Be sure to remove your auto-rotate sprite movie from a job if you
use the new functionality to prevent unexpected behavior.
Protection
The Disallow Save checkbox sets a flag in the movie that tells the QuickTime Plugin not to allow
viewers to save the movie to their local hard drive through the popup menu. Additionally, changes
cannot be saved to the movie, and tracks cannot be extracted through QuickTime Player. This
provides a rudimentary level of copy protection for panoramas.
Fast Start Preview
The QuickTime plugin can display a low-resolution preview of the panorama after only a small
percentage of the movie has been downloaded. This is a fast start preview. Select the resolution of
the preview in the popup as a fraction of the original size. To reduce the aliased appearance of a
preview, check the "Blur" box to perform a light blurring effect.
Static/Dynamic Quality
Affects the rendering of a panorama in QuickTime. Static quality is the rendering mode when the
user is not panning. Dynamic quality is the mode while navigating the panorama. Typically dynamic
quality is set to "good" to deliver good rendering performance while moving, and static quality is set
to "better" to give a smoother steady picture. As of QuickTime 6, there is no difference in quality
between "better" and "best" modes.
FlashVR Settings
FlashVR settings
Perspective Correction
FlashVR uses a clever technique to show perspective-corrected panoramas using the Flash viewer.
There is a compromise between the smoothness of this perspective correction and playback
performance. Medium or High correction values will give the best looking results, but performance
will be slow. A low correction value will be fast, but 'blocky' looking.
Flash Antialiasing
This is equivalent to the Quality parameter passed to the Flash plug-in. Higher values give smoother
results, but somewhat slower performance.
Templates
Job Templates
Often, you may use one set of formats and web scripts for one client, and a different set for another
client. To accomodate this, PhotoWarp allows jobs to be saved as templates for easy access.
To create a job template, simply create a job and set it up with the formats, settings and web scripts
desired. Then choose "File → Save Job Template..." to save a copy of the job as a template. The
template will not include any sources you might have added to the job. Type a name for the
template, and save it in the Job Templates folder that is shown.
To make a new job using that template, choose "File → New Job From Template → Your
Template". A new job window will appear with the same formats and settings you just saved.
Note:
A default template is always maintained by PhotoWarp for the last job unwarped. Whenever "File →
New Job" is selected, the job created will use this template.
You can reveal the folder containing your job templates by selecting "File → New Job From
Template → Show Templates Folder". You can then copy, move or rename template files as needed.
This can be useful to share templates with other PhotoWarp users: Just email or upload the template,
and instruct users to place the downloaded template file in their Job Templates folder.
Format Templates
A flexible way to manage formats for your PhotoWarp jobs is to use format templates. The
Templates window is used to display and manage these templates. To view the templates window,
choose the "View → Templates" menu item.
The Templates shown in the toolbox provide standard settings for each of the output formats
supported in PhotoWarp. To use them, just drag a template from the toolbox window onto the
window or format tray of your job. A copy of the template will be used to create a new format.
The Templates window is divided into two tabs. Built-in templates are all the basic formats available
in PhotoWarp. Custom templates are those that you define yourself, or that you have received from
another PhotoWarp user.
Creating your own templates is very easy. In a job window, set up a format with the settings you
would like to use for your template. Drag the format icon from the format tray onto the Templates
window. A new template is created based on your settings. You can edit the name of the format by
double-clicking. Your template can now be used in any other job simply by dragging from the
Templates window.
The button in the upper-right corner of the Templates window will reveal the Templates menu.
Remove... will remove the selected custom templates from the Template window. You
can only remove custom templates, not built-in templates.
Load Templates... allows you to load custom templates from a file. Use this for
template files you might have downloaded from the web, or that were sent to you by
another PhotoWarp user.
Save Templates... lets you save your custom templates to a file. You might use this to
save sets of templates associated with a particular web site or client, and organize them
into separate template files. You can share the template file with other PhotoWarp
users, which can be useful to ensure your colleagues use the same settings for a
particular web site, for example.
By default, template files are saved in PhotoWarp's templates folder. Template files
placed here will appear automatically at the bottom of the Template menu for quick
access.
Show Templates Folder will reveal PhotoWarp's Templates folder in the Finder or
Windows Explorer. This gives you quick access to template files to send to other users,
or to delete unused files.
Additional Features
Inspector / Details Window
The Inspector (Mac) or Details (Windows) window shows information about the currently viewed
source, format or output. If a source is visible in the front-most job window, the info window will
contain two tabs.
General inspector tab
The General tab shows summary information about the image file and its settings. You can see the
original file name, and file size, the dimensions of the image, and the modification date for the file.
Source settings shown include the format of the image, the calculated resolution of the panorama,
and the pan and tilt limits used for the panorama (reflected by the mask on 360 One VR sources).
EXIF inspector tab
The EXIF tab shows information recorded in the image by the digital camera. This information may
include the make and model of the camera, exposure times, aperture settings, focal lengths, or even
GPS coordinates. The tags shown for any image will vary from camera to camera, or may not be
present at all. You can select the tags in the list to copy or drag into another application. This
information can be useful to diagnose problems with your images, or can provide a reference on how
a good shot was achieved.
When a format is selected in the active job, the view changes to display the (editable) name of the
format, along with a listing of the customized settings for that format.
Preview window
The preview window shows a low resolution unwarped preview of the selected source. You can
reveal it from the "View → Preview" menu item.
Preview window
The preview is updated automatically as source settings are changed, so you can see the results of
changes immediately. The preview window can also be used to set the default view interactively.
Just navigate to the desired initial view, then click "Save".
Unwarp log
The log window shows a detailed description of jobs that have been unwarped. The window may
appear after unwarping a job if an error occurred. You can show it directly by choosing the "View →
Show Log" menu.
Each log entry is stamped with a date and time. Following is a message describing the entry. You
may see entries for files created or replaced, or errors that occurred on certain sources.
Depending on your preferences, the log window will show entries saved from previous PhotoWarp
sessions, or just entries for the latest session.
Preferences
The Preferences window shows settings that control the way PhotoWarp behaves. You can customize
PhotoWarp to better suit your needs in this way. Choose the "PhotoWarp → Preferences..." menu
(Mac) or the "File → Preferences..." to reveal the Preferences window.
General preferences
Check for updates when starting PhotoWarp
PhotoWarp 2 includes an auto update capability that can retrieve newly updated components from
EyeSee360's server automatically. Enabling this checkbox will allow PhotoWarp to check with the
server when the application is started for available updates. Auto update transmits the version of
PhotoWarp you are using, along with your platform and operating system to the server to perform
this function. If unchecked, auto update will not activate unless "Help → Check for Updates..." is
selected manually.
Allow 16 bit per channel processing
This feature is useful when using PhotoWarp as a workflow tool with high-end cameras. When
supplied with a 16 bits per channel source image (sometimes called a 48-bit image) PhotoWarp will
preserve the channel depth throughout processing, instead of down-sampling to the normal 8 bits per
channel. If an output format also supports high bit depths (such as a TIFF or PSD image), the full
dynamic range of the image is preserved.
Display progress while unwarping
While unwarping a job, the current image is displayed as it is being unwarped. You can turn off the
progress display if you find it distracting or unnecessary. This can marginally improve performance
while unwarping.
Share mirror position between similar images
Turning this on activates EXIF Grouping for the target detection software. Target detection for one
shot images can deliver poor results under certain circumstances, such as low light. EXIF grouping
will compare the images in the job that were taken with identical camera settings within a few
minutes of each other. Then PhotoWarp will choose the best target detection match among those
images, and apply the position to all the images in the group. This will often give improved match
results for large jobs, but it will increase the time needed for adding sources to a job.
Tip:
If this feature is active, you can improve target detection results during shooting. For example, if you
will be taking a few pictures in a dark room, first take a picture in a well-lit room or with a white
card placed behind the mirror. PhotoWarp will be able to detect the position accurately on this
reference image, then apply it to the subsequent images automatically.
Save unwarp log between sessions
This controls the persistence of the log window. If selected, the log will be saved to the PhotoWarp
application support folder, and reloaded the next time you open PhotoWarp. You can choose the
maximum number of log entries to record in this file.
Source preferences
Default Source Type
Images with traditional 4:3 or 3:2 aspect ratios will default to this source type. Usually a one-shot
source type is chosen here corresponding to the optic being used.
Mirror Distance
Only active with 360 One source types. This is a measure, in millimeters, between the tip of the
mirror and the focal point of the camera. Using this measurement, the unwarped geometry can be
very accurate and no distortions should be visible.
Mirror Position
If "Automatically locate" is checked, PhotoWarp will detect the location of the mirror in the frame
automatically. This detection is fast and accurate in most cases, but if this causes problems
consistently, it can be disabled.
Image cache
The image cache allows you to control how much memory PhotoWarp may use to speed the loading
of source images. PhotoWarp will use only as much RAM as necessary to perform a job, but you
can provide additional RAM to be used as an image cache. The image cache keeps recently used
images in memory, so you can switch between sources more quickly. The control is shown as a
percentage of the physical RAM on your computer. You can use up to half of your computer's RAM
as an image cache. Note that using too much memory for your cache can degrade performance if you
switch between applications frequently.
FlashVR preferences
FlashVR License Key
If you have licensed a full version of the FlashVR viewer, enter your license key here to author SWF
files that are compatible with your license. To use the basic FlashVR functionality included with
PhotoWarp, just leave this field blank.
Web Scripts
PhotoWarp 2 includes a powerful feature to generate custom web pages for your jobs based on a
template. These templates are called web scripts. Some web scripts are included with PhotoWarp.
You can also write your own web scripts using the popular web scripting language, PHP.
Web Script format
To use a web script, add a web script format to your job. A graphical list of web scripts is presented
at the top of the format pane:
Web script format
To use a particular web script, simply click on the icon for the script of your choosing. When you
unwarp your job, PhotoWarp will run the web script for each panorama, generating an HTML file
for viewing in a browser.
Web Script Options
Options following the selection control certain aspects of the generated pages. Some of these options
may be disabled depending upon your job.
Create index
Select this checkbox if you would like an index page to be generated for all the panoramas in a job.
Enter the name to use for the index file in the text field shown. "index.html" is the default
filename. The file extension you use here will also be used for the individual web pages.
Include thumbnails
This option will be available if you have chosen to create an index page, and if you have a
Thumbnail format in your job. If selected, the thumbnail image will be used as a link to each
individual pano, in addition to the normal text link.
Use automatic fallback
If your job contains both a QuickTime VR format and a FlashVR or Java-based format (such as
PTViewer or Zoom Viewer), this option will be available. If checked, then a single web page will be
created for the QuickTime VR, Flash and/or Java versions of a panorama. JavaScript code will be
added to the generated HTML file that detects the presence or absence of QuickTime, Flash or a
Java virtual machine, and automatically chooses the appropriate viewer for the situation. If neither
QuickTime, Flash nor Java is available, the panoramic image will be replaced with a warning and
instructions for installing software for one of the viewers.
Show Web Scripts Folder
Clicking this button will reveal the Web Scripts folder in the Finder or Windows Explorer. Use this
button to quickly gain access to add, remove or change your web scripts.
Using source notes
Most web scripts will make use of source notes if they are present in your job. Using notes, things
like copyright notices, author credit or a description of a panorama can be included.
Switch to the source pane, and choose a source to annotate. Open the source settings, and switch to
the "Notes" tab.
Source notes
Complete the fields of interest. Author and Copyright are automatically applied to the entire job and
every source in it. Comment and description are stored only for a particular source. Go through each
of the sources in your job to give useful descriptions for each panorama.
It is a good idea to save your job when you have added annotations, because these annotations are
not stored anywhere else and will be lost if you decided to change them later on.
Included Web Scripts
PhotoWarp includes some basic web scripts to get started.
Basic
The Basic web script generates a plain HTML file that simply includes a title, panorama and source
annotations if present.
Debug
The Debug web script is used as a guide when creating your own web scripts. A complete list of all
the defined variables will be printed in a table, along with their values. Simply copy and paste
variables from the table into the PHP code to use then in a custom script.
Creating Web Scripts
Web Scripts folder
Custom web scripts are stored in the PhotoWarp user settings folder on your computer:
On Mac OS: ~/Library/Application Support/PhotoWarp 2/Web Scripts
On Windows: %USERPROFILE%\Application Data\EyeSee360\PhotoWarp\2.5\Web Scripts
A single sample web script should be present, called Sample. You can download this sample from
the EyeSee360 Web Scripts page. Sample is a folder on your computer, which contains a certain set
of files and folders within it:
Sample/
script/
index.php
singleton.php
copy/
Thumbnail 64x64.tif
Version
Web Script folder must have a .pw extension to be recognized as a Web Script. On Mac OS X,
folders with a .pw extension will be shown as PhotoWarp script files. Remove the extension to view
or edit their contents in the Finder.
script
folder
The script folder contains the actual web scripts that will be run by PhotoWarp. These scripts are
written in the PHP scripting language. Traditionally, PHP is a server-side scripting language that is
used to dynamically generate content on a web server. For PhotoWarp, this same mechanism is used
to generate static web pages from a PhotoWarp Job. No special software is required on your web
server, since standard HTML files are created.
Every web script contains at least two script files in this folder. singleton.php is run for each source
in the job, possibly more than one time depending upon the formats applied. Web pages for
individual panoramas are created from this script. index.php is run once for each job, after all the
sources have been unwarped. It is used to generate an index page for the job, typically containing
thumbnails and links to HTML pages made for each panorama.
copy
folder
The copy folder contains files that are to be copied to the output directory whenever the job is
unwarped. If your page layout uses shared files such as style sheets, image files or .swf files, place
them here to be copied. All files in this folder will be copied to the output folder directly. Sub-
folders will be copied in their entirety.
Thumbnail 64x64.tif
This thumbnail image file is used as the icon in PhotoWarp's listing of web scripts. You can use
your favorite image editor to create this image to better suit your script. The size of the image must
be 64 by 64 pixels exactly.
Version
The version file is a simple text file containing a version string, such as "1.0". This file is optional,
but may be useful for maintaining your web scripts. PhotoWarp's auto update feature uses Version
files internally to make sure web scripts are up-to-date with the version stored on our server; since
your web script probably doesn't exist on our server, this should not impact your scripts.
Contents of scripts
Examining the singleton.php script
Writing your own scripts is a matter of creating or modifying the singleton.php and index.php
files in a web script. To begin, make a copy of the Sample web script and give it a name of your
choosing.
Open the singleton.php script file in your favorite text editor, such as Notepad or BBEdit. PHP
files contain standard HTML code that should look familiar if you know HTML. The normal HTML
is interjected with PHP sequences, which begin with <? or <?php tags and end with a ?> tag. The
PHP code itself looks similar to JavaScript or C++ code, but is actually a different language.
Note:
You can find lots of information about the PHP language at the official web site, http://www.php.net
The sample file contains lots of comments to explain what the script does at each step. Comments in
PHP start with /* and end with */; these are completely ignored when executing the script.
Comments on a single line can also be started by //, ending at the end of the line.
Read through the source file to get a feeling for what a web script contains. Below each section of
the file will be broken down for discussion. Comments and HTML may be excluded for brevity.
<?php
include($_ENV["PW_PREFIX_FILE"]);
$source = $sources[0];
?>
This should be at the top of every PhotoWarp web script. The first line of PHP includes a file passed
to it by PhotoWarp, which is able to parse all the variables sent from PhotoWarp to be used to make
the web page. Some useful shorthand functions are also provided through the prefix file.
sets up a shorthand variable for the current source. In the singleton script,
only a single source is passed in. This allows all attributes of that source to be accessed from the
$source = $sources[0];
$source
Note:
variable.
A reference to the prefix file and standard variables can be found in the Web Script Reference.
<title><? echo $source['name'] ?></title>
Sets the title of the page to the name of the current source. This is a typical pattern to include a
variable in your script: <? echo $variable_name; ?>. The name of the current source is stored in
the variable $source['name'].
<? ScriptHeader(); ?>
This includes a standard set of values into the <head> of the HTML document. This includes
standard CSS style sheets, and possibly JavaScript code used for the Java viewer fallback capability.
<body <? echo BodyArgs(); ?>>
Begins the body of the HTML document. The BodyArgs() PHP function is called inside the tag to
include any body attributes needed by the script (such as a JavaScript onLoad() statement).
<div>
<? ShowPano($source); ?>
</div>
is a helper function included in the prefix file. Quite simply, this is what you call to
place the panorama on the page. The proper embed, object or applet tags are generated by the script
and included here.
ShowPano()
<?
if ($source['options']['AnnotationAuthor']) {
echo ("<p><b>Author:</b> " .
$source['options']['AnnotationAuthor'] . "</p>\n\n");
}
if ($source['options']['AnnotationDescription']) {
echo ("<p>" .
$source['options']['AnnotationDescription'] . "</p>\n\n");
}
if ($source['options']['AnnotationComment']) {
echo ("<p>" .
$source['options']['AnnotationComment'] . "</p>\n\n");
}
if ($source['options']['AnnotationCopyright']) {
echo ("<p>" .
$source['options']['AnnotationCopyright'] . "</p>\n\n");
}
?>
This block of code is used to include any annotations set for this source. The particular annotations
are only included if they were set for this source. A block similar to this should be used in any script
where annotations are to be used.
<?
if ($PW_IndexURL) { ?>
<p>
<a href="<? echo $PW_IndexURL; ?>">Return to Index</a>
</p>
<? } ?>
If an index is being created for the job, a link will be added to it here. $PW_IndexURL is a shorthand
for the relative address of the index file.
Examining the index.php script
The index.php script will look similar to the singleton script, with the addition of some loop
structures needed to produce an index. Open index.php with your text editor. The important
differences are shown below.
<table>
while(list(,$source) = each($sources) ) {
?>
<tr>
<td>
<a href="<? echo $source['pages'][0]['link_url']; ?>">
<? ShowPano($source); ?></a>
<br>
<a href="<? echo $source['pages'][0]['link_url']; ?>">
<? echo($source['name']); ?></a>
</td>
Since an index is passed every source in the job, it is necessary to loop across each source in the job
and produce an entry for each. The while() block accomplishes this. list(,$source) =
each($sources) will loop across every entry in the $sources array, placing the current source into
the $source variable (just like in the singleton script).
In this example, we build a table row for each source. The first cell includes the thumbnail image
(if selected) by calling ShowPano() for the active source. ShowPano() will return an empty string if
"Include thumbnails" was off. Following the thumbnail, we echo the name of the current source for a
text link
<td>
<?
if ($source['options']['AnnotationAuthor']) {
echo ("<p><b>Author:</b> " . $source['options']['AnnotationAuthor'] . "</p>\n\n");
}
if ($source['options']['AnnotationDescription']) {
echo ("<p>" . $source['options']['AnnotationDescription'] . "</p>\n\n");
}
?>
</td>
</tr>
<? } ?>
</table>
Here we echo the author and description annotations for the selected source. This code is nearly
identical to the singleton example. We close the while loop with a bracket }, which will repeat the
containing code for each source. When every source has been completed, the next line is used to
close the table ( </table>).
Writing scripts
Writing a web script begins by writing a sample HTML file. Using your favorite HTML editor,
produce a web page with the appearance you desire. You can even include an image or panorama as
a placeholder for the actual panorama to insert. Save or rename the HTML file to singleton.php,
and place a copy in to the script folder.
If you use the web script in this state, you will get a copy of that HTML file for each source
panorama in your job. An HTML file saved with a PHP extension is perfectly valid PHP, it simply
contains no code.
To turn this into a useful script, open the file in your text editor and make a few modifications:
1. Include the prefix file
Copy the prefix file include at the beginning of your HTML:
<?php
include($_ENV["PW_PREFIX_FILE"]);
$source = $sources[0];
?>
Only copy the $source = $sources[0]; for the singleton script.
2. Script header and body arguments
Before the end of the <head>, paste this code:
<? ScriptHeader(); ?>
Next, include this echo statement inside of your body tag:
<body <? echo BodyArgs(); ?>>
3. Include the panorama
Find the placeholder for your panoramic image in your page. Replace the image or embed tag with
this:
<? ShowPano($source); ?>
4. Include annotations and other variables
If you wish to use the name of the source, source annotations, or other variables in your script, just
insert the appropriate echo statement. This code will copy the name of the current source:
<? echo $source['name'] ?>
You can include a variable conditionally (only if it is set) by wrapping the echo in an if condition:
<?
if ($source['options']['AnnotationAuthor']) {
echo ("<p><b>Author:</b> " .
$source['options']['AnnotationAuthor'] . "</p>\n\n");
}
?>
You can use some of the echoes in the original file as a reference. Also, you can unwarp your job
using the Debug script, then copy-and-paste the variables shown there into your script.
5. Prepare the index.php script
Make another copy of your script file to use as an index. Place the while loop around the elements
of your file that should be repeated for each source. Here's what this may look like for a table with
one row per source:
<table>
while(list(,$source) = each($sources) ) {
?>
<tr>
(Row content goes here)
</tr>
<? } >
</table>
5. Prepare the script for PhotoWarp
Place any images or style sheets you've used in your HTML into the web script's copy folder. Then,
rename the web script with a .pw extension. On Mac OS X, you will see the icon for the web script
change from a folder to a PhotoWarp 'Script' icon.
Unwarp a job with your web script selected. You should see the results of your script right away.
Web Script Reference
PhotoWarp communicates information about the current job to a web script through a job description
file. This is an XML text file that contains all information needed by a particular web script,
including all known meta information about a job, a source, and its outputs. The description file is
never seen directly by a script, but rather is parsed by a PHP function into an associative array,
called $job.
The parsing function is included in a private prefix file maintained internally by PhotoWarp. The
name of the file is passed in the environment variable PW_PREFIX_FILE to the script, which should
include the file before any other script code is reached:
<?php
include($_ENV["PW_PREFIX_FILE"]);
?>
The prefix file may be changed at any point in the future to provide new or improved capabilities,
which is why it is maintained privately by PhotoWarp. Updates may be provided through
PhotoWarp's auto update capability, or through new versions of the application itself.
Job Description Variables
is the global variable used by web scripts to access information passed in by PhotoWarp.
Several shorthand variables are also defined by the prefix file for convenience, which are expressed
below.
$job
Tip
For a complete list of all values in a job description array, run the "Debug" web script on a job and
view the resulting HTML file in your browser.
$job
$job['name']
$job['options']
$script
$PW_IndexURL
$script['options']
['ScriptOutputList']
$PW_IsIndex
$PW_UseJavaFallback
Top level variable. Contains values pertaining to the job
itself.
Name of the job file
Job-level options. Usually ignored.
Settings pertaining to the current web script.
Same as $job['script'].
Link to the index file for this job (if available).
Same as $script['index']['link_url'].
An indexed array of each output to be represented by this
script. Attributes include the format name, base format,
template, and all options for the output.
True if this output represents an index.
Same as $script['options']['ScriptIsIndex'].
True if this script should use the automatic fallback script.
Usually only ShowPano() needs to know this.
$script['options']['ScriptUseJavaFallback']
$sources
$source
$source['name']
$source['path']
$source['options']
$source['exif']
$source['outputs']
$source['pages']
An indexed array of each source to be represented by this
script. For singleton scripts, this will contain only one
element, $sources[0].
Same as $job['sources']
Not actually set by the prefix file, but a useful convenience
provided within a script. For singleton scripts, set $source
= $sources[0]. For indices, $source is set in a while
loop to the value of the current source to be represented.
Name of the current source. This defaults to the source file
name, but may be renamed in PhotoWarp to something
more appropriate.
Local path of the current source image.
Calculated option values for this source, including pan and
tilt constraints and resolution.
EXIF values retrieved from this source image, if present.
These are the same values displayed in the
Inspector/Details pane for the source.
Settings for each output representing the source.
An array of pages generated for this source.
$source['pages'][n]['link_url'] contains the relative
URL for each page.
Prefix Functions
In addition to parsing the job description file, the prefix file contains several PHP functions for
added capabilities or easier access to the contents of the description file.
ScriptHeader()
should be called in the <head> section of an HTML document. This includes
Javascript code necessary for the Java fallback capability.
ScriptHeader()
BodyArgs()
Provides a mechanism for the prefix file to include Javascript events in the page body. Presently this
functionality is unused.
ShowPano($source)
generates HTML to display the pano for the given source. This function will generate
the appropriate code for standard images, Java viewers, and QuickTime movies, as well as the Java
fallback behavior.
ShowPano()
Customizing embedded panoramas
You can add additional parameters to QuickTime VR, Zoom Viewer or PTViewer embedding tags.
Create a new array variable with one of the following names, and set the parameters as needed.
$PW_QTVRParams - Additional QuickTime VR parameters
$PW_ZoomParams - Additional Zoom Viewer parameters
$PW_PTViewerParams - Additional PTViewer parameters
The following code sample hides the controller bar and activates kiosk mode for a QuickTime VR
movie:
$PW_QTVRParams = new array();
$PW_QTVRParams['autoplay'] = "true";
$PW_QTVRParams['kioskmode'] = "true";
ShowPano($source);
Version History
PhotoWarp has introduced many new capabilities and improvements with each new version. Here is
a record of the most important changes:
PhotoWarp 2.5
Additional one-shot optic source types
PhotoWarp 2.5 includes support for the following one shot optics:
Kaidan™ 360 One VR®
0-360™ Lens
BeHere® TotalView®
Remote Reality® OneShot360®
Egg Solution® Egg 360°
All of these source formats use a calibrated optical profile to ensure the most accurate geometry
possible for each lens. Often, this profile is even more accurate than the original software that came
with the optic.
FlashVR output format
FlashVR is a perspective-correct panorama viewer written in Macromedia Flash. As more computers
today have Java applets disabled or unavailable in their browsers, this is an attractive way to deliver
interactive panoramas to an Internet audience.
Cube face image output format
Some users may like to manipulate the faces of a QuickTime VR Cubic image in an external
program before generating their final panorama. This might be useful for composing multiple shots
for a "full cubic" pano, or for hot spot generation tools. The Cube face images format will generate
six image files for the faces of a cube for easier editing.
Perspective and spherical projections for thumbnails
Thumbnails always used a cylindrical projection in earlier versions. Now, you can choose a
cylindrical, spherical, or perspective projection for the thumbnail.
Auto Levels filter
A simple checkbox on most output formats, auto levels will adjust the contrast of the image to fill
the entire dynamic range from black to white. This has identical functionality to the Photoshop
function of the same name, and is useful to enhance images and bring out small details.
Live preview window
A preview window generates low resolution QuickTime VR movies as sources are manipulated. This
gives an accurate preview of the results without unwarping. The preview can be used to precisely set
the default view of panoramas as well.
New Setup Assistant
Initial setup of PhotoWarp has been simplified with the new Setup Assistant. The assistant guides
new users through entering a license key, software registration, and essential preferences.
AppleScript support on Mac OS X
PhotoWarp 2.5 includes a scripting dictionary to automate with AppleScript. You can create a script
to make new jobs, add sources and change their formats, unwarp jobs, and more.
16 bit per channel processing
Previous versions of PhotoWarp would always downsample source images to 8 bits per channel for
unwarping. In 2.5, PhotoWarp can preserve the full dynamic range of source images throughout
processing. If an output format is selected that supports 16 bits per channel, the full range of the
source will be emitted.
Even faster unwarping
PhotoWarp 2.5 has the fastest unwarping engine available in any application. PhotoWarp is fully
optimized for multiple processors, G4 and G5 processors with Altivec, and Intel processors with
MMX, SSE or SSE2.
Unwarp Selection command
Rather than unwarping all the sources in a job, the Unwarp Selection command in the File menu will
unwarp only the current or selected sources.
Image file proxy icon
A draggable proxy icon for the currently visible image file is shown in the Job window. This can be
used for easy access to the original file for editing or reference.
Faster, more accurate mirror detection
A new algorithm is made available in PhotoWarp 2.5 for detecting the position of a mirror in a oneshot image. The new technique is extremely fast (under half a second per image), and more accurate
than the previous technique for the most common image. The new algorithm supports all one-shot
optics available in PhotoWarp.
EXIF grouping for mirror detection
PhotoWarp 2.5 interprets image files to group photographs likely to have identical mirror positions.
PhotoWarp will take the best position match within a group and apply it to all the images in the
group to improve mirror detection in batch jobs.
Source images can be edited externally while PhotoWarp is active
Image files can be manipulated and saved in Photoshop or another image editor that is an active
source in PhotoWarp. Once PhotoWarp is reactivated, the display will update automatically to reflect
changes in the file
Mirror distance parameter for 360 One VR sources
For 360 One VR lenses, a "mirror distance" parameter records the distance in millimeters between
the apex of the mirror and the camera's focal point. PhotoWarp 2.5 uses a ray tracing algorithm and
the precise geometry of the mirror to deliver an extremely accurate unwarped image. Previously,
unwarping images taken at a significant offset from the base of the optic resulted in some "bending"
of lines in resulting panoramas. This is eliminated with this new control.
Customizable panorama constraints
PhotoWarp 2.5 allows the user to customize the view constraint parameters manually for each
source. By default, PhotoWarp will intelligently select constraints for the source, which can be easily
overridden for any purpose.
Auto-rotate panoramas
PhotoWarp 2.5 offers an "auto-rotate" capability for all interactive panorama output formats. This
uses the built-in facility for PTViewer and Zoom viewers, or generates a custom wired sprite for
QuickTime VR movies.
Adjustable tilt for view knob
The view knob for sources with PhotoWarp 2 was restricted to the horizon. In 2.5, the knob will
"stick" to the horizon, but can be moved to any tilt position. Holding the alt key while dragging will
disable the sticky horizon.
Split line for sources
Sources, when unwarped to a cylindrical or spherical format, will be split consistently at the same
angle in PhotoWarp 2.5. This "split line" position is displayed on the source pane directly opposite
the view knob, and can be moved by dragging the view knob.
Next and Previous source buttons
By clicking the arrow buttons above the Unwarp button, you can switch between sources in a batch
job without accessing the source list.
Multiple selection in the source list
You can now select one or more sources in the source list at the same time. Once selected, you can
unwarp, remove or change the type of all the selected sources at once.
Dimensions indicator for image files
Below the resolution slider for cylindrical and spherical image formats, the Dimensions indicator
shows the exact dimensions of the image file that will be generated. The value changes live as the
resolution slider is changed.
Target file size
A "target file size" can be indicated. PhotoWarp will automatically adjust compression settings to
meet this file size as closely as possible.
Web view output pane
The output pane will now display web pages using Safari on Mac OS X or Internet Explorer on
Windows.
PhotoWarp 2.0
New interface
The interface of PhotoWarp 2 has been redesigned to accomodate a professional workflow, while
maintaining the simplicity of the original.
Batch processing
PhotoWarp 2 accepts one or more source image files which will be unwarped sequentially into one
or more output formats. This is a tremendous time savings compared to the one source to one output
format model used in the original.
Fast unwarping
PhotoWarp 2's optimized unwarping engine is considerably faster than the original PhotoWarp, and
by far the fastest available. Coupled with batch processing, PhotoWarp can produce hundreds of
panoramas in minutes.
Format templates
PhotoWarp supports several output formats, each having many settings to tailor the output to your
needs. These settings can be saved as a format template in the Templates palette for re-use in other
jobs.
Draggable formats
Output formats are shown as icons in an expanding Tray. The formats can be repositioned, copied to
or from the Templates window, and renamed just like file icons
Job files
A job consists of all the sources, output formats and settings used when unwarping. Jobs can be
saved for later reference or to repeat the same unwarping process later on. You can save, load and
change job files just like any kind of document.
Job templates
Job templates are simply job files with the sources removed. They can be saved into a "Job
Templates" folder and reused by choosing "File → New Job from Template...". This preserves all
the formats and settings used.
Inspector / Details window
You can examine the settings and file information for sources, formats and outputs using the new
Inspector (Mac) or Details (Windows) window.
Exposure/EXIF information
The inspector will show EXIF tags from source images, so you can examine camera settings and
other valuable information encoded in the image files.
Unwarp log
PhotoWarp can maintain a log of all unwarping activity in the program. The log is also useful for
tracking problems and errors that may have occurred during the unwarping process.
Cylindrical, spherical and QuickTime VR cylinder sources
In addition to images photographed with the 360 One VR, PhotoWarp 2 accepts any of these formats
as sources, which can be unwarped into any of the desired output formats.
Mirror detection
When source images from 360 One VR are loaded, PhotoWarp uses an algorithm to automatically
locate the position of the mirror in the frame. This is a big time savings for batch processing jobs.
Default view selection
The source pane displays a view knob that controls the default viewing direction of the panorama
when opened.
QuickTime VR Cubic output format
In addition to the traditional cylindrical QuickTime VR movies, PhotoWarp 2 can unwarp into the
new QuickTime VR Cubic format.
PTViewer and Zoom Viewer Java®-based output formats
By popular demand, PhotoWarp 2 supports two of the most popular Java®-based panorama viewers
in addition to QuickTime VR.
Custom image file formats
Image files can be emitted using any file format QuickTime supports. This includes JPEG, TIFF,
Adobe Photoshop, and many other popular formats.
Customizable compression settings
PhotoWarp 2 allows most any codec to be selected to compress QuickTime VR movies.
"Based on Movie"
For QuickTime VR output formats, generated VRs can be based upon another movie file to copy
advanced QuickTime capabilities. For instance, a "based on movie" can provide a watermark
overlay, a movie skin, or an auto-rotate sprite.
Web Scripts
Web Scripts allow automatic generation of web pages from PhotoWarp jobs. Web pages for
individual panos as well as an index page for all the panoramas in a job, complete with thumbnails,
can be created. Web Scripts automatically can generate JavaScript® code for seamless fallback from
QuickTime to Java-based panorama viewers. You can create web page templates using the popular
PHP scripting language.
PhotoWarp 1.0
Mac OS 9, X and Windows 98 support
PhotoWarp runs on all the most popular operating systems and platforms today.
Unwarping 360 One VR images
PhotoWarp "unwarps" images photographed with the 360 One VR panoramic optic quickly and
accurately. The result is high-quality interactive panoramas in seconds!
Simple, award-winning interface
PhotoWarp has an amazingly simple, single-click interface to unwarp images. PhotoWarp and 360
One VR received the "Best of Show" award at Macworld Expo San Francisco 2002, and a four-mice
rating from Macworld magazine.
QuickTime VR output format
PhotoWarp can generate QuickTime VR movies for the highest quality panoramic viewing
experience available.
Cylindrical and spherical output formats
PhotoWarp can also generate JPEG or TIFF image files with these traditional image projections for
use with image editing applications, or to support other panoramic image formats such as Java
viewers.
Thumbnails
PhotoWarp can automatically generate small, fixed-size cylindrical image thumbnails for a
panorama.
Output Preview
PhotoWarp shows generated image files and QuickTime VR images for your review after
unwarping.
Credits
Engineering
Seth Porter
Michael Rondinelli
Interface Design and Documentation
Michael Rondinelli
Acknowledgments
This product includes PHP 4.3.7, freely available from
http://www.php.net/
FlashVR viewer provided under license by Stehle GMK
http://www.flashvr.de/
Java viewer fallback support inspired by Autoviewer 3.0 by Mike Carambat, HomeSpunVR
Photography
http://www.designwizardry.com/autoviewer/
Zoom Viewer by iSeeMedia
http://www.iseemedia.com/
PTViewer, part of Panorama Tools by Helmut Dersch
http://www.fh-furtwangen.de/~dersch/
EyeSee360, 360 One VR and PhotoWarp are registered trademarks of EyeSee360, Inc.
BeHere and TotalView are registered trademarks of BeHere Technologies.
0-360 Panoramic Optic is a trademark of 0-360.com.
Remote Reality and OneShot360 is a registered trademark of Remote Reality.
Egg Solution is a registered trademark of Egg Solution, Ltd.
Macromedia, Macromedia Flash and Flash are registered trademarks of Macromedia, Inc.
QuickTime is a registered trademark of Apple Computer, Inc.
© 2001 – 2004 EyeSee360, Inc. All rights reserved.