From 137465f60a51c04881e6de920eba7a048938865d Mon Sep 17 00:00:00 2001 From: Jochem-L <55313523+Jochem-L@users.noreply.github.com> Date: Thu, 8 Feb 2024 13:45:34 +0100 Subject: [PATCH 1/2] Update README.md --- README.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 3c9550e..2e0d01a 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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). @@ -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) @@ -74,24 +76,24 @@ 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 and should not be used for large amouts of data or when high availability is required. > **example** > @@ -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 | | --- | --- | @@ -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: @@ -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}" From d6e6a4da3afac714c91ca354755797fbce9685e4 Mon Sep 17 00:00:00 2001 From: Jochem-L <55313523+Jochem-L@users.noreply.github.com> Date: Thu, 8 Feb 2024 15:59:26 +0100 Subject: [PATCH 2/2] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2e0d01a..9ed8191 100644 --- a/README.md +++ b/README.md @@ -93,11 +93,11 @@ A Docker image to run your own Coordinate Transformation API, as a backend servi ### :globe_with_meridians: Coordinate Transformation API -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 and should not be used for large amouts of data or when high availability is required. +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: >