PTStitcher
Preface
PTStitcher is one of the core applications of Panorama tools, together with PTOptimizer and the Panorama Tools Plugins[*].
For stitching panoramas you most probably won't get in contact with PTStitcher frequently, since the scripting is more or less completely done by the various GUI front-ends[*] and some tools like PanoCube[*].
However, there are several occasions where you might need to write or at least understand the scripts or call PTStitcher directly (for some batch tasks f.e.).
Updates
The PTStitcher source code was never published, hence there are no changes possible to certain functions. But since a considerable part of its functionality is in pano12 library, PTStitcher benefits from every update of this core library.
You can take PTStitcher from any of the panotools distribution on one of the Mirrors[*]. In order to use new functionality you need a recent copy of pano12 library. Note that only win32, i386 Linux and mac classic binary versions were ever made available, so you are out of luck if you use OS X or a 64bit operating system.
There is an open source replacement for PTStitcher called nona in the hugin project which has much (but not all) of the PTStitcher features. Another open source replacement is PTmender, part of the pano12 project at sourceforge.
Intro
PTStitcher is script driven. The scripts are in pure text format and can be edited with any text or programming editor (on windows notepad will do).
They are processed on a line by line basis. Each line starts with a special character (case sensitive) that indicates the meaning of the rest of the line. All other first in line characters are ignored and considered comments.
Features
Most features of PTStitcher are conveniently accessible by the usual GUIs (see top), but some are not.
Accessible by GUI
PTStitcher can stitch
- spherical (equirectangular), cylindrical, rectilinear and fisheyed (or mirror ball) panoramas
- multi row panoramas
- panoramas from images that where shot tilted up or down.
- images from any lens (including spherical mirrors)
- images with different Focal Length into one panorama
- flat images[*] like scanned maps.
The capabilities of PTStitcher go far beyond panorama stitching: It can be used
- to remap images between different Projections
- to extract and insert rectilinear images[*] from a spherical or cylindrical panorama.
- to remap a spherical panorama[*] such that Nadir and Zenith are editable.
- to down- or upsample images[*] with high quality interpolators.
- to correct perspective distortion.
Accessible by Script or other Tool
PTStitcher can be used stand alone or with some other (non-GUI) Tool:
- together with some tool that separate color channels (ImageMagick[*]) to correct Chromatic aberration
- assembling 6 cube faces to an equirectangular panorama can be done by GUI but is more conveniently done by script, batch file or PanoCube Plus[*].
Example Script
The updated original example script with lots of comments is below. Copied from Jim Watters' page
############# Example Script ########################## # to run PTStitcher # # # Only lines starting with 'p','o', i', or 'm' are read, # so you can add comments and info as you like by using # other line starting characters. # The * character at the first of a line indicated the end of the script file. # The stitcher script must contain: # one 'p'- line describing the output image (eg Panorama) # one 'o'-line for each input image # one 'i' line for each input image that is optional # the 'm'-line is optional and allows you to specify modes for the optimization. # the 'C'-line is optional and allows morphing of control points.
p-line options
# 'p'-line options # w1000 width in pixels # h600 height in pixels (default: width/2) # f0 projection format, # 0 - rectilinear (for printing and viewing) # 1 - Cylindrical (for Printing and QTVR) # 2 - Equirectangular ( for Spherical panos), default # 3 - full-frame fisheye # v360 horizontal field of view of panorama (default 360) # nPICT Panorama file format, one of: # PICT pict-file on macs, bmp-file on win (default) # PSD single layer Photoshop file, 48bits supported # PNG png-format, 48bits supported # TIFF tiff-format, 48bits supported # PSD_mask Photoshop file, one image per layer # + shape mask & feathered clip mask at overlap center # PSD_nomask Photoshop file, one image per layer, # TIFF_mask tiff-format, multi-file, one image per file, 48bit supported # alpha layer with feathered clip mask at overlap center # TIFF_m tiff-format, multi-file, one image per file, 48bit supported # alpha layer with non-feathered clip mask at image border # + shape mask & non-feathered clip mask at image border # JPEG Panoramic image in jpeg-format. Use with f1 # for IBM Hotmedia panoramas. # PAN SmoothMove movie. Use only with f2. # IVR LivePicture IVR movie # cylindrical (format f1) or spherical (format f2) # IVR_java LivePicture Java Panorama, # cylindrical (format f1) or spherical (format f2) # VRML VRML background node, use only with f2 for panoramas, or # VRML-object for PTStereo # QTVR Apple QTVR-panomovie. Use only with f1 # 3DMF 3DMF-object (PTStereo). # # n"QTVR w400 h300 c1" additional viewer options in a quoted string together with format # the following options are recognized: # w(width) and h(height) of viewer window (only QTVR on Macs) # c(codec: 0-JPEG, 1-Cinepak, 2-Sorenson) (only QTVR on Macs) # q(codec quality): # 0-high,1-normal,2-low QTVR on Macs # 0-100(highest) on other jpeg-formats (PAN, IVR, IVR_java, VRML) # g progressive jpeg (0-no, 1-yes) (PAN, IVR, IVR_java, VRML) # Optimized JPEG (0-on(default), 2-disabled), (3-progressive with optimized disabled) # p initial pan angle ( QTVR on Macs, VRML, IVR) # v field of view (QTVR, VRML, IVR) # Many more options can be set by editing the viewer scripts # u10 width of feather for stitching all images. default:10 # k1 attempt color & brightness correction using image number as anchor # b1 attempt brightness correction with no color change using image number as anchor # d1 attempt color correction with no brightness change using image number as anchor # Do not use more than one of k, d, b.This is new method of correcting p w800 nPSD_mask
i-line options
# The 'i' lines describe input images and is optional # nName file name of the input image. # over ridable with command line parameters to PTStitcher i n"photo1.jpg"
o-line options
# The 'o' lines describe input images. One line per image is required
# The width and height of the image is obtained from image
# f0 projection format,
# 0 - rectilinear (normal lenses)
# 1 - Panoramic (Scanning cameras like Noblex)
# 2 - Circular fisheye
# 3 - full-frame fisheye
# 4 - PSphere, equirectangular
# v82 horizontal field of view of image (required)
# y0 yaw angle (required)
# p43 pitch angle (required)
# r0 roll angle (required)
# a,b,c lens correction coefficients (optional)
# (see http://www.fh-furtwangen.de/~dersch/barrel/barrel.html)
# d,e initial lens offset in pixels(defaults d0 e0, optional).
# Used to correct for offset from center of image
# d - horizontal offset,
# e - vertical offset
# g,t initial lens shear. Use to remove slight misalignment
# of the line scanner relative to the film transport
# g - horizontal shear
# t - vertical shear
# +buf (obsolete, -buf and +buf are now ignored when stitching)
# load and merge image with buffer
# -buf (obsolete, -buf and +buf are now ignored when stitching)
# save result to buffer. The first 'o' line should
# contain one '-buf' command, the last line one '+buf'
# command, and all other lines both '+buf -buf'
# Exception: remove all 'buf' commands when
# creating Photoshop-files to preserve the original images.
# u10 (obsolete, globally used on p line) width of feather for stitching. default:10
# S100,600,100,800 Selection(l,r,t,b), Only pixels inside the rectangle will be used for conversion.
# Original image size is used for all image parameters
# (e.g. field-of-view) refer to the original image.
# Selection can be outside image dimension.
# C100,600,100,800 Crop(l,r,t,b), Only pixels inside the rectangle will be used for conversion.
# Cropped image size is used for all image parameters
# (e.g. field-of-view) refer to the cropped part of the image.
# m20 (obsolete, use S & C) ignore a frame 20 pixels wide. default: 0
# mx100 (obsolete, use S & C) crop to brightest rectangle with size 100x200;
# my200 (obsolete, use S & C) used only for circular fisheye images (f2)
# s0 (obsolete, ignored, always blend) specify placement of seam between buffer and image:
# 0-middle of overlap('blend' ,default)
# 1- at edge of image ('paste').
# o (the small letter). Morph-to-fit using control points.
# k0 (obsolete, use p line correction still used with plugin)
# attempt color/brightness correction when merging image and buffer, one of:
# 0 - no correction(default);
# 1 - change image;
# 2 - change buffer;
# 3 - change both
# this feature does not work very well!
o f2 r0 p0 y0 v183 a0 b-0.1 c0 S100,600,100,800
o f2 r0 p0 y180 v183 a0 b-0.1 c0 S100,600,100,800
m-line options
# 'm'-line options # ---------------- # Set mode for stitcher, not required # # g2.5 Set gamma value for internal computations (default 1.0) # See <http://www.fh-furtwangen.de/~dersch/gamma/gamma.html> # i2 Set interpolator, See <http://www.fh-furtwangen.de/~dersch/interpolator/interpolator.html> # one of: # 0 - poly3 (default) # 1 - spline16, # 2 - spline36, # 3 - sinc256, # 4 - spline64, # 5 - bilinear, # 6 - nearest neighbor, # 7 - sinc1024 # \/ antialiasing filters \/ See <http://www.pano2qtvr.com/dll_patch/> # 8 - Box # 9 - Bartlett/Triangle # 10 - Hermite # 11 - Hanning # 12 - Hamming # 13 - Blackmann # 14 - Gaussian 1/sqrt(2) # 15 - Gaussian 1/2 # 16 - Quadardic # 17 - Cubic # 18 - Catmull-Rom # 19 - Mitchell # 20 - Lanczos2 # 21 - Lanczos3 # 22 - Blackman/Bessel # 23 - Blackman/sinc # # f0 Invoke Faster Transformation also invoked by creating a file named "pano12_opt.txt" # in the same foler as project with a line FAST_TRANSFORM m g1.5 i6 f0
z-line options
# 'z'-lines options # ---------------- # Extended Depth-Of-Field, not required # # Automatically determine, for every point in a picture, which of mumerous overlapping # images has best focus. Masks are generated to reveale the best focused parts of # each image. Feathering must be selected. Used with PSD_mask or TIFF_mask file format # to edit the mask or with flattened file formats for flattened final result. Does not # work if color and/or brightness correction are invoked. # # m2 mask type # m0 hard-edged masks, mutually exclusive # m1 hard-edged masks, stack of nested masks # m2 blended masks, stack of nested masks (default & strongly recommended) # (this option includes a smoothing computation that seems to help a lot.) # fN focus estimation window size, N = halfwidth of window. # Recommended value is 0.5% of image width, e.g. 4 pixels for an 800-pixel image. # Computation cost for focus estimation increases proportional to N^2. Default f4. # sN smoothing window size, N = halfwidth of window. # Recommended value is 0.5% of image width, e.g. 4 pixels for an 800-pixel image. # Computation cost for smoothing increases proportional to N^2. Default s4. z m2 f4 s4
C-line options
# 'C' lines # ---------------- # Morphing of control point lines # One line per point # Created automatically by optimizer # # i0 image # x363.726 starting x point position # y125.738 starting y point position # X363.838 morphed x point position # Y125.618 morphed y point position C i0 x363.726 y125.738 X363.838 Y125.618 * Every thing after * is ignored.
Tutorials
Information on how to create and use PTStitcher scripts can be found on the web and on the wiki:
- The original PTStitcher Readme[*] file contains basic information.
- The updated original example script with lots of comments is found at Jim Watters' page
- Ben Kreunen has an excellent list about the parameters of the p- o- and m-line and some example scripts.
- Frequently asked questions about PTStitcher including solutions to common problems are found at the unofficial Panorama Tools FAQ.
- On the wiki there are some techniques described that use PTStitcher:
Calling from the command line
PTStitcher can be called from the command line (this is what all GUIs do, too). More information in the PTStitcher Readme[*]