Batch Processing with PTAssembler and PTAutomate

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. In a single day, it is quite easy to 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/mosaic.
  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/mosaic.
  6. Repeat Process for next panorama/mosaic.

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/mosaics.


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, command line application designed to 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 one at a time. All that is required is that you create an input file for PTAutomate consisting of one project filename 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 by pressing Ctrl-C).

While PTAutomate is running, it writes details about which item is currently being processed, which items have been processed, and which are still waiting to be processed to a log file. By default, PTAutomate overwrites the input file as its log file, but the location of the log file can be changed using the -m option. PTAutomate writes the log file in a format that enables the log file to be reused as an input file for a subsequent invocation of PTAutomate. Items in the input file that have been processed are prefixed with a "#" (comment) 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.


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 (using a program like Raw Therapee), 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: Command Line Operation. PTAutomate is a command line application, i.e. it is designed to be executed from the command prompt.

PTAutomate (ptauto.exe) is installed in the same directory as PTAssembler (by default, this directory is c:\program files\ptasmblr). 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 PTAutomate's fully qualified path name when invoking PTAutomate. By default, PTAutomate assumes that PTAssembler is installed in the same directory as PTAutomate. If not, then you will have to specify the location of PTAssembler using the -p option:


Invoking PTAutomate (PTAssembler/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 (PTAssembler/PTAutomate on path).

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


Invoking PTAutomate (PTAssembler/PTAutomate on path, default input filename).

Running PTAutomate: Windows Operation (.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). when PTAutomate is invoked this way, you cannot specify any program options via the command line. However, you can specify any desired program options in the input file. Lines in the input file that start with the "-" character (e.g. -o -s) are processed as a series of program options. When program options are specified in the input file, PTAutomate will rewrite these options to the log file it creates. The list of valid program options is described below.

PTAutomate Help

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



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


Syntax:

  ptauto.exe [options] file.txt

Description:

  PTAutomate is a command line application that automates 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 (more details below), 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 moves to 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 has elapsed 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 " - " (space hyphen space). If files or projects 
  are specified without a directory, then the current directory is assumed.
  Program options can also be specified in the input file; if a line starts 
  with a "-" character (e.g. -s -o), PTAutomate interprets the line as a 
  series of program options.
  

  While PTAutomate is running, it writes details about which item is currently
  being processed, which items have been processed, and which are still 
  waiting to be processed to a log file.  By default, PTAutomate overwrites the 
  input file as its log file, but the location of the log file can be changed
  using the -m option.  PTAutomate writes the log file in a format that 
  enables the log file to be reused as an input file for a subsequent 
  invocation of PTAutomate.  Items in the input file that have been processed 
  are prefixed with a "#" (comment) 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.

  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:

  These options can be specified as part of the command line when invoking
  PTAutomate, or they can be included as a line in an input file for
  PTAutomate.

    -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 existing project file
    -n       Force PTAssembler not to create preview image after autocreate
    -w n     Process list for n seconds before terminating
    -l       Do not perform any logging
    -m fname Write logging information to fname, (rather than input file)
    -x       Shutdown computer after processing completes
    -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