snaphu(1)                   General Commands Manual                  snaphu(1)

NAME
       snaphu - phase unwrapping algorithm for SAR interferometry

SYNOPSIS
       snaphu [options] [infile] [linelength] [options]

DESCRIPTION
       snaphu is a statistical-cost network-flow algorithm for phase
       unwrapping.  Given an input interferogram and other observable data,
       snaphu attempts to compute congruent phase-unwrapped solutions that are
       maximally probable in an approximate a posteriori sense.  The
       algorithm's solver routine is based on network optimization.  By
       default, snaphu assumes that its input is a synthetic aperture radar
       (SAR) interferogram measuring surface topography.  Deformation
       measurements are assumed if the -d option is given.  Smooth, generic
       data are assumed if the -s option is given.

       This man page documents only the syntax and usage of snaphu.  Its
       theoretical foundations are discussed in the references cited below.

       The most common input parameters may be given on the command line,
       while many other twiddle parameters are handled via the -f option and
       configuration files.  At the very least, the name of a wrapped-phase
       input file and its line length must be specified.  For topography
       interferograms, range should increase towards the right in the
       interferogram, and the flat-earth phase ramp should be removed from the
       input interferogram before snaphu is run.  For deformation
       interferograms, phase variations due to topography should be removed as
       well.

       Except for the input file name and the line length, all input
       parameters take default values if not specified.  However, these
       parameters should be customized whenever possible since the accuracy of
       the solution depends on how well the statistics of the estimation
       problem are modeled.  To avoid poor-quality solutions, users are
       strongly encouraged to provide their best estimates of the relevant
       problem parameters.  Parameters are set in the order in which they are
       given on the command line, so multiple configuration files or options
       may be given, with later values overriding earlier ones.

       Allowable file formats are detailed below.  The default format for the
       input file is COMPLEX_DATA, but any of the described formats may be
       used.  If either of the ALT_LINE_DATA or ALT_SAMPLE_DATA formats are
       used, the magnitude and phase (in radians from 0 to 2pi) of the
       interferogram should be in the first and second channels of the file,
       respectively.  If the FLOAT_DATA format is used, the input file should
       contain only the phase of the interferogram (in radians from 0 to 2pi);
       the magnitude may be passed with the -m option.

