Merge ae028f5 into 5e05d78

doc/source/api.md

@@ -11,13 +11,19 @@ documentation.
 .. currentmodule:: xdem
 ```
 
-## DEM
-
 ```{eval-rst}
 .. minigallery:: xdem.DEM
       :add-heading:
 ```
 
+## DEM
+
+```{important}
+A {class}`~xdem.DEM` inherits all raster methods and attributes from the {class}`~geoutils.Raster` object of GeoUtils.
+Below, we only repeat the core attributes and methods of GeoUtils, see
+[the Raster API in GeoUtils](https://geoutils.readthedocs.io/en/latest/api.html#raster) for the full list.
+```
+
 ### Opening a DEM
 
 ```{eval-rst}
@@ -41,27 +47,40 @@ documentation.
 
 ### Unique attributes
 
-```{note}
-A {class}`~xdem.DEM` inherits four unique attributes from {class}`~geoutils.Raster`, see [the dedicated section of GeoUtils' API](https://geoutils.readthedocs.io/en/latest/api.html#unique-attributes).
+#### Inherited from {class}`~geoutils.Raster`
+
+```{eval-rst}
+.. autosummary::
+    :toctree: gen_modules/
+
+    DEM.data
+    DEM.crs
+    DEM.transform
+    DEM.nodata
 ```
 
+#### Specific to {class}`~xdem.DEM`
+
 ```{eval-rst}
 .. autosummary::
     :toctree: gen_modules/
 
     DEM.vcrs
 ```
 
-### Derived attributes
+### Georeferencing
+
+#### Inherited from {class}`~geoutils.Raster`
 
 ```{eval-rst}
 .. autosummary::
     :toctree: gen_modules/
 
-    DEM.ccrs
+    DEM.reproject
+    DEM.crop
 ```
 
-### Vertical referencing
+#### Vertical referencing for {class}`~xdem.DEM`
 
 ```{eval-rst}
 .. autosummary::
@@ -71,6 +90,53 @@ A {class}`~xdem.DEM` inherits four unique attributes from {class}`~geoutils.Rast
     DEM.to_vcrs
 ```
 
+### Raster-vector interface
+
+```{note}
+See the full list of vector methods in [GeoUtils' documentation](https://geoutils.readthedocs.io/en/latest/api.html#vector).
+```
+
+```{eval-rst}
+.. autosummary::
+    :toctree: gen_modules/
+
+    DEM.polygonize
+    DEM.proximity
+```
+
+### Coregistration
+
+```{tip}
+To build and pass your coregistration pipeline to {func}`~xdem.DEM.coregister_3d`, see the API of {ref}`api-geo-handle`.
+```
+
+```{eval-rst}
+.. autosummary::
+    :toctree: gen_modules/
+
+    DEM.coregister_3d
+```
+
+### Terrain attributes
+
+```{eval-rst}
+.. autosummary::
+    :toctree: gen_modules/
+
+    DEM.slope
+    DEM.aspect
+    DEM.hillshade
+    DEM.curvature
+    DEM.profile_curvature
+    DEM.planform_curvature
+    DEM.maximum_curvature
+    DEM.topographic_position_index
+    DEM.terrain_ruggedness_index
+    DEM.roughness
+    DEM.rugosity
+    DEM.fractal_roughness
+```
+
 ## dDEM
 
 ```{eval-rst}
@@ -113,6 +179,25 @@ A {class}`~xdem.DEM` inherits four unique attributes from {class}`~geoutils.Rast
     xdem.coreg.BlockwiseCoreg
 ```
 
+#### Fitting and applying transforms
+
+```{eval-rst}
+.. autosummary::
+    :toctree: gen_modules/
+
+    xdem.coreg.Coreg.fit
+    xdem.coreg.Coreg.apply
+```
+
+#### Other functionalities
+
+```{eval-rst}
+.. autosummary::
+    :toctree: gen_modules/
+
+    xdem.coreg.Coreg.residuals
+```
+
 ### Affine coregistration methods
 
 

doc/source/coregistration.md

@@ -23,6 +23,14 @@ Those transformations include for instance:
 - rotations, reflections,
 - scalings.
 
+## Quick use
+
+Coregistrations are defined using either a single method or pipeline of {class}`~xdem.coreg.Coreg` methods, that are listed below.
+
+Performing the coregistration on a pair of DEM is done either by using {func}`xdem.DEM.coregister_3d` from the DEM that will be aligned, or
+by specifying the {func}`xdem.coreg.Coreg.fit` and {func}`xdem.coreg.Coreg.apply` steps, which allows array inputs and
+to apply the same fitted transformation to several objects (e.g., horizontal shift of both a stereo DEM and its ortho-image).
+
 ## Introduction
 
 Coregistration of a DEM is performed when it needs to be compared to a reference, but the DEM does not align with the reference perfectly.

doc/source/dem_class.md

@@ -0,0 +1,71 @@
+---
+file_format: mystnb
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: xdem-env
+  language: python
+  name: xdem
+---
+(dem-class)=
+
+# The digital elevation model ({class}`~xdem.DEM`)
+
+Below, a summary of the {class}`~xdem.DEM` object and its methods.
+
+(dem-obj-def)=
+
+## Object definition and attributes
+
+A {class}`~xdem.DEM` is a {class}`~geoutils.Raster` with an additional georeferenced vertical dimension stored in the attribute {attr}`~xdem.DEM.vcrs`.
+It inherits the **four main attributes** of {class}`~geoutils.Raster` which are {attr}`~xdem.DEM.data`,
+{attr}`~xdem.DEM.transform`, {attr}`~xdem.DEM.crs` and {attr}`~xdem.DEM.nodata`.
+
+Many other useful raster attributes, such as {attr}`~xdem.DEM.bounds` and {attr}`~xdem.DEM.res` and raster methods
+such {attr}`~xdem.DEM.reproject` or {attr}`~xdem.DEM.crop` are available through the {class}`~geoutils.Raster` object.
+
+```{important}
+Below, we only cover a few core aspects linked to the {class}`~geoutils.Raster` object. For more details, see [GeoUtils' Raster documentation page](https://geoutils.readthedocs.io/en/stable/raster_class.html).
+The complete list of {class}`~geoutils.Raster` attributes and methods in [GeoUtils' API](https://geoutils.readthedocs.io/en/stable/api.html#raster).
+```
+
+## Open and save
+
+A {class}`~xdem.DEM` is opened, as for a {class}`~geoutils.Raster`, by instantiating with either a {class}`str`, a {class}`pathlib.Path`, a {class}`rasterio.io.DatasetReader` or a
+{class}`rasterio.io.MemoryFile`.
+
+
+```{code-cell} ipython3
+import xdem
+
+# Instantiate a DEM from a filename on disk
+filename_dem = xdem.examples.get_path("longyearbyen_ref_dem")
+dem = xdem.DEM(filename_dem)
+dem
+```
+
+Detailed information on the {class}`~xdem.DEM` is printed using {func}`~geoutils.Raster.info`, along with basic statistics using `stats=True`:
+
+```{code-cell} ipython3
+# Print details of raster
+dem.info(stats=True)
+```
+
+```{note}
+Calling {class}`~xdem.DEM.info()` with `stats=True` automatically loads the array in-memory, like any other operation calling {attr}`~xdem.DEM.data`.
+```
+
+A {class}`~xdem.DEM` is saved to file by calling {func}`~xdem.DEM.save` with a {class}`str` or a {class}`pathlib.Path`.
+
+```{code-cell} ipython3
+# Save raster to disk
+dem.save("mydem.tif")
+```
+```{code-cell} ipython3
+:tags: [remove-cell]
+import os
+os.remove("mydem.tif")
+```

doc/source/elevation_objects.md

@@ -0,0 +1,12 @@
+(elevation-objects)=
+# Elevation data objects
+
+Elevation data objects of xDEM inherit their characteristics from raster and vector objects of
+our sister-package [GeoUtils](https://geoutils.readthedocs.io/en/stable/).
+
+```{toctree}
+:maxdepth: 2
+
+dem_class
+elevation_point_cloud
+```

doc/source/elevation_point_cloud.md

@@ -0,0 +1,17 @@
+---
+file_format: mystnb
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: xdem-env
+  language: python
+  name: xdem
+---
+(elevation-point-cloud)=
+
+# The elevation point cloud ({class}`~xdem.EPC`)
+
+In construction, planned for 2024.

doc/source/index.md

@@ -98,6 +98,7 @@ intro_accuracy_precision
 :caption: Features
 :maxdepth: 2
 
+elevation_objects
 vertical_ref
 terrain
 coregistration

doc/source/terrain.md

@@ -2,12 +2,21 @@
 
 # Terrain attributes
 
-For analytic and visual purposes, deriving certain attributes of a DEM may be required.
-Some are useful for direct analysis, such as a slope map to differentiate features of different angles, while others, like the hillshade, are great tools for visualizing a DEM.
+xDEM can derive a wide range of **terrain attributes** from a DEM.
+
+Attributes are derived in pure Python for modularity (e.g., varying window size) and other uses (e.g., uncertainty),
+and tested for consistency against [gdaldem](https://gdal.org/programs/gdaldem.html) and [RichDEM](https://richdem.readthedocs.io/).
+
+## Quick use
+
+Terrain attribute methods can either be called directly from a {class}`~xdem.DEM` (e.g., {func}`xdem.DEM.slope`) or
+through the {class}`~xdem.terrain` module which allows array input. If computational performance
+is key, xDEM can rely on [RichDEM](https://richdem.readthedocs.io/) by specifying `use_richdem=True` for speed-up
+of its supported attributes (slope, aspect, curvature).
 
 ## Slope
 
-{func}`xdem.terrain.slope`
+{func}`xdem.DEM.slope`
 
 The slope of a DEM describes the tilt, or gradient, of each pixel in relation to its neighbours.
 It is most often described in degrees, where a flat surface is 0° and a vertical cliff is 90°.
@@ -29,7 +38,7 @@ example.
 
 ## Aspect
 
-{func}`xdem.terrain.aspect`
+{func}`xdem.DEM.aspect`
 
 The aspect describes the orientation of strongest slope.
 It is often reported in degrees, where a slope tilting straight north corresponds to an aspect of 0°, and an eastern
@@ -48,7 +57,7 @@ As the aspect is directly based on the slope, it varies between the method of [H
 
 ## Hillshade
 
-{func}`xdem.terrain.hillshade`
+{func}`xdem.DEM.hillshade`
 
 The hillshade is a slope map, shaded by the aspect of the slope.
 The slope map is a good tool to visualize terrain, but it does not distinguish between a mountain and a valley.
@@ -73,7 +82,7 @@ It therefore has little analytic purpose, but it still constitutes a great visua
 
 ## Curvature
 
-{func}`xdem.terrain.curvature`
+{func}`xdem.DEM.curvature`
 
 The curvature map is the second derivative of elevation, which highlights the convexity or concavity of the terrain.
 If a surface is convex (like a mountain peak), it will have positive curvature.
@@ -93,7 +102,7 @@ The curvature is based on the method of [Zevenbergen and Thorne (1987)](http://d
 
 ## Planform curvature
 
-{func}`xdem.terrain.planform_curvature`
+{func}`xdem.DEM.planform_curvature`
 
 The planform curvature is the curvature perpendicular to the direction of slope, reported in 100 m{sup}`-1`.
 
@@ -110,7 +119,7 @@ It is based on the method of [Zevenbergen and Thorne (1987)](http://dx.doi.org/1
 
 ## Profile curvature
 
-{func}`xdem.terrain.profile_curvature`
+{func}`xdem.DEM.profile_curvature`
 
 The profile curvature is the curvature parallel to the direction of slope, reported in 100 m{sup}`-1`..
 
@@ -127,7 +136,7 @@ It is based on the method of [Zevenbergen and Thorne (1987)](http://dx.doi.org/1
 
 ## Topographic Position Index
 
-{func}`xdem.terrain.topographic_position_index`
+{func}`xdem.DEM.topographic_position_index`
 
 The Topographic Position Index (TPI) is a metric of slope position, based on the method of [Weiss (2001)](http://www.jennessent.com/downloads/TPI-poster-TNC_18x22.pdf) that corresponds to the difference of the elevation of a central
 pixel with the average of that of neighbouring pixels. Its unit is that of the DEM (typically meters) and it can be
@@ -144,7 +153,7 @@ computed for any window size (default 3x3 pixels).
 
 ## Terrain Ruggedness Index
 
-{func}`xdem.terrain.terrain_ruggedness_index`
+{func}`xdem.DEM.terrain_ruggedness_index`
 
 The Terrain Ruggedness Index (TRI) is a metric of terrain ruggedness, based on cumulated differences in elevation between
 a central pixel and its surroundings. Its unit is that of the DEM (typically meters) and it can be computed for any
@@ -167,7 +176,7 @@ where the TRI is defined by the mean absolute difference with neighbouring pixel
 
 ## Roughness
 
-{func}`xdem.terrain.roughness`
+{func}`xdem.DEM.roughness`
 
 The roughness is a metric of terrain ruggedness, based on the maximum difference in elevation in the surroundings.
 The roughness is based on the method of [Dartnell (2000)](http://dx.doi.org/10.14358/PERS.70.9.1081). Its unit is that of the DEM (typically meters) and it can be computed for any window size (default 3x3 pixels).
@@ -183,7 +192,7 @@ The roughness is based on the method of [Dartnell (2000)](http://dx.doi.org/10.1
 
 ## Rugosity
 
-{func}`xdem.terrain.rugosity`
+{func}`xdem.DEM.rugosity`
 
 The rugosity is a metric of terrain ruggedness, based on the ratio between planimetric and real surface area. The
 rugosity is based on the method of [Jenness (2004)](<https://doi.org/10.2193/0091-7648(2004)032[0829:CLSAFD]2.0.CO;2>).
@@ -200,7 +209,7 @@ It is unitless, and is only supported for a 3x3 window size.
 
 ## Fractal roughness
 
-{func}`xdem.terrain.fractal_roughness`
+{func}`xdem.DEM.fractal_roughness`
 
 The fractal roughness is a metric of terrain ruggedness based on the local fractal dimension estimated by the volume
 box-counting method of [Taud and Parrot (2005)](https://doi.org/10.4000/geomorphologie.622).
@@ -221,7 +230,7 @@ DEM pixels. Its unit is that of a dimension, and is always between 1 (dimension
 
 Often, one may seek more terrain attributes than one, e.g. both the slope and the aspect.
 Since both are dependent on the gradient of the DEM, calculating them separately is computationally repetitive.
-Multiple terrain attributes can be calculated from the same gradient using the {func}`xdem.terrain.get_terrain_attribute` function.
+Multiple terrain attributes can be calculated from the same gradient using the {func}`xdem.DEM.get_terrain_attribute` function.
 
 ```{eval-rst}
 .. minigallery:: xdem.terrain.get_terrain_attribute