Provided by: snaphu_2.0.3-1_amd64 
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.
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
overridden 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)