Skip to content

Normalize CRS handling #2116

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

Open
wants to merge 12 commits into
base: master
Choose a base branch
from
+1,107 −1,119
Open

Normalize CRS handling #2116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
d790217
Normalize CRS handling
webb-ben Sep 19, 2025
98c2fe8
Normalize storage_crs
webb-ben Sep 19, 2025
addcf87
Update crs.py
webb-ben Sep 19, 2025
2be130c
Cleanup
webb-ben Sep 19, 2025
9004fe2
Use CrsTransformSpec for all CRS conversion
webb-ben Sep 22, 2025
3553272
Create `get_transform_from_spec`
webb-ben Sep 22, 2025
ec594bf
Add additional tests
webb-ben Sep 22, 2025
a6b5f89
Reduce diff
webb-ben Sep 22, 2025
b3f80c3
Revert transform_bbox changes
webb-ben Sep 22, 2025
34237c3
Update documentation
webb-ben Sep 22, 2025
ddc876e
Update CRS docs
webb-ben Sep 23, 2025
8fb0d6e
Update plugins.rst
webb-ben Oct 21, 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
33 changes: 16 additions & 17 deletions docs/source/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,21 +219,25 @@ default.
end: 2007-10-30T08:57:29Z # end datetime in RFC3339
trs: http://www.opengis.net/def/uom/ISO-8601/0/Gregorian # TRS
providers: # list of 1..n required connections information
# provider name
# see pygeoapi.plugin for supported providers
# for custom built plugins, use the import path (e.g. mypackage.provider.MyProvider)
# see Plugins section for more information
- type: feature # underlying data geospatial type: (allowed values are: feature, coverage, record, tile, edr)
default: true # optional: if not specified, the first provider definition is considered the default
name: CSV
- type: feature # underlying data geospatial type. Allowed values are: feature, coverage, record, tile, edr
name: CSV # required: plugin name or import path. See Plugins section for more information.
data: tests/data/obs.csv # required: the data filesystem path or URL, depending on plugin setup
id_field: id # required for vector data, the field corresponding to the ID
uri_field: uri # optional field corresponding to the Uniform Resource Identifier (see Linked Data section)
time_field: datetimestamp # optional field corresponding to the temporal property of the dataset
title_field: foo # optional field of which property to display as title/label on HTML pages
properties: # optional: only return the following properties, in order

# optional fields
uri_field: uri # field corresponding to the Uniform Resource Identifier (see Linked Data section)
time_field: datetimestamp # field corresponding to the temporal property of the dataset
title_field: foo # field of which property to display as title/label on HTML pages
default: true # if not specified, the first provider definition is considered the default
properties: # if specified, return only the following properties, in order
- stn_id
- value
format: # default format
name: GeoJSON # required: format name
mimetype: application/json # required: format mimetype
options: # optional options to pass to provider (i.e. GDAL creation)
option_name: option_value
include_extra_query_parameters: false # include extra query parameters that are not part of the collection properties (default: false)
# editable transactions: DO NOT ACTIVATE unless you have setup access control beyond pygeoapi
editable: true # optional: if backend is writable, default is false
# coordinate reference systems (CRS) section is optional
Expand All @@ -245,12 +249,7 @@ default.
- http://www.opengis.net/def/crs/EPSG/0/4326
storage_crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84 # optional CRS in which data is stored, default: as 'crs' field
storage_crs_coordinate_epoch: : 2017.23 # optional, if storage_crs is a dynamic coordinate reference system
format: # optional default format
name: GeoJSON # required: format name
mimetype: application/json # required: format mimetype
options: # optional options to pass to provider (i.e. GDAL creation)
option_name: option_value
include_extra_query_parameters: false # include extra query parameters that are not part of the collection properties (default: false)
always_xy: false # optional should CRS respect axis ordering
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

always_xy: false # optional should CRS respect axis ordering. (i.e. two spaces before hash, as a rule)


hello-world: # name of process
type: process # REQUIRED (collection, process, or stac-collection)
Expand Down
108 changes: 86 additions & 22 deletions docs/source/crs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,42 +3,95 @@
CRS support
===========

pygeoapi supports the complete specification: `OGC API - Features - Part 2: Coordinate Reference Systems by Reference corrigendum`_.
The specified CRS-related capabilities are available for all Feature data Providers.
pygeoapi supports multiple Coordinate Reference Systems (CRS).
This enables the import and export of any data according to dedicated projections.
A "projection" is specified with a CRS identifier.
In particular CRS support allows for the following:

* to specify the CRS in which the data is stored, in pygeoapi the `storage_crs` config option
* to specify the list of valid CRS representations, in pygeoapi the `crs` config option
* to publish these in the collection metadata
* the `bbox-crs=` query parameter to indicate that the `bbox=` parameter is encoded in that CRS
* the `crs=` query parameter for a collection or collection item
* the HTTP response header `Content-Crs` denotes the CRS of the Feature(s) in the data returned

