snaphu(1)                                               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 snaphu's  syntax  and  usage.
       Its  theoretical  foundations  are discussed in the refer-
       ences cited below.

       The most common input parameters may be given on the  com-
       mand 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 con-
       figuration  files or options may be given, with later val-
       ues 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  -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 interfer-
              ogram if the formats ALT_SAMPLE_DATA  (default)  or
              ALT_LINE_DATA are used.  It should contain an aver-
              age 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  interfero-
              gram  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 interfero-
              gram, 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.   Conse-
              quently,  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.

       -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 den-
              sity 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  for-
              mat 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  con-
              tains  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,  with  all
              pixels of the same value belonging to the same con-
              nected 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     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.

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

       -m magfile
              Read  interferogram  magnitude data from the speci-
              fied 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.

       -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 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  statis-
              tics  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.

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

       -u     Assume that the input file is unwrapped rather than
              wrapped.   The  algorithm  makes iterative improve-
              ments to this solution instead of using an initial-
              ization routine.  The input file may be in the for-
              mats 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 inte-
              gers, are applied to whichever cost  functions  are
              used.   There  is  one weight value for each arc in
              the network, so weightfile should be the concatena-
              tion  of  raster  horizontal-flow and vertical-flow
              arc weights.  Thus, for an N row by M column inter-
              ferogram,  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 dirname
              Assemble the tile-mode temporary files in the spec-
              ified  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.

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