snaphu(1)                                               snaphu(1)NAME       snaphu - phase unwrapping algorithm for SAR interferometrySYNOPSIS       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.