Skip to content
プロジェクト

kanglcn/moraine has 44 GitHub stars and 7 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and 0 in 15 days. Last checked 2026-11-20 07:07 UTC. Last push 2026-11-18.

この数値の測り方

計測したスター増加

24時間
0
7日間
0
15日間
0
1か月
履歴を収集中

期間ごとの純増数です。期間は重複しており、日別の値ではありません。未計測の値は空欄です。スター数は注目度の指標であり、品質の保証ではありません。

概要

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

機械学習

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.

Principle[^1]

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. The commands process zarr data chunk by chunk with moraine's own workers, in threads or in one process per GPU, so the data can be larger than memory and several GPUs work on it at once.

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 numba-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 and numba-cuda by:

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

The numba-cuda package is NVIDIA's package of the numba CUDA target that moraine's GPU kernels use; without it the deprecated CUDA target built into numba is used, which starts every kernel about 4 times slower. numba-cuda finds the CUDA libraries through CONDA_PREFIX (an activated environment) or CUDA_HOME; if none is set, moraine sets CUDA_HOME to the conda environment of the python that runs it.

Then

With conda:

conda install -c conda-forge moraine

Or with pip:

pip install moraine

The deep learning filters (n2f, n2fs3d, n2ft) additionally need PyTorch and the trained models:

pip install 'moraine[dl]'   # or install torch following the PyTorch guide for your CUDA version
python -c "import moraine; moraine.download_dl_model()"

In development mode:

git clone [email protected]:kanglcn/moraine.git ./moraine
cd ./moraine
pip install -e '.[dev,dl]'
pytest                      # or `pytest -m "not slow"` for a quick run

Tests that need the sample data set, a GPU, GAMMA or the deep learning models are skipped when these are not available. Point MORAINE_TEST_DATA to the sample data directory (default: ./data, containing rslc.zarr and the GAMMA output gamma/; gamma/sim_orb/ with the precomputed simulated orbital phases makes the GAMMA loading test take seconds instead of ~15 min) to run them.

How to use

The manual is at https://kanglcn.github.io/moraine/: concepts, the workflows, the command line and Python API references generated from the code, the tutorials and a recorded session with an AI agent. Every function is documented by its docstring, e.g. help(moraine.emi) or help(moraine.cli.emi), and every command by moraine COMMAND --help. The source of the manual is docs/ (pip install -e '.[docs]', mkdocs serve).

Command line and pipelines

Every processing function of moraine.cli is also a moraine command, with its options and help generated from the function docstring:

moraine list                                   # all commands
moraine amp-disp --help
moraine amp-disp --rslc raw/rslc.zarr --adi ps/adi.zarr --cuda
moraine info ps/adi.zarr                       # shape, dtype and chunks of a result
moraine ras-pyramid --ras ps/adi.zarr --out_dir ps/adi_pyramid
moraine info ps/adi_pyramid                    # + statistics and anomaly warnings, from a coarse level
moraine quicklook ps/adi_pyramid -o adi.png    # PNG of the whole scene, drawn from the pyramid
moraine view ps/adi_pyramid -o view.ipynb      # notebook with interactive maps (moraine.cli.view)
moraine image-pairs --rslc raw/rslc.zarr --bandwidth 1 --out pairs.txt

A whole processing chain can be written in a TOML file and run with moraine run pipeline.toml. Finished steps are skipped when their arguments and inputs did not change, so a failed or modified pipeline is resumed where needed; moraine status pipeline.toml shows the state, and logs, output metadata and PNGs of the pyramids made by ras-pyramid / pc-pyramid steps are kept in .moraine/:

[defaults]
cuda = true

[[step]]
name = "adi"
run = "amp-disp"
rslc = "raw/rslc.zarr"
adi = "ps/adi.zarr"

[[step]]
name = "ps_can"
run = "pc-logic-ras"
ras = "ps/adi.zarr"
gix = "ps/ps_can_gix.zarr"
operation = "(ras>=0)&(ras<=0.3)"

Add --json to any command for machine readable output (logs go to stderr), which makes moraine easy to drive from scripts and AI agents.

The whole processing chain is available as verified example pipelines in examples (load GAMMA data, PS, DS, PS+DS refinement, unwrapping), each with a guide in docs/workflows: parameters, expected result ranges and checks.

Processing with an AI agent

AGENTS.md tells coding agents (Claude Code, Codex, Cursor, ...) how to run and check moraine processing; CLAUDE.md and .claude/skills/ point Claude Code to it. Prepare the input data, then ask the agent in plain words, e.g. "process the GAMMA data in /data/site_a (reference 20220620) up to unwrapping in /work/site_a".

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

  • Read docs/development.md (how to change, validate and report), ARCHITECTURE.md (module map), docs/decisions/ and docs/contracts/ (formats others depend on).

  • The source code is the .py files in moraine/. Document new functions with numpy style docstrings and add tests in tests/; run pytest before submitting.

  • The CI runs on machines without GPU, so GPU related packages (cupy, numba.cuda) must only be imported behind moraine.api.utils_.is_cuda_available(), and GPU tests are marked with @pytest.mark.gpu.

  • 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.

[^1]: The pronciples are modified from the principle of Arch Linux.

[^2]: this is modified from the Contributers Guide of PyGMT.