OPTIONS
       -a ampfile
              Read brightness data from the file ampfile.  The file should
              contain the amplitudes (not powers) of the two individual SAR
              images forming the interferogram if the formats ALT_SAMPLE_DATA
              (default) or ALT_LINE_DATA are used.  It should contain an
              average of those two images if the FLOAT_DATA format is used.
              If (1) the amplitudes of both images are available, (2) the
              interferogram magnitude is also available, and (3) the -c option
              is not used, then a coherence estimate is automatically formed
              from the available data.  The number of looks used for this
              estimate can be set in a configuration file.  If no amplitude or
              power data are specified, then the magnitude of the input
              interferogram is used as the average amplitude, and no coherence
              estimate is formed.  Note that the magnitude of the
              interferogram is not equal to the average amplitude of the SAR
              images.  The amplitude data should be in the same system of
              units used for the input interferogram, and also coregistered to
              it.

       -A pwrfile
              Similar to the -a option, except the data in the specified file
              is assumed to represent the powers of the two individual SAR
              images.

       -b Bperp
              For topography mode, use Bperp (decimal value, in meters) as the
              value of the perpendicular component of the interferometric
              baseline.  The sign is defined such that Bperp is negative if
              the unwrapped phase increases with the elevation.  By default,
              repeat-pass or ping-pong mode is assumed; for single-antenna-
              transmit data, the value of Bperp should be halved, or the
              transmit mode should be set accordingly in a configuration file
              (see the -f option).  The baseline value is only used in
              topography mode.

       -c corrfile
              Read correlation data from the file corrfile.  The correlation
              data should be the same size as, and registered to, the input
              interferogram.  Consequently, a raw correlation estimate may
              need to be upsampled if it incorporates more looks than the
              interferogram.  If the -c option is not given, a coherence
              estimate is formed from the available data if possible.
              Otherwise, a uniform default coherence is assumed for the entire
              interferogram.  If the ALT_LINE_DATA (default) or
              ALT_SAMPLE_DATA formats are used, the correlation data should be
              in the second data channel of the file; the first channel is
              ignored.  The FLOAT_DATA format may also be used.  The
              correlation values should be between zero and one, inclusive.

       -C configstr
              Parse the string configstr as if it were a line from a
              configuration file containing a keyword-value pair (see the -f
              option).  Configuration lines generally have whitespace between
              the keyword and the value, so configstr will usually need to be
              surrounded by quotation marks on a command line so that the
              shell does not split it into separate arguments (snaphu itself
              does not require or allow quotation marks, however).  The syntax
              for how quotation marks are handled is defined by the shell.
              Multiple instances of the -C option may be used in order to
              specify multiple configuration inputs.  Later instances of the
              -C option take precedence over both earlier instances of the -C
              option and the configurations specified by earlier instances of
              the -f option.

       -d     Run in deformation mode.  The problem statistics and resulting
              cost functions are based on the assumption that the true
              unwrapped phase represents surface displacement rather than
              elevation.

       -e estimatefile
              Flatten using the unwrapped phase estimate in the file
              estimatefile.  The estimate is subtracted from the input
              interferogram before unwrapping, and is inserted back into the
              solution just before the output is written.  The estimate also
              affects the cost functions used, since subtracting a constant
              from a random variable shifts the probability density function
              of the random variable.  If the formats ALT_LINE_DATA (default)
              or ALT_SAMPLE_DATA are used, the unwrapped estimate (in radians)
              should be in the second data channel of the file; the first
              channel is ignored.  The FLOAT_DATA format may also be used.

       -f configfile
              Read configuration parameters from file configfile.  The file is
              parsed line by line for key-value pairs.  Template configuration
              files are included with the snaphu source code: snaphu.conf.full
              contains all valid key-value pairs; snaphu.conf.brief contains
              the most important parameters.  Lines not beginning with
              alphanumeric characters are treated as comment lines.  Command
              line options specified after -f will override parameters
              specified in the configfile and vice versa.  The -f option may
              be given multiple times with different configuration files, with
              parameters in later-specified files overriding those in earlier
              ones.

       -g maskfile
              Grow a connected component mask for the unwrapped solution and
              write the mask to the file maskfile.  A connected component is a
              region of pixels in the solution that is believed to have been
              unwrapped in a relative, internally self-consistent manner
              according to the statistical costs used.  Regions that are
              smaller than a preselected threshold are masked out.  Parameters
              for this option can be set in the configuration file.  The
              connected component file is composed of unsigned characters by
              default, with all pixels of the same value belonging to the same
              connected component and zero corresponding to masked pixels.

       -G maskfile
              Grow a connected component mask (see the -g option) for the
              input data array, assuming that it is already unwrapped, and
              write the mask to the file maskfile.  Statistical cost functions
              are computed for forming the mask, but a new unwrapped solution
              is not computed.

       -h, --help
              Print a help message summarizing command-line options and exit.

       -i     Run in initialize-only mode.  Normally, snaphu uses either an
              approximate minimum spanning tree (MST) algorithm or a minimum
              cost flow (MCF) algorithm for generating the initialization to
              its iterative, modified network-simplex solver.  If -i is given,
              the initialization is written to the output and the program
              exits without running the iterative solver.

       -k     Keep temporary tile outputs.  If this option is specified when
              snaphu runs in tile mode, the temporary directory where tile
              outputs are stored will be left in place rather than deleted.
              The tile-mode initialization of the -S option will also be left
              in place rather than deleted.

       -l logfile
              Log all runtime parameters and some other environment
              information into the specified file.  The log file is a text
              file in the same format as a configuration file.

       -m magfile
              Read interferogram magnitude data from the specified file.  This
              option is useful mainly if the wrapped-phase input file is given
              as a set of real phase values rather than complex interferogram
              values.  The interferogram magnitude is used to form a coherence
              estimate if appropriate amplitude data are given as well.  The
              default file format is FLOAT_DATA.  If the formats ALT_LINE_DATA
              or ALT_SAMPLE_DATA are used, the magnitude should be in the
              first data channel of the file; the second channel is ignored.
              If the COMPLEX_DATA format is used, the phase information is
              ignored.  Areas where the magnitude is zero are treated as
              masked areas (see the -M option).

       -M bytemaskfile
              Read a byte mask from the specified file.  The mask file should
              be the same size as the input array to be unwrapped.  The mask
              should have the binary (not ASCII) value 0 where pixels of the
              input array are to be ignored during the primary optimization
              stage of the program.  Values elsewhere should be binary 1.
              Masking is not applied until after the initialization stage of
              snaphu.  Masked areas are treated as areas in which the solution
              phase value is irrelevant to the solution cost.  The magnitude
              of the interferogram is set to zero in masked areas in the
              output file.  Areas with zero magnitude in the input data are
              treated as masked areas as well.  Areas near the edges of the
              input may also be masked via options in a configuration file.

       -n     Run in no-statistical-costs mode.  If the -i or -p options are
              given, snaphu will not use statistical costs.  Information from
              a weight file (-w option) will still be used if given.

       -o outfile
              Write the unwrapped output to a file called outfile.  If the
              file formats ALT_LINE_DATA (default) or ALT_SAMPLE_DATA are
              used, the unwrapped phase is written into the second data
              channel, while the interferogram magnitude is written into the
              first channel.  The format FLOAT_DATA may also be used.

       -p value
              Run in Lp-norm mode with p=value, where value is a nonnegative
              decimal.  Instead of statistical cost functions, the program
              uses Lp cost functions with statistically based weights (unless
              -n is also given).  Solutions are still always congruent.
              Moreover, congruence is enforced within the solver routine, not
              as a post-optimization processing step.  Therefore, if p=2, for
              example, least-squares cost functions are used, but the solution
              will probably be more accurate than one generated from a
              transform-based least-squares algorithm.

       -q     Run in quantify-only mode.  The input data are assumed to be
              unwrapped already, and the total cost of this solution is
              calculated and printed.  The unwrapped phase is wrapped assuming
              congruence for the cost calculation.  Round-off errors may limit
              the precision of the quantified cost.  See the -u option for
              allowable file formats.

       -s     Run in smooth-solution mode.  The problem statistics and
              resulting cost functions are based on the assumption that the
              true unwrapped phase represents a generic surface with no
              discontinuities.  This is the same as deformation mode with the
              DEFOMAX parameter set to zero.

       -S     Do single-tile re-optimization after tile-mode initialization.
              If this option is specified, snaphu will run in tile mode to
              generate an unwrapped solution, which is then used as the
              initialization to a single-tile optimization that produces the
              final unwrapped output.  The tile-mode initialization may itself
              be initialized by the MST or MCF algorithms (or an input
              unwrapped phase file) as normal.  This option is equivalent to
              running an instance of snaphu in tile mode, then running another
              instance of snaphu taking the tile-mode output as an unwrapped
              input via the -u option.  Tile parameters must be specified when
              using this option.  This approach is often faster than
              unwrapping an interferogram as a single tile from an MST
              initialization, especially if multiple processors are used.

       -t     Run in topography mode.  The problem statistics and resulting
              cost functions are based on the assumption that the true
              unwrapped phase represents surface elevation.  This is the
              default.

       -u     Assume that the input file is unwrapped rather than wrapped.
              The algorithm makes iterative improvements to this solution
              instead of using an initialization routine.  The input file may
              be in the formats ALT_LINE_DATA (default) or ALT_SAMPLE_DATA;
              the interferogram magnitude should be in the first data channel
              and the unwrapped phase should be in the second data channel.
              The format FLOAT_DATA may also be used.

       -v     Run in verbose mode.  Extra information on the algorithm's
              progress is printed to the standard output.

       -w weightfile
              Read external, scalar weights from file weightfile.  The
              weights, which should be positive short integers, are applied to
              whichever cost functions are used.  There is one weight value
              for each arc in the network, so weightfile should be the
              concatenation of raster horizontal-flow and vertical-flow arc
              weights.  Thus, for an N row by M column interferogram,
              weightfile would consist of a rasterized (N-1) by M array
              followed by a rasterized N by (M-1) array of short integer data.
              This option is not well tested.

       --aa ampfile1 ampfile2
              Amplitude data are read from the files specified.  The data from
              the two individual SAR images forming the interferogram are
              assumed to be separately stored in files ampfile1 and ampfile2.
              These files should be in the format FLOAT_DATA.  This option is
              similar to the -a option.

       --AA pwrfile1 pwrfile2
              Similar to the --aa option, but power data are read from the
              specified files.

       --assemble
              Assemble the tile-mode temporary files from a previous tile-mode
              run of snaphu, possibly with different secondary optimization
              parameters, to produce a new unwrapped solution.  The tile
              directory name must be specified with the --tiledir option.
              Most configuration options (from the command line and any
              configuration files) must be specified similar to the previous
              run, including the output file name from which the names of
              temporary tile files are derived.  The previous output file may
              hence be overwritten by the new output file.  This option is
              useful if the user wishes to modify tile-assembly parameters
              without unwrapping the individual tiles over again.

       --copyright, --info
              Print the software copyright notice and bug report info, then
              exit.

       --costinfile costfile
              Read statistical cost arrays from file costfile.  This file
              should be in the format written by the --costoutfile option.
              The cost file does not control whether snaphu runs in
              topography, deformation, or smooth-solution mode; the latter two
              must be specified explicitly even if costfile was generated
              while running in those modes.

       --costoutfile costfile
              Write statistical cost arrays to file costfile.  This option can
              be used with the --costinfile option to save the time of
              generating statistical costs if the same costs are used multiple
              times.

       --debug, --dumpall
              Dump all sorts of intermediate arrays to files.

       --mst  Use a minimum spanning tree (MST) algorithm for the
              initialization.  This is the default.

       --mcf  Use a minimum cost flow (MCF) algorithm for the initialization.
              The cs2 solver by Goldberg and Cherkassky is used.  The modified
              network-simplex solver in L1 mode may give different results
              than the cs2 solver, though in principle both should be L1
              optimal.

       --nproc n
              Use n parallel processes when in tile mode.  The program forks a
              new process for each tile so that tiles can be unwrapped in
              parallel; at most n processes will run concurrently.  Forking is
              done before data are read.  The standard output streams of child
              processes are directed to log files in the temporary tile
              directory.

       --piece firstrow firstcol nrow ncol
              Read and unwrap only a subset or part of the input
              interferogram.  The read piece is the nrow by ncol rectangle
              whose upper left corner is the pixel at row firstrow and column
              firstcol (indexed from 1).  All input files (such as amplitude,
              coherence, etc.) are assumed to be the same size as the input
              phase file.  All output files are nrow by ncol.

       --tile ntilerow ntilecol rowovrlp colovrlp
              Unwrap the interferogram in tile mode.  The interferogram is
              partitioned into ntilerow by ntilecol tiles, each of which is
              unwrapped independently.  Tiles overlap by rowovrlp and colovrlp
              pixels in the row and column directions.  The tiles are then
              segmented into reliable regions based on the cost functions, and
              the regions are reassembled.  The program creates a subdirectory
              for temporary files in the directory of the eventual output file
              (see the --tiledir and -k options).  Tiles can be unwrapped in
              parallel (see the --nproc option).

       --tiledir dirname
              Use dirname as the name of the directory in which temporary
              tile-model outputs are written and/or read.  The directory is
              created if it does not exist, and it is removed at the end of
              the run unless the -k or --assemble options are specified.

