WL#8684: ST_Transform

This WL implements ST_Transform(<geometry>, <srid>), which will transform the input geometry to the specified spatial reference system (SRS), identified by SRID.

In general, this allows the user to convert geometries between various projected SRSs ("maps"), between projected SRSs and geographic SRSs (longitude-latitude on an ellipsoid), and between geographic SRSs. However, in this WL the scope is limited to conversions between different geographic SRSs. Conversions to/from different projections will be implemented in future WLs.

The transformation algorithms are provided by Boost.Geometry.

Closes BUG#88871 (feature request for ST_Transform).

F-1

The function MUST return NULL if one or both of its arguments are NULL.

F-2

The function MUST NOT return NULL if none of its arguments are NULL.

F-3

The function MUST raise ER_GIS_INVALID_DATA during function evaluation if the geometry argument is not a syntactically well-formed geometry.

F-4

The function MUST raise ER_SRS_NOT_FOUND during function evaluation if either the SRID of the geometry or the target SRID is not the SRID of an existing SRS.

F-5

The function MUST raise ER_TRANSFORM_SOURCE_SRS_NOT_SUPPORTED if the geometry is in an SRS that MySQL can't transform from (currently all Cartesian SRSs).

F-6

The function MUST raise ER_TRANSFORM_TARGET_SRS_NOT_SUPPORTED if the target SRID is the SRID of an SRS that MySQL can't transform to (currently all Cartesian SRSs).

F-7

The function MUST raise ER_TRANSFORM_SOURCE_SRS_MISSING_TOWGS84 if the SRS of the geometry is not WGS 84 and has no TOWGS84 clause.

F-8

The function MUST raise ER_TRANSFORM_TARGET_SRS_MISSING_TOWGS84 if the target SRS is not WGS 84 and has no TOWGS84 clause.

F-9

If there are no errors, and none of the parameters are NULL, the function MUST return a geometry transformed to the target SRS. I.e., a geometry of the same type as the input geometry where all the coordinates have been transformed to the new SRS. The SRID of the result MUST be the same as the SRID parameter.

F-10

If the target SRID is the same as the SRID of the geometry, and the SRID refers to an existing SRS, the function MUST return the input geometry. This applies also if transformations to/from the SRS are not allowed in general.

NF-1

The function MUST be non-nullable if both arguments are non-nullable.

NF-2

The function MUST be nullable if at least one argument is nullable.

I-1

No new files.

I-2

Interface SQL01 is extended with 1 new function: ST_Transform(geometry, target srid).

I-3

No new commands.

I-4

No new tools.

I-5

Interface ERR01 is extended with 4 new error messages:
ER_TRANSFORM_SOURCE_SRS_NOT_SUPPORTED, SQLSTATE 22S00, "Transformation from SRID %u is not supported."
ER_TRANSFORM_TARGET_SRS_NOT_SUPPORTED, SQLSTATE 22S00, "Transformation to SRID %u is not supported."
ER_TRANSFORM_SOURCE_SRS_MISSING_TOWGS84, SQLSTATE 22S00, "Transformation from SRID %u is not supported. The spatial reference system has no TOWGS84 clause."
ER_TRANSFORM_TARGET_SRS_MISSING_TOWGS84, SQLSTATE 22S00, "Transformation to SRID %u is not supported. The spatial reference system has no TOWGS84 clause."

Function ST_Transform

The function is implemented as class Item_func_st_transform and calls gis::transform to compute the new geometry.

The item's val_str function checks that its parameters are valid, in particular that the SRID exists, so that gis::transform is only called with valid SRSs.

Functor gis::Transform and function gis::transform

Similar to other functions, transformation is implemented as a pair of functor and function, gis::Transform and gis::transform, respectively.

The functor will do the runtime dispatching to geometry type specific instances of overloaded function implementations. The functor may throw.

The function will do parameter checking to find out if it is possible to transform the geometry to the desired SRS (if it fails to do so, an exception will be thrown from the functor and then caught). Only valid transformations should be sent to the functor. The function is declared noexcept and will catch and handle all exceptions thrown from the functor.

Extending dd::Spatial_reference_system

Class dd::Spatial_reference_system is extended with two new virtual member functions: proj4_parameters and cs_type.

dd::Spatial_reference_system::proj4_parameters

Function proj4_parameters returns the proj4 parameter string for the SRS. This string should always be a valid proj4 string (as understood by Boost Geometry). (If it is not valid, the transformation will fail with an exception, which is then caught and handled by gis::transform, but proj4_parameters should not generate such strings to begin with.) This means that if bounds checking, beyond what is done when the SRS was created (e.g., during SRS WKT parsing), should be done here.

dd::Spatial_reference_system::cs_type

Function cs_type returns the coordinate system type, i.e., Cartesian or geographic. This is different from the SRS type, which currently can be projected or geographic. If, later, other types of SRSs are implemented, e.g., LOCAL_CS or GEOCCS, a mapping has to be done for those too.

The purpose of this function is to find out which type of geometry a geometry should be (e.g., Cartesian_point or Geographic_point). In particular, gis::Transform needs to know which type of geometry to create for the result of the transformation.