| Environments | PYTHON :: EASI :: MODELER |
| Quick links | Description :: Parameters :: Parameter descriptions :: Details :: Examples :: Algorithm :: Acknowledgements :: References :: Related |
| Back to top |
| Back to top |
insunwrap(fili, dbic, mask, maskfile, filo, initalgo, procmode, tilesize, interp, minthres)
| Name | Type | Caption | Length | Value range |
|---|---|---|---|---|
| FILI* | str | Database input file name | 1 - | |
| DBIC* | List[int] | Database input channel list | 1 - 1 | |
| MASK | List[int] | Area mask (bitmap or vector) | 0 - 1 | |
| MASKFILE | str | Mask file | 0 - | |
| FILO* | str | Database output file name | 1 - | |
| INITALGO* | str | Cost-initialization algorithm | 3 - 3 | MST| MCF |
| PROCMODE* | str | Processing mode | 1 - 6 | RUN| PREP| FINISH |
| TILESIZE | List[int] | Tile size: X,Y (pixels) | 0 - 2 | Default: 2000,2000 |
| INTERP | str | Interpolate values over mask | 0 - 3 | NO|YES Default: NO |
| MINTHRES | List[float] | Minimum coherence threshhold override | 0 - 1 | Default: 0.3 |
| Back to top |
FILI
The name of the PCIDSK file containing the interferometric data.
DBIC
The input layer of the interferogram to unwrap. The channel specified must be complex-valued and have the layer's InSARContent metadata tag set to either "TopographicInterferogram" or "DeformationInterferogram".
MASK
The areas of the interferogram to be masked out before unwrapping with SNAPHU. The masked areas may be filled by setting INTERP to "Yes"
You can define masked areas using either a bitmap or vector polygons.
All the pixels within the specified bitmap segment having a value of one define the area to mask.
If a polygon vector mask is specified; identify the polygon segment to be used. The pixels within the polygons will be masked.
Note: In the event the bitmap and vector polygon segments share the same segment number, the bitmap segment is selected in preference over the vector segment.
If you specify a mask, but not a mask file, the mask segment from the input file is used.
MASKFILE
The name of the file containing the mask, which you can specify as an option. If you specify a mask, but not a mask file, the mask from the input file is used. If a MASKFILE is explicitly specified; you must identify a MASK segment.
FILO
The name of the PCIDSK (.pix) output file which contains the unwrapped deformation (for deformation mode) or elevation (for topographic mode). In deformation mode, the output represents surface displacements, in meters and is projected into the radar line-of-sight direction. In topographic mode, the output contains terrain-elevation (meters) relative to the WGS-84 ellipsoid. The output is in slant range projection.
In RUN and PREP processing modes (see the description of PROCMODE), the file must not already exist. In FINISH mode, the output file must already exist (after running RUN and PREP modes).
When the output file is created, all segments are moved from the input file to the output.
INITALGO
The SNAPHU cost-initialization algorithm to use, either minimum spanning tree (MST) or minimum cost flow (MCF). For more information about the algorithms, see the SNAPHU documentation included with your installation.PROCMODE
The processing mode for phase unwrapping.Important: Any changes to the SNAPHU parameters must not modify the names of the input and output files, their line length, or formats. The processing parameters in FINISH mode must be the same as in the previous run of INSUNWRAP.
TILESIZE
Specifies the size of the multi-look tile (in pixels) to be generated prior to unwrapping by SNAPHU. The tile size can be specified independently for the pixel and line directions. If a single value is given, the size of the tile will be identical in the pixel and line direction. The tile size must be a positive integer larger than the minimum required by SNAPHU (approximately 160). If you wish to unwrap the interferogram as a single tile, any value exceeding the size of the file will be acceptable. The default tile size is 2000 x 2000.INTERP
When a mask is specified and INTERP is set to NO or left blank (default), the output file will contain "NO_DATA_VALUE" for all pixels within the masked area or below the coherence level as specified by MINTHRES.
When the INTERP parameter is set to YES the masked pixels and low coherence pixels are filled in with interpolated values.
MINTHRES
Prior to unwrapping, pixels with a coherence value below the specified minimum threshold will be replaced with interpolated values from surrounding pixels with coherence above the threshold. The specified value must be between zero and one. The default value is 0.3| Back to top |
The unwrapped phase values are converted to displacement values in meters for deformation mode, and elevation in meters for topographic mode.
The process sets up the input files and parameters, calls SNAPHU to unwrap, and then writes the result to the output file. If a mask is used, it is applied to the input files generated for SNAPHU.
The process removes the low coherence values and the masked values with interpolated values. The interpolated values are down sampled to the specified tile size and unwrapped by SNAPHU. The unwrapped phase is up sampled back to the original file size and adjusted to the original phase with the appropriate number of cycles. The masked areas and low coherence areas are set back to NO DATA if INTERP is set to "NO".
The unwrapped phase is converted from interferometric cycles to meters and written to the output file. The content of the output file depends on the InSARContent metadata tag, which is updated by the INSTOPO algorithm.
In the SNAPHU deformation mode, the real-valued output contains surface displacements, in meters. The values represent the displacement in the direction of the radar line-of-sight (LOS), where positive values are nominally up; that is, toward the radar. In the SNAPHU topographic mode, the real-valued channel contains elevation values in meters, relative to the WGS-84 ellipsoid.
The interferogram to unwrap must first be prepared in a manner consistent with the SNAPHU unwrapping mode. The flat-Earth correction must always be applied prior to running INSUNWRAP. For information about applying a flat-Earth correction, see the INSTOPO algorithm under Related functions.
Before you can run insunwrap, you must have downloaded and installed SNAPHU, a statistical-cost, network-flow algorithm for phase unwrapping.
| Back to top |
The following example is based on the premise that the topographic effects have been removed from the interferogram, and that it now represents deformation. The selected unwrapping algorithm is minimum spanning tree (MST). The original data will be multi-looked to the default tile size of 2000 x 2000. Pixels with a coherence lower than the default (0.3) and the pixels within the polygon regions of segment 2 of the MASKFILE will be set to NO DATA
from pci.insunwrap import insunwrap
fili = r"C:\MyProject\Wrapped_Deformation_Interferogram.pix"
dbic = [1]
mask = [2]
maskfile = "C:\MyProject\WaterMask.pix"
filo = r"C:\MyProject\Unwrapped_Deformation_Interferogram.pix"
initalgo = "MST"
procmode = "RUN"
tilesize = []
interp = "NO"
minthres = []
insunwrap(fili, dbic, mask, maskfile, filo, initalgo, procmode, tilesize, interp, minthres)
The following example is similar to Example 1, except that it is based on the premise that you want to examine (and possibly modify) the configuration file before manually running SNAPHU.
from pci.insunwrap import insunwrap
fili = r"C:\MyProject\Wrapped_Deformation_Interferogram.pix"
dbic = [1]
mask = [2]
maskfile = "C:\MyProject\WaterMask.pix"
filo = r"C:\MyProject\Unwrapped_Deformation_Interferogram.pix"
initalgo = "MST"
procmode = "PREP"
tilesize = []
interp = "NO"
minthres = []
insunwrap(fili, dbic, mask, maskfile, filo, initalgo, procmode, tilesize, interp, minthres)
The following example is based on the premise that an interferogram is available in channel 4 of the input file. The fourth channel contains topographic fringes; that is, no DEM was specified in INSTOPO, and the selected unwrapping algorithm is minimum cost function (MCF). The relative elevation, in meters, is written to the output file. The size of the multi-look tile is 2000 x 1000. Pixels with coherence less than 0.25 will be interpolated.
from pci.insunwrap import insunwrap
fili = r"C:\MyProject\Wrapped_Deformation_Interferogram.pix"
dbic = [4]
mask = []
maskfile = ""
filo = r"C:\MyProject\Unwrapped_Deformation_Interferogram.pix"
initalgo = "MFC"
procmode = "RUN"
tilesize = [2000,1000]
interp = "NO"
minthres = [0.25]
insunwrap(fili, dbic, mask, maskfile, filo, initalgo, procmode, tilesize, interp, minthres)
| Back to top |
INSUNWRAP prepares the configuration file required by SNAPHU by using metadata extracted from the input PCIDSK file. The low coherence and masked areas are replaced by interpolated values and subsequently down sampled to the requested tile size. The unwrapped result is up sampled to the original file size and adjusted to match the primary phase of the original. The unwrapped phase is then converted to relative topography or deformation as required. In RUN mode, the configuration file is passed to SNAPHU for phase unwrapping. The output from SNAPHU is rewritten to the original projection of the PCIDSK file. If the PREP mode is specified, you can modify the SNAPHU configuration file prior to running SNAPHU. To reformat the output from SNAPHU in PREP mode back to PSIDSK format, you must run INSUNWRAP in FINISH mode.
For more information about the algorithms used by SNAPHU, refer to the publications listed under References.
| Back to top |
The PCI Interferometric SAR (InSAR) project was funded in part by the Canadian Space Agency under the Earth Observation Application Development Program (EOADP) contract (9F043-130644/006/MTB), Application Development for Environmental Monitoring and Remediation.
To unwrap the interferogram, the insunwrap algorithm runs an unlicensed version of SNAPHU that is compiled independently. The copyright statement for the SNAPHU code, and the minimum-cost-flow solver CS2 that SNAPHU uses, is as follows:
Copyright
---------
Copyright 2002 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
hereby granted without fee, provided that the above copyright notice
appear in all copies and that both that copyright notice and this
permission notice appear in supporting documentation, and that the
name of the copyright holders be used in advertising or publicity
pertaining to distribution of the software with specific, written
prior permission, and that no fee is charged for further distribution
of this software, or any modifications thereof. The copyright holder
makes no representations about the suitability of this software for
any purpose. It is provided "as is" without express or implied
warranty.
THE COPYRIGHT HOLDER DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA, PROFITS, QPA OR GPA, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
The parts of this software derived from the CS2 minimum cost flow
solver written by A. V. Goldberg and B. Cherkassky are governed by the
terms of the copyright holder of that software. Permission has been
granted to use and distrubute that software for strictly noncommercial
purposes as part of this package, provided that the following
copyright notice from the original distribution and URL accompany the
software:
COPYRIGHT C 1995 IG Systems, Inc. Permission to use for
evaluation purposes is granted provided that proper
acknowledgments are given. For a commercial licence, contact
[email protected].
This software comes with NO WARRANTY, expressed or implied. By way
of example, but not limitation, we make no representations of
warranties of merchantability or fitness for any particular
purpose or that the use of the software components or
documentation will not infringe any patents, copyrights,
trademarks, or other rights.
| Back to top |
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, vol. 17, pp. 401-414 (2000).
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, vol. 18, pp. 338-351 (2001).
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, vol. 40, pp. 1709-1719 (2002).
© PCI Geomatics Enterprises, Inc.®, 2024. All rights reserved.