diff --git a/docs/mkdocs/tutorials/geodetic-projects-and-queries.md b/docs/mkdocs/tutorials/geodetic-projects-and-queries.md new file mode 100644 index 000000000..c44219ef6 --- /dev/null +++ b/docs/mkdocs/tutorials/geodetic-projects-and-queries.md @@ -0,0 +1,81 @@ +# Geodetic projects and querying within another spatial reference system + +This tutorial features creating a project in a user-specified geographic +spatial reference system and +spatially querying SEEREP from another spatial reference system. + +The transforms are implemented with the help of [PROJ](https://proj.org/en/stable/)s +C API. + +## Creating geodetic projects + +Source: +[examples/python/gRPC/meta/gRPC_fb_createGeodeticCoordProject.py](https://github.com/agri-gaia/seerep/blob/main/examples/python/gRPC/meta/gRPC_fb_createGeodeticCoordProject.py) + +```python +--8<-- "https://raw.githubusercontent.com/agri-gaia/seerep/geoCordPolygonQuery/examples/python/gRPC/meta/gRPC_fb_createGeodeticCoordProject.py:15:28" +``` + +This function call creates a project in the reference system `EPSG:4326` +with its topocentric origin at `latitude=52.358199`, `longitude=8.279679` +and `altitude=4`. +With `latitude` and `longitude` in decimal degree and `altitude` in meters. +Altitude specifies the ellipsoidal height of the origin. +The `"2"` string here defines the name of the projects map frame. + +**NOTE**: Currently only SRIDs(Spatial Reference System Identifiers) +with geographic coordinates are supported. +The coordinates defined by the SRID also have to be in latitude first +and longitude second order. + +## Query with polygons defined in other spatial reference systems + +Source: [examples/python/gRPC/images/gRPC_fb_queryImage.py](https://github.com/agri-gaia/seerep/blob/main/examples/python/gRPC/images/gRPC_fb_queryImages.py) + +```python +--8<-- "https://raw.githubusercontent.com/agri-gaia/seerep/geoCordPolygonQuery/examples/python/gRPC/images/gRPC_fb_queryImages.py:146:169" +``` + +**NOTE**: This is not the full function definition. + +This queries SEEREP from another SRID, in this case `"EPSG:3857"`, in which the +spatial polygon has to be defined in. +In this case every SRID supported by PROJ can be used, `x` is the first coordinate +and `y` the second. + +According to the used SRID this can mean a different type of +coordinate. When using `"EPSG:4314"` for example `x` would be the `latitude` and +`y` the `longitude` in decimal degree (see [EPSG:4314](https://epsg.io/4314)) +or when using `"EPSG:32632"` `x` would be `easting` and `y` would be `northing` +in meters (see [EPSG:32632](https://epsg.io/32632)). + +The polygon will be transformed to the projects CRS (coordinate reference system) +and then projected to topocentric using PROJ in the backend. + +**NOTE**: These transformations can have strong deviations or even use ballpark +transformations with even larger errors in the resulting positions depending on +the different SRIDs used. +For testing [https://epsg.io/](https://epsg.io/) can be used, +it uses PROJ in the backend as well. + +## Transforms backend + +For the first stage transform +(transforming coordinates to the projects coordinate reference system) the +[cs2cs](https://proj.org/en/stable/apps/cs2cs.html) [C API equivalent](https://proj.org/en/stable/development/reference/functions.html#c.proj_create_crs_to_crs) +is used. The following example essentially simulates that step. + +```bash +cs2cs EPSG:4326 EPSG:3857 <<<"52.3588799817 8.2796787735 -100.0000000000" +``` + +In the second stage projection to topocentric a `PROJ` string, like in the +following [cct](https://proj.org/en/stable/apps/cct.html) pipeline, is used. + +```bash +echo "8.2796787735 52.3588799817 -100.0000000000" | cct -d 10 +proj=pipeline ++step +proj=cart +step +proj=topocentric +lat_0=52.358199 +lon_0=8.279679 +h_0=0.000000 +``` + +The source for the transforms can be found [here](https://github.com/agri-gaia/seerep/blob/geoCordPolygonQuery/seerep_srv/seerep_core/src/core_project.cpp) +in the `transformToMapFrame` method. diff --git a/examples/python/gRPC/meta/gRPC_fb_createGeodeticCoordProject.py b/examples/python/gRPC/meta/gRPC_fb_createGeodeticCoordProject.py index 88a49c4d4..029e70ea2 100755 --- a/examples/python/gRPC/meta/gRPC_fb_createGeodeticCoordProject.py +++ b/examples/python/gRPC/meta/gRPC_fb_createGeodeticCoordProject.py @@ -1,4 +1,7 @@ #!/usr/bin/env python3 +# NOTE: This file is referenced in the following mkdocs files: +# geodetic-projects-and-queries.md +# Any changes done in here will be reflected in there import flatbuffers from grpc import Channel from seerep.fb import ProjectInfo diff --git a/mkdocs.yml b/mkdocs.yml index 136ef24e3..e4ee4788b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -82,6 +82,7 @@ nav: - Overview: 'tutorials/overview.md' - Creating & retrieving projects: 'tutorials/projects.md' - Sending & Querying Images: 'tutorials/images.md' + - Projects & Queries in other spatial reference systems: 'tutorials/geodetic-projects-and-queries.md' - Writing Python Tests: 'tutorials/writing-python-tests.md' - Writing Python Examples: 'tutorials/writing-python-examples.md'