Re-organize documentation to list features independently of data objects (#565)

Author: rhugonnet

doc/source/api.md

@@ -47,6 +47,7 @@ documentation.
     Raster.crs
     Raster.transform
     Raster.nodata
+    Raster.area_or_point
 ```
 
 ### Derived attributes
@@ -83,8 +84,8 @@ documentation.
     Raster.reproject
     Raster.polygonize
     Raster.proximity
-    Raster.value_at_coords
     Raster.interp_points
+    Raster.reduce_points
 ```
 
 ### Plotting
@@ -120,6 +121,7 @@ documentation.
     Raster.load
     Raster.save
     Raster.to_pointcloud
+    Raster.from_pointcloud_regular
     Raster.to_rio_dataset
     Raster.to_xarray
 ```
@@ -133,7 +135,7 @@ documentation.
     Raster.xy2ij
     Raster.ij2xy
     Raster.coords
-    Raster.shift
+    Raster.translate
     Raster.outside_image
 ```
 
@@ -265,6 +267,7 @@ And reverse operations.
 .. autosummary::
     :toctree: gen_modules/
 
+    raster.load_multiple_rasters
     raster.stack_rasters
     raster.merge_rasters
 ```

doc/source/conf.py

@@ -65,6 +65,7 @@
     "xdem": ("https://xdem.readthedocs.io/en/stable", None),
     "rioxarray": ("https://corteva.github.io/rioxarray/stable/", None),
     "pandas": ("https://pandas.pydata.org/docs/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
 }
 
 example_path = os.path.join("../", "../", "examples")
@@ -110,7 +111,7 @@
 }
 
 # For matplotlib figures generate with sphinx plot: (suffix, dpi)
-plot_formats = [(".png", 400)]
+plot_formats = [(".png", 500)]
 
 # To avoid long path names in inheritance diagrams
 inheritance_alias = {
@@ -193,7 +194,8 @@ def setup(app):
         "⚠️ Our 0.1 release refactored several early-development functions for long-term stability, "
         'to update your code see <a href="https://github.com/GlacioHack/geoutils/releases/tag/v0.1.0">here</a>. ⚠️'
         "<br>Future changes will come with deprecation warnings! 🙂"
-    )
+    ),
+    "show_toc_level": 3
     # "logo_only": True,
     # "icon_links": [
     #         {

doc/source/config.md

@@ -0,0 +1,37 @@
+---
+file_format: mystnb
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: geoutils-env
+  language: python
+  name: geoutils
+---
+(config)=
+# Configuration
+
+You can configure the default behaviour of GeoUtils at the package level for operations that depend on user preference
+(such as resampling method, or pixel interpretation).
+
+## Changing configuration during a session
+
+Using a global configuration setting ensures operations will always be performed consistently, even when used
+under-the-hood by higher-level methods (such as [Coregistration](https://xdem.readthedocs.io/en/stable/coregistration.html)),
+without having to rely on multiple keyword arguments to pass to subfunctions.
+
+```{code-cell}
+import geoutils as gu
+# Changing default behaviour for pixel interpretation for this session
+gu.config["shift_area_or_point"] = False
+```
+
+## Default configuration file
+
+Below is the full default configuration file, which is updated by changes in configuration during a session.
+
+```{literalinclude} ../../geoutils/config.ini
+:class: full-width
+```

doc/source/rasters_index.md renamed to doc/source/data_object_index.md

@@ -1,12 +1,14 @@
-(rasters-index)=
-# Rasters
+(data-object-index)=
+# Geospatial data objects
 
 Prefer to learn by running examples? Explore our example galleries on {ref}`examples-io`, {ref}`examples-handling` and {ref}`examples-analysis`.
 
 ```{toctree}
 :maxdepth: 2
 
 raster_class
+vector_class
+pointcloud_class
 mask_class
 satimg_class
 ```

doc/source/distance_ops.md

@@ -0,0 +1,99 @@
+---
+file_format: mystnb
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: geoutils-env
+  language: python
+  name: geoutils
+---
+(distance-ops)=
+# Distance operations
+
+Computing distance between sets of geospatial data or manipulating their shape based on distance is often important
+for later analysis. To facilitate this type of operations, GeoUtils implements distance-specific functionalities
+for both vectors and rasters.
+
+```{code-cell} ipython3
+:tags: [remove-cell]
+
+# To get a good resolution for displayed figures
+from matplotlib import pyplot
+pyplot.rcParams['figure.dpi'] = 600
+pyplot.rcParams['savefig.dpi'] = 600
+pyplot.rcParams['font.size'] = 9
+```
+
+```{tip}
+It is often important to compute distances in a metric CRS. For this, reproject (with
+{func}`~geoutils.Raster.reproject`) to a local metric CRS (that can be estimated with {func}`~geoutils.Raster.get_metric_crs`).
+```
+
+## Proximity
+
+Proximity corresponds to **the distance to the closest target geospatial data**, computed on each pixel of a raster's grid.
+The target geospatial data can be either a vector or a raster.
+
+{func}`geoutils.Raster.proximity` and {func}`geoutils.Vector.proximity`
+
+```{code-cell} ipython3
+:tags: [hide-cell]
+:mystnb:
+:  code_prompt_show: "Show the code for opening example files"
+:  code_prompt_hide: "Hide the code for opening example files"
+
+import matplotlib.pyplot as plt
+import geoutils as gu
+import numpy as np
+
+rast = gu.Raster(gu.examples.get_path("everest_landsat_b4"))
+rast.set_nodata(0)  # Annoying to have to do this here, should we update it in the example?
+vect = gu.Vector(gu.examples.get_path("everest_rgi_outlines"))
+```
+
+```{code-cell} ipython3
+# Compute proximity to vector outlines
+proximity = vect.proximity(rast)
+```
+
+```{code-cell} ipython3
+:tags: [hide-input]
+:mystnb:
+:  code_prompt_show: "Show the code for plotting the figure"
+:  code_prompt_hide: "Hide the code for plotting the figure"
+
+f, ax = plt.subplots(1, 2)
+ax[0].set_title("Raster and vector")
+rast.plot(ax=ax[0], cmap="gray", add_cbar=False)
+vect.plot(ref_crs=rast, ax=ax[0], ec="k", fc="none")
+ax[1].set_title("Proximity")
+proximity.plot(ax=ax[1], cmap="viridis", cbar_title="Distance to outlines (m)")
+_ = ax[1].set_yticklabels([])
+plt.tight_layout()
+```
+
+## Buffering without overlap
+
+Buffering consists in **expanding or collapsing vector geometries equally in all directions**. However, this can often lead to overlap
+between shapes, which is sometimes undesirable. Using Voronoi polygons, we provide a buffering method with overlap.
+
+{func}`geoutils.Vector.buffer_without_overlap`
+
+```{code-cell} ipython3
+# Compute buffer without overlap from vector exterior
+vect_buff_nolap = vect.buffer_without_overlap(buffer_size=500)
+```
+
+```{code-cell} ipython3
+:tags: [hide-input]
+:mystnb:
+:  code_prompt_show: "Show the code for plotting the figure"
+:  code_prompt_hide: "Hide the code for plotting the figure"
+
+# Plot with color to see that the attributes are retained for every feature
+vect.plot(ax="new", ec="k", column="Area", alpha=0.5, add_cbar=False)
+vect_buff_nolap.plot(column="Area", cbar_title="Buffer around initial features\ncolored by glacier area (km)")
+```

doc/source/feature_overview.md

@@ -16,15 +16,23 @@ kernelspec:
 
 The following presents a descriptive example show-casing all core features of GeoUtils.
 
-For more details, refer to the {ref}`core-index`, {ref}`rasters-index` or {ref}`vectors-index` pages.
-
 ```{tip}
 All pages of this documentation containing code cells can be **run interactively online without the need of setting up your own environment**. Simply click the top launch button!
 (MyBinder can be a bit capricious: you might have to be patient, or restart it after the build is done the first time 😅)
 
 Alternatively, start your own notebook to test GeoUtils at [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/GlacioHack/geoutils/main).
 ```
 
+```{code-cell} ipython3
+:tags: [remove-cell]
+
+# To get a good resolution for displayed figures
+from matplotlib import pyplot
+pyplot.rcParams['figure.dpi'] = 600
+pyplot.rcParams['savefig.dpi'] = 600
+pyplot.rcParams['font.size'] = 9
+```
+
 ## The core {class}`~geoutils.Raster` and {class}`~geoutils.Vector` classes
 
 In GeoUtils, geospatial handling is object-based and revolves around {class}`~geoutils.Raster` and {class}`~geoutils.Vector`.