FILE FORMATS
       The formats of input files may be specified in a configuration file.
       All of these formats are composed of raster, single-precision (float,
       real*4, or complex*8) floating-point data types in the platform's
       native byte order.  Data are read line by line in row-major order
       (across then down, with the column index varying faster than the row
       index).  Regardless of the file format, all input data arrays should
       have the same number of samples in width and depth and should be
       coregistered to one another.  Note that weight files and cost files
       have their own formats.  The allowable formats for other data files are
       described below.

       COMPLEX_DATA
              Alternating floats correspond to the real (in-phase) and
              imaginary (quadrature) components of complex data samples.  The
              specified line length should be the number of complex samples
              (pairs of real and imaginary samples) per line.

       ALT_LINE_DATA
              Alternating lines (rows) of data correspond to lines of purely
              real data from two separate arrays.  The first array is often
              the magnitude of the interferogram, and the second may be
              unwrapped phase, coherence, etc.  This is also sometimes called
              hgt, rmg, or line-interleaved format.

       ALT_SAMPLE_DATA
              Alternating samples correspond to purely real samples from two
              separate arrays.  This format is sometimes used for the
              amplitudes of the two SAR images.

       FLOAT_DATA
              The file contains data for only one channel or array, and the
              data are purely real.

EXAMPLES
       Unwrap a wrapped topographic interferogram called ``wrappedfile'' whose
       line length is 1024 complex samples (output will be written to a file
       whose name is compiled into the program):

           snaphu wrappedfile 1024

       Unwrap the same file as above, but use brightness information from the
       file ``ampfile,'' set the perpendicular baseline to -165 m at midswath,
       and place the output in a file called ``unwrappedfile'' (coherence data
       are generated automatically if ``wrappedfile'' contains complex data
       and ``ampfile'' contains amplitude data from both SAR images):

           snaphu wrappedfile 1024 -a ampfile \
               -b -165 -o unwrappedfile

       Unwrap the interferogram as above, but read correlation information
       from the file ``corrfile'' instead of generating it from the
       interferogram and amplitude data:

           snaphu wrappedfile 1024 -a ampfile -c corrfile \
               -b -165 -o unwrappedfile

       The following is equivalent to the previous example, but input
       parameters are read from a configuration file, and verbose output is
       displayed:

           cat > configfile
           # This is a comment line which will be ignored
           AMPFILE      ampfile
           CORRFILE     corrfile
           BPERP        -165
           OUTFILE      unwrappedfile
           EOF (ie, Ctrl-D)

           snaphu -v -f configfile wrappedfile 1024

       Unwrap the same interferogram, but use only the MST initialization
       (with scalar statistical weights) and write the output to ``mstfile'':

           snaphu -f configfile -i wrappedfile 1024 -o mstfile

       Read the unwrapped data in ``mstfile'' and use that as the
       initialization to the modified network-simplex solver:

           snaphu -f configfile -u mstfile 1024 -o unwrappedfile

       Note that in the previous two examples, the output file name in the
       configuration file is overrided by the one given on the command line.
       The previous two commands together are in principle equivalent to the
       preceding one, although round-off errors in flow-to-phase conversions
       may cause minor differences

       Unwrap the interferogram as above, but use the MCF algorithm for
       initialization:

           snaphu -f configfile wrappedfile 1024 --mcf

       Unwrap the interferogram once again, but first flatten it with the
       unwrapped data in ``estfile,'' then reinsert the subtracted phase after
       unwrapping:

           snaphu -f configfile wrappedfile 1024 -e estfile

       The following assumes that the wrapped input interferogram measures
       deformation, not topography.  Unwrap the interferogram with the given
       correlation data:

           snaphu -d wrappedfile 1024 -c corrfile

       Unwrap the input interferogram by minimizing the unweighted congruent
       L2 norm:

           snaphu -p 2 -n wrappedfile 1024

       Unwrap the interferogram as a three-by-four set of tiles that overlap
       by 30 pixels, with the specified configuration file, using two
       processors:

           snaphu wrappedfile 1024 -f configfile \
               --tile 3 4 30 30 --nproc 2

