Demcompare Tutorial

Demcompare Team

Outline

• Tutorial preparation
• Context
• How Demcompare works?
• Quickstart

Tutorial preparation

Preparation

Prerequisites:

python >= 3.8
python-venv or virtualenv
web access

Demcompare install from pypi

Demcompare install:

python -m venv venv # virtualenv venv init
source ./venv/bin/activate # enter the virtualenv
pip install --upgrade pip
pip install demcompare[notebook]

Jupyter notebook preparation

Install Jupyter packages in previous virtualenv:

source ./venv/bin/activate # enter the virtualenv
pip install notebook rise bokeh
# add any tool you may need through pip install

Build Jupyter kernel:

python -m ipykernel install --sys-prefix --name=dc-kernel --display-name=dc-kernel

Jupyter environnement:

jupyter notebook

Context

Demcompare in a nutshell

Demcompare aims at comparing two DEMs together.

Demcompare has several benefits:

• Works whether or not the two DEMs share common format projection system, planimetric resolution, and altimetric unit.
• Performs the coregistration based on the Nuth & Kääb universal coregistration method.
• Computes the statistics on an input DEM, or on the difference of two input DEMs.
• Provides a wide variety of standard metrics and allows one to classify the DEMs to obtain statistics by class.

Open to contributions: remarks, bugs, ... !

License: Apache-2.0

Web sites:

• Repository: https://github.com/cnes/Demcompare/
• Documentation: https://demcompare.readthedocs.io/

Projects context

• CO3D project: four small satellites in the CO3D constellation to map the whole globe in 3D
• AI4GEO : production of automatic 3D geospatial information based on IA technologies.
• Internal studies, internships, phd, ...

Authors

• Emmanuel Dubois emmanuel.dubois@cnes.fr
• Emmanuelle Sarrazin emmanuelle.sarrazin@cnes.fr
• Natalia Jimenez natalia.jimenez-diaz@csgroup.eu
• Alice de Bardonnèche-Richard alice.de-bardonneche-richard@csgroup.eu

See Authors.md for full contributions in Github repository.

Copyright

• CNES Copyright to ease maintenance with Contributor License Aggrement.

Contributions

See Contributing documentation

Glossary

DEM: Digital Elevation Model. Usually means all elevation models in raster: DSM, DTM,…

DSM: Digital Surface Model. Represents the earth’s surface and includes all objects on it.

DTM: Digital Terrain Model. Represents bare ground surface without any objects like plants and buildings.

ROI: Region of Interest means a subpart of a DSM raster.

Related tools

• CARS: https://github.com/cnes/cars
• Bulldozer: https://github.com/cnes/bulldozer

How Demcompare works?

Demcompare pipeline

From data inputs, a coregistration optional step is executed before a statistics configurable step. A report is generated optionnally.

Data inputs

• REF: reference input
• SEC: raster to compare to the reference

Some elements can be configured:

• geoid
• no data
• ROI
• classification layers

Follow https://demcompare.readthedocs.io/en/latest/userguide/inputs.html documentation

Demcompare coregistration

The coregistration step:

• reprojects inputs with offset estimation and resampling (depending on a parameter sampling_source)
• does coregistration (Nuth and Kaab) to find planimetric x,y shifts to align rasters

An altimetric shift is also given but not applied.

Follow https://demcompare.readthedocs.io/en/latest/userguide/coregistration.html documentation

Demcompare statistics

The statistics step computes statistics on REF-SEC difference (coregistered and reprojected) depending on:

• metrics chosen (scalars or vectors)
• classification layers and configured modes (global, segmentation, slope, fusion, ...)
• remove_outliers input parameter

Follow https://demcompare.readthedocs.io/en/latest/userguide/statistics.html documentation.

Demcompare report (experimental)

A report is generated:

• presents initial and final snapshots, histograms and cumulative density functions.
• presents aggregated statistics.
• show final configuration

Quickstart

Quickstart

# download data samples
wget https://raw.githubusercontent.com/CNES/demcompare/master/data_samples/srtm_blurred_and_shifted.tif
wget https://raw.githubusercontent.com/CNES/demcompare/master/data_samples/srtm_ref.tif

# download demcompare predefined configuration
wget https://raw.githubusercontent.com/CNES/demcompare/master/data_samples/sample_config.json

# run demcompare
demcompare sample_config.json

Warning: Internet needed to download demo data.

Quick start outputs

demcompare sample_config.json
2023-06-24/18:38:13 :: INFO :: *** Demcompare ***
2023-06-24/18:38:13 :: INFO :: Output directory: /tmp/test_output
2023-06-24/18:38:14 :: INFO :: Input Reference DEM (REF): /tmp/./srtm_ref.tif
2023-06-24/18:38:14 :: INFO :: Input Secondary DEM (SEC): /tmp/./srtm_blurred_and_shifted.tif
2023-06-24/18:38:14 :: INFO :: [Coregistration]
2023-06-24/18:38:14 :: INFO :: Coregistration method name: nuth_kaab_internal
2023-06-24/18:38:16 :: INFO :: Coregistration results:
2023-06-24/18:38:16 :: INFO :: Planimetry 2D shift between reprojected SEC and REF:
2023-06-24/18:38:16 :: INFO ::  -> row : 0.00417 m
2023-06-24/18:38:16 :: INFO ::  -> col : 0.0025 m
2023-06-24/18:38:16 :: INFO :: GDAL translate bounds:
2023-06-24/18:38:16 :: INFO ::  -> ulx : 40.00 , -> uly : 40.00 , -> lrx : 40.83 , -> lry : 39.17 
2023-06-24/18:38:16 :: INFO :: Altimetry shift between reprojected SEC and REF (not applied):
2023-06-24/18:38:16 :: INFO ::  -> alti : -0.01764540854150804 m
2023-06-24/18:38:17 :: INFO :: [Stats]
2023-06-24/18:38:17 :: INFO :: (COREG_REF-COREG_SEC) altimetric stats generation
2023-06-24/18:38:26 :: INFO :: [Report]
2023-06-24/18:38:33 :: INFO :: Generated report: /tmp/test_output/./report/published_report

Quick start results

initial diff	final diff

Quick start details

1. See input data
   • Input Raster DEM reference: REF
   • Input Raster DEM secondary: SEC

Quick start details

2. See sample configuration

{
    "output_dir": "./test_output/",
	"input_ref" : {
		"path" : "./srtm_ref.tif",
		"zunit" : "m"
	},
	"input_sec" : {
		"path" : "./srtm_blurred_and_shifted.tif",
		"zunit" : "m",
		"nodata" : -32768
	},
	"coregistration": {
		"method_name": "nuth_kaab_internal",
		"number_of_iterations": 6,
		"estimated_initial_shift_x": 0,
		"estimated_initial_shift_y": 0
	},
  "statistics": {
    "classification_layers": {
      "Slope0": {
        "type": "slope",
        "ranges": [
          0,
          5,
          10,
          25,
          45
        ]
      }
    },
    "remove_outliers": "True"
  },
  "report": "default"
}