Batch Processing with PTAssembler and PTAutomate

September 2009

Summary. This page explains how to quickly create multiple panoramas and mosaics using PTAssembler and PTAutomate.

Introduction. Even with fast panoramic image stitching software like PTAssembler, creating large numbers of panoramic images can be quite time consuming, particularly if you shoot in RAW format and need to convert your images to TIFF before processing with PTAssembler. On a typical day, you might shoot several hundred frames to be assembled into dozens of panoramas or mosaic images. Creating these panoramas and mosaics can take quite a lot of time, particularly if you have a large number of panoramas and/or the panoramas contain a lot of images. In particular, processing RAW images into TIFF can often add a large amount of time to the creation process.

A Non-Automated Workflow. Once all the images are loaded from the camera onto the computer, a typical non-automated workflow might look something like this:

  1. Open RAW processing software and look for a sequence of images that comprise a panorama.
  2. Convert RAW images into TIFF format.
  3. Load TIFF images into PTAssembler and hit Autocreate.
  4. Once Autocreate produces a preview, adjust/tweak panorama as necessary.
  5. Create final panorama
  6. Repeat Process for next panorama

Speeding Up The Process. PTAssembler's Batch Processing screen is helpful in speeding up this process by allowing for the unattended creation of batches of final panoramas.


PTAssembler's Batch Processing Screen.

This is very useful if you have a number of projects that have already been optimized and just need to be stitched into a final result. But, the batch processing screen doesn't help to speed up the processing of RAW files or creation of projects ready to be stitched. This is where PTAutomate is useful.

PTAutomate. PTAutomate (included with PTAssembler 5.1) is a small, simple application that can be used to automate the Autocreate process in PTAssembler. It is run from the command line (sorry, no clickable GUI) and takes a plain text file (as input) containing a listing of PTAssembler projects or image pairs (more below). PTAutomate reads the input file, and invokes PTAssembler with each project or image pair in the input text file (one project or image pair at a time), waits until PTAssembler has "autocreated" the project or image pair, and then moves on to the next project or image pair in the input text file. The text file can be created using any text editor such as notepad.


Sample Input File for PTAutomate.

PTAssembler Projects. If you have a number of projects that are ready to be processed by PTAssembler, then PTAutomate can be used to feed them to PTAssembler's Autocreate routine. You can create an input file for PTAutomate consisting of one project per line. (This assumes that you have already loaded the images into PTAssembler and saved a PTAssembler project file for each project.)

Image Pairs. An alternate, and easier, approach to creating an input file for PTAutomate is to take advantage of PTAssembler's ability (new in version 5.1) to process "image pairs" when invoked from the command line. An image pair is the first and last image in a project separated by a " - " (space hyphen space). When PTAssembler encounters an image pair, it looks at the first and last image names, tries to detect any common numeric pattern in the first and last image names, and then fills in the remaining images. For example, this image pair:

IMG_0186.TIF - IMG_0189.TIF

is interpreted by PTAssembler as:

IMG_0186.TIF IMG_0187.TIF IMG_0188.TIF IMG_0189.TIF

PTAssembler has detected the numeric pattern in the first and last image names, and "filled in" the intermediate names. Note that when invoked with an image pair, PTAssembler also checks to see if the intermediate files actually exist, so if one or more don't exist, then PTAssembler ignores these files.

Waiting For Images. If you need to convert RAW images to TIFF before loading into PTAssembler, a big time bottleneck is waiting for the TIFF files to appear before running PTAutomate/PTAssembler. Conveniently, PTAutomate will only invoke PTAssembler for image pairs or projects that actually exist. This means that you can specify the image pairs in a file, and start PTAutomate before/while converting your RAW files to TIFF. PTAutomate processes the items in the input file in order, but if it cannot find the project or image pair it will move on to the next item, rather than invoking PTAssembler. PTAutomate keeps track of which items it has found, and keeps checking for those that it has not found until it finds them and invokes PTAssembler. PTAutomate terminates once it has found and invoked PTAssembler for all items on the input list. (PTAutomate can be terminated at any time before this by pressing Ctrl-C).

As PTAutomate is running it continually updates (rewrites) the input file with status information, noting which projects or image pairs have finished processing, which project or image pair is currently processing and which are still in a waiting state. PTAutomate updates the input list file in a format that enables it to be used as an input file for a subsequent invocation of PTAutomate. Items in the input file that have been processed are prefixed with a "#" symbol (so that they will not be processed again), while items that have not yet been processed are not prefixed with a "#" symbol so they will be processed the next time PTAutomate is invoked with the input list file.


Input File updated by PTAutomate, while processing.

A PTAutomated Workflow. With PTAutomate, a typical workflow might look something like this:

  1. Open RAW processing software and look for sequences of images that comprise multiple panoramas.
  2. Note first and last images in each sequence, and record what their names will be when converted to TIFF format as image pairs in a text file.
  3. Start PTAutomate with text file created above.
  4. Start processing RAW images, and converting into TIFF format...As PTAutomate detects the TIFF images appearing, it invokes PTAssembler's Autocreate function.
  5. Optional (but recommended): Once all the projects have finished, load them (one at a time) into PTAssembler to generate a preview and perform any final adjustments/corrections.
  6. Load the PTAssembler project files into PTAssembler's Batch Processing screen, and run the batch to create the final output for multiple panoramas.

This is only one possible workflow...there are many different variations and approaches. However, using this approach, you can set up PTAutomate/PTAssembler to Autocreate multiple projects without any supervision/attention. Once you have started all the RAW images converting to TIFF, you can leave the computer alone and come back later to find a set of "autocreated" PTAssembler project files, ready for final preview/adjustment/tweaking before stitching into a final project.

