From 6ed7880e885073a72255a315979529325e3ca74d Mon Sep 17 00:00:00 2001 From: Doug Wright Date: Wed, 9 Nov 2022 17:56:31 +0000 Subject: [PATCH] Document custom conversions --- CHANGELOG.md | 1 + docs/coordinate_conversions_hard.rst | 2 + docs/custom_conversions.rst | 103 +++++++++++++++++++ docs/custom_coordinate_reference_systems.rst | 12 ++- docs/index.rst | 1 + 5 files changed, 116 insertions(+), 3 deletions(-) create mode 100644 docs/custom_conversions.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f74f3849..b46016c9d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ ## [5.1.0] - 2022-xx-xx ### Added - Support for 3D projected coordinates +- Support for custom coordinate reference systems and custom conversions ### Changed - Updates to data for ITRF, WGS84, Australia, Belgium, Canada, France, Germany, Iceland, Indonesia, Ireland, Japan, Luxembourg, Norway, North Macedonia, UK and USA diff --git a/docs/coordinate_conversions_hard.rst b/docs/coordinate_conversions_hard.rst index 8700b8244..d11bf2134 100644 --- a/docs/coordinate_conversions_hard.rst +++ b/docs/coordinate_conversions_hard.rst @@ -1,3 +1,5 @@ +.. _coordinate_conversions_hard: + The hard way ============ Each type of ``Point`` has methods you can invoke to run well-known algorithmic conversions on its coordinates. diff --git a/docs/custom_conversions.rst b/docs/custom_conversions.rst new file mode 100644 index 000000000..49eb32bad --- /dev/null +++ b/docs/custom_conversions.rst @@ -0,0 +1,103 @@ +Custom conversions +================== + +.. note:: + In ISO 19111 terminology, when converting points between one CRS and another, a distinction is drawn between a + conversion and a transformation. PHPCoord uses the words interchangeably. + +In addition to simply :ref:`invoking a particular coordinate conversion method with the parameters of your choice`, +PHPCoord also supports registering a custom conversion so that you can :ref:`use easy mode` +thereafter. + +Adding a custom coordinate transformation to PHPCoord is a 2-step process. Step 1 is to register the *coordinate operation* +within the system. A coordinate operation is the combination of the conversion method (e.g. Transverse Mercator or +Molodensky-Badekas, together any parameters that particular formula requires). Step 2 is to register that particular +coordinate operation as a way to transform 1 CRS to another. + +The reason for the 2-step process is because the same method/parameters are often used across multiple different +CRS pairs - e.g. the projection method and params for any particular US State Plane conversion remain constant across +NAD83 revisions. Keeping this conceptual separation even for custom conversions helps to keep PHPCoord internals clean. + +.. code-block:: php + + // step 1, register an operation + + PHPCoord\CoordinateOperation\CoordinateOperations::registerCustomOperation( + string $srid, + string $name, + string $methodSrid, + BoundingArea $extent, + array $params + ); + + // step 2, register that operation as a way to convert between 2 CRSs + + PHPCoord\CoordinateOperation\CoordinateOperations::registerCustomTransformation( + string $operationSrid, + string $name, + string $sourceCRSSrid, + string $targetCRSSrid, + float $accuracy // in metres, used by easy-mode conversion to pick the most accurate option available + ); + +For example, to construct a conversion to a hypothetical GDA2020 with Sydney Opera House as the prime meridian rather +than Greenwich: + +.. code-block:: php + + new Degree(-151.214167), + ] + ); + + // step 2, register that operation as a way to convert between 2 CRSs + CoordinateOperations::registerCustomTransformation( + 'urn:yourcompany:geo:coordinateOperation:GDA2020-greenwich-sydney', + 'GDA2020 (Greenwich) to GDA2020 (Sydney)', + Geographic2D::fromSRID(Geographic2D::EPSG_GDA2020), + 'urn:yourcompany:geo:crs:GDA2020-sydney', + 0.0 + ); + + // step 3, use it + $from = GeographicPoint::create( + Geographic2D::fromSRID(Geographic2D::EPSG_GDA2020), + new Degree(-33.858611), + new Degree(151.214167) + ); + $to = $from->convert( + Geographic2D::fromSRID('urn:yourcompany:geo:crs:GDA2020-sydney') + ); + + $latitude = $point->getLatitude(); // -33.858611 + $longitude = $point->getLongitude(); // 0.0 + +.. tip:: + A SRID (spatial reference identifier), is a just a unique string that can be used to identify the specific CRS or + other geospatial type in question. The PHPCoord built-in systems all use an URN for this purpose, but you can use + anything you like as long as it is unique. diff --git a/docs/custom_coordinate_reference_systems.rst b/docs/custom_coordinate_reference_systems.rst index 20e67193f..8cd08489e 100644 --- a/docs/custom_coordinate_reference_systems.rst +++ b/docs/custom_coordinate_reference_systems.rst @@ -52,6 +52,8 @@ used exactly like any other built into PHPCoord. To register, call the appropria BoundingArea $extent ); +For example + .. code-block:: php