[Git][debian-gis-team/snaphu][master] 7 commits: New upstream version 2.0.6
Antonio Valentino (@antonio.valentino)
gitlab at salsa.debian.org
Sun Jun 11 15:59:52 BST 2023
Antonio Valentino pushed to branch master at Debian GIS Project / snaphu
Commits:
36505485 by Antonio Valentino at 2023-06-10T16:24:56+00:00
New upstream version 2.0.6
- - - - -
90d0a1c9 by Antonio Valentino at 2023-06-10T16:24:56+00:00
Update upstream source from tag 'upstream/2.0.6'
Update to upstream version '2.0.6'
with Debian dir c8ee1dd5700a5eff292b5c2111af937f5884ffef
- - - - -
daf7c806 by Antonio Valentino at 2023-06-10T16:25:34+00:00
New upstream release
- - - - -
4d7e0bd1 by Antonio Valentino at 2023-06-10T16:26:11+00:00
Update copyright dates
- - - - -
85b11780 by Antonio Valentino at 2023-06-10T16:26:12+00:00
Refresh all patches
- - - - -
d7200a99 by Antonio Valentino at 2023-06-11T16:58:48+02:00
Bump debhelper-compet version to 13
- - - - -
897eefe2 by Antonio Valentino at 2023-06-11T16:58:48+02:00
Set distribution to unstable
- - - - -
12 changed files:
- README
- README_releasenotes.txt
- debian/changelog
- debian/control
- debian/copyright
- debian/patches/0002-Spelling.patch
- man/man1/snaphu.1
- man/snaphu_man1.html
- man/snaphu_man1.txt
- src/snaphu.c
- src/snaphu.h
- src/snaphu_tile.c
Changes:
=====================================
README
=====================================
@@ -1,7 +1,7 @@
SNAPHU
Statistical-Cost, Netowrk-Flow Algorithm for Phase Unwrapping
Author: Curtis W. Chen
-Version 2.0.5, December 2021
+Version 2.0.6, April 2023
Contents
@@ -53,7 +53,7 @@ itself to unwrap each tile. The structure of the solver does not lend
itself to easy parallelization for a single tile, however.
The CS2 MCF solver module is governed by the terms of the original
-authors (see the README.copyright file). In order to compile snaphu
+authors (see the copyright below). In order to compile snaphu
without this module, specify -D NO_CS2 as a compiler option in the
Makefile.
@@ -71,7 +71,7 @@ accept.
Copyright
---------
-Copyright 2002-2021 Board of Trustees, Leland Stanford Jr. University
+Copyright 2002-2023 Board of Trustees, Leland Stanford Jr. University
Except as noted below, permission to use, copy, modify, and
distribute, this software and its documentation for any purpose is
=====================================
README_releasenotes.txt
=====================================
@@ -1,3 +1,10 @@
+Notable changes in v2.0.6 since v2.0.5:
+---------------------------------------
+
+* Change conditions for breaking out of outermost loop over flow
+ increments in optimizer to avoid possible infinite loop issue.
+
+
Notable changes in v2.0.5 since v2.0.4:
---------------------------------------
=====================================
debian/changelog
=====================================
@@ -1,14 +1,19 @@
-snaphu (2.0.5-2) UNRELEASED; urgency=medium
+snaphu (2.0.6-1) unstable; urgency=medium
[ Antonio Valentino ]
+ * New upstream release.
* Add lintian-overrides for "superficial-tests".
* Fix d/copyright formatting.
+ * debian/copyright:
+ - update copyright dates.
+ * Refresh all patches.
+ * Bump debhelper-compat version to 13.
[ Bas Couwenberg ]
* Bump Standards-Version to 4.6.2, no changes.
* Enable Salsa CI.
- -- Antonio Valentino <antonio.valentino at tiscali.it> Tue, 01 Feb 2022 07:27:32 +0000
+ -- Antonio Valentino <antonio.valentino at tiscali.it> Sat, 10 Jun 2023 16:26:38 +0000
snaphu (2.0.5-1) unstable; urgency=medium
=====================================
debian/control
=====================================
@@ -5,7 +5,7 @@ Section: non-free/science
XS-Autobuild: yes
Rules-Requires-Root: no
Priority: optional
-Build-Depends: debhelper-compat (= 12)
+Build-Depends: debhelper-compat (= 13)
Standards-Version: 4.6.2
Vcs-Browser: https://salsa.debian.org/debian-gis-team/snaphu
Vcs-Git: https://salsa.debian.org/debian-gis-team/snaphu.git
=====================================
debian/copyright
=====================================
@@ -5,7 +5,7 @@ Disclaimer: this package is in the non-free archive because parts of the
sources can be used only for noncommercial purposes
Files: *
-Copyright: 2002-2021, Board of Trustees, Leland Stanford Jr. University
+Copyright: 2002-2023, Board of Trustees, Leland Stanford Jr. University
License: other
Except as noted below, permission to use, copy, modify, and
distribute, this software and its documentation for any purpose is
@@ -67,7 +67,7 @@ License: igsys
http://www.igsystems.com/cs2
Files: debian/*
-Copyright: 2010-2022, Antonio Valentino <antonio.valentino at tiscali.it>
+Copyright: 2010-2023, Antonio Valentino <antonio.valentino at tiscali.it>
License: GPL-3+
This package is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
=====================================
debian/patches/0002-Spelling.patch
=====================================
@@ -9,10 +9,10 @@ Forwarded: not-needed
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/man/man1/snaphu.1 b/man/man1/snaphu.1
-index 161cc25..a4ed3c9 100644
+index 7047b66..74c838c 100644
--- a/man/man1/snaphu.1
+++ b/man/man1/snaphu.1
-@@ -464,7 +464,7 @@ initialization to the modified network-simplex solver:
+@@ -465,7 +465,7 @@ initialization to the modified network-simplex solver:
.fi
.PP
Note that in the previous two examples, the output file name in the
@@ -22,7 +22,7 @@ index 161cc25..a4ed3c9 100644
preceding one, although round-off errors in flow-to-phase conversions
may cause minor differences
diff --git a/src/snaphu.h b/src/snaphu.h
-index eef5220..53af853 100644
+index d45514b..26b2fb9 100644
--- a/src/snaphu.h
+++ b/src/snaphu.h
@@ -407,7 +407,7 @@
=====================================
man/man1/snaphu.1
=====================================
@@ -25,7 +25,8 @@ theoretical foundations are discussed in the references cited below.
The most common input parameters may be given on the command line,
while many other twiddle parameters are handled via the \fB\-f\fR
option and configuration files. At the very least, the name of a
-wrapped-phase input file and its line length must be specified. Range
+wrapped-phase input file and its line length must be specified. For
+topography interferograms, range
should increase towards the right in the interferogram, and the
flat-earth phase ramp should be removed from the input interferogram
before \fBsnaphu\fR is run. For deformation interferograms, phase
=====================================
man/snaphu_man1.html
=====================================
@@ -1,5 +1,5 @@
-<!-- Creator : groff version 1.19.2 -->
-<!-- CreationDate: Sat Feb 23 16:54:09 2019 -->
+<!-- Creator : groff version 1.22.4 -->
+<!-- CreationDate: Fri Apr 28 17:25:16 2023 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
@@ -8,16 +8,17 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
- p { margin-top: 0; margin-bottom: 0; }
- pre { margin-top: 0; margin-bottom: 0; }
- table { margin-top: 0; margin-bottom: 0; }
+ p { margin-top: 0; margin-bottom: 0; vertical-align: top }
+ pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
+ table { margin-top: 0; margin-bottom: 0; vertical-align: top }
+ h1 { text-align: center }
</style>
<title>snaphu</title>
</head>
<body>
-<h1 align=center>snaphu</h1>
+<h1 align="center">snaphu</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
@@ -35,22 +36,25 @@
<hr>
+<h2>NAME
<a name="NAME"></a>
-<h2>NAME</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em">snaphu −
phase unwrapping algorithm for SAR interferometry</p>
+<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
-<h2>SYNOPSIS</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em"><b>snaphu</b>
[options] [infile] [linelength] [options]</p>
+<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
-<h2>DESCRIPTION</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em"><b>snaphu</b>
@@ -77,11 +81,12 @@ input parameters may be given on the command line, while
many other twiddle parameters are handled via the
<b>−f</b> 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
-<b>snaphu</b> is run. For deformation interferograms, phase
-variations due to topography should be removed as well.</p>
+length must be specified. For topography interferograms,
+range should increase towards the right in the
+interferogram, and the flat-earth phase ramp should be
+removed from the input interferogram before <b>snaphu</b> is
+run. For deformation interferograms, phase variations due to
+topography should be removed as well.</p>
<p style="margin-left:11%; margin-top: 1em">Except for the
input file name and the line length, all input parameters
@@ -106,8 +111,9 @@ format is used, the input file should contain only the phase
of the interferogram (in radians from 0 to 2pi); the
magnitude may be passed with the <b>−m</b> option.</p>
+<h2>OPTIONS
<a name="OPTIONS"></a>
-<h2>OPTIONS</h2>
+</h2>
@@ -194,23 +200,22 @@ earlier instances of the <b>-C</b> option and the
configurations specified by earlier instances of the
<b>-f</b> option.</p>
-<table width="100%" border=0 rules="none" frame="void"
+<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−d</b></p> </td>
+<p><b>−d</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">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.</p></td>
+<p>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.</p></td></tr>
</table>
<p style="margin-left:11%;"><b>−e</b>
@@ -278,44 +283,41 @@ is not computed.</p>
<p style="margin-left:22%;">Print a help message
summarizing command-line options and exit.</p>
-<table width="100%" border=0 rules="none" frame="void"
+<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−i</b></p> </td>
+<p><b>−i</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Run in
-initialize-only mode. Normally, <b>snaphu</b> 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 <b>−i</b> is given, the initialization is
-written to the output and the program exits without running
-the iterative solver.</p></td>
+<p>Run in initialize-only mode. Normally, <b>snaphu</b>
+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 <b>−i</b> is given, the
+initialization is written to the output and the program
+exits without running the iterative solver.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−k</b></p> </td>
+<p><b>−k</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Keep temporary tile
-outputs. If this option is specified when <b>snaphu</b> runs
-in tile mode, the temporary directory where tile outputs are
-stored will be left in place rather than deleted. The
-tile-mode initialization of the <b>-S</b> option will also
-be left in place rather than deleted.</p></td>
+<p>Keep temporary tile outputs. If this option is specified
+when <b>snaphu</b> runs in tile mode, the temporary
+directory where tile outputs are stored will be left in
+place rather than deleted. The tile-mode initialization of
+the <b>-S</b> option will also be left in place rather than
+deleted.</p> </td></tr>
</table>
<p style="margin-left:11%;"><b>−l</b>
@@ -361,24 +363,22 @@ input data are treated as masked areas as well. Areas near
the edges of the input may also be masked via options in a
configuration file.</p>
-<table width="100%" border=0 rules="none" frame="void"
+<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−n</b></p> </td>
+<p><b>−n</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Run in
-no-statistical-costs mode. If the <b>−i</b> or
-<b>−p</b> options are given, <b>snaphu</b> will not
+<p>Run in no-statistical-costs mode. If the <b>−i</b>
+or <b>−p</b> options are given, <b>snaphu</b> will not
use statistical costs. Information from a weight file
-(<b>−w</b> option) will still be used if given.</p></td>
+(<b>−w</b> option) will still be used if given.</p></td></tr>
</table>
<p style="margin-left:11%;"><b>−o</b>
@@ -406,117 +406,109 @@ are used, but the solution will probably be more accurate
than one generated from a transform-based least-squares
algorithm.</p>
-<table width="100%" border=0 rules="none" frame="void"
+<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−q</b></p> </td>
+<p><b>−q</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Run in
-quantify-only mode. The input data are assumed to be
-unwrapped already, and the total cost of this solution is
+<p>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 <b>−u</b> option for allowable file formats.</p></td>
+the <b>−u</b> option for allowable file formats.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−s</b></p> </td>
+<p><b>−s</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Run in
-smooth-solution mode. The problem statistics 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.</p></td>
+<p>Run in smooth-solution mode. The problem statistics 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.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−S</b></p> </td>
+<p><b>−S</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Do single-tile
-re-optimization after tile-mode initialization. If this
-option is specified, <b>snaphu</b> will run in tile mode to
-generate an unwrapped solution, which is then used as the
-initialization to a single-tile optimization that produces
-the final unwrapped output. The tile-mode initialization may
-itself be initialized by the MST or MCF algorithms (or an
-input unwrapped phase file) as normal. This option is
-equivalent to running an instance of <b>snaphu</b> in tile
-mode, then running another instance of <b>snaphu</b> taking
-the tile-mode output as an unwrapped input via the <b>-u</b>
-option. Tile parameters must be specified when using this
-option. This approach is often faster than unwrapping an
-interferogram as a single tile from an MST initialization,
-especially if multiple processors are used.</p></td>
+<p>Do single-tile re-optimization after tile-mode
+initialization. If this option is specified, <b>snaphu</b>
+will run in tile mode to generate an unwrapped solution,
+which is then used as the initialization to a single-tile
+optimization that produces the final unwrapped output. The
+tile-mode initialization may itself be initialized by the
+MST or MCF algorithms (or an input unwrapped phase file) as
+normal. This option is equivalent to running an instance of
+<b>snaphu</b> in tile mode, then running another instance of
+<b>snaphu</b> taking the tile-mode output as an unwrapped
+input via the <b>-u</b> option. Tile parameters must be
+specified when using this option. This approach is often
+faster than unwrapping an interferogram as a single tile
+from an MST initialization, especially if multiple
+processors are used.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−t</b></p> </td>
+<p><b>−t</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Run in topography
-mode. The problem statistics and resulting cost functions
-are based on the assumption that the true unwrapped phase
-represents surface elevation. This is the default.</p></td>
+<p>Run in topography mode. The problem statistics and
+resulting cost functions are based on the assumption that
+the true unwrapped phase represents surface elevation. This
+is the default.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−u</b></p> </td>
+<p><b>−u</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Assume that the
-input file is unwrapped rather than wrapped. The algorithm
-makes iterative improvements to this solution instead of
-using an initialization routine. The input file may be in
-the formats 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.</p></td>
+<p>Assume that the input file is unwrapped rather than
+wrapped. The algorithm makes iterative improvements to this
+solution instead of using an initialization routine. The
+input file may be in the formats 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.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
-
-<p style="margin-top: 1em" valign="top"><b>−v</b></p> </td>
+<p><b>−v</b></p></td>
<td width="8%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Run in verbose
-mode. Extra information on the algorithm’s progress is
-printed to the standard output.</p></td>
+<p>Run in verbose mode. Extra information on the
+algorithm’s progress is printed to the standard
+output.</p> </td></tr>
</table>
<p style="margin-left:11%;"><b>−w</b>
@@ -602,39 +594,35 @@ multiple times.</p>
<p style="margin-left:22%;">Dump all sorts of intermediate
arrays to files.</p>
-<table width="100%" border=0 rules="none" frame="void"
+<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="7%">
-
-<p style="margin-top: 1em" valign="top"><b>−−mst</b></p> </td>
+<p><b>−−mst</b></p></td>
<td width="4%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">Use a minimum
-spanning tree (MST) algorithm for the initialization. This
-is the default.</p></td>
+<p>Use a minimum spanning tree (MST) algorithm for the
+initialization. This is the default.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="7%">
-
-<p style="margin-top: 1em" valign="top"><b>−−mcf</b></p> </td>
+<p><b>−−mcf</b></p></td>
<td width="4%"></td>
<td width="78%">
-<p style="margin-top: 1em" valign="top">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.</p> </td>
+<p>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.</p></td></tr>
</table>
<p style="margin-left:11%;"><b>−−nproc</b>
@@ -686,8 +674,9 @@ exist, and it is removed at the end of the run unless the
<b>-k</b> or <b>−−assemble</b> options are
specified.</p>
+<h2>FILE FORMATS
<a name="FILE FORMATS"></a>
-<h2>FILE FORMATS</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em">The formats of
@@ -731,8 +720,9 @@ images.</p>
<p style="margin-left:22%;">The file contains data for only
one channel or array, and the data are purely real.</p>
+<h2>EXAMPLES
<a name="EXAMPLES"></a>
-<h2>EXAMPLES</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em">Unwrap a
@@ -848,8 +838,9 @@ two processors:</p>
wrappedfile 1024 -f configfile \ <br>
--tile 3 4 30 30 --nproc 2</p>
+<h2>HINTS AND TIPS
<a name="HINTS AND TIPS"></a>
-<h2>HINTS AND TIPS</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em">The program may
@@ -892,8 +883,9 @@ after optimization.</p>
be run in initialize-only (<b>−i</b>) mode for quick
down-and-dirty MST or MCF solutions.</p>
+<h2>SIGNALS
<a name="SIGNALS"></a>
-<h2>SIGNALS</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em">Once the
@@ -906,16 +898,18 @@ 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.</p>
+<h2>EXIT STATUS
<a name="EXIT STATUS"></a>
-<h2>EXIT STATUS</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em">Upon successful
termination, the program exits with code 0. Errors result in
exit code 1.</p>
+<h2>FILES
<a name="FILES"></a>
-<h2>FILES</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em">The following
@@ -940,8 +934,9 @@ command line, default parameters may be read from a
system-wide configuration file if such a file is named when
the program is compiled.</p>
+<h2>BUGS
<a name="BUGS"></a>
-<h2>BUGS</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em">The
@@ -985,8 +980,9 @@ capability is built into the code and can be enabled from a
configuration file, but this functionality is experimental
and not well tested.</p>
+<h2>REFERENCES
<a name="REFERENCES"></a>
-<h2>REFERENCES</h2>
+</h2>
<p style="margin-left:11%; margin-top: 1em">C. W. Chen and
=====================================
man/snaphu_man1.txt
=====================================
@@ -1,6 +1,4 @@
-snaphu(1) snaphu(1)
-
-
+snaphu(1) General Commands Manual snaphu(1)
NAME
snaphu - phase unwrapping algorithm for SAR interferometry
@@ -9,431 +7,433 @@ SYNOPSIS
snaphu [options] [infile] [linelength] [options]
DESCRIPTION
- snaphu is a statistical-cost network-flow algorithm for phase unwrap-
- ping. Given an input interferogram and other observable data, snaphu
- attempts to compute congruent phase-unwrapped solutions that are maxi-
- mally 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) interfero-
- gram 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 the syntax and usage of snaphu. Its theo-
- retical foundations are discussed in the references cited below.
-
- The most common input parameters may be given on the command 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 topog-
- raphy should be removed as well.
-
- Except for the input file name and the line length, all input parame-
- ters take default values if not specified. However, these parameters
- should be customized whenever possible since the accuracy of the solu-
- tion depends on how well the statistics of the estimation problem are
- modeled. To avoid poor-quality solutions, users are strongly encour-
- aged to provide their best estimates of the relevant problem parame-
- ters. Parameters are set in the order in which they are given on the
- command line, so multiple configuration files or options may be given,
- with later values 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 from 0 to 2pi) of the inter-
- ferogram should be in the first and second channels of the file,
- respectively. If the FLOAT_DATA format is used, the input file should
+ 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 the syntax and usage of snaphu. Its
+ theoretical foundations are discussed in the references cited below.
+
+ The most common input parameters may be given on the command 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. For topography
+ interferograms, 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 configuration files or options
+ may be given, with later values 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 from 0 to 2pi) 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 from 0 to 2pi);
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 interferogram 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 inter-
- ferogram 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 interfero-
- gram is used as the average amplitude, and no coherence estimate
- is formed. Note that the magnitude of the interferogram 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
- interferogram, and also coregistered to it.
+ Read brightness data from the file ampfile. The file should
+ contain the amplitudes (not powers) of the two individual SAR
+ images forming the interferogram if the formats ALT_SAMPLE_DATA
+ (default) or ALT_LINE_DATA are used. It should contain an
+ average 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
+ interferogram 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 interferogram, 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
+ 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 topog-
- raphy mode.
+ 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. Consequently, 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 esti-
- mate is formed from the available data if possible. Otherwise,
- a uniform default coherence is assumed for the entire interfero-
- gram. 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.
+ Read correlation data from the file corrfile. The correlation
+ data should be the same size as, and registered to, the input
+ interferogram. Consequently, 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.
-C configstr
- Parse the string configstr as if it were a line from a configu-
- ration file containing a keyword-value pair (see the -f option).
- Configuration lines generally have whitespace between the key-
- word and the value, so configstr will usually need to be sur-
- rounded by quotation marks on a command line so that the shell
- does not split it into separate arguments (snaphu itself does
- not require or allow quotation marks, however). The syntax for
- how quotation marks are handled is defined by the shell. Multi-
- ple instances of the -C option may be used in order to specify
- multiple configuration inputs. Later instances of the -C option
- take precedence over both earlier instances of the -C option and
- the configurations specified by earlier instances of the -f
- option.
-
- -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 ele-
- vation.
+ Parse the string configstr as if it were a line from a
+ configuration file containing a keyword-value pair (see the -f
+ option). Configuration lines generally have whitespace between
+ the keyword and the value, so configstr will usually need to be
+ surrounded by quotation marks on a command line so that the
+ shell does not split it into separate arguments (snaphu itself
+ does not require or allow quotation marks, however). The syntax
+ for how quotation marks are handled is defined by the shell.
+ Multiple instances of the -C option may be used in order to
+ specify multiple configuration inputs. Later instances of the
+ -C option take precedence over both earlier instances of the -C
+ option and the configurations specified by earlier instances of
+ the -f option.
+
+ -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 estimate-
- file. 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 density function of the random
- variable. If the formats ALT_LINE_DATA (default) or ALT_SAM-
- PLE_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 format may also be used.
+ 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 density 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 format 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
- contains 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 speci-
- fied 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
+ contains 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
+ 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
+ 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 con-
- nected component file is composed of unsigned characters by
+ for this option can be set in the configuration file. The
+ connected component file is composed of unsigned characters by
default, with all pixels of the same value belonging to the same
connected 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
+ 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
+ are computed for forming the mask, but a new unwrapped solution
is not computed.
-h, --help
- Print a help message summarizing command-line options and exit.
+ 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
+ -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
+ the initialization is written to the output and the program
exits without running the iterative solver.
- -k Keep temporary tile outputs. If this option is specified when
- snaphu runs in tile mode, the temporary directory where tile
- outputs are stored will be left in place rather than deleted.
- The tile-mode initialization of the -S option will also be left
+ -k Keep temporary tile outputs. If this option is specified when
+ snaphu runs in tile mode, the temporary directory where tile
+ outputs are stored will be left in place rather than deleted.
+ The tile-mode initialization of the -S option will also be left
in place rather than deleted.
-l logfile
- Log all runtime parameters and some other environment informa-
- tion into the specified file. The log file is a text file in
- the same format as a configuration file.
+ Log all runtime parameters and some other environment
+ information into the specified file. The log file is a text
+ file in the same format as a configuration file.
-m magfile
Read interferogram magnitude data from the specified 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
+ 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
+ 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. Areas where the magnitude is zero are treated as
+ 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. Areas where the magnitude is zero are treated as
masked areas (see the -M option).
-M bytemaskfile
- Read a byte mask from the specified file. The mask file should
- be the same size as the input array to be unwrapped. The mask
- should have the binary (not ASCII) value 0 where pixels of the
- input array are to be ignored during the primary optimization
- stage of the program. Values elsewhere should be binary 1.
- Masking is not applied until after the initialization stage of
+ Read a byte mask from the specified file. The mask file should
+ be the same size as the input array to be unwrapped. The mask
+ should have the binary (not ASCII) value 0 where pixels of the
+ input array are to be ignored during the primary optimization
+ stage of the program. Values elsewhere should be binary 1.
+ Masking is not applied until after the initialization stage of
snaphu. Masked areas are treated as areas in which the solution
- phase value is irrelevant to the solution cost. The magnitude
- of the interferogram is set to zero in masked areas in the out-
- put file. Areas with zero magnitude in the input data are
- treated as masked areas as well. Areas near the edges of the
+ phase value is irrelevant to the solution cost. The magnitude
+ of the interferogram is set to zero in masked areas in the
+ output file. Areas with zero magnitude in the input data are
+ treated as masked areas as well. Areas near the edges of the
input may also be masked via options in a configuration file.
- -n Run in no-statistical-costs mode. If the -i or -p options are
- given, snaphu will not use statistical costs. Information from
+ -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 a 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 chan-
- nel, while the interferogram magnitude is written into the first
- channel. The format FLOAT_DATA may also be used.
+ Write the unwrapped output to a 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. More-
- over, congruence is enforced within the solver routine, not as a
- post-optimization processing step. Therefore, if p=2, for exam-
- ple, least-squares cost functions are used, but the solution
- will probably be more accurate than one generated from a trans-
- form-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 calcu-
- lated and printed. The unwrapped phase is wrapped assuming con-
- gruence for the cost calculation. Round-off errors may limit
- the precision of the quantified cost. See the -u option for
+ 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 statistics and result-
- ing cost functions are based on the assumption that the true
- unwrapped phase represents a generic surface with no discontinu-
- ities. This is the same as deformation mode with the DEFOMAX
- parameter set to zero.
+ -s Run in smooth-solution mode. The problem statistics 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.
- -S Do single-tile re-optimization after tile-mode initialization.
- If this option is specified, snaphu will run in tile mode to
- generate an unwrapped solution, which is then used as the ini-
- tialization to a single-tile optimization that produces the
+ -S Do single-tile re-optimization after tile-mode initialization.
+ If this option is specified, snaphu will run in tile mode to
+ generate an unwrapped solution, which is then used as the
+ initialization to a single-tile optimization that produces the
final unwrapped output. The tile-mode initialization may itself
- be initialized by the MST or MCF algorithms (or an input
- unwrapped phase file) as normal. This option is equivalent to
+ be initialized by the MST or MCF algorithms (or an input
+ unwrapped phase file) as normal. This option is equivalent to
running an instance of snaphu in tile mode, then running another
- instance of snaphu taking the tile-mode output as an unwrapped
+ instance of snaphu taking the tile-mode output as an unwrapped
input via the -u option. Tile parameters must be specified when
- using this option. This approach is often faster than unwrap-
- ping an interferogram as a single tile from an MST initializa-
- tion, especially if multiple processors are used.
+ using this option. This approach is often faster than
+ unwrapping an interferogram as a single tile from an MST
+ initialization, especially if multiple processors are used.
- -t Run in topography mode. The problem statistics and resulting
- cost functions are based on the assumption that the true
- unwrapped phase represents surface elevation. This is the
+ -t Run in topography mode. The problem statistics and resulting
+ cost functions are based on the assumption that the true
+ unwrapped phase represents surface elevation. This is the
default.
- -u Assume that the input file is unwrapped rather than wrapped.
- The algorithm makes iterative improvements to this solution
- instead of using an initialization routine. The input file may
- be in the formats 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.
+ -u Assume that the input file is unwrapped rather than wrapped.
+ The algorithm makes iterative improvements to this solution
+ instead of using an initialization routine. The input file may
+ be in the formats 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
+ -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
+ Read external, scalar weights from file weightfile. The
weights, which should be positive short integers, are applied to
- whichever cost functions are used. There is one weight value
- for each arc in the network, so weightfile should be the con-
- catenation of raster horizontal-flow and vertical-flow arc
- weights. Thus, for an N row by M column interferogram, weight-
- file 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.
+ whichever cost functions are used. There is one weight value
+ for each arc in the network, so weightfile should be the
+ concatenation of raster horizontal-flow and vertical-flow arc
+ weights. Thus, for an N row by M column interferogram,
+ 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
+ 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
+ Similar to the --aa option, but power data are read from the
specified files.
--assemble
Assemble the tile-mode temporary files from a previous tile-mode
- run of snaphu, possibly with different secondary optimization
- parameters, to produce a new unwrapped solution. The tile
- directory name must be specified with the --tiledir option.
- Most configuration options (from the command line and any con-
- figuration files) must be specified similar to the previous run,
- including the output file name from which the names of temporary
- tile files are derived. The previous output file may hence be
- overwritten by the new output file. This option is useful if
- the user wishes to modify tile-assembly parameters without
- unwrapping the individual tiles over again.
+ run of snaphu, possibly with different secondary optimization
+ parameters, to produce a new unwrapped solution. The tile
+ directory name must be specified with the --tiledir option.
+ Most configuration options (from the command line and any
+ configuration files) must be specified similar to the previous
+ run, including the output file name from which the names of
+ temporary tile files are derived. The previous output file may
+ hence be overwritten by the new output file. 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
+ 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 control whether snaphu runs in topogra-
- phy, deformation, or smooth-solution mode; the latter two must
- be specified explicitly even if costfile was generated while
- running in those modes.
+ Read statistical cost arrays from file costfile. This file
+ should be in the format written by the --costoutfile option.
+ The cost file does not control whether snaphu runs in
+ topography, deformation, or smooth-solution mode; the latter two
+ must be specified explicitly even if costfile was generated
+ 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 gener-
- ating statistical costs if the same costs are used multiple
+ 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 initializa-
- tion. This is the default.
+ --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.
+ --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 opti-
- mal.
+ 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 par-
- allel; at most n processes will run concurrently. Forking is
+ new process for each tile so that tiles can be unwrapped in
+ parallel; at most n processes will run concurrently. Forking is
done before data are read. The standard output streams of child
- processes are directed to log files in the temporary tile direc-
- tory.
+ 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 interfero-
- gram. 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, coher-
- ence, etc.) are assumed to be the same size as the input phase
- file. All output files are nrow by 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 interferogram is
- partitioned into ntilerow by ntilecol tiles, each of which is
+ Unwrap the interferogram in tile mode. The interferogram 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
+ 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
- (see the --tiledir and -k options). Tiles can be unwrapped in
+ (see the --tiledir and -k options). Tiles can be unwrapped in
parallel (see the --nproc option).
--tiledir dirname
- Use dirname as the name of the directory in which temporary
- tile-model outputs are written and/or read. The directory is
- created if it does not exist, and it is removed at the end of
+ Use dirname as the name of the directory in which temporary
+ tile-model outputs are written and/or read. The directory is
+ created if it does not exist, and it is removed at the end of
the run unless the -k or --assemble options are specified.
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 in row-major order
- (across then down, with the column index varying faster than the row
- index). Regardless of the file format, all input data arrays should
- have the same number of samples in width and depth and should be coreg-
- istered to one another. Note that weight files and cost files have
- their own formats. The allowable formats for other data files are
+ 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 in row-major order
+ (across then down, with the column index varying faster than the row
+ index). 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 imagi-
- nary (quadrature) components of complex data samples. The spec-
- ified line length should be the number of complex samples (pairs
- of real and imaginary samples) per line.
+ 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
+ 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, rmg, or line-interleaved format.
ALT_SAMPLE_DATA
- Alternating samples correspond to purely real samples from two
- separate arrays. This format is sometimes used for the ampli-
- tudes of the two SAR images.
+ Alternating samples correspond to purely real samples 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
+ 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
+ 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 information from the
+ 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
+ are generated 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 generating it from the interfero-
- gram and amplitude data:
+ Unwrap the interferogram as above, but read correlation information
+ from the file ``corrfile'' instead of generating 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 parame-
- ters are read from a configuration file, and verbose output is dis-
- played:
+ 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
@@ -445,79 +445,78 @@ EXAMPLES
snaphu -v -f configfile wrappedfile 1024
- Unwrap the same interferogram, but use only the MST initialization
+ Unwrap the same interferogram, but use only the MST initialization
(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 initializa-
- tion to the modified network-simplex solver:
+ 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
+ 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 ini-
- tialization:
+ Unwrap the interferogram as above, but use the MCF algorithm for
+ initialization:
snaphu -f configfile wrappedfile 1024 --mcf
- Unwrap the interferogram once again, but first flatten it with the
+ 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 interferogram with the given
+ The following assumes that the wrapped input interferogram measures
+ deformation, not topography. Unwrap the interferogram with the given
correlation data:
snaphu -d wrappedfile 1024 -c corrfile
- Unwrap the input interferogram by minimizing the unweighted congruent
+ 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 configuration file, using two proces-
- sors:
+ Unwrap the interferogram as a three-by-four set of tiles that overlap
+ by 30 pixels, with the specified configuration 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 configuration file (via the -f option).
+ 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 -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
+ 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 disconti-
- nuities, 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 discon-
- tinuities, 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 -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
+ 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 -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-
@@ -525,80 +524,80 @@ HINTS AND TIPS
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 immedi-
- ately. If a hangup signal is received, the program dumps its current
- solution then continues to execute normally.
+ 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.
EXIT STATUS
- Upon successful termination, the program exits with code 0. Errors
+ 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
+ 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
+ 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
+ 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 com-
- piled.
+ 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 mod-
- eled that well in the cost functions for topography mode.
+ 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
+ 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
+ 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 poten-
- tials (incost and outcost) do not overflow their integer data types.
+ There is no error checking that ensures that the network node
+ potentials (incost and outcost) do not overflow their integer data
+ types.
- Automatic flow clipping is built into the MST initialization, but it
+ 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 snaphu in Lp mode. Note that snaphu enforces congruence as part
- of the problem formulation, however, not as a post-optimization pro-
- cessing step.
+ 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.
- A tree pruning capability is built into the code and can be enabled
- from a configuration file, but this functionality is experimental and
+ A tree pruning capability is built into the code and can be enabled
+ from a configuration file, but this functionality is experimental and
not well tested.
REFERENCES
- C. W. Chen and H. A. Zebker, ``Two-dimensional phase unwrapping with
- use of statistical models for cost functions in nonlinear optimiza-
- tion,'' Journal of the Optical Society of America A, 18, 338-351
- (2001).
+ 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
+ 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 interfer-
- ograms: Statistical segmentation and generalized network models,'' IEEE
- Transactions on Geoscience and Remote Sensing, 40, 1709-1719 (2002).
-
-
+ C. W. Chen and H. A. Zebker, ``Phase unwrapping for large SAR
+ interferograms: Statistical segmentation and generalized network
+ models,'' IEEE Transactions on Geoscience and Remote Sensing, 40,
+ 1709-1719 (2002).
snaphu(1)
=====================================
src/snaphu.c
=====================================
@@ -416,7 +416,7 @@ int UnwrapTile(infileT *infiles, outfileT *outfiles, paramT *params,
long nflow, ncycle, mostflow, nflowdone;
long candidatelistsize, candidatebagsize;
long isource, nsource;
- long nincreasedcostiter;
+ long nnondecreasedcostiter;
long *nconnectedarr;
int *nnodesperrow, *narcsperrow;
short **flows, **mstcosts;
@@ -546,7 +546,7 @@ int UnwrapTile(infileT *infiles, outfileT *outfiles, paramT *params,
&narcsperrow,nrow,ncol,¬firstloop,&totalcost,params);
oldtotalcost=totalcost;
mintotalcost=totalcost;
- nincreasedcostiter=0;
+ nnondecreasedcostiter=0;
/* regrow regions with -G parameter */
if(params->regrowconncomps){
@@ -654,9 +654,9 @@ int UnwrapTile(infileT *infiles, outfileT *outfiles, paramT *params,
fprintf(sp1,"Caution: Unexpected increase in total cost\n");
}
if(totalcost > mintotalcost){
- nincreasedcostiter++;
+ nnondecreasedcostiter++;
}else{
- nincreasedcostiter=0;
+ nnondecreasedcostiter=0;
}
}
@@ -670,9 +670,9 @@ int UnwrapTile(infileT *infiles, outfileT *outfiles, paramT *params,
/* find maximum flow on network, excluding arcs affected by masking */
mostflow=MaxNonMaskFlow(flows,mag,nrow,ncol);
- if(nincreasedcostiter>=mostflow){
+ if(nnondecreasedcostiter>=2*mostflow){
fflush(NULL);
- fprintf(sp0,"WARNING: Unexpected sustained increase in total cost."
+ fprintf(sp0,"WARNING: No overall cost reduction for too many iterations."
" Breaking loop\n");
break;
}
=====================================
src/snaphu.h
=====================================
@@ -14,7 +14,7 @@
/**********************/
#define PROGRAMNAME "snaphu"
-#define VERSION "2.0.5"
+#define VERSION "2.0.6"
#define BUGREPORTEMAIL "snaphu at gmail.com"
#ifdef PI
#undef PI
=====================================
src/snaphu_tile.c
=====================================
@@ -1207,7 +1207,7 @@ int AssembleTiles(outfileT *outfiles, paramT *params,
long nrow, ncol, prevnrow, prevncol, nextnrow, nextncol;
long n, ncycle, nflowdone, nflow, candidatelistsize, candidatebagsize;
long nnodes, maxnflowcycles, arclen, narcs, sourcetilenum, flowmax;
- long nincreasedcostiter;
+ long nnondecreasedcostiter;
long *totarclens;
long ***scndrycosts;
double avgarclen;
@@ -1419,7 +1419,7 @@ int AssembleTiles(outfileT *outfiles, paramT *params,
NULL,NULL,NULL,NULL,ntiles,0,¬firstloop,&totalcost,params);
oldtotalcost=totalcost;
mintotalcost=totalcost;
- nincreasedcostiter=0;
+ nnondecreasedcostiter=0;
/* set pointers to functions for nongrid secondary network */
CalcCost=CalcCostNonGrid;
@@ -1468,10 +1468,10 @@ int AssembleTiles(outfileT *outfiles, paramT *params,
fflush(NULL);
fprintf(sp1,"Caution: Unexpected increase in total cost\n");
}
- if(totalcost>mintotalcost){
- nincreasedcostiter++;
+ if(totalcost>=mintotalcost){
+ nnondecreasedcostiter++;
}else{
- nincreasedcostiter=0;
+ nnondecreasedcostiter=0;
}
}
@@ -1483,10 +1483,10 @@ int AssembleTiles(outfileT *outfiles, paramT *params,
nflowdone=1;
}
- /* break if total cost increase is sustained */
- if(nincreasedcostiter>=params->maxflow){
+ /* break if lack of total cost reduction is sustained */
+ if(nnondecreasedcostiter>=2*params->maxflow){
fflush(NULL);
- fprintf(sp0,"WARNING: Unexpected sustained increase in total cost."
+ fprintf(sp0,"WARNING: No overall cost reduction for too many iterations."
" Breaking loop\n");
break;
}
View it on GitLab: https://salsa.debian.org/debian-gis-team/snaphu/-/compare/599672fa6d554853cd06a9fee695a42ded408487...897eefe24f42f11b01b29535dca103a8ae99281f
--
View it on GitLab: https://salsa.debian.org/debian-gis-team/snaphu/-/compare/599672fa6d554853cd06a9fee695a42ded408487...897eefe24f42f11b01b29535dca103a8ae99281f
You're receiving this email because of your account on salsa.debian.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/pkg-grass-devel/attachments/20230611/a9ac3946/attachment-0001.htm>
More information about the Pkg-grass-devel
mailing list