diff --git a/doc/source/georeferencing.md b/doc/source/georeferencing.md index 11e6a410..2dbf05ae 100644 --- a/doc/source/georeferencing.md +++ b/doc/source/georeferencing.md @@ -13,16 +13,21 @@ kernelspec: (georeferencing)= # Referencing -Below, a summary of the **georeferencing attribute definition** of geospatial data objects and the **methods to manipulate -georeferencing attributes** in different projections, without any data transformation. For georeferenced transformation -(reprojection, cropping), see {ref}`geotransformations`. +Below, a summary of the **georeferencing attributes** of geospatial data objects and the **methods to manipulate these +georeferencing attributes** in different projections, without any data transformation. For georeferenced transformations +(such as reprojection, cropping), see {ref}`geotransformations`. # Attributes -In GeoUtils, the georeferencing syntax is consistent across all geospatial data objects. Additionally, data objects -load only their metadata by default, allowing quick operations on georeferencing without requiring the array data +In GeoUtils, the **georeferencing syntax is consistent across all geospatial data objects**. Additionally, **data objects +load only their metadata by default**, allowing quick operations on georeferencing without requiring the array data (for a {class}`~geoutils.Raster`) or geometry data (for a {class}`~geoutils.Vector`) to be present in memory. +## Metadata summary + +To summarize all the metadata of a geospatial data object, including its georeferencing, {func}`~geoutils.Raster.info` can be used: + + ```{code-cell} ipython3 :tags: [hide-cell] :mystnb: @@ -34,10 +39,6 @@ rast = gu.Raster(gu.examples.get_path("exploradores_aster_dem")) vect = gu.Vector(gu.examples.get_path("exploradores_rgi_outlines")) ``` -## Metadata summary - -To summarize all the metadata of a geospatial data object, including its georeferencing, {func}`~geoutils.Raster.info` can be used: - ```{code-cell} ipython3 # Print raster and vector info rast.info() @@ -65,8 +66,8 @@ can help define a 3D CRS. ## Bounds -Bounds define the spatial extent of geospatial data, and are often useful to calculate extent intersections, or to reproject or crop on a matching extent. -The {attr}`~geoutils.Raster.bounds` of a raster of vector correspond to a {class}`rasterio.coords.BoundingBox` object, composed of the "left", "right", "bottom" and "top" coordinates making up the bounds. +Bounds define the spatial extent of geospatial data, composed of the "left", "right", "bottom" and "top" coordinates. +The {attr}`~geoutils.Raster.bounds` of a raster or a vector is a {class}`rasterio.coords.BoundingBox` object: ```{code-cell} ipython3 # Show bounds attribute of a raster and vector @@ -75,18 +76,19 @@ print(vect.bounds) ``` ```{note} -To define {attr}`~geoutils.Raster.bounds` consistently between rasters and vectors, the {attr}`~geoutils.Vector.bounds` -attribute corresponds to the {attr}`geopandas.GeoDataFrame.total_bounds` attribute (bounds of all geometries). +To define {attr}`~geoutils.Raster.bounds` consistently between rasters and vectors, {attr}`~geoutils.Vector.bounds` + corresponds to {attr}`geopandas.GeoSeries.total_bounds` (total bounds of all geometry features) converted to a {class}`rasterio.coords.BoundingBox`. -To derive per-geometry bounds with a {class}`~geoutils.Vector` (matching {attr}`geopandas.GeoDataFrame.bounds`), use -{attr}`~geoutils.Vector.geom_bounds`. +To reproduce the behaviour of {attr}`geopandas.GeoSeries.bounds` (per-feature bounds) with a +{class}`~geoutils.Vector`, use {attr}`~geoutils.Vector.geom_bounds`. ``` ## Footprints -Reprojections between CRSs deform shapes, including raster or vector extents, thus it is often better to consider a -vectorized footprint. The {class}`~geoutils.Raster.footprint` is a {class}`~geoutils.Vector` object with a single polygon -geometry for which points have been densified, allowing reliable computation of extents between CRSs. +As reprojections between CRSs deform shapes, including extents, it is often better to consider a vectorized footprint +to calculate intersections in different projections. The {class}`~geoutils.Raster.footprint` is a +{class}`~geoutils.Vector` object with a single polygon geometry for which points have been densified, allowing +reliable computation of extents between CRSs. ```{code-cell} ipython3 # Show bounds attribute of a raster and vector @@ -180,7 +182,11 @@ rast_footprint.plot() ## Getting a metric CRS -A metric CRS at the location of the geospatial data can be derived using {func}`geoutils.Raster.get_metric_crs`. +A local metric coordinate system can be estimated for both {class}`Rasters` and {class}`Vectors` through the +{func}`~geoutils.Raster.get_metric_crs` function. + +The metric system returned can be either "universal" (zone of the Universal Transverse Mercator or Universal Polar Stereographic system), or "custom" +(Mercator or Polar projection centered on the {class}`Raster` or {class}`Vector`). ```{code-cell} ipython3 # Get local metric CRS @@ -190,6 +196,8 @@ print(rast.get_metric_crs()) ## Re-set georeferencing metadata +To add? + {func}`geoutils.Vector.set_crs` {func}`geoutils.Raster.set_transform` {func}`geoutils.Raster.set_area_or_point` diff --git a/doc/source/geotransformations.md b/doc/source/geotransformations.md index 66ba0483..01f7ff35 100644 --- a/doc/source/geotransformations.md +++ b/doc/source/geotransformations.md @@ -7,4 +7,8 @@ ## Crop -{attr}`geoutils.Raster.crop` and {attr}`geoutils.Vector.crop` \ No newline at end of file +{attr}`geoutils.Raster.crop` and {attr}`geoutils.Vector.crop` + +## Shift + + diff --git a/doc/source/index.md b/doc/source/index.md index c06fab8a..3d56bfac 100644 --- a/doc/source/index.md +++ b/doc/source/index.md @@ -35,8 +35,9 @@ GeoUtils is built on top of core geospatial packages (Rasterio, GeoPandas) and n (NumPy, Xarray, SciPy) to provide **consistent higher-level functionalities at the interface of raster, vector and point cloud objects** (such as match-reference reprojection, point interpolation or gridding). -It is **tailored to perform quantitative analysis that implicitly understands the intricacies of geospatial data** -(such as nodata values, pixel interpretation) and **to be computationally scalable** by supporting Dask. +It is **tailored to perform quantitative analysis that implicitly understands the intricacies of geospatial data**, +(nodata values, projection, pixel interpretation), through **an intuitive object-based API to foster accessibility**, +and **to be computationally scalable** through Dask. If you are looking to **port your GDAL or QGIS workflow in Python**, GeoUtils is made for you! diff --git a/doc/source/proj_tools.md b/doc/source/proj_tools.md deleted file mode 100644 index d58162fe..00000000 --- a/doc/source/proj_tools.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -file_format: mystnb -jupytext: - formats: md:myst - text_representation: - extension: .md - format_name: myst -kernelspec: - display_name: geoutils-env - language: python - name: geoutils ---- -(proj-tools)= - -# Projection tools - -This section describes projection tools that are common to {class}`Rasters` and {class}`Vectors`, and facilitate -geospatial analysis. - -## Get a metric coordinate system - -A local metric coordinate system can be estimated for both {class}`Rasters` and {class}`Vectors` through the -{func}`~geoutils.Raster.get_metric_crs` function. - -The metric system returned can be either "universal" (zone of the Universal Transverse Mercator or Universal Polar Stereographic system), or "custom" -(Mercator or Polar projection centered on the {class}`Raster` or {class}`Vector`). - -```{code-cell} ipython3 -import geoutils as gu - -# Initiate a raster from disk -rast = gu.Raster(gu.examples.get_path("exploradores_aster_dem")) -rast.info() - -# Estimate a universal metric CRS for the raster -rast.get_metric_crs() -``` - -## Get projected bounds - -Projected bounds can be directly derived from both {class}`Rasters` and {class}`Vectors` through the -{func}`~geoutils.Raster.get_bounds_projected` function. - -```{code-cell} ipython3 -# Get raster bounds in geographic CRS by passing its EPSG code -rast.get_bounds_projected(4326) -``` - -```{important} -When projecting to a new CRS, the footprint shape of the data is generally deformed. To account for this, use {func}`~geoutils.Raster.get_footprint_projected` described below. -``` - -## Get projected footprint - -A projected footprint can be derived from both {class}`Rasters` and {class}`Vectors` through the -{func}`~geoutils.Raster.get_footprint_projected` function. - -For this, the original rectangular footprint polygon lines are densified to respect the deformation during reprojection. - -```{code-cell} ipython3 -# Get raster footprint in geographic CRS -rast_footprint = rast.get_footprint_projected(4326) - -rast_footprint.plot() -``` - -This is for instance useful to check for intersection with other data.