PTStitcherNG 0.4b

Prof. Dr. H. Dersch - HFU Furtwangen
December 30, 2009


Introduction

A new release of PTStitcherNG, now for Windows, MacOS and X86-Linux. This is the first beta-release, and supposed to being useful on its own in addition to being tested. It works as a fast replacement for the combination PTStitcher (or compatibel remapper) + blender (e.g. enblend).

Some speedresults first, obtained with my fastest platform (Intel Celeron 1.8GHz, 1 GByte ram, Nvidia GeForce GTX 285, OpenSUSE 11.1):

3 x 11 MPixel -------> 18 MPixel equirect 2.1 sec (the decimal point is correct)
For source images and project files see here.

337 x 6 MPixel ------->1433 MPixel cylinder 250 sec (4min 10 sec)
For source images and project files see here.

The cellprocessor version (Playstation 3) has been discontinued: Recent decisions by Sony (new PS3 without Linux) and IBM (dim future for the cellprocessor) made me switch to CUDA as one basis for PTStitcherNG. Friendly folks from Nvidia sent me one of their gpu-cards for evaluation. However, PTStitcherNG also runs very fast on plain vanilla current x86 systems.

What is PTStitcherNG ?

PTStitcherNG reads and transforms any number and type of input images, and combines them into one seamless panoramic image with larger field-of-view. Given enough input images, full spherical 360x180 degree views can be synthesized suitable for virtual-reality viewers or printing. Transformation parameters and names of the input images are read from a plain-text projectfile. The transformations consist of correcting distortions due to camera lenses, perspective tranlation and remapping to any of the usual panorama projections. Merging employs an eight level multiresolution algorithm which hides seams even if the source images fit badly. PTStitcherNG natively reads PPM, TIFF and JPEG images, and almost any raw or other format through plug-ins.

PTStitcherNG combines a panorama stitcher and multiresolution blender in one application. It is optimized for speed by using parallel processing (SIMD-instructions, multiple processor cores). The main novel feature is the tight coupling of the remapper and blender, with an optimized management of temporary data. This enables PTStitcherNG to keep all intermediate data and processed images in ram (in the case of the CUDA-version: in gpu-ram) even when stitching hundreds of images to gigapixel sized panoramas. As a result, no data have to be written to disk, or reread from disk with corresponding speed improvements. As an aside, this makes PTStitcherNG perform fast even on low profile host systems: E.g. the 2.1s result mentioned above is obtained on a single-core Celeron system.

PTStitcherNG is free software. No license is required to download and use it.

Installation

All versions of PTStitcherNG are copy-installed, i.e. the necessary program files are simply copied to a suitable location on your computer. No automatic "installer" corrupts your system by manipulating low-level settings.

Windows

The Windows version of PTSTitcherNG has been tested to work up to Windows XP. In Vista and Windows 7 the application can only be run in Win98-compatibility mode, see this link for setting this mode. Use one of the files PTStitcherNG_cuda.exe or PTStitcherNG.exe. PTStitcherNG.exe should run as is, while the CUDA-version requires two libraries (dlls): The file pano_cuda.dll from the distribution, and Nvidias CUDA-runtime cudart.dll which is part of Nvidias software development kit (SDK). You also need Nvidias CUDA-driver (and, of course, a CUDA-capable grapics card): Download driver and SDK from Nvidia and install them. If PTStitcherNG_cuda.exe can not startup due to a missing cudart.dll even if the SDK is installed, locate the file on your computer, and manually copy it to the directory where PTStitcherNG_cuda.exe resides. Do not use the cudart.dll file from the x86-Linux tree of this distribution. It has the same name, but is a different version, and will not work on Windows computers.

X86-Linux

The Linux-binary has been compiled for OpenSuse 11.1 (x86_64), and should run on this installation. The CUDA-version requires the Nvidia driver (download here) and runtime (download SDK from the same source). On other Linux-systems, you can use wine to run the Windows-version. This works actually quite well, and I am using this approach to develop and debug the Windows-version.

Even the CUDA-version PTStitcherNG_cuda.exe runs under wine if the basic linuxsystem is CUDA-capable. This requires some more tweaking: A very recent wine-version (>=1.1.34) is needed. You also need the Nvidia driver and SDK for linux from Nvidia. Follow these instructions to install a wrapper-cudart.dll for Linux on your system, but do not use the version from the FHA-project mentioned in the article. Rather, use the version of cudart.dll of this distribution from the X86-Linux directory. Finally, when calling PtStitcherNG_cuda.exe from wine you have to specify the full (POSIX-)path to the PTStitcherNG-executable, otherwise wine crashes.

X86-MacOS

Only the non-CUDA version of PTStitcherNG is available for Macintoshs. Simply copy the files PTStitcherNG (the actual program) and the file PTStitcherNG.app (an AppleScript GUI-wrapper for PTStitcherNG) to your computer. The default PTStitcherNG application is compiled for MacOS 10.5 (Leopard). There is a second version compiled to run under 10.4 (Tiger) which, however, is limited: It always uses deferred merging (see manpage) due to a bug in the seek-function of MacOS. It does not recognize the number of cores correctly due to an incomplete sysconf-function. To get multiple threads the user has to use the -j option (see manpage). And finally, it is somewhat slower. To use the 10.4 version together with the Applescript PTStitcherNG.app you have to rename PTStitcherNG_tiger to PTStitcherNG. There is no version for PowerPC processors.

Extending PTStitcherNG

