= Hugin batch processing =

== Stitching process overview ==

With the 0.7.0 release, hugin changes the stitching system entirely.  Instead
of running each of the steps directly from the hugin application, a
''Makefile'' is written containing all the rules necessary to create the final
output files - This Makefile is then processed by the ''make'' tool as a
separate process.

The advantage of this is that it allows more efficient use of resources and
plenty of new customisation options.

When a hugin project is saved, two files are created:

* The .pto file is portable across systems and contains all the information
describing the relationship between the input photos in the project.

* The .pto.mk file contains all the specific instructions to create all
intermediate and output files that need to be generated to actually stitch the
panorama.

== Stitching on the command-line ==

When you click on '''Save project and stitch''', hugin writes a .pto file and
launches a separate tool called ''hugin_stitch_project'' that creates a .pto.mk
file, processes it with 'make all clean' and displays all progress messages.

Alternatively, if you just save a project, both these files are created but
''make'' isn't run.  This allows you to simply stitch the project at a later
date using ''make'' on the command-line:

  make -f DSC_01-DSC_16.pto.mk

This will create all the intermediate files and final output.  One of the
advantages of using make is that re-running this command will only redo
necessary work - If none of the input files have changed, then 'make' will
finish immediately.

=== make options ===

''make'' supports multiple ''targets'', by default hugin creates an 'all' and a
'clean' target that deletes intermediate files.  So you can clean up afterwards
like so:

  make -f DSC_01-DSC_16.pto.mk clean

Internal variables can be overriden using the '-e' flag, so to stitch using the
alternative ''nona-mask'' tool instead of ''nona'', use something like this:

  make -e -f DSC_01-DSC_16.pto.mk NONA=nona-mask

In a shell such as ''bash'', setting the environment will modify internal
variables for the rest of the session:

  export ENFUSE_OPTS='-l 29'

(note that this will override any existing useful enfuse options)

=== Parallel make ===

''make'' supports parallel processing for machines with multiple
cores/processors with the '-j' parameter, so for a 16 core system this command
will stitch using 16 parallel processes:

  make -e -j 16 -f DSC_01-DSC_16.pto.mk NONA='nona -t 1'

(note that by default ''nona'' uses all available cores, in this case it needs
to be limited to one thread so that 16 instances of nona can run at the same
time)

=== Stitching queues ===

Processing a series of projects one after another is simple enough, this will
stitch all the projects in a folder:

  for file in *.pto.mk; do make -f $file; done

For more advanced command-line stitching, a tool like ''distmake'' will manage
a queue of ''Makefile'' stitching jobs, and even load-balance multiple machines
over a network:

http://sourceforge.net/projects/distmake/

== Makefile 'plugins' ==

A Makefile can be extended with additional targets by creating a second
Makefile that includes the original hugin project Makefile.  For instance a
''plugin'' Makefile called 'Makefile.psd.mk' might define a new target called
'ldr_psd' that assembles a multilayer PSD file for manual blending in a tool
such as the Gimp:

  make -f Makefile.psd.mk ldr_psd PTO=DSC_01-DSC_16.pto

=== Useful Makefile variables ===

Each PATH in this table has a matching PATH_SHELL version with special
characters escaped - This is the version that should be used in command-lines
themselves.

{|
| $(INPUT_IMAGES) | list of input files
| $(INPUT_IMAGE_1) | first input file
| $(PROJECT_FILE) | .pto project file
|-
| $(LDR_REMAPPED_PREFIX) | normal blended output prefix
| $(LDR_EXPOSURE_REMAPPED_PREFIX) | exposure blended output prefix
| $(HDR_STACK_REMAPPED_PREFIX) | HDR merged output prefix
|-
| $(LDR_BLENDED) | normal blended output file
| $(LDR_STACKED_BLENDED) | exposure blended output file
| $(HDR_BLENDED) | HDR merged output file
|-
| $(LDR_LAYERS) | list of normal unblended output files
| $(LDR_STACKS) | list of exposure blended stack files
| $(HDR_STACKS) | list of HDR merged stack files
|}

=== Problems to be solved ===

* Some potential Makefile extensions assume a particular panorama projection, usually equirectangular.  There is no clue as to the projection in the generated .pto.mk file.
* Similarly field of view would be important for any extension that performed remapping.
* Rules for each type of output (ldr/fused/hdr) are included in the .pto.mk but stacks generally produce garbage output if blended as a 'normal' project.  Most extensions would work fine with whichever of the normal ldr or fused ldr output was intended and don't need to know about this stuff.
* Some variables are difficult to override, for instance it isn't possible to insert '-l 29' into 'ENBLEND_OPTS=-v -w -f1740x870'.

