snaphu_man1.txt

phase unwrapping algorithm for SAR interferometry

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.