HINTS AND TIPS
       The program may print a warning message about costs being clipped to
       avoid overflow.  If too many costs are clipped, the value of COSTSCALE
       may need to be decreased in a configuration file (via the -f option).
       If the program prints a warning message about an unexpected increase in
       the total solution cost, this is an indication that too many costs are
       clipped.  It is usually okay if just a few costs are clipped.

       In topography mode, if the unwrapped result contains too many
       discontinuities, try increasing the value of LAYMINEI or decreasing the
       value of LAYCONST.  The former determines the normalized intensity
       threshold for layover, and the latter is the relative layover
       probability.  If there are too many discontinuities running in azimuth,
       try decreasing the value of AZDZFACTOR, which affects the ratio of
       azimuth to range costs.  If the baseline is not known, take a guess at
       it and be sure its sign is correct.  Specify the SAR imaging geometry
       parameters as well as possible.  The defaults assume ERS data with five
       looks taken in azimuth.

       In deformation mode, if the unwrapped result contains too many
       discontinuities, try increasing the value of DEFOTHRESHFACTOR or
       decreasing the value of DEFOCONST.  If the surface displacement varies
       slowly and true discontinuities are not expected at all, DEFOMAX_CYCLE
       can be set to zero.  This behavior is also invoked with the -s option.
       The resulting cost functions will be similar to correlation-weighted L2
       cost functions, though the former are not necessarily centered on the
       wrapped gradients.  Congruence is still enforced during rather than
       after optimization.

       The program can be run in initialize-only (-i) mode for quick down-and-
       dirty MST or MCF solutions.

