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:
  • Automated, iterative implementation of the algorithm outlined by Nuth and Kaab (2011)
  • Wrappers around the Ames Stereo Pipeline Iterative Closest Point (ICP) pc_align utility (https://stereopipeline.readthedocs.io/en/latest/tools/pc_align.html)
  • Normalized cross-correlation (NCC) with sub-pixel refinment
  • Sum of absolute differences (SAD)
• 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:
  • RGI glacier polygons
  • Land-use/Land-cover classification:
    • National Land Cover Database (NLCD) 30-m products for CONUS with pre-configured filter combinations (e.g., 'not_forest+not_water')
    • Global Bare Ground 30-m products
  • Snow mask:
    • Thresholded MODSCAG fSCA from ~2-week period around DEM timestamp
    • Thresholded SNODAS model
    • Thresholded Top-of-atmosphere reflectance values from corresponding orthoimage (requires pregeneration)

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

dem_mask.py

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

filter_glas.py output

Example applications

High-mountain Asia

• Co-registration of ~35000 high-resolution DEMs from multiple sensors
• https://github.com/dshean/hma_mb_paper

Pine Island Glacier, Antarctica

• Least-squares optimization to correct for offset and "tilt" of ~800 high-resolution DEMs with limited ground control
• https://github.com/dshean/pig_dem_meltrate

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.