snaphu_man1.txt

phase unwrapping algorithm for SAR interferometry

              This  file  should  be in the format written by the
              --costoutfile option.  The cost file does not  con-
              trol  whether  snaphu  runs in topography, deforma-
              tion, or smooth-solution mode; the latter two  must
              be specified explicitly even if costfile was gener-
              ated 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 pro-
              cesses 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.

       --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 inter-
              ferogram 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.  This
              option is currently enabled  only  for  statistical
              cost functions.

FILE FORMATS
       The  formats of input files may be specified in a configu-
       ration 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.

       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 or line-interleaved format.

       ALT_SAMPLE_DATA
              Alternating  samples correspond to purely real sam-
              ples 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 informa-
       tion  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 gener-
       ated 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 generat-
       ing 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
            <Ctrl-D>

            snaphu -v -f configfile wrappedfile 1024

       Unwrap the same interferogram, but use only the  MST  ini-
       tialization  (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  algo-
       rithm 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  inter-
       ferogram 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 configura-
       tion 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  con-
       figuration  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 deter-
       mines 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 disconti-
       nuities 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  exe-
       cute 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
       long-integer data types.

       Automatic  flow clipping is built into the MST initializa-
       tion, but  it  can  give  erratic  results  and  may  loop
       infinitely  for  certain  input  data  sets.  It is conse-
       quently 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.

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  general-
       ized network models,'' IEEE Transactions on Geoscience and
       Remote Sensing, 40, 1709-1719 (2002).



                                                        snaphu(1)