          How to Use "flow"
          -----------------
    J. E. Boyd - UCSD - 21-Feb-97


Purpose:
--------

"flow" computes optical flow for a sequences of images in pgm format
using the algorithm of Bulthoff, Little and Poggio.


Use:
----

The input images must be in pgm format.  File names must be structured
in such a way that their names can be constructed using a "printf" with a
single integer argument that is the frame number.

Usage is as follows:
   flow [command switches]

Command line switches are:

-width <integer>	Specifies size of window that algorithm will
			search to find a matching region.  This limits
			the size of flow that can be found.  The default
			value is 5 which limits the flow output to +/- 5
			in both the horizontal and vertical directions.

-sigma <float>		Specifies the sigma for a Gaussian region of support
			for matches in image intensity.  A large Gaussian has
			fewer spurious errors in flow but has less spatial
			resolution.  Default = 5 (very large)

-dog <float>		Specifies sigma for a difference of Gaussian filter
			applied to the images to "whiten" the signal before
			the flow is computed. Default = 2 (very large)

-start <integer>
-stop <integer>		The start and stop frames for the input sequence.
			Flow is computed for start to stop-1. Default is
			start = 0 to stop = 5.

-input <string>		A format string that indicates how sprintf should
			construct the input file name from the fram number.
			Default = "input%03d.pgm", for input files
			input001.pgm input002.pgm input003.pgm ...

-x <string>
-y <string>		An sprintf format string for creating the x- and
			y-direction flow output images.
			Default = "xout%03d.pgm"

-mask <string>		As above but for the validity mask if verified flow
			is computed. Default = "mask%03d.pgm".

-v on/off		Compute verified flow and produce a validity mask.
			This means for every two frames, A and B, flow will
			compute the flow from A to B and from B to A.  If the
			flows match, then it will set the validity mask, else
			it resets the validity mask.  In either case, the flow
			output is for the forward direction. This gives a good
			check to eliminate spurious flow caused by occlusions.

The ouput x and y output images are 8-bit 2s compliment that means that
values of 0 to 127 correspond to 0 to + 127 while 128 to 255 correspond to
-128 to -1.

Notes:
------

1. The smoothing for support is done using Deriches 2D IIR filters so
they are not genuine Gaussian filters, but close enough.  This means that
the flow computaton will not slow down for greater amounts of smoothing.

2. For an example of how to use it chech out the demo shell script.  It
does some ppm stuff to manipulate the color map for displaying the
flow as gray scale or color images.
