No interpolator
Bilinear
Lanczos2
Lanczos3
Welcome to the FSPViewer web page. FSPViewer is a free viewer for spherical (equirectangular) panoramic images.
There already many viewers available, so let's start from what FSPViewer is not. It is not a program for viewing panoramas on the internet.
FSPViewer is designed for viewing local (hard-disk, network or CD) high resolution panoramic images at full screen and with very high image quality. It uses advanced interpolation algorithms to show you smooth images without losing sharpness.
Internet viewers are designed for displaying small images in small windows, since bandwidth is limited. Viewing a panorama at full screen will give you a much more immersive feeling, but it will require much more resources from the computer. The whole image will be loaded in memory and the program will need to write a very high number of pixels, so a fast processor will be needed for smooth panning.
Today's (and tomorrow's) computers have fast processors and a lot of RAM, so it's now possible to write a full screen viewer. FSPViewer can handle images limited only from the available RAM and is heavily optimized so it's fast enough on modern computers. It can even use both processors of a dual core CPU like most modern ones.
FSPViewer does not require installation, just run it and look at the panorama. It supports hotspots so you can create virtual tours and distribute them on a CD. Every Windows computer will be able to run it immediately.
FSPViewer runs on any Windows 32 bit operating system. It requires DirectX 7
or later, which is almost certainly already installed on your computer, since
version 7 shipped in 1999 and most multimedia programs require DirectX. It is
possible to download it from Microsoft, anyway.
The graphic card must be set to True Color (16 million colors). The program
works in 24 and 32 bit modes, but 32 bit is noticeably faster.
FSPViewer also runs on Linux computers using WINE.
See below for the command line switches list.
Download
Download FSPViewer version 1.51 (295 KB)
Download FSPViewer 64 bit version 1.51 (442 KB)
KNOWN PROBLEM: some people have reported that when going full-screen the screen becomes black. This only happens on some computers and often it can be solved by pressing a few times the "F" key to toggle full-screen mode.
LICENSE TERMS: This version of FSPViewer is free for commercial and non commercial
use outside Italy. It
cannot be used for commercial purposes in Italy, that is you cannot use it to make
money in Italy.
You can contact me if you need a license for commercial use in Italy.
I hope that you'll enjoy using this program, at least as much as I enjoyed writing it. Please feel free to contact me for bug reports, suggestions and impressions at the following e-mail address: fsenore@ica-net.it
Fulvio Senore
Sample image
You can download a sample image. It is an 8500 pixels wide JPEG file, big enough to view the panorama at full screen without losing quality. It is a big file, but if you have patience or a fast connection it can be a good example.
Download the image (2.7 Mb)
Other software
If you create panoramic images by stitching together many photographs you may find useful this free program for removing vignetting.
FSPViewer does not require installation: just copy it to a computer and run it. It will not modify the settings of the computer so it will not cause problems to other programs. It simply writes the user options to the registry, but this is harmless.
When you run it, FSPViewer shows an empty window: select the File/Open menu command or press the Open button in the toolbar to open a panorama. The program can open JPEG images or *.FSV control files that are described below. You can open a file by dragging and dropping it to the FSPViewer icon, too.
You can navigate in an image by dragging the mouse or pressing the arrow
keys. Press the A key or the SHIFT key to zoom in, press the Z
key or the CONTROL key to zoom out.
In the lower part of the window there is a status bar: it will show the current
zoom factor and the horizontal and vertical fields of view. A zoom factor of
100% means that you are viewing the panorama at the same size of the panoramic
image. A zoom factor less than 100% means that you are viewing a smaller image,
a zoom factor higher than 100% means that tour are viewing a bigger image: of
course you will start losing details.
You can move as you want in the panorama: as soon as you stay still, the viewer computes a high quality image using an interpolator and draws it on the screen. This image does not have jagged edges and other artifacts: it is relatively slow to compute, so it is not shown while panning in order to give you a smooth movement. As far as I know, no other viewers use such high quality interpolators.
You can use the slider in the toolbar to make the image brighter or darker. You can also press the B or D key. The slider changes the gamma correction of the image, like the middle slider in Photoshop's Levels command, so the highlights are nor burned and the shadows do not turn completely black.
The View menu contains commands that will show or hide the toolbar ant
the status bar.
The View/Hotspots command shows the hotspots, too. This command is
only enabled if the current panorama has defined some hotspots.
The View/Hotspots List... command will open a dialog box with the list of
the hotspots defined for the current panorama. You can select an hotspot and
press OK (you can also double click the hotspot name in the list) and the viewer
will change direction of view so that the selected hospot will be in the center
of the window. This command is
only enabled if the current panorama has defined some hotspots.
The View/Full Screen command shows the panorama at full screen: you will
only see the panorama, without window borders or taskbar. Press ESC or any other
unused key to return to windowed mode. You can also press the F key to
enter full screen mode.
The Tools/Options menu command will let you set the quality level of the
interpolator and the default horizontal field of view value: this value will be
used when you open an image. It can be overridden by a command line switch or by
the content of the .FSV file (see below).
The Help/Test Speed command will display some continuous frames to test
the speed of the computer.
Interpolator options
Here are some information about the interpolators used by the program: they
are a little technical, but you will not need to fully understand them in order
to use the program.
All panoramic viewers work in the same way: they load an image in memory and use
the pixels of that image to compute the different views that you see on the
screen. Every pixel on the screen maps to a position between the pixels of the
base image. While panning, FSPViewer will take the nearest pixel in the base
image and show it on the screen. This is the fastest option and is used to
obtain a smooth panning, but it yields to poor quality. For this reason the
program will compute a higher quality image as soon as you stop panning.
FSPViewer implements three different algorithms: each one trades quality for speed
at different extents and you can choose which one to use with the Tools/Options
menu command.
The values shown above hold for zoom factors greater or equal to 100%. When the zoom factor is less then 100% the interpolators will use a progressively higher number of pixels so they will be slower. For example when the zoom factor is 50% the interpolators will use four times the pixels, so Lanczos3 will use 144 pixels in the base image foe each pixel on the screen. This will become slow, but you will need a *really* big image to obtain a 50% zoom factor for a full screen window.
Note: since version 1.1 the computation of the high quality image has been moved to a different thread, so the user interface is always responsive. Now there is usually no reason to use a low quality interpolator since a good one will only take a little longer to display the image. You can start panning again when you want, without any delay.
An example
Here's an example of the result of the various interpolator options. The image represents some rusted iron bars: it has been chosen because its sharp edges make clear the difference. The following images are part of screenshots taken at a zoom level of 87%
|
No interpolator |
Bilinear |
Lanczos2 |
Lanczos3 |
As you can see, without interpolation the lines are jagged and distorted but the image looks sharp. This is why many people prefer this setting to bilinear. Bilinear interpolation renders smooth edges but creates a blurred image. Lanczos interpolators render smooth edges and sharp images. This is a very good result, but it has a very high computing cost: only modern computers can compute it fast enough to use it an almost real-time application.
Here's the same image, part of screenshots taken at a zoom level of 300%, to make the difference easier to notice:
|
No interpolator |
Bilinear |
Lanczos2 |
Lanczos3 |
Interpolator (when panning) options
You can choose the interpolator to be used while panning. Since panning requires a fast computation of each frame you do not have higher quality options that are too slow.
None does not use any interpolator: it simply takes a single pixel in the base image. This is the fastest option so panning is smoother, but if you are panning very slowly you can often see a "shimmering" effect. This happens more often if the zoom factor is less than 100%.
Bilinear uses 4 pixels in the base image in order to compute each pixel on the screen. This option greatly reduces the "shimmering" effect, but it is slower so panning is not so smooth. I have used MMX instructions to speed up the computation but it is still slower than the previous option.
Auto uses the "bilinear" setting when you are panning slowly to avoid the "shimmering" effect, and it uses the "none" setting when you are panning faster so that the viewer is more responsive. This should be the best option for most users.
FSV control files
FSPViewer con directly open the JPEG image file of the panorama,
but you may want to use more advanced features of the program, such as hotspots.
In order to use these features you must supply more information to the program.
This is accomplished by writing a control file for each panoramic image.
The control file has a default extension of *.FSV ad is a text file written according to some guidelines.
Each line contains a key and a value, separated by an equal sign
(=), without spaces. The keys are not case sensitive, so you can mix upper and
lower case letters as you like.
The keys are:
| KEY | Meaning |
| ImageName=name of the jpeg file | specifies the name of the JPEG file to open. |
| WindowTitle=window text | specifies the text to be written in the title bar of the window. |
| Yaw=initial yaw value | specifies the initial value for the yaw angle (default 180) |
| Pitch=initial pitch value | specifies the initial value for the pitch angle (default 0) |
| hFov=initial hFov value | specifies the initial value for the horizontal field of view (default 50, maximum value 140) |
| MinYaw=minimum yaw value | specifies the minimum value of the yaw (horizontal) angle. It can be used to limit the movement in the left direction. |
| MaxYaw=maximum yaw value | specifies the maximum value of the yaw (horizontal) angle. It can be used to limit the movement in the right direction. |
| MinPitch=minimum pitch value | specifies the minimum value of the pitch (vertical) angle. It can be used to limit the movement in the down direction. |
| MaxPitch=maximum pitch value | specifies the maximum value of the pitch (vertical) angle. It can be used to limit the movement in the up direction. |
| AutoSpin=angle to add | used for autorotation of the panorama. The specifed value is added to yaw angle for each frame. Positive numers rotate to the right, negative numers rotate to the left. Since the drawing of each frame is very fast you will probably need small values. You can use decimal numbers. |
| HorizonPosition=nn | used if the horizon is not in the middle of the pano image. Without this parameter FSPViewer would show a curved horizon. The parameter is a % value of the image height, measured from the top. The default value is 50 and the horizon is considered to be in the middle of the image. If the value is less than 50 the horizon is nearer to the top of the image, if it is greater than 50 the horizon is nearer to the bottom of the image. For example, if you have a pano 1150 pixels high and the horizon is 430 pixels from the top then the parameter value is 430/1150*100 = 37. You must use an integer value, without decimals. |
| //comment | every line starting with two slashes is a comment: the program ignores it and can be used as a reference for future readers |
All the keys are optional except for the first, that is
mandatory (of course...).
All numeric values can have fractional values, the decimal separator must always be a period (not a comma).
For example, the following file:
ImageName=photo.jpg
WindowTitle=An example panorama
will tell FSPViewer to open a file named "photo.jpg" and to display the text "An example panorama" in the title bar of the window. Note that you must not write spaces before ad after the "=" sign.
Yaw and pitch
A full spherical panoramic image represents the whole view from a point, in any direction. Here is the structure of the image:
As you can see, the yaw is the horizontal angle, from left to right. Its values are between 0 (left border) and 360 (right border). The pitch is the vertical angle, from bottom to top. Its values are between -90 (straight bottom) and +90 (straight top). The horizontal direction has a pitch of 0. If you load such an image in FSPViewer you will be able to look in any direction. These images always have an height that is half their width.
Partial panoramic images
Creating a full panoramic image is a complex task and it
usually limits you to relatively low resolution. Moreover, in many cases, such
as landscape images, there is not much interest in shooting at you feet.
For these (and other) reasons you may have an image that is only partial, i.e.
it will not show every direction.
Most often you will have an image that is limited in the pitch
angle: the yaw value will still go to from 0 to 360 while the pitch range
will not go from -90 to +90 but will lie in a smaller range. For example,
stitching together some photographs taken with a 28mm lens (35mm equivalent) in
portrait mode will yield to a pitch range of about -30..+30.
FSPViewer will handle these images without problems: it will only make the
assumption that the horizon lies in the center of the image and it will compute
the maximum pitch value from the image size. If the horizon does not lie in the
center of the image you can use an FSV control file with the
"HorizonPosition" parameter to show the panorama with the correct
perspective. Without that parameter FSPViewer would show a curved horizon.
You may have images with a limited yaw range (less than 360): you will not be able to directly open them with FSPViewer, since the program expects a full 360 yaw range. You can solve the problem in the following way: create a monochrome (black, for example) image of the right size for a full 360 image, than paste the partial panorama inside the black image, in the correct position. Your original image will be surrounded by black areas but the program will now be able to open it. Now you can use the MinYaw and MaxYaw parameters of the FSV file to limit the horizontal view so that the black areas will not be visible.
Hotspots
An typical feature of viewers are hotspots: an hotspot is a
portion of a panorama that can be clicked to open another panorama. With FSPViewer you can define hotspots inside the FSV control file. You can specify
the viewing direction and angle of view of the opened panorama, in order to
create immersive virtual tours.
Each hotspot is defined by a number of consecutive lines in the FSV file. The
first line must be "BEGIN HOTSPOT" and the last must be "END
HOTSPOT". The other lines contain key-value pairs as stated below. The keys
are:
| KEY | Meaning |
| X=x coordinate | specifies the x coordinate of the hotspot. It
is computed as the absolute x coordinate of the pixel divided by the width
of the image and multiplied by 100. The resulting value will be between 0
and 100. This may seem complicated, but the result will not change as you
resize the image. The decimal separator must always be a period (not a comma). |
| Y=y coordinate | specifies the y coordinate of the hotspot. It is computed as the x coordinate |
| Description=hotspot description | specifies a description of the hotspot to be shown in the status bar |
| Target=JPEG or FSV file | specifies the name of the file to be opened when clicking the hotspot |
| InitialYaw=yaw angle | specifies the yaw (horizontal angle) for the opened panorama. It must be between 0 and 360. |
| InitialPitch=pitch angle | specifies the pitch (vertical angle) for the opened panorama. It must be between -90 and 90. |
| InitialHFov=field of view | specifies the horizontal field of view for the opened panorama. It is an angle and must be less than 70 degrees. |
To improve readability you can indent the lines between
"begin hotspot" and "end hotspot".
For example, an hotspot definition can be as follows:
begin hotspot
x=12.25
y=48.02
description=A new panorama
target=pano2.fsv
initialYaw=231.34
initialPitch=4.2
initialHFov=45.0
end hotspot
How to compute InitialYaw and InitialPitch
In order to compute these values you need to open the target
panorama with an image editor and take note of the coordinates of the point where you want to look.
InitialYaw is simpler: just multiply the x coordinate by 360 and divide by the
width of the image. You will obtain a number between 0 and 360.
InitialPitch is a little harder: let w be
the width of the image, h its height, y
the y coordinate of the point.
Then InitalPitch = 90*(h/2 - y)/(w/4).
You will obtain a number between -90 and 90: negative values mean "look
down", positive values mean "look up". You can create an Excel
worksheet to automate the computations.
Command line switches
You can use some switches in the command line that starts FSPViewer. The complete syntax is:
FSPViewer imagename -s -y=nn -p=nn -hf=nn -hson -top=nn -left=nn -nn -nn
| Switch | Meaning |
| imagename | specifies the name of the image file to be opened. |
| -s | will make the File Open dialog box show .FSV files by default instead of JPEG files. It can be useful if you have a folder or CD containing many .FSV files: the users will immediately see the right files. |
| -y=nn | specifies the initial yaw value. nn must be an integer number. |
| -p=nn | specifies the initial pitch value. nn must be an integer number. |
| -hf=nn | specifies the initial hFov value. nn must be an integer number. |
| -hson | shows the panoramic image with hotspost enabled. |
| -top=nn | specifies the y coordinate of the top border of the window, in pixels. |
| -left=nn | specifies the x coordinate of the left border of the window, in pixels.. |
| -nn | specifies the width of the window, in pixels. |
| -nn | specifies the height of the window, in pixels. |
| -fs | if the command line contains a filename FSPViewer will start in full-screen mode. If the command line does not contain a filename the viewer will go to full-screen mode as soon as a file is opened. |
All the four "top", "left", "width" and "height" switches must be present, otherwise they will be ignored.
The switch letters are not case sensitive. All switches are optional. The switch character can be either "-" or "/".
Here are some example command lines:
FSPViewer MyImage.jpg -s -y=30 -p=-10 -hf=80
FSPViewer MyImage.jpg -hson -top=0 -left=0 - -
How to create a CD with panoramic images
You can create a CD to show your panoramic images to other people using FSPViewer. The CD will not require installation and it will work on almost every Windows computer: only really old ones do not have DirectDraw7 installed, and probably those computers do not have enough RAM or CPU power to show your panoramas anyway. FSPViewer also runs on Linux computers using WINE.
Simply copy FSPViewer.exe and your panoramic images to a CD. It is better to use JPEG images than TIFF ones. TIFF images are so large that loading them from a CD takes a much longer time. To see the panoramic images just run FSPViewer and open the desired file. You can also drag an image file and drop it into the FSPViewer icon.
You can create an autostart CD that will automatically open a panoramic image when inserted in a computer. Just add to the CD a text file named "AUTORUN.INF" containing the following three lines:
[autorun]
OPEN=FSPViewer.exe PanoImage.jpg
ICON=FSPViewer.exe,0
Where "PanoImage.jpg" is the name of one of your panoramic images.
If you are using "*.fsv" control files the autorun.inf file could look like
[autorun]
OPEN=FSPViewer.exe PanoImage.fsv -s
ICON=FSPViewer.exe,0
The "-s" switch forces FSPViewer to show "*.fsv" files in the file open dialog, so users will not open the underlying jpeg files losing the information contained in the control file.
FSPViewer associates the "*.fsv" files with itself, so double-clicking an "*.fsv" file will open it with FSPViewer. The problem is that the association takes place the first time that FSPViewer runs on a computer: if FSPViewer was never executed on a computer Window will not know what to do with "*.fsv" files. For this reason you should not put a reference to "*.fsv" files in a batch files, but you should put a reference to "FSPViewer Panoimage.fsv" to make sure that it will run on new computers.