As is, PTStitcherNG reads TIFF, JPEG and PPM-images. Reading RAW and other formats is accomplished by external readers, which feed PPM-data to PTStitcherNG. Once setup, this is done automatically. On startup PTStitcherNG reads a textfile PTImageReader.txt, which contains fileextensions and program commands, see the example of the distribution. Download and install dcraw for reading almost any RAW format, pngtopnm for reading PNG images, or any other of the netpbm utilities for almost any format.

PTStitcherNG writes TIFF (multilayer using "tiff_m" and single layer "tiff", see scriptsyntax below), PPM ("ppm"), and JPEG images. Pixelsize defaults to 3-byte RGB. The commandline option -p switches output format to 6-byte RGB (only PPM and TIFF). Large files exceeding 2GByte size can be written in PPM and (flat) TIFF-format, provided the operating system and file format permits it. In the case of TIFF-multilayer format, a filename with extension ".btf" or ".tf8" has to be used to force BigTIFF format on Linux and MacOS, the Windows-version supports multilayer format only for regular TIFFs.

Using PTStitcherNG

PTStitcherNG can be run as standalone programs with minimal graphical user interface. Simply drag and drop a suitable projectfile (e.g. the speedtest.pts-files from the above mentioned speedtests) onto PTStitcher's icon (in the case of MacOS: onto PTStitcherNG.app's icon). You will be asked for a save-location, and PTStitcherNG will then proceed and convert the input images.

PTStitcherNG can be run as a console application from the command line with many more options to finetune the conversion process. This might be used for batch-processing large amounts of images using shell scripts. See the man-page ptstitcher_man.pdf for details.

Finally, PTStitcherNG can be registered into one of the many graphical frontends to panorama tools, see the docs of your favorite system for details.

Examples

The distribution includes a small sample project which can be used to test the installation. Open the folder test and locate the file project.txt. Drag and drop this file onto PTStitcherNG's icon (on Macs: on PTStitcherNG.app's icon). PTStitcherNG should start up, ask for a save-location and convert the 6 images to a cylindrical panorama. Open the file project.txt with any plain-text editor, and change the settings to test other features, see the documentation on scripting syntax below. To run PTStitcherNG from the commandline, open a console window, navigate to the test-folder, and issue the command
..\win\PTStitcherNG.exe -o pano.tif Project.txt on Windows
../mac/PTStitcherNG -o pano.tif Project.txt on Macs
In this mode all commandline switches can be tested, see the PTStitcherNG manpage.

For larger panoramas and to test image quality, download any of the speedtest examples mentioned above: 18 megapixel sphere or 1433 megapixel cylinder .

Some Performance Issues

When selecting TIFF or PPM output, PTStitcherNG immediateley starts writing the final panorama from the first image without saving intermediate results. This requires the ability to seek forward into an initially empty file which operating systems handle quite differently: On Linux this is completely transparent, there is virtually no delay compared to sequential writing. On MacOS and especially on Windows XP however, the system spends a lot of time either writing zeros or otherwise working on the empty spaces in the files. Using TIFF_m always writes files in sequential order, and, depending on the OS, may be much faster.

There are many options influencing speed on a particular system, see the PTStitcherNG man-page for some more information.

Projectfile

Projectfiles are plain-text files generated either by hand using any texteditor or (usually) using one of the panorama tools utilities for aligning images, e.g. PTOptimizer, which is integrated in most graphical frontends to panorama tools. A subset of PTStitcher and PTGui scripting parameters is supported:

One line describing the output panoramic image:
p   wwidth   hheight   fprojection   vfield-of-view   nfileformat
projection is one of 0 (rectilinear), 1 (cylinder), 2,4 (equirectangular), 3 (spherical equidistant), 5,10 (spherical equisolid), 6 (spherical mirror).
fileformat = PPM, JPEG, TIFF, TIFF_m (TIFF-multilayer). In the case of JPEG-ouput, the quality (q=0...100 and progressive-flag g=0,1 can be set in a quoted string like n"JPEG q95 g0".

and one line describing each input image:
o   yyaw  ppitch  rroll   wwidth   hheight   fprojection   vfield-of-view   nfilename aa   bb   cc   dd   ee   Cxleft,xright,ytop,ybottom   Sxleft,xright,ytop,ybottom
yaw, pitch and roll specify angles to tilt, pan and rotate the images.
C and S options specify rectangles: C specifies new image dimensions (cut), all other parameters refer to these new dimensions, while S mereley selects an area by setting the alpha channel to zero outside.
a,b,c refer to polynomial coefficients for distortion corrections, and d,e shift the optical center of the image.
The projection parameter is almost identical to the panorama case, with one exception: 2 means spherical equidistant.
The line describing imagefiles in PTGui-pts-projectfiles
#-imgfile   width   height   "filename"
is also accepted to support script-generating programs which do not supply the filenames for input images on the o-line (see above). PTStitcherNG requires the input image names in the script. They can not be supplied on the commandline as in old PTStitcher. Most other parameters are optional with the exceptions y,p,r. PTStitcherNG supports the global image description line termed "#-dummyimage" in PTGui-projectfiles. Identical parameters for all images, e.g. field-of-view (v) or correction parameters (a,b,c) can be specified as v=0 (meaning identical to the value of dummyimage Nr.0 ), a=0 b=0 etc.

and one line describing global options:
m   iintrepolator
with interpolator = 0(cubic, default),1 (spline 4x4), 2 (spline 6x6), 3 (sinc 16x16), 4 (spline 8x8), 5 (bilinear), 6 (nearest neigthbor), 7 (sinc 32x32).


Copyright 2009  Helmut Dersch
der@fh-furtwangen.de