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

Update README.md #6

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update README.md #6

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
137465f
Update README.md
Jochem-L Feb 8, 2024
d6e6a4d
Update README.md
Jochem-L Feb 8, 2024
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
34 changes: 18 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# NSGI coordinate reference system transformation examples

The [NSGI](https://www.nsgi.nl/) is responsible for the CRS (coordinate reference system) of the Netherlands and their relations with international CRSs. The NSGI also gives advices and guidance about the usage of these CRSs. The Guidance document (in: Dutch) ["Handreiking Gebruik coordinaatreferentiesystemen bij uitwisseling en visualisatie van geo-informatie"](https://docs.geostandaarden.nl/crs/crs/) and the [EPSG repository](https://epsg.org/home.html) has documented the advices and guidelines that are relevant for exchange and visualisation of geo information.
The [NSGI](https://www.nsgi.nl/) is responsible for the CRSs (coordinate reference systems) of the Netherlands and their relations with international CRSs. The NSGI also gives advice and guidance about the usage of these CRSs. The Guidance document (in: Dutch) ["Handreiking Gebruik coordinaatreferentiesystemen bij uitwisseling en visualisatie van geo-informatie"](https://docs.geostandaarden.nl/crs/crs/) and the [EPSG repository](https://epsg.org/home.html) has documented the advices and guidelines that are relevant for exchange and visualisation of geoinformation.

## Goal

The goal of this GitHub organisation and the repositories associated with it is to give a technical perspective into how to implement these advices and guidelines.
The goal of this GitHub organisation and the repositories associated with it is to give a technical perspective into how to implement the advice and guidelines.

## Relations

The image below shows the relevant relations between the Dutch and international CRSs. The transformation path between these CRs can be ambiguous and dependent on the use case, especially for transformations between international and dynamic CRSs. NSGI has recommendations for the paths within the Netherlands. Defining these relations by making specific transformation rules within `proj.db` enables users to transform coordinates within the bounds of the European Netherlands, including the Exclusive Economic Zones in a more accurate and consistent way.
The image below shows the relevant relations between the Dutch and international CRSs. The transformation path between these CRSs can be ambiguous and dependent on the use case, especially for transformations between dynamic international CRSs and plate-fixed CRSs. NSGI has recommendations for the transformation procedures for use within the Netherlands. Defining these relations by making specific transformation rules within `proj.db` enables users to transform coordinates within the bounds of the European Netherlands and Caribbean Netherlands, including the Exclusive Economic Zones in a more accurate and consistent way.

![relations](https://raw.githubusercontent.com/GeodetischeInfrastructuur/transformations/main/supported-transformations-nsgi.drawio.svg)

Expand Down Expand Up @@ -38,11 +38,13 @@ The modified `proj.db` is available to download through _github.com_ as:

### :mag: Geodense

A straight line in reality is usually not a straight line in a CRSs, the deflection in the CRS dependents on the location, orientation, length of line segments and the projection used for visualisations or computations. The deflection can cause inconsistency between the same data in different CRSs or compared to reality. To avoid topology issues line segments can be densified.
A straight line in reality (geodesic) is usually not a straight line in a projected CRS. The deviation in the CRS dependents on the location, orientation and length of line segments. For unprojected CRS, the deviation depends on the projection used for visualisation or the computation method that is used. The deviation can cause inconsistency between the same data in different CRSs or compared to reality. To avoid topology issues, line segments can be densified by introducing additional vertices.

Geodense is used to check density and densify `LINESTRING` and `POLYGON` GeoJSON geometries. In other words, this tool can be used to check 'straightness' of a line and introduce new points to compensated for possible deviations that might occur when such a geometry is transformed from a cartographic to a geographic projection (and vice versa). It pre-processes certain geometry types so they are better suited for transformation.
Geodense is used to check the density and to densify `LINESTRING` and `POLYGON` GeoJSON geometries. In other words, this tool can be used to check the magnitude of the deviation of a line segment and introduce new points to that define the correct trajectory. It pre-processes certain geometry types so transformation doesn't affect the topology.

> :exclamation: For context a `LINESTRING` in `EPSG:28992` that would have a length of over 2km could have a deviation of 5mm. With a line of 20km this can be 26cm. [[1]](https://gnss-data.kadaster.nl/misc/docs/langelijnenadvies.pdf)
> :exclamation: For context:
> * a straight line in RD (`EPSG:28992`) with a length of 2 km could have a deviation up to 5 mm in reality (geodesic). For a length of 20 km the deviation can be up to 26 cm. [[1]](https://gnss-data.kadaster.nl/misc/docs/langelijnenadvies.pdf)
> * a straight line in Webmercator (`EPSG:3857`) with a length of 2 km could have a deviation up to 9,7 cm in reality (geodesic). For a length of 20 km the deviation can be up to 9,7 m. [[1]](https://gnss-data.kadaster.nl/misc/docs/langelijnenadvies.pdf)

For an example how to use Geodense one can look at [coordinate-transformation-api](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api).

Expand All @@ -59,7 +61,7 @@ For an example how to use Geodense one can look at [coordinate-transformation-ap
> from geojson_pydantic import Feature
> from pyproj import CRS
>
> feature: Feature = {"type": "Feature","properties": {},"geometry": {"type": "LineString","coordinates": [[156264.906359842570964,601302.588919493253343],[165681.> 964475793502061,605544.313164469087496]]}}
> feature: Feature = {"type": "Feature","properties": {},"geometry": {"type": "LineString","coordinates": [[156264.9064,601302.5889],[165681.9644,605544.3132]]}}
> c = DenseConfig(CRS.from_epsg(28992))
> result: Nested[ReportLineString] = check_density_geometry_coordinates(feature['geometry']['coordinates'], c)
> print(result)
Expand All @@ -74,28 +76,28 @@ Geodense is available as:

> :warning: The Coordinate Transformation API makes use of pyproj. Pyproj has it's own PROJ 'build in' that needs to be updated. By default this can be found `/usr/local/lib/python3.11/site-packages/pyproj/proj_dir/share/proj/proj.db`.

The [coordinate-transformation-api](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api) is written in Python where the modified `proj.db` and Geodense are used together with specific code to create an API that will transform certain CRS and is focused on the European Netherlands including the Exclusive Economic Zones.
The [coordinate-transformation-api](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api) is written in Python where the modified `proj.db` and Geodense are used together with specific code to create an API that will transform certain CRS and is focused on the European and Caribbean Netherlands including the Exclusive Economic Zones.

> :warning: The Coordinate Transformation API offers transformations that are not possible when using only PROJ.

The code for the Coordinate Transformation API is available at:

1. [github.com](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api)
1. [`Dockerfile`](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api/blob/main/Dockerfile)
1. [Dockerfile](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api/blob/main/Dockerfile)

### :whale2: Docker

A Docker image to run your own Coordinate Transformation API, as a backend service, is also available at _github.com_. Running the Coordinate Transformation API in your own container environment gives you full control over the availability of the API.

1. [Docker image](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api/pkgs/container/coordinate-transformation-api)
* [Docker image](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api/pkgs/container/coordinate-transformation-api)

### :globe_with_meridians: Coordinate Transformation API

For demo purposes, we also host this Coordinate Transformation API on the following URL: [`https://api.transformation.nsgi.nl/v2/`](https://api.transformation.nsgi.nl/v2/). This can be used for none-production applications and should not be depended on for high availability.
We also host this Coordinate Transformation API on the following URL: [`https://api.transformation.nsgi.nl/v2/`](https://api.transformation.nsgi.nl/v2/). This can be used for datasets of limited size.

> **example**
>
> :exclamation: For instance don't use this API in a test environment. The API will go down for maintenance, will throttle under 'high' load, and so on. This will impact the "test" results.
> :exclamation: The API should not be used for large amouts of data or when high availability is required. The API could go down for maintenance, will throttle under 'high' load, and so on.
>
> :heavy_check_mark: For implementing these CRSs and transformations in a test environment either:
>
Expand All @@ -106,7 +108,7 @@ For demo purposes, we also host this Coordinate Transformation API on the follow

## API Conformance

The Coordinate Transformation API conforms to certain degree to the following specification:
The Coordinate Transformation API conforms to certain degree to the following specifications:

| spec | compliance |
| --- | --- |
Expand All @@ -115,13 +117,13 @@ The Coordinate Transformation API conforms to certain degree to the following sp
| NL-API | [report](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api/blob/main/docs/NL-API.md) |
| KP-API geospatial | [report](https://github.com/GeodetischeInfrastructuur/coordinate-transformation-api/blob/main/docs/KP-API-geospatial.md) |

> :warning: The coordinate transformation API only transforms user input and doesn't contain something like a 'state'. It therefor doesn't conform to a traditional data object or feature collection API (like OGC API features), on which these specs (above) are primarily focussed. So specification requirements or recommendations focussed on certain type of query parameters cannot be applied. Reasoning to including these reports regarding compliance (at least our current assumption) is that this can/will be used in environments that so implement those kind of API's. Having these reports will highlight the differences and similarities between the API's
> :warning: The coordinate transformation API only performs coordinate transformation of the user input and doesn't contain something like a 'state'. Therefore, it doesn't conform to a traditional data object or feature collection API (like OGC API features), on which the above specifications are primarily focussed. So specification requirements or recommendations focussed on certain type of query parameters cannot be applied. The reason to include these reports regarding compliance (at least our current assumption) is that this can/will be used in environments that implement those kind of APIs. Having these reports will highlight the differences and similarities between the APIs

## Examples

### QGIS

The following instructions are for configuring QGIS on Windows to use the modified `proj.db` by GeodetischeInfrastructuur.
The following instructions are for configuring QGIS on Windows to use the modified `proj.db` by NSGI.

Steps:

Expand Down Expand Up @@ -161,7 +163,7 @@ Steps:
in_crs=CRS.from_epsg(7931)
out_crs=CRS.from_epsg(28992)
t=Transformer.from_crs(in_crs, out_crs, always_xy=True)
input_point = (5,52, 43)
input_point = (5, 52, 43)
expected_output_point = (128410.0958, 445806.496, 43.0)
output_point=tuple(map(lambda x: float("{:.4f}".format(x)),t.transform(*input_point)))
assert output_point == expected_output_point, f"expected output is {expected_output_point}, was {output_point}"
Expand Down