# WL#14178: ST_PointAtDistance

This WL implements a new function, ST_PointAtDistance(linestring, distance), that takes a linestring and a distance in the length unit of the spatial reference system and returns the point along that linestring at that distance from the starting point.

The function is implemented for linestrings in all spatial reference systems, both Cartesian and geographic.

Example use case: ST_PointAtDistance is used to find points along a line, e.g., along a road or along a recording av a GPS tracked vehicle. What is the point 400 meters from the start: ST_PointAtDistance(<line in SRS using meters as length unit>, 400).

- F-1
- The function MUST return NULL if any of its arguments are NULL.
- F-2
- If the geometry argument is not a syntactically well-formed geometry, the function MUST raise ER_GIS_INVALID_DATA during function evaluation.
- F-3
- If the geometry argument is a syntactically well-formed geometry in an undefined SRS, the function MUST raise ER_SRS_NOT_FOUND during function evaluation.
- F-4
- If the geometry argument is a syntactically well-formed geometry but not a linestring, the function MUST raise ER_UNEXPECTED_GEOMETRY_TYPE during function evaluation.
- F-5
- If the geometry argument is a geometry in a geographic SRS and a longitude value is not in the range (-180,180] (in degrees -- other limits in other units), the function MUST raise ER_GEOMETRY_PARAM_LONGITUDE_OUT_OF_RANGE. (*)
- F-6
- If the geometry argument is a geometry in a geographic SRS and a latitude value is not in the range [-90,90] (in degrees -- other limits in other units), the function MUST raise ER_GEOMETRY_PARAM_LATITUDE_OUT_OF_RANGE. (*)
- F-7
- If the distance parameter is outside the range [0.0, length of linestring], the function MUST raise ER_DATA_OUT_OF_RANGE during function evaluation.
- F-8
- If the geometry argument is a syntactically well-formed linestring and the distance parameter is within the range [0.0, length of linestring], the function MUST return the point at that distance from the starting point of the linestring along the linestring, measured in the unit of the spatial reference system of the linestring.
- F-9
- The return type of the function MUST be POINT.

(*) The exact limits will deviate slightly because of floating point arithmetics.

- I-1
- The syntax of interface SQL01 is extended with function ST_PointAtDistance(
*linestring*,*length*). - I-2
- No new errors.
- I-3
- No new warnings.

## Item_func_st_pointatdistance

The Item_func_st_pointatdistance class implements the SQL level ST_PointAtDistance function. The class is placed in sql/item_geofunc.{h,cc}. Class declarations and definitions are supposed to be sorted in alphabetical order in these files.

A link between the SQL level function name and class is added to sql/item_create.cc.

The SQL level function interface is tested by an MTR test in mysql-test/suite/gis/t/st_pointatdistance.test.

## gis::line_interpolate_point and gis::Line_interpolate_point

The gis::Line_interpolate_point functor (sql/gis/line_interpolate_functor.{h,cc}) and gis::line_interpolate_point function (sql/gis/line_interpolate.{h,cc}) implement the interface to the Boost Geometry line_interpolate function. The functor may throw exceptions, while the function is declared nothrow and will wrap the functor in try-catch and translate exceptions to my_error calls.

The function is unit tested by tests in unittest/gunit/gis_line_interpolate_point-t.cc. These tests handle boundary testing that don't affect the SQL level interface.