Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add draft re-write of intro docs #190

Draft
wants to merge 3 commits into
base: develop
Choose a base branch
from
Draft

Add draft re-write of intro docs #190

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
003ddfd
Add draft re-write of intro docs
robbibt Nov 29, 2024
d8728d2
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 29, 2024
7242c34
Apply minor edits and add link to xarray extension page
caitlinadams Jan 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 38 additions & 17 deletions docs/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,35 @@
Overview
########

This library combines geometry shape classes from shapely_ with CRS from pyproj_ to provide
projection aware :py:class:`~odc.geo.geom.Geometry`. It exposes all the functionality provided by
:py:mod:`shapely` modules, but will refuse operations between geometries defined in different
projections. Geometries can be brought into a common projection with
:py:meth:`~odc.geo.geom.Geometry.to_crs` method.
The ``odc-geo`` library provides powerful tools for geospatial data manipulation in Python, including working
with coordinate reference systems, grid definitions, and spatial transformations.

Based on that foundation a number of data types and utilities useful for working with geospatial
metadata are implemented. Of particular importance is :py:class:`~odc.geo.geobox.GeoBox`. It is an
abstraction for a geo-registered bounded pixel plane where a linear mapping from pixel coordinates
to the real world is defined.
The library integrates closely with the Python geospatial ecosystem (including shapely_ and pyproj_),
providing a projection-aware :py:class:`~odc.geo.geom.Geometry` class that simplifies complex geospatial
operations. Geo-registered raster analysis is supported through an ``.odc.`` `Xarray extension`_ that is automatically
added to :py:class:`xarray.Dataset` and :py:class:`xarray.DataArray` data loaded using the `Open Data Cube`_
or rioxarray_ - exposing important geospatial metadata and a variety of useful geospatial analysis tools.

Key features
************

* **Vector and raster reprojection:** Efficiently reproject data between coordinate reference systems using high-performance reprojection utilities powered by dask_
* **Geospatial metadata handling:** Inspect and manipulate geo-registered raster metadata using a standardised :py:class:`~odc.geo.geobox.GeoBox` pixel grid model
* **Spatial grid definition:** Generate precise :py:class:`~odc.geo.gridspec.GridSpec` tile grids for seamless large-scale analysis
* **Cloud-optimised data:** Export geo-registered raster data into optimised cloud-optimised GeoTIFF files
* **Spatial analysis:** Rasterise, mask and clip vector and raster data
* **Interactive visualisation:** Plot and explore spatial vector and raster data on an interactive map

.. This library combines geometry shape classes from shapely_ with CRS from pyproj_ to provide
.. projection aware :py:class:`~odc.geo.geom.Geometry`. It exposes all the functionality provided by
.. :py:mod:`shapely` modules, but will refuse operations between geometries defined in different
.. projections. Geometries can be brought into a common projection with
.. :py:meth:`~odc.geo.geom.Geometry.to_crs` method.

.. Based on that foundation a number of data types and utilities useful for working with geospatial
.. metadata are implemented. Of particular importance is :py:class:`~odc.geo.geobox.GeoBox`. It is an
.. abstraction for a geo-registered bounded pixel plane where a linear mapping from pixel coordinates
.. to the real world is defined.

.. jupyter-execute::
:stderr:
Expand All @@ -21,13 +40,13 @@ to the real world is defined.
2_250_000, -1_000_000),
"epsg:3577", resolution=1000)

To make working with geo-registered raster data easier an integration with xarray_ is provided.
Importing ``odc.geo.xr`` enables ``.odc.`` accessor on every :py:class:`xarray.Dataset` and
:py:class:`xarray.DataArray` that exposes geospatial information of the raster loaded with `Open
Datacube`_ or rioxarray_. Methods for attaching geospatial information to xarray objects in a robust
way are also provided. Geospatial information attached in this way survives most operations you
might do on the data: basic mathematical operations, type conversions, cropping, serialization to
most formats like zarr, netcdf, GeoTIFF.
.. To make working with geo-registered raster data easier an integration with xarray_ is provided.
.. Importing ``odc.geo.xr`` enables ``.odc.`` accessor on every :py:class:`xarray.Dataset` and
.. :py:class:`xarray.DataArray` that exposes geospatial information of the raster loaded with `Open
.. Datacube`_ or rioxarray_. Methods for attaching geospatial information to xarray objects in a robust
.. way are also provided. Geospatial information attached in this way survives most operations you
.. might do on the data: basic mathematical operations, type conversions, cropping, serialization to
.. most formats like zarr, netcdf, GeoTIFF.

Installation
############
Expand All @@ -47,8 +66,10 @@ Using Conda
conda install -c conda-forge odc-geo


.. _dask: https://docs.dask.org/en/stable/
.. _rioxarray: https://corteva.github.io/rioxarray/stable/
.. _xarray: https://docs.xarray.dev/en/stable/
.. _shapely: https://shapely.readthedocs.io/en/stable/manual.html
.. _pyproj: https://pyproj4.github.io/pyproj/stable/
.. _`Open Datacube`: https://github.com/opendatacube/datacube-core
.. _`Open Data Cube`: https://github.com/opendatacube/datacube-core
.. _`Xarray extension`: https://docs.xarray.dev/en/stable/internals/extending-xarray.html
Loading