Terminology

CRS

A Coordinate Reference System defines how coordinate labels are related to real locations on Earth. XProj uses pyproj.crs.CRS objects to handle those reference systems.

Spatial reference coordinate

An Xarray scalar coordinate that usually declares a specific CRS via its metadata. CF conventions use the term grid mapping variable for almost the same concept (the only difference is that a grid mapping variable is a data variable, not a coordinate, although Xarray’s builtin CF decoders automatically promote it as a coordinate). XProj associates a CRSIndex to such coordinate. The name and the value of the coordinate is arbitrary, although spatial_ref is a common name used by default in rioxarray and odc-geo (inspired by GDAL).

CRS-aware index

Any custom xarray.Index that implements data selection, alignment and/or other functionality that depends on a CRS. It is usually associated with one or more Xarray coordinate variables with spatial labels (e.g., x/y or latitude/longitude grid point labels, shapely.Geometry features, etc.). It is distinct from a CRSIndex, which is exclusively associated with a spatial reference coordinate. XProj identifies an Xarray index as CRS-aware if the latter implements the proj index interface.

Proj index interface

A set of XProj-specific “hook” methods that can be implemented in a CRS-aware index and that allow executing custom logic (e.g., coordinate transformation) or updating the internal state of the index via XProj’s public API. It is also used by XProj to access the index’s CRS. The index interface is defined in ProjIndexMixin, although it is not required for an Xarray Index to inherit from this mixin class.

Proj accessor interface

A set of XProj-specific “hook” methods that can be implemented in an Xarray Dataset or DataArray accessor and that allow executing custom logic (e.g., re-projection) or updating the internal state of the accessor via XProj’s public API. The proj accessor interface is defined in ProjAccessorMixin, from which the accessor class should inherit.