snaphu.1

phase unwrapping algorithm for SAR interferometry

.B \-\-mst
Use a minimum spanning tree (MST) algorithm for the initialization.
This is the default.
.TP
.B \-\-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.
.TP
.B \-\-nproc \fIn\fP
Use \fIn\fP 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 \fIn\fP processes will run concurrently.  Forking is done
before data is read.  The standard output streams of child processes
are directed to log files in the temporary tile directory.
.TP
.B \-\-piece \fIfirstrow firstcol nrow ncol\fP
Read and unwrap only a subset or part of the input interferogram.  The
read piece is the \fInrow\fP by \fIncol\fP rectangle whose upper left
corner is the pixel at row \fIfirstrow\fP and column \fIfirstcol\fP
(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 \fInrow\fP by \fIncol\fP.
.TP
.B \-\-tile \fIntilerow ntilecol rowovrlp colovrlp\fP
Unwrap the interferogram in tile mode.  The interferogram is
partitioned into \fIntilerow\fP by \fIntilecol\fP tiles, each of which
is unwrapped independently.  Tiles overlap by \fIrowovrlp\fP and
\fIcolovrlp\fP 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.  This
option is currently enabled only for statistical cost functions.
.SH 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 (across then down).
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.
.TP
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.
.TP
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 \fBhgt\fP or
line-interleaved format.
.TP
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.
.TP
FLOAT_DATA
The file contains data for only one channel or array, and the data are
purely real.
.SH 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):

.nf
	snaphu wrappedfile 1024
.fi

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):

.nf
	snaphu wrappedfile 1024 -a ampfile \\\ 
		-b -165 -o unwrappedfile
.fi

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

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

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

.nf
	cat > configfile
	# This is a comment line which will be ignored
	AMPFILE      ampfile
	CORRFILE     corrfile
	BPERP        -165
	OUTFILE      unwrappedfile
	<Ctrl-D>

	snaphu -v -f configfile wrappedfile 1024
.fi

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

.nf
	snaphu -f configfile -i wrappedfile 1024 -o mstfile
.fi

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

.nf
	snaphu -f configfile -u mstfile 1024 -o unwrappedfile
.fi

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:

.nf
	snaphu -f configfile wrappedfile 1024 --mcf
.fi

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

.nf
	snaphu -f configfile wrappedfile 1024 -e estfile
.fi

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

.nf
	snaphu -d wrappedfile 1024 -c corrfile 
.fi

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

.nf
	snaphu -p 2 -n wrappedfile 1024
.fi

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

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

.SH "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 \fB\-f\fR
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 \fB\-s\fR
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 (\fB\-i\fR) mode for quick
down-and-dirty MST or MCF solutions.
.SH SIGNALS
Once the iterative solver has started, \fBsnaphu\fR 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.
.SH "EXIT STATUS"
Upon successful termination, the program exits with code 0.  Errors
result in exit code 1.
.SH 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.
.TP
\fIsnaphu.conf.full\fP
Template configuration file setting all valid input parameters (though
some may be commented out).
.TP
\fIsnaphu.conf.brief\fP
General-purpose template configuration file setting the most
important or commonly modified input parameters.
.PP
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.
.SH BUGS
The \fB\-w\fR 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 long-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 \fBsnaphu\fR in Lp mode.  Note that snaphu enforces congruence as
part of the problem formulation, however, not as a post-optimization
processing step.  
.SH REFERENCES
C. W. Chen and H. A. Zebker, ``Two-dimensional phase unwrapping with
use of statistical models for cost functions in nonlinear
optimization,'' \fIJournal of the Optical Society of America A\fP,
\fB18\fP, 338-351 (2001).

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

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