SARvey - survey with SAR¶
Open-source InSAR time series analysis software developed within the project SAR4Infra. SARvey aims to analyze InSAR displacement time series for engineering applications.
Documentation¶
The documentation with installation instructions, processing steps, and examples with a demo dataset can be found at: https://luhipi.github.io/sarvey/docs/
Status¶
See also the latest coverage report and the pytest HTML report.
License¶
SARvey is distributed under the GNU General Public License, version 3 (GPLv3).
The following exceptions applies:
This package uses PyMaxFlow. The core of PyMaxflows library is the C++ implementation by Vladimir Kolmogorov. It is also licensed under the GPL, but it REQUIRES that you cite [BOYKOV04] in any resulting publication if you use this code for research purposes. This requirement extends to SARvey.
Please check out the details of the license here.
How to cite¶
If you use SARvey in your research, please cite the following.
The paper describing the methodology:
Piter A, Haghshenas Haghighi M, Motagh M (2024). Challenges and Opportunities of Sentinel-1 InSAR for Transport Infrastructure Monitoring. PFG – Journal of Photogrammetry, Remote Sensing and Geoinformation Science, 92, 609-627.
The software itself. Please specify the version you use:
Piter A, Haghshenas Haghighi M, FERN.Lab, Motagh M (2024). SARvey - survey with SAR [version]. Zenodo. https://doi.org/10.5281/zenodo.12544131
If you use the PUMA method for unwrapping in your research, please cite the following publication as indicated in the license:
Boykov Y, Kolmogorov V (2004). An experimental comparison of min-cut/max- flow algorithms for energy minimization in vision. IEEE Transactions on Pattern Analysis and Machine Intelligence 26(9):1124–1137, DOI 10.1109/TPAMI.2004.60. Link to paper.
Processing overview¶
Processing workflow for using the SARvey software to derive displacement time series.
SARvey is a command-line-based software. The major steps for running SARvey are the following:
Installation
SARvey is a cross-platform python-based software and can be installed on Linux and MacOS. On Windows, SARvey is tested on Windows Subsystem for Linux (WSL) version 2. Details of installation can be found in installation instruction.
Preprocessing
The software requires a coregistered stack of SLC and the related geometry information in the MiaplPy data format. The coregistered stack of SLC can be created using an InSAR processor. Currently MiaplPy only supports ISCE. Support for GAMMA and SNAP is planned for future. After creating the coregistered stack of SLC, run the “load_data” step from Miaplpy to create the “inputs” directory which contains “slcStack.h5” and “geometryRadar.h5”. Details are explained in the preparation section
Time series analysis
Time series analysis is performed using sarvey. It consists of 5 steps (steps 0 to 4). The details of each step are explained in processing steps. The processing parameters are handled in a json config file. Visualization and export are handled by sarvey_plot and sarvey_export packages. Below are the major steps:
Go to your working directory:
cd path/to/working_dir/
Create a default config file using “-g” flag:
sarvey -f config.json 0 4 -g
Modify config.json to change path to “inputs” directory. Modify other parameters as desired.
Run all processing steps (steps 0 to 4):
sarvey -f config.json 0 4
Different processing steps are explained in processing section.
Plot the resulting displacement time series:
sarvey_plot outputs/p2_coh80_ts.h5 -t
Export the results as Shapefiles:
sarvey_export outputs/p2_coh80_ts.h5 -o outputs/shp/p2_coh80.shp
Feature overview¶
SARvey has three main components for processing, visualization, and exporting data.
sarvey performs time series analysis.
sarvey_plot plots the outputs.
sarvey_export exports InSAR time series results from to GIS data formats. The GIS data format can be visualized for example in QGIS.
It also has two components that facilitate transport infrastructure monitoring.
sarvey_mask creates mask from Shapefiles, e.g. for transport infrastructures.
sarvey_osm downloads transport infrastructure information from OSM and store as Shapefiles.
You can run each component in the command line with “-h” argument for more information about the usage. For example:
sarvey -h
SARvey supports two processing schemes:
Two-step unwrapping with atmospheric correction (default).
One-step unwrapping for a small area.
History / Changelog¶
You can find the protocol of recent changes in the SARvey package history.
We follow the principle of semantic versioning. The version number is structured as follows: MAJOR.MINOR.PATCH. You can find a description of the versioning scheme here.
Credits¶
This software was developed within the project SAR4Infra (2020-2024) with funds of the German Federal Ministry for Digital and Transport. The project consortium consists of the Institute of Photogrammetry and GeoInformation at Leibniz University Hannover, FERN.Lab (innovation and technology transfer lab of the GFZ German Research Centre for Geosciences, Potsdam), Landesamt fuer Vermessung und Geoinformation Schleswig-Holstein, and Landesbetrieb Strassenbau und Verkehr Schleswig-Holstein. The scientific and methodological development was carried out by Andreas Piter (piter@ipi.uni-hannover.de), supervised by Mahmud H. Haghighi (mahmud@ipi.uni-hannover.de) and Mahdi Motagh (motagh@gfz-potsdam.de). The FERN.Lab (fernlab@gfz-potsdam.de) contributed to the development, documentation, continuous integration, and testing of the package.
This package was created with Cookiecutter and the fernlab/cookiecutter-pypackage project template.