diff --git a/doc/source/authors.md b/doc/source/authors.md index c744d485..25248dac 100644 --- a/doc/source/authors.md +++ b/doc/source/authors.md @@ -1,32 +1,19 @@ ---- -file_format: mystnb -jupytext: - formats: md:myst - text_representation: - extension: .md - format_name: myst -kernelspec: - display_name: xdem-env - language: python - name: xdem ---- (authors)= - -# Credits +## Authors © 2024 **xDEM developers**. -**xDEM** is licensed under permissive Apache 2 license (See [LICENSE file](license.md)). +**xDEM** is licensed under permissive Apache 2 license (See [LICENSE file](license.md) or below). All contributors listed in this document are part of the **xDEM developers**, and their contributions are subject to the project's copyright under the terms of the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0). -This file keeps track of authors contributions. +This section keeps track of authors contributions. --- -## Development Lead +### Development lead - **Romain Hugonnet** [@rhugonnet](https://github.com/rhugonnet) - **Amaury Dehecq** [@adehecq](https://github/adehecq) @@ -34,7 +21,7 @@ This file keeps track of authors contributions. --- -## Contributors +### Contributors - **Friedrich Knuth** [@friedrichknuth](https://github/friedrichknuth) @@ -52,11 +39,9 @@ This file keeps track of authors contributions. - **Amelie Froessl** [@ameliefroessl](https://github.com/ameliefroessl) - **Simon Gascoin** [@sgascoin](https://github.com/sgascoin) -Update here with new contributors. - --- -## Original Developers/Designers/Supporters +### Original developers - **Romain Hugonnet** [@rhugonnet](https://github.com/rhugonnet) - **Amaury Dehecq** [@adehecq](https://github/adehecq) diff --git a/doc/source/background.md b/doc/source/background.md deleted file mode 100644 index 2e593bc2..00000000 --- a/doc/source/background.md +++ /dev/null @@ -1,133 +0,0 @@ -(background)= - -# Background - -Below, some more information on the people behind the package, its funding sources, and its mission. - -## The people behind xDEM - -### Creation - -```{margin} -1More on our GlacioHack founder at [adehecq.github.io](https://adehecq.github.io/). -``` - -xDEM was created during the **[GlacioHack](https://github.com/GlacioHack) hackathon**, that was initiated by -Amaury Dehecq1 and took place online on November 8, 2020. - -```{margin} -2Check-out [glaciology.ch](https://glaciology.ch) on our founding group of VAW glaciology! -``` - -The initial core development of xDEM was performed by members of the Glaciology group of the Laboratory of Hydraulics, Hydrology and -Glaciology (VAW) at ETH Zürich2, with contributions by members of the University of Oslo, the University of Washington, and University -Grenoble Alpes. - -### Current team - -```{margin} -3More on CNES's 3D missions on the [CO3D constellation page](https://cnes.fr/en/projects/co3d). -``` - -The current lead development team includes **researchers in Earth observation and engineers from -[CNES](https://cnes.fr/en)** (French Space Agency). We specialize in elevation data analysis, for application in Earth -science or for operational use for 3D satellite missions3. - -Other volunteer contributors span diverse scientific backgrounds in industry or research. We welcome -any new contributors! See how to contribute on [the dedicated page of our repository](https://github.com/GlacioHack/xdem/blob/main/CONTRIBUTING.md). - -## Funding acknowledgments - -Members of the lead development team acknowledge funding from: -- SNSF grant no. 184634, a MeteoSwiss [GCOS](https://gcos.wmo.int/en/home) project on elevation data analysis for glaciology, -- NASA award 80NSSC22K1094, an [STV](https://science.nasa.gov/earth-science/decadal-surveys/decadal-stv/) project on the fusion of elevation data, -- NASA award 80NSSC23K0192, an [ICESat-2](https://icesat-2.gsfc.nasa.gov/) project on the processing of elevation data in the cloud, -- CNES (French Space Agency) award on merging [demcompare](https://github.com/CNES/demcompare) and xDEM while further developing related 3D tools. - - -::::{grid} -:reverse: - -:::{grid-item} -:columns: 4 -:child-align: center - -```{image} ./_static/nasa_logo.svg - :width: 200px - :class: dark-light -``` - -::: - -:::{grid-item} -:columns: 4 -:child-align: center - -```{image} ./_static/snsf_logo.svg - :width: 220px - :class: only-light -``` - -```{image} ./_static/snsf_logo_dark.svg - :width: 220px - :class: only-dark -``` - -::: - -:::{grid-item} -:columns: 4 -:child-align: center - -```{image} ./_static/cnes_logo.svg - :width: 200px - :class: only-light -``` - -```{image} ./_static/cnes_logo_dark.svg - :width: 200px - :class: only-dark -``` - -::: - - -:::: - -## Mission - -```{epigraph} -The core mission of xDEM is to be **easy-of-use**, **modular** and **robust**. - -It also attempts to be as **efficient**, **scalable** and **state-of-the-art** as possible. - -Finally, as an open source package, it aspires to foster **reproducibility** and **open science**. -``` - -In details, those mean: - -- **Ease-of-use:** all basic operations or methods from published works should only require a few lines of code to be performed; - -- **Modularity:** all methods should be fully customizable, to allow both flexibility and inter-comparison; - -- **Robustness:** all methods should be tested within our continuous integration test-suite, to enforce that they always perform as expected; - -```{note} -:class: margin -**Scalability** is currently being improved towards a first major release ``v1.0``. -``` - -And, additionally: - -- **Efficiency**: all methods should be optimized at the lower-level, to function with the highest performance offered by Python packages; - -- **Scalability**: all methods should support both lazy processing and distributed parallelized processing, to work with high-resolution data on local machines as well as on HPCs; - -- **State-of-the-art**: all methods should be at the cutting edge of remote sensing science, to provide users with the most reliable and up-to-date tools. - -And finally: - -- **Reproducibility:** all code should be version-controlled and release-based, to ensure consistency of dependent - packages and works; - -- **Open-source:** all code should be accessible and reusable to anyone in the community, for transparency and open governance. diff --git a/doc/source/biascorr.md b/doc/source/biascorr.md index d2c6380b..6d6ff160 100644 --- a/doc/source/biascorr.md +++ b/doc/source/biascorr.md @@ -26,6 +26,24 @@ passed any external variables (e.g., land cover type, processing metric) to atte Still, many methods rely either on coordinates (e.g., deramping, along-track corrections) or terrain (e.g., curvature- or elevation-dependant corrections), derived solely from the elevation data. +```{code-cell} ipython3 +:tags: [remove-cell] + +################################################################################# +# This a temporary trick to allow vertical referencing to work in other notebooks +################################################################################# +# Somehow, only on Readthedocs (locally works fine), the first notebook to run (in alphabetical order) fails +# to download from PROJ... while all other notebook render normally. +# The first alphabetical notebook is "biascorr", so adding this trick here + +import xdem +dem = xdem.DEM(xdem.examples.get_path("longyearbyen_ref_dem")) +# Define the vertical CRS as the 3D ellipsoid of the 2D CRS +dem.set_vcrs("Ellipsoid") +# Transform to the EGM96 geoid +dem.to_vcrs("EGM96") +``` + ## Quick use Bias-correction methods are **used the same way as coregistrations**: diff --git a/doc/source/cheatsheet.md b/doc/source/cheatsheet.md index bf47f725..ea4d65ea 100644 --- a/doc/source/cheatsheet.md +++ b/doc/source/cheatsheet.md @@ -25,7 +25,7 @@ identify on **a map of elevation differences with another elevation dataset (loo ## Cheatsheet The patterns of errors categories listed in this spreadsheet **are linked to visual examples further below** that -you use to compare to your own elevation differences. +you can use to compare to your own elevation differences. ```{list-table} :widths: 1 2 2 2 @@ -40,6 +40,10 @@ you use to compare to your own elevation differences. - Positive and negative errors that are larger near high slopes and symmetric with opposite slope orientation, making landforms appear visually. - Likely horizontal shift due to geopositioning errors, use a {ref}`coregistration` such as {class}`~xdem.coreg.NuthKaab`. - Even a tiny horizontal misalignment can be visually identified! To not confuse with {ref}`peak-cavity`. + * - {ref}`peak-cavity` + - Positive and negative errors, with one sign located exclusively near peaks and the other exclusively near cavities. + - Likely resolution-type errors, use a {ref}`biascorr` such as {class}`~xdem.coreg.TerrainBias`. + - Can be over-corrected, sometimes better to simply ignore during analysis. Or avoid by downsampling all elevation data to the lowest resolution, rather than upsampling to the highest. * - {ref}`smooth-large-field` - Smooth offsets varying at scale of 10 km+, often same sign (either positive or negative). - Likely wrong {ref}`vertical-ref`, can set and transform with {func}`~xdem.DEM.set_vcrs` and {func}`~xdem.DEM.to_vcrs`. @@ -52,10 +56,6 @@ you use to compare to your own elevation differences. - Positive and negative errors undulating patterns at one or several frequencies well larger than pixel size. - Likely jitter-type errors, use a {ref}`biascorr` such as {class}`~xdem.coreg.DirectionalBias`. - Can sometimes be more rigorously fixed ahead of DEM generation with jitter correction. - * - {ref}`peak-cavity` - - Positive and negative errors, with one sign located exclusively near peaks and the other exclusively near cavities. - - Likely resolution-type errors, use a {ref}`biascorr` such as {class}`~xdem.coreg.TerrainBias`. - - Can be over-corrected, sometimes better to simply ignore during analysis. Or avoid by downsampling all elevation data to the lowest resolution, rather than upsampling to the highest. * - {ref}`point-alternating` - Point data errors that alternate between negative and positive, higher on steeper slopes. - Likely wrong point-raster comparison, use [point interpolation or reduction on the raster instead](https://geoutils.readthedocs.io/en/stable/raster_vector_point.html#rasterpoint-operations) such as {func}`~xdem.DEM.interp_points`. @@ -128,6 +128,27 @@ dh = dem - dem_shift.reproject(dem) dh.plot(cmap='RdYlBu', vmin=-3, vmax=3, cbar_title="Elevation differences of\nhorizontal shift (m)") ``` +(peak-cavity)= +### Peak cuts and cavity fills + +Example of peak cutting and cavity filling errors. We here downsampled our DEM from 20 m to 100 m to simulate a lower +native resolution, then upsample it again to 20 m, to show the errors affect areas near high curvatures such as +peaks and cavities. + +```{code-cell} ipython3 +:tags: [hide-input] +:mystnb: +: code_prompt_show: "Show code to simulate resolution errors" +: code_prompt_hide: "Hide code to simulate resolution errors" + +# Downsample DEM (bilinear) +dem_100m = dem.reproject(res=100) + +# Upsample (bilinear again) and compare +dh = dem - dem_100m.reproject(dem) +dh.plot(cmap='RdYlBu', vmin=-40, vmax=40, cbar_title="Elevation differences of\nresolution change (m)") +``` + (smooth-large-field)= ### Smooth-field offset @@ -141,9 +162,9 @@ geoid added on top of the ellipsoid. : code_prompt_hide: "Hide code to simulate vertical referencing errors" # Set current vertical CRS as ellipsoid -dem.set_vcrs("Ellipsoid") +dem.set_vcrs("EGM96") # Transform vertical reference to geoid -trans_dem = dem.to_vcrs("EGM96") +trans_dem = dem.to_vcrs("Ellipsoid") # Plot the elevation differences of the vertical transformation dh = dem - trans_dem @@ -210,27 +231,6 @@ synthetic_bias = dem.copy(new_array=synthetic_bias_arr) synthetic_bias.plot(cmap='RdYlBu', vmin=-3, vmax=3, cbar_title="Elevation differences of\nundulations (m)") ``` -(peak-cavity)= -### Peak cuts and cavity fills - -Example of peak cutting and cavity filling errors. We here downsampled our DEM from 20 m to 100 m to simulate a lower -native resolution, then upsample it again to 20 m, to show the errors affect areas near high curvatures such as -peaks and cavities. - -```{code-cell} ipython3 -:tags: [hide-input] -:mystnb: -: code_prompt_show: "Show code to simulate resolution errors" -: code_prompt_hide: "Hide code to simulate resolution errors" - -# Downsample DEM (bilinear) -dem_100m = dem.reproject(res=100) - -# Upsample (bilinear again) and compare -dh = dem - dem_100m.reproject(dem) -dh.plot(cmap='RdYlBu', vmin=-40, vmax=40, cbar_title="Elevation differences of\nresolution change (m)") -``` - (point-alternating)= ### Point alternating diff --git a/doc/source/conf.py b/doc/source/conf.py index f37be141..57e1f3ec 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -27,7 +27,7 @@ project = "xDEM" copyright = "2024, xDEM developers" -author = "Erik Mannerfelt, Romain Hugonnet, Amaury Dehecq and others" +author = "Romain Hugonnet, Erik Mannerfelt, Amaury Dehecq and others" # The full version, including alpha/beta/rc tags release = xdem.__version__ @@ -177,7 +177,7 @@ def setup(app): }, "announcement": ( "⚠️ Our 0.1 release refactored several early-development functions for long-term stability, " - 'to update your code see here. ⚠️' + "to update your code see the release notes. ⚠️" ), } diff --git a/doc/source/credits.md b/doc/source/credits.md new file mode 100644 index 00000000..ff0b52bd --- /dev/null +++ b/doc/source/credits.md @@ -0,0 +1,12 @@ +(credits)= +# Credits and background + +```{toctree} +:maxdepth: 2 + +history +mission +authors +funding +license +``` diff --git a/doc/source/funding.md b/doc/source/funding.md new file mode 100644 index 00000000..b4583bc3 --- /dev/null +++ b/doc/source/funding.md @@ -0,0 +1,58 @@ +(funding)= +## Funding acknowledgments + +Members of the lead development team acknowledge funding from: +- SNSF grant no. 184634, a MeteoSwiss [GCOS](https://gcos.wmo.int/en/home) project on elevation data analysis for glaciology, +- NASA award 80NSSC22K1094, an [STV](https://science.nasa.gov/earth-science/decadal-surveys/decadal-stv/) project on the fusion of elevation data, +- NASA award 80NSSC23K0192, an [ICESat-2](https://icesat-2.gsfc.nasa.gov/) project on the processing of elevation data in the cloud, +- CNES (French Space Agency) award on merging [demcompare](https://github.com/CNES/demcompare) and xDEM while further developing related 3D tools. + + +::::{grid} +:reverse: + +:::{grid-item} +:columns: 4 +:child-align: center + +```{image} ./_static/nasa_logo.svg + :width: 200px + :class: dark-light +``` + +::: + +:::{grid-item} +:columns: 4 +:child-align: center + +```{image} ./_static/snsf_logo.svg + :width: 220px + :class: only-light +``` + +```{image} ./_static/snsf_logo_dark.svg + :width: 220px + :class: only-dark +``` + +::: + +:::{grid-item} +:columns: 4 +:child-align: center + +```{image} ./_static/cnes_logo.svg + :width: 200px + :class: only-light +``` + +```{image} ./_static/cnes_logo_dark.svg + :width: 200px + :class: only-dark +``` + +::: + + +:::: diff --git a/doc/source/history.md b/doc/source/history.md new file mode 100644 index 00000000..da0d2a95 --- /dev/null +++ b/doc/source/history.md @@ -0,0 +1,44 @@ +(history)= +# History + +Below, some more information on the history behind the package. + +## Creation + +```{margin} +1More on our GlacioHack founder at [adehecq.github.io](https://adehecq.github.io/). +``` + +xDEM was created during the **[GlacioHack](https://github.com/GlacioHack) hackathon**, that was initiated by +Amaury Dehecq1 and took place online on November 8, 2020. + +```{margin} +2Check-out [glaciology.ch](https://glaciology.ch) on our founding group of VAW glaciology! +``` + +The initial core development of xDEM was performed by members of the Glaciology group of the Laboratory of Hydraulics, Hydrology and +Glaciology (VAW) at ETH Zürich2, with contributions by members of the University of Oslo, the University of Washington, and University +Grenoble Alpes. + +## Joining effort with **demcompare** + +In 2024, xDEM and [demcompare](https://github.com/CNES/demcompare) joined efforts in the perspective of +merging the best of both packages into one, and to jointly continue the development of new features for +analyzing elevation data with a larger expertise pool. + +[demcompare](https://github.com/CNES/demcompare) is a tool developed by the CNES (French Space Agency) to +support its 3D satellite missions in analyzing elevation data, for instance from stereophotogrammetric DEMs +that can be generated with [CARS](https://github.com/CNES/cars). + +## Current team + +```{margin} +3More on CNES's 3D missions on the [CO3D constellation page](https://cnes.fr/en/projects/co3d). +``` + +The current lead development team includes **researchers in Earth observation and engineers from +[CNES](https://cnes.fr/en)** (French Space Agency). We specialize in elevation data analysis, for application in Earth +science or for operational use for 3D satellite missions3. + +Other volunteer contributors span diverse scientific backgrounds in industry or research. We welcome +any new contributors! See how to contribute on [the dedicated page of our repository](https://github.com/GlacioHack/xdem/blob/main/CONTRIBUTING.md). diff --git a/doc/source/index.md b/doc/source/index.md index d2be2649..dafb338a 100644 --- a/doc/source/index.md +++ b/doc/source/index.md @@ -148,9 +148,7 @@ release_notes :maxdepth: 2 publis -background -authors -license +credits ``` # Indices and tables diff --git a/doc/source/license.md b/doc/source/license.md index 03515f25..dbcc26d0 100644 --- a/doc/source/license.md +++ b/doc/source/license.md @@ -1,18 +1,6 @@ ---- -file_format: mystnb -jupytext: - formats: md:myst - text_representation: - extension: .md - format_name: myst -kernelspec: - display_name: xdem-env - language: python - name: xdem ---- (license)= -# Apache License +# License _Version 2.0, January 2004_ _<>_ diff --git a/doc/source/mission.md b/doc/source/mission.md new file mode 100644 index 00000000..d33bca8c --- /dev/null +++ b/doc/source/mission.md @@ -0,0 +1,38 @@ +(mission)= +## Mission + +```{epigraph} +The core mission of xDEM is to be **easy-of-use**, **modular** and **robust**. + +It also attempts to be as **efficient**, **scalable** and **state-of-the-art** as possible. + +Finally, as an open source package, it aspires to foster **reproducibility** and **open science**. +``` + +In details, those mean: + +- **Ease-of-use:** all basic operations or methods from published works should only require a few lines of code to be performed; + +- **Modularity:** all methods should be fully customizable, to allow both flexibility and inter-comparison; + +- **Robustness:** all methods should be tested within our continuous integration test-suite, to enforce that they always perform as expected; + +```{note} +:class: margin +**Scalability** is currently being improved towards a first major release ``v1.0``. +``` + +And, additionally: + +- **Efficiency**: all methods should be optimized at the lower-level, to function with the highest performance offered by Python packages; + +- **Scalability**: all methods should support both lazy processing and distributed parallelized processing, to work with high-resolution data on local machines as well as on HPCs; + +- **State-of-the-art**: all methods should be at the cutting edge of remote sensing science, to provide users with the most reliable and up-to-date tools. + +And finally: + +- **Reproducibility:** all code should be version-controlled and release-based, to ensure consistency of dependent + packages and works; + +- **Open-source:** all code should be accessible and reusable to anyone in the community, for transparency and open governance.