SIGNALS
       Once the iterative solver has started, snaphu traps the interrupt (INT)
       and hangup (HUP) signals.  Upon receiving an interrupt, for example if
       the user types Ctrl-C, the program finishes a minor iteration, dumps
       its current solution to the output, and exits.  If a second interrupt
       is given after the first (caught) interrupt, the program exits
       immediately.  If a hangup signal is received, the program dumps its
       current solution then continues to execute normally.

EXIT STATUS
       Upon successful termination, the program exits with code 0.  Errors
       result in exit code 1.

FILES
       The following files may be useful for reference, but are not required.
       They are included in the program source distribution and may be
       installed somewhere on the system.

       snaphu.conf.full
              Template configuration file setting all valid input parameters
              (though some may be commented out).

       snaphu.conf.brief
              General-purpose template configuration file setting the most
              important or commonly modified input parameters.

       In addition to parameters read from configuration files specified on
       the command line, default parameters may be read from a system-wide
       configuration file if such a file is named when the program is
       compiled.

BUGS
       The -w option has not been tested exhaustively.

       Extreme shadow discontinuities (i.e., abrupt elevation drops in
       increasing range due to cliffs facing away from the radar) are not
       modeled that well in the cost functions for topography mode.

       Abrupt changes in surface reflectivity, such as those of coastlines
       between bright land and dark water, might be misinterpreted as layover
       and assigned inappropriate costs.

       The algorithm's behavior may be unpredictable if the costs are badly
       scaled and excessively clipped to fit into their short-integer data
       types.

       There is no error checking that ensures that the network node
       potentials (incost and outcost) do not overflow their integer data
       types.

       Automatic flow clipping is built into the MST initialization, but it
       can give erratic results and may loop infinitely for certain input data
       sets.  It is consequently turned off by default.

       Dedicated programs for specific Lp objective functions may work better
       than snaphu in Lp mode.  Note that snaphu enforces congruence as part
       of the problem formulation, however, not as a post-optimization
       processing step.

       A tree pruning capability is built into the code and can be enabled
       from a configuration file, but this functionality is experimental and
       not well tested.

REFERENCES
       C. W. Chen and H. A. Zebker, ``Two-dimensional phase unwrapping with
       use of statistical models for cost functions in nonlinear
       optimization,'' Journal of the Optical Society of America A, 18,
       338-351 (2001).

       C. W. Chen and H. A. Zebker, ``Network approaches to two-dimensional
       phase unwrapping: intractability and two new algorithms,'' Journal of
       the Optical Society of America A, 17, 401-414 (2000).

       C. W. Chen and H. A. Zebker, ``Phase unwrapping for large SAR
       interferograms: Statistical segmentation and generalized network
       models,'' IEEE Transactions on Geoscience and Remote Sensing, 40,
       1709-1719 (2002).

                                                                     snaphu(1)