Although GeoJSON mandates WGS84 in longitude, latitude order, the client and server may still agree on other CRSs.


Background
----------

pygeoapi implements the complete specification:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

pygeoapi implements the `OGC API - Features - Part 2: Coordinate Reference Systems by Reference`_ specification.

Under the hood, pygeoapi uses the `pyproj`_ Python package.

.. note::

   For more information on implementing CRS on custom plugins, see `Implementation`_.

`OGC API - Features - Part 2: Coordinate Reference Systems by Reference corrigendum`_.
Under the hood, pygeoapi uses the well-known `pyproj`_ Python wrapper to the `PROJ`_ library.
For information on implementing CRS on custom plugins, see `Implementation`_.

CRS support exists for the following OGC APIs:

.. csv-table::
:header: OGC API, bbox-crs, filter-crs, crs
:align: left

:ref:`OGC API - Features<ogcapi-features>`,✅,✅,✅
:ref:`OGC API - Maps<ogcapi-maps>`,✅,❌,❌
:ref:`OGC API - Coverages<ogcapi-coverages>`,✅,❌,❌

Configuration
-------------

For details visit the :ref:`configuration` section for Feature Providers. At this moment only the 'URI' CRS notation format is supported.
The CRS of a collection is defined in the provider block of your resource.
The configuration controls how the `crs` related query parameters behave.


* `crs` - list of CRSs supported
* `storage_crs` - CRS in which the data is stored (must be in `crs` list)
* `storage_crs_coordinate_epoch` - epoch of `storage_crs` for a dynamic coordinate reference system
* ``crs`` - list of CRSs supported
* ``storage_crs`` - CRS in which the data is stored (must be in `crs` list)
* ``storage_crs_coordinate_epoch`` - epoch of `storage_crs` for a dynamic coordinate reference system
* ``always_xy`` - CRS should ignore authority on axis order, disobeying `ISO-19111`_ (default: false)

.. note::
bbox-crs and filter-crs are used to convert the request geometry to the configured ``storage_crs``.
An error will be returned for any interaction with CRS not included in the configured ``crs`` list.

These per-Provider configuration fields are all optional. Default for CRS-values is `http://www.opengis.net/def/crs/OGC/1.3/CRS84`, so "WGS84" with lon/lat axis ordering.
If the storage CRS of the spatial feature collection is a dynamic coordinate reference system,
`storage_crs_coordinate_epoch` configures the coordinate epoch of the coordinates.
The per-Provider configuration fields are all optional,
with the following as default configuration:

.. code-block:: yaml

crs:
- http://www.opengis.net/def/crs/OGC/1.3/CRS84
- http://www.opengis.net/def/crs/OGC/1.3/CRS84h
storage_crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84

.. note::
Configuration is done with URI formats like http://www.opengis.net/def/crs/OGC/1.3/CRS84.
Both `URI` and `URN` CRS notation format are supported.
The `EPSG:` format like EPSG:4326 is outside the scope of the OGC standard.

There is also support for CRSs that support height like `http://www.opengis.net/def/crs/OGC/1.3/CRS84h`. In that case
bbox parameters (see below) may contain 6 coordinates.

Metadata
--------

The conformance class `http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs` is present as a `conformsTo` field
in the root landing page response.
The conformance class http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs is
present as a `conformsTo` field in the root landing page response.

The configured CRSs, or their defaults, `crs` and `storageCrs` and optionally `storageCrsCoordinateEpoch` will be present in the "Describe Collection" response.

.. note::
If the storage CRS of the spatial feature collection is a dynamic coordinate reference system,
`storage_crs_coordinate_epoch` configures the coordinate epoch of the coordinates.

.. note::
There is also support for CRSs that support height like `http://www.opengis.net/def/crs/OGC/1.3/CRS84h`. In that case
bbox parameters (see below) may contain 6 coordinates.

Parameters
----------

The `items` query supports the following parameters:

* `crs` - the CRS in which Features coordinates should be returned, also for the 'get single item' request
* `bbox-crs` - the CRS of the `bbox` parameter (only for Providers that support the `bbox` parameter)
* ``crs`` - the CRS in which Features coordinates should be returned, also for the 'get single item' request
* ``bbox-crs`` - the CRS of the `bbox` parameter (for Providers that support the `bbox` parameter)
* ``filter-crs`` - the CRS of the CQL filter expression (for Providers that support `CQL` filters)

If any or both of these parameters are specified, their CRS-value should be from the advertised CRS-list in the Collection metadata (see above).

Expand All @@ -52,21 +105,29 @@ Note that the values of these parameters may need to be URL-encoded.
Implementation
--------------

CRS and BBOX CRS support is implemented for all Feature Providers. Some details may help understanding (performance) implications.
CRS and BBOX CRS support is implemented for all Feature Providers.
Some details may help understanding (performance) implications.

BBOX CRS Parameter
bbox-crs Parameter
^^^^^^^^^^^^^^^^^^

