FSPViewer

Version 2 beta available, see bottom of page

Welcome to the FSPViewer web page. FSPViewer is a free viewer for spherical (equirectangular) panoramic images.

Table of contents
Yet Another Panoramic Viewer?

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.

System requirements

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.

What's new in version 1.51 64 bit?
What's new in version 1.51?

    See below for the command line switches list.

What's new in version 1.5?
What's new in version 1.41?
What's new in version 1.4?
What's new in version 1.3?
What's new in version 1.23?
What's new in version 1.22?
What's new in version 1.21?
What's new in version 1.2?
What's new in version 1.12?
What's new in version 1.11?

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.

Instructions

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.

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 -width=nn -height=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..
-width=nn specifies the width of the window, in pixels.
-height=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 -width=600 -height=400

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.

Version 2 beta (1.9)

A beta version of FSPViewer 2 is available.

This new version is available for Linux, Mac and Windows. The 64 bit version can open images of virtually any size, but of course you need enough RAM in your computer.

The new version at the moment has the same features as the older one, except for the brightness slider. I plan to add new features in the next future.

Here are the download links:

Linux 32 bit
Linux 64 bit
OS X (64 bit, 10.6 or later required)
Windows 32 bit
Windows 64 bit

How to set the program's options in the various operating systems:

Linux: menu Edit/Preferences
OS X standard Preferences menu
Windows menu Tools/Options

It is now possible to select the number of threads to use when computing frames. The default is 2, you can try 4 if you have at least a quad-core CPU.

A note about speed testing. The menu Help/Test speed computes the frame creation speed. It uses the first interpolator setting in the program's options, so you have 4 choices. Remember to reset to Lanczos3 after testing for optimal image quality.