snaphu.1

phase unwrapping algorithm for SAR interferometry

.TH "snaphu" 1
.SH NAME
snaphu \- phase unwrapping algorithm for SAR interferometry
.SH SYNOPSIS
.B snaphu
[options]
[infile]
[linelength]
[options]
.SH DESCRIPTION
\fBsnaphu\fR is a \fBs\fRtatistical-cost \fBn\fRetwork-flow
\fBa\fRlgorithm for \fBph\fRase \fBu\fRnwrapping.  Given an input
interferogram and other observable data, \fBsnaphu\fR attempts to
compute congruent phase-unwrapped solutions that are maximally
probable in an approximate \fIa posteriori\fR sense.  The algorithm's
solver routine is based on network optimization.  By default,
\fBsnaphu\fR assumes that its input is a synthetic aperture radar
(SAR) interferogram measuring surface topography.  Deformation
measurements are assumed if the \fB\-d\fR option is given.  Smooth,
generic data are assumed if the \fB\-s\fR option is given.

This man page documents only \fBsnaphu\fR's syntax and usage.  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 \fB\-f\fR
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 \fBsnaphu\fR 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) 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); the magnitude may be passed
with the \fB\-m\fR option.
.SH OPTIONS
.TP
\fB\-a\fP \fIampfile\fP 
Read brightness data from the file \fIampfile\fP.  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 \fB\-c\fP 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.
.TP
\fB\-A\fP \fIpwrfile\fP
Similar to the \fB\-a\fP option, except the data in the specified file
is assumed to represent the powers of the two individual SAR images.
.TP
\fB\-b\fP \fIBperp\fP
For topography mode, use \fIBperp\fP (decimal value, in meters) as the
value of the perpendicular component of the interferometric baseline.
The sign is defined such that \fIBperp\fP 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 \fIBperp\fP should be halved, or the transmit mode should be set
accordingly in a configuration file (see the \fB\-f\fP option).  The
baseline value is only used in topography mode.
.TP
\fB\-c\fP \fIcorrfile\fP
Read correlation data from the file \fIcorrfile\fP.  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 \fB\-c\fP 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.
.TP
.B \-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.
.TP
\fB\-e\fP \fIestimatefile\fP
Flatten using the unwrapped phase estimate in the file
\fIestimatefile\fP.  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.
.TP
\fB\-f\fP \fIconfigfile\fP 
Read configuration parameters from file \fIconfigfile\fP.  The file is
parsed line by line for key-value pairs.  Template configuration files
are included with the \fBsnaphu\fP source code: \fIsnaphu.conf.full\fP
contains all valid key-value pairs; \fIsnaphu.conf.brief\fP contains
the most important parameters.  Lines not beginning with alphanumeric
characters are treated as comment lines.  Command line options
specified after \fB\-f\fP will override parameters specified in the
\fIconfigfile\fP and vice versa.  The \fB\-f\fP option may be given
multiple times with different configuration files, with parameters in
later-specified files overriding those in earlier ones.
.TP
.B \-g \fImaskfile\fP
Grow a connected component mask for the unwrapped solution and write
the mask to the file \fImaskfile\fP.  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, with all pixels of the same value
belonging to the same connected component and zero corresponding to
masked pixels.
.TP
.B \-G \fImaskfile\fP
Grow a connected component mask (see the \fB\-g\fP option) for the
input data array, assuming that it is already unwrapped, and write the
mask to the file \fImaskfile\fP.  Statistical cost functions are
computed for forming the mask, but a new unwrapped solution is not
computed.
.TP
.B \-h
Print a help message summarizing command-line options and exit.
.TP
.B \-i
Run in initialize-only mode.  Normally, \fBsnaphu\fP 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 \fB\-i\fP is given,
the initialization is written to the output and the program exits
without running the iterative solver.
.TP
\fB\-l\fP \fIlogfile\fP
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.
.TP
\fB\-m\fP \fImagfile\fP
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.
.TP
.B \-n
Run in no-statistical-costs mode.  If the \fB\-i\fP or \fB\-p\fP
options are given, \fBsnaphu\fP will not use statistical costs.
Information from a weight file (\fB\-w\fP option) will still be used
if given.
.TP
\fB\-o\fP \fIoutfile\fP
Write the unwrapped output to file called \fIoutfile\fP.  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.
.TP
\fB\-p\fP \fIvalue\fP
Run in Lp-norm mode with p=\fIvalue\fP, where \fIvalue\fP is a
nonnegative decimal.  Instead of statistical cost functions, the
program uses Lp cost functions with statistically based weights
(unless \fB\-n\fP 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.
.TP
.B \-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 \fB\-u\fP option for allowable file formats.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-v
Run in verbose mode.  Extra information on the algorithm's progress is
printed to the standard output.
.TP
\fB\-w\fP \fIweightfile\fP
Read external, scalar weights from file \fIweightfile\fP.  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 \fIweightfile\fP should be the concatenation of
raster horizontal-flow and vertical-flow arc weights.  Thus, for an N
row by M column interferogram, \fIweightfile\fP 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.
.TP
\fB\-\-aa\fP \fIampfile1 ampfile2\fP 
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 \fIampfile1\fP and \fIampfile2\fP.  These
files should be in the format FLOAT_DATA.  This option is similar to
the \fB\-a\fP option.
.TP
\fB\-\-AA\fP \fIpwrfile1 pwrfile2\fP
Similar to the \fB\-\-aa\fP option, but power data are read from the
specified files.
.TP
\fB\-\-assemble \fIdirname\fP
Assemble the tile-mode temporary files in the specified directory.
Most configuration options (from the command line and any
configuration files) must be specified.  This option is useful
if the user wishes to modify tile-assembly parameters without
unwrapping the individual tiles over again.
.TP
.B \-\-copyright, \-\-info
Print the software copyright notice and bug report info, then exit.
.TP
\fB\-\-costinfile\fP \fIcostfile\fP
Read statistical cost arrays from file \fIcostfile\fP.  This file
should be in the format written by the \fB\-\-costoutfile\fP option.
The cost file does not control whether \fBsnaphu\fP runs in
topography, deformation, or smooth-solution mode; the latter two must
be specified explicitly even if \fIcostfile\fP was generated while
running in those modes.
.TP
\fB\-\-costoutfile\fP \fIcostfile\fP
Write statistical cost arrays to file \fIcostfile\fP.  This option can
be used with the \fB\-\-costinfile\fP option to save the time of
generating statistical costs if the same costs are used multiple times.
.TP
.B \-\-debug, \-\-dumpall
Dump all sorts of intermediate arrays to files.  
.TP