Moraine

Modern Radar Interferometry Environment; A simple, stupid InSAR postprocessing tool in big data era

This package provide functions for InSAR post-processing which refers as processing after SAR images co-registration and geocoding. The functions include PS/DS identification, coherence matrix estimation, phase linking etc.

Warning

Due to the heavy dependence on CuPy and CUDA, this package only works on device with Nivida GPU.

Warning

This package is under intensive development. API is subjected to change without any noticement.

Principle1

Simplicity

There is no perfect workflow that always generate satisfactory InSAR result, mostly due to decorrelation, strong atmospheric artifact and high deformation gradient. Different methods implemented in different packages need to be tried which is frustrating especially when the packages are over-encapsulated and no detailed documentations are provided. Furthermore, it brings more dirty work when users need to save intermediate data from one software and prepared them in a designated format and structure required by another software.

Moraine defines simplicity as without complex data structure and over-encapsulation. Most data in Moraine is just the basic multi-dimentional array, i.e., NumPy array or CuPy array in memory, or Zarr on disk. Instead of providing a standard workflow as StamPS and MintPy, Moraine is designed as a collection of functions that implement specific InSAR processing techniques and data manipulation infrastructure.

Modernity

Moraine strives to implement state-of-art InSAR techniques, including advanced PS/DS identification, phase linking and deep-learning-based methods.

Moraine also emphasizes performance, especially in this big data era. Most Moraine functions are implemented with well-optimized GPU code or OpenMP code. Furthermore, with the support of Dask, Moraine can be runed on multi-GPUs to further accelerate the processing, get rid of the limitation of memory and achieve asynchronous IO.

Pragmatism

Moraine is a pragmatic library rather than an ideological workflow. The large number of functions in MOraine offer free and open source implementation for many InSAR techniques. Ultimately, workflow designs are made on a case-by-case basis by the user. We provide the necessary infrastructure and your role is to be innovative!

User centrality

Whereas many InSAR packages attempt to be more user-friendly, Moraine has always been, and shall always remain user-centric. This package is intended to fill the needs of those contributing to it, rather than trying to appeal to as many users as possible. It is targeted at the proficient InSAR user, or anyone with a do-it-yourself attitude who is willing to read the documentation, and solve their own problems.

All users are encouraged to participate and contribute to this package. Reporting bugs and requesting new features by raising a Github issue is highly valued and bugs fixing, documentation improving and features implementation by make a Github pull request are very appreciated. Users can also freely ask questions, provide technical assistance to others or just exchange opinions in the discussions.

Install

Because of GPU driver and CUDA Version Compatibility, there is no simple solution for CUDA related packages installation. Users need to successfully install cupy and dask_cuda first.

Here is some tips for installing them. Generally, the cuda driver is alrealy installed and maintained by the system administrator. Users only need to determine the right cudatoolkit version. Frist run

nvidia-smi

It will prints something like:

...
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 525.105.17   Driver Version: 525.105.17   CUDA Version: 12.0     |
|-------------------------------+----------------------+----------------------+
...

The CUDA Version is the maxminum cudatoolkit version that supported by the current CUDA driver. Here we use version 11.8 as an example. Then you can install the needed cudatoolkit, cupy, dask_cuda by:

conda install -c "nvidia/label/cuda-11.8.0" cuda-toolkit
conda install -c conda-forge cupy cuda-version=11.8
conda install -c rapidsai -c conda-forge -c nvidia dask-cuda rmm cuda-version=11.8

Then

With conda:

conda install -c conda-forge moraine

Or with pip:

pip install moraine

In development mode:

git clone git@github.com:kanglcn/moraine.git ./moraine
cd ./moraine
pip install -e '.[dev]'

How to use

Read the software architecture for an overview of the software design. Refer to Tutorials for the examples. Refer to API and CLI for the detailed usage of every functions.

Contact us

  • Most discussion happens on GitHub. Feel free to open an issue or comment on any open issue or pull request.
  • use github discussions to ask questions or leave comments.

License

  • This package is opened under GPL-v3.
  • The deep learning models under moraine/dl_model/* are opened under CC BY-NC-SA 4.0.

General Guidelines for Making a Pull Request (PR)2

We follow the git pull request workflow to make changes to our codebase.

Before you make a PR, have a quick look at the titles of all the existing issues first. If there is already an issue that matches your PR, leave a comment there to let us know what you plan to do. Otherwise, open an issue describing what you want to do.

What should be included in a PR

  • Each pull request should consist of a small and logical collection of changes; larger changes should be broken down into smaller parts and integrated separately.

  • Bug fixes should be submitted in separate PRs.

How to write and submit a PR

  • This package is developed with the nbdev, a notebook-driven development platform. Developers should write or edit the notebooks rather than the .py files. After than, run nbdev_export to export the code in the notebooks to .py files and run nbdev_clean to clean the notebooks.

  • The github bot to generate docs do not support GPU, so all GPU related packages (dask_cuda) should be prevented in import cells and export cells. cupy v13 now allow import cupy on a cpu-only machine. So it can be used now.

  • Describe what your PR changes and why this is a good thing. Be as specific as you can. The PR description is how we keep track of the changes made to the project over time.

  • Do not commit changes to files that are irrelevant to your feature or bugfix (e.g.: .gitignore, IDE project files, etc).

  • Write descriptive commit messages. Chris Beams has written a guide on how to write good commit messages.

PR review

Be willing to accept criticism and work on improving your code; we don’t want to break other users’ code, so care must be taken not to introduce bugs.

Be aware that the pull request review process is not immediate, and is generally proportional to the size of the pull request.

Footnotes

  1. The pronciples are modified from the principle of Arch Linux.↩︎

  2. this is modified from the Contributers Guide of PyGMT.↩︎