The `bbox-crs` parameter is handled at the common level of pygeoapi, thus transparent for Feature Providers.
Obviously the Provider should support `bbox`.
A transformation of the `bbox` parameter is performed
The ``bbox-crs`` parameter is handled at the common level of pygeoapi.
A transformation of the request `bbox` parameter is performed
according to the `storage_crs` configuration. Then the (transformed) `bbox` is passed with the
other query parameters to the Provider instance.

CRS Parameter
filter-crs Parameter
^^^^^^^^^^^^^^^^^^^^

The ``filter-crs`` parameter is handled at the common level of pygeoapi.
A transformation of the request `CQL` filter is performed
according to the `storage_crs` configuration. Then the (transformed) `filter` is passed with the
other query parameters to the Provider instance.

crs Parameter
^^^^^^^^^^^^^

When the value of the `crs` parameter differs from the Provider data Storage CRS, the response Feature coordinates
When the value of the ``crs`` parameter differs from the Provider data Storage CRS, the response Feature coordinates
need to be transformed to that CRS. As some Feature Providers like PostgreSQL or OGR may support native
coordinate transformation, pygeoapi delegates transformation to those Providers, passing the `crs` with the other query parameters.

Expand Down Expand Up @@ -245,4 +306,7 @@ Or you may specify both `crs` and `bbox-crs` and thus `bbox` in that CRS `http:/
.
.

.. _`ISO-19111`: http://docs.opengeospatial.org/as/18-005r5/18-005r5.html
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://docs.ogc.org/as/18-005r5/18-005r5.html

.. _`OGC API - Features - Part 2: Coordinate Reference Systems by Reference corrigendum`: https://docs.opengeospatial.org/is/18-058r1/18-058r1.html
.. _`PROJ`: https://proj.org/
.. _`pyproj`: https://pyproj4.github.io/pyproj/stable
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://pyproj4.github.io/pyproj

3 changes: 3 additions & 0 deletions docs/source/plugins.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ In this section we will explain how pygeoapi provides plugin architecture for da

Plugin development requires knowledge of how to program in Python as well as Python's package/module system.

.. seealso::
:ref:`publishing` for configuration of default plugins.

Overview
--------

Expand Down
2 changes: 1 addition & 1 deletion docs/source/publishing/ogcapi-coverages.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ The `Xarray`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data.
time_field: time
# optionally specify the coordinate reference system of your dataset
# else pygeoapi assumes it is WGS84 (EPSG:4326).
storage_crs: 4326
storage_crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84
format:
name: netcdf
mimetype: application/x-netcdf
Expand Down
8 changes: 1 addition & 7 deletions docs/source/publishing/ogcapi-edr.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ The `xarray-edr`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data
time_field: time
# optionally specify the coordinate reference system of your dataset
# else pygeoapi assumes it is WGS84 (EPSG:4326).
storage_crs: 4326
storage_crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84
format:
name: netcdf
mimetype: application/x-netcdf
Expand Down Expand Up @@ -94,11 +94,6 @@ The `xarray-edr`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data
S3 URL. Any parameters required to open the dataset using fsspec can be added
to the config file under `options` and `s3`, as shown above.

.. note::
When providing a `storage_crs` value in the EDR configuration, specify the
coordinate reference system using any valid input for
`pyproj.CRS.from_user_input`_.


SensorThingsEDR
^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -147,5 +142,4 @@ Data access examples
.. _`xarray`: https://docs.xarray.dev/en/stable/
.. _`NetCDF`: https://en.wikipedia.org/wiki/NetCDF
.. _`Zarr`: https://zarr.readthedocs.io/en/stable
.. _`pyproj.CRS.from_user_input`: https://pyproj4.github.io/pyproj/stable/api/crs/coordinate_system.html#pyproj.crs.CoordinateSystem.from_user_input
.. _`OGC Environmental Data Retrieval (EDR) (API)`: https://ogcapi.ogc.org/edr
8 changes: 1 addition & 7 deletions docs/source/publishing/ogcapi-features.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,19 +37,13 @@ parameters.
`TinyDB`_,✅/✅,results/hits,✅,✅,✅,✅,✅,❌,✅,✅

.. note::

* All Providers that support `bbox` also support the `bbox-crs` parameter. `bbox-crs` is handled within pygeoapi core.
* All Providers support the `crs` parameter to reproject (transform) response data. Some, like PostgreSQL and OGR, perform this natively.
For more information on CRS transformations, see :ref:`crs`.


Connection examples
-------------------

Below are specific connection examples based on supported providers.
To support `crs` on queries, one needs to configure both a list of supported CRSs, and a 'Storage CRS'.
See also :ref:`crs` and :ref:`configuration`. When no CRS information is configured the
default CRS/'Storage CRS' value http://www.opengis.net/def/crs/OGC/1.3/CRS84 is assumed.
That is: WGS84 with lon,lat axis-ordering as in standard GeoJSON.

CSV
^^^
Expand Down
Loading