Note that PTAssembler must be configured to generate a preview image during Autocreate (see the Autocreate tab of PTAssembler's preferences screen) or you should use the -n switch with PTAutomate (see help below) to prevent PTAssembler from creating a final (full-size) output as part of Autocreate.

Running PTAutomate. PTAutomate is a command line application, i.e. it is designed to be executed from the command prompt.

PTAutomate (ptauto.exe) should be installed in the same directory as PTAssembler (by default, this directory is c:\program files\ptasmblr), although it should work correctly if stored in other directories. It is highly recommended that you add PTAssembler's directory to the Windows system path. If this directory is not added to the Windows system path, then you'll have to specify the fully qualified path name when invoking PTAutomate as well as giving PTAutomate the location of PTAssembler:


Invoking PTAutomate (not on path).

If you have added PTAssembler's directory to the Windows system path, then PTAutomate can be invoked without a directory name and the location of PTAssembler does not need to be specified either:


Invoking PTAutomate (on path).

Because PTAutomate defaults to looking for a file named "list.txt", if this file exists in the current directory, then no input file name need be specified:


Invoking PTAutomate (on path, default input filename).

.pta File Type. When PTAssembler (version 5.1 or later) is installed, it creates a Windows file association with PTAutomate for ".pta" files. This means that if you name your input file with a ".pta" extension (e.g. myfile.pta) and double-click on this file in Windows Explorer, then PTAutomate will be invoked with your input file (as if you had typed "ptauto myfile.pta" at the command prompt). It is important to note that when PTAutomate is invoked this way, you have no ability to specify any command line arguments to alter the way in which it operates. One important consequence of this is that unless you have added PTAssembler's directory to the Windows system path, then PTAutomate won't be able to find PTAssembler and will not work correctly.

PTAutomate Help

To display a screen with instructions and options for PTAutomate, type ptauto -h. The following information was generated using PTAutomate 1.10: 



                                PTAutomate 1.10
                           http://www.tawbaware.com
                        (c) Tawbaware Software, 2009


Syntax:

  ptauto.exe [options] file.txt

Description:

  PTAutomate is a command line application to automate the processing of 
  batches of images by PTAssembler. PTAutomate requires an input file 
  (file.txt, above) that contains a list of PTAssembler projects or image 
  pairs, and invokes PTAssembler for each entry in the list. By default 
  PTAssembler's "Autocreate" function is invoked, but the "Autoalign" and 
  "Stitch" commands can be invoked instead.

  PTAutomate checks for the existence of each item (project or image files) 
  in the list before invoking PTAssembler. If the item does not exist, 
  PTAutomate attempts to invoke the next project or image pair in the 
  list.  PTAutomate continutally checks to see if a project or image pair
  exists for items in the input list, and only invokes PTAssembler once
  it has determined that the project or image pair exists.  PTAutomate only 
  launches one instance of PTAssembler a time, waiting for PTAssembler to 
  complete before moving onto the next item in the input list.  By default, 
  PTAutomate terminates once it has detected all items in the input list 
  and launched PTAssembler for all items.  However, PTAutomate can be 
  configured to terminate after a specified time period using the -w option.

  The input file should contain one project or image pair per line,
  illustrated in this example:

    #A project without a directory name, assumed to be in the current directory
    project1.ptp
    #A project with a fully qualified path
    c:\images\20090901\project2.ptp
    #An image pair, assumed to be in the current directory
    img_0074.tif - img_0078.tif
    #An image pair in another (explicitly specified) directory
    c:\images\20070804\image_1200.tif - c:\images\20070804\image_1205.tif

  Any empty lines or lines that start with the "#" character are ignored.  
  Entries can be either a project name (e.g. project1.ptp) or a pair of image 
  files (e.g. img_0074.tif - img_0078.tif).  Note that the images in a pair 
  must be separated with " - ". If files or projects are specified without a 
  directory, then the current directory is assumed.

  While PTAutomate is running, it overwrites the input list file with details
  about which items have been processed, and which are still waiting to be 
  processed.  PTAutomate updates the input list file in a format that enables 
  it to be used as an input file for a subsequent invocation of PTAutomate.  
  Lines in the input file that have been processed are prefixed with a "#"
  symbol so that they will not be processed again. Items that have not yet 
  been processed are not prefixed with a "#" symbol so they will be 
  processed the next time PTAutomate is invoked with the input list file.  The 
  -l option prevents PTAutomate from updating the input file.

  If no input file is specified, PTAutomate defaults to looking for an input 
  file named "list.txt".

  Important Note: In order for PTAutomate to invoke PTAssembler, PTAssembler
  must either be in one of the directories included in the system PATH 
  variable, or the -p option must be used to explicitly specify PTAssembler's
  location.

Options:

    -p loc   Specify location of PTAssembler (required if not on PATH)
    -a       Invoke PTAssembler with "Autoalign" command
    -s       Invoke PTAssembler with "Stitch" command
    -o       Force PTAssembler to overwrite exising project file
    -n       Force PTAssembler not to create preview image after autocreate
    -w n     Process list for n seconds before terminating
    -l       Do not overwrite input file as items are processed
    -v       Verbose output

Examples:

  ptauto.exe mylist.txt
  ptauto.exe -w 1800 mylist.txt
  ptauto.exe -p "c:\program files\ptasmblr\ptasmblr.exe" -n mylist.txt

License:

  This program is licensed for use with PTAssembler.  Other uses are
  explicitly prohibited