/demcoreg

Utilities for DEM and point cloud co-registration

Primary LanguageJupyter NotebookMIT LicenseMIT

DOI

demcoreg

Python and shell scripts for co-registration of rasters, specifically horizontal and vertical alignment of digital elevation models (DEMs).

Overview

All DEMs have some horizontal and vertical geolocation error. It is important to remove relative offsets when differencing DEMs for elevation change analyses. These tools offer several options to solve this problem. Most solve for the sub-pixel horizontal shift and vertical offset required to minimize errors over "static" control surfaces. The ASP pc_align tool can also solve for more complex transformations with rotations and scaling.

Features

  • Multiple co-registration algorithms:
  • Command-line utilities for raster differencing with necessary resampling (compute_diff.py), raster stats (robust_stats.py), and raster sampling at point locations (sample_raster_at_pts.py)
  • Mask preparation and automatic determination of static control surfaces (i.e., exposed bedrock) for a user-specified combination of:

Some useful command-line utilities (run with -h option for complete usage)

  • dem_align.py - robust raster DEM co-registration (e.g., Nuth and Kaab [2011]) for surfaces with variable slope and aspect (e.g., mountains)
  • dem_mask.py - pre-generate mask to identify "stable" surfaces to use during co-registration
  • pc_align_wrapper.sh - wrapper around NASA Ames Stereo Pipeline pc_align utility for iterative closest point co-registration
  • apply_dem_translation.py - update raster geotransform and remove vertical offset
  • compute_diff.py - simple DEM difference calculation with intuitive resampling options
  • robust_stats.py - print out robust raster statistics (e.g,. for DEM difference map before/after co-registration)

Sample output

dem_align.py

Sample command: dem_align.py ref_dem.tif src_dem.tif Sample dem_align Nuth and Kaab plot

dem_mask.py

Sample command: dem_mask.py --toa --bareground --glaciers src_dem.tif Sample dem_mask

filter_glas.py output

Sample filter_glas

Example applications

High-mountain Asia

Pine Island Glacier, Antarctica

Installation

We are hoping to clean up the code, remove unnecessary dependencies, and streamline installation using conda. For now, we recommend following the "Building from Latest Source" instructions below, to obtain latest features/bugfixes.

If unfamiliar with this process, or if you are new to Python, bash, and/or git/github, start with these more detailed instructions and notes: Beginner's guide for installation and basic usage

Building from Latest Source (recommended)

  1. Assuming you have working Python3 install with GDAL and NumPy, install pygeotools
  2. Clone the demcoreg repository: git clone https://github.com/dshean/demcoreg.git
  3. Perform developer install with pip: pip install -e demcoreg
    • The -e flag ("editable mode", setuptools "develop mode") will allow you to modify source code and immediately see changes. Useful if you need to make minor tweaks or bugfixes (please submit a Pull Request!)
  4. Optionally, append the demcoreg subdirectory containing scripts to your PATH: export PATH=${PATH}:$PWD/demcoreg/demcoreg (replacing $PWD with the absolute path to the cloned demcoreg repository)
    • To make this permanent, add that line to your shell config file (e.g., ~/.bashrc).

Simple install with PyPI

pip install demcoreg

Documentation

http://demcoreg.readthedocs.io (autogenerated from source code, may be out of date)

License

This project is licensed under the terms of the MIT License.

Citation

If you use any of this software for research applications that result in publications, please cite:
Shean, D. E., O. Alexandrov, Z. Moratto, B. E. Smith, I. R. Joughin, C. C. Porter, Morin, P. J., An automated, open-source pipeline for mass production of digital elevation models (DEMs) from very high-resolution commercial stereo satellite imagery, ISPRS J. Photogramm. Remote Sens, 116, 101-117, doi: 10.1016/j.isprsjprs.2016.03.012, 2016.