WL#7929: GIS: Implement ST_Buffer and ST_Distance with Boost.Geometry
Status: Complete — Priority: Medium
Replace the current Buffer/ST_Buffer implementation with BG when BG supports buffer. Replace remaining st_distance() implementation which uses old GIS algorithm with BG algorithms.
F-1: ST_Buffer MUST return NULL if any of its arguments is NULL, or if the geometry argument is an invalid GEOMETRY byte string. In case of an invalid GEOMETRY byte string, ER_GIS_INVALID_DATA should be reported; And it MUST not return NULL if all arguments are valid and the geometry is not empty. F-2: ST_Buffer receives a geometry and a distance value(of double type) as the 1st and 2nd parameter respectively, and returns a GEOMETRY byte string which is a polygon or multipolygon and which is the buffer of the geometry. F-3: Given a geometry collection, its buffer should be computed this way: Firstly its components' buffers are computed, then the [multi]polygons are merged into the final multipolygon. F-4: The distance argument for ST_Buffer can be positive or zero, and if the geometry is a polygon or multipolygon, it can also be negative, i.e. the polygon or multipolygon is eroded/deflated to a specified distance as result. If the distance is zero, the geometry MUST be returned as is without any computation done; If the distance is negative but the geometry is not a polygon or multipolygon, the ST_Buffer MUST report ER_WRONG_ARGUMENTS error and return NULL. If the geometry is empty, ST_Buffer should return the empty geometry as result. F-5: If a negative distance value is specified for a [multi]polygon and the resulting eroded/deflated [multi]polygon is gone, an empty geometry is returned. ST_Buffer MUST never return a [multi]point or [multi]linestring in any case. F-6: ST_Buffer allows specifying strategies optionally using ST_Buffer_Strategy() function, in order to compute the buffer in various ways. ST_Buffer MUST return NULL if any of the option arguments is invalid or NULL. Available strategy categories and strategy options in each category(bracketed) are: point strategies(point round, point square) join strategy(join round, join miter) end strategy(end round, end flat) F-7: ST_Buffer_Strategy function accepts one or two arguments and returns one strategy option as a byte string with the strategy setting encoded. It MUST return NULL if any argument is NULL, or any of the arguments is not valid; it MUST not return NULL if all arguments are valid. F-8: The first argument of ST_Buffer_Strategy MUST be one of these strategy options in strings(case insensitive): "point_circle", "point_square", "join_round", "join_miter", "end_round", "end_flat", otherwise ER_WRONG_ARGUMENTS is raised and NULL returned. F-9: If the 1st argument for ST_Buffer_Strategy is one these strategy options: "point_circle", "join_round", "end_round", and "join_miter", ST_Buffer_Strategy requires a 2nd argument called 'points_per_circle' which must be a positive numeric value. In case of lack of arguments or argument range mismatch, ER_WRONG_ARGUMENTS is raised and NULL returned. F-10: If the 1st argument for ST_Buffer_Strategy is one of these strategy options: "point_square" and "end_flat", no more arguments can be specified to ST_Buffer_Strategy otherwise it returns NULL and reports ER_WRONG_ARGUMENTS. F-11: Each category of strategy applies to certain types of geometries, if a strategy option of a strategy category is specified to a geometry that it can't be applied to, ST_Buffer MUST report ER_WRONG_ARGUMENTS error and return NULL. point strategy: applies to [multi]point join strategy: applies to [multi]linestring, [multi]polygon end strategy: applies to [multi]linestring F-12: the user may optionally specify any of the three strategy categories by calling ST_Buffer_Strategy. Each strategy category must be specified at most once, otherwise ER_WRONG_ARGUMENTS is reported and NULL is returned. But different strategy categories may be mixed and provided to ST_Buffer in any order. F-13: If no strategy option is specified into ST_Buffer for a category, its system wide global fixed default option is used. The default options for each category are defined as: point strategies --- "point_circle" with 'points_per_circle' = 32; join strategy --- "join_round" with 'points_per_circle' = 32; end strategy --- "end_round" with 'points_per_circle' = 32. F-14: The SRID of the geometry argument of ST_Buffer must be 0, because only cartessian coordinate system is supported by boost::geometry::buffer currently. F-15: ST_Buffer's 3rd and more arguments must be valid buffer strategy values produced by valid ST_Buffer_Strategy calls, otherwise ER_WRONG_ARGUMENTS should be reported. F-16: Replace the remaining ST_distance code which used old GIS algorithm with Boost Geometry. The syntax of st_distance MUST NOT change.
Changes to the interface specification: I-1: No new files. I-2: New syntax: 1. One new function:
= ST_Buffer_Strategy( [, ]) 2. One function with extended interface (0 to 3 optional arguments) = ST_Buffer( , [, [, [, ] ] ]) Here the is the returned by the ST_Buffer_Strategy() function call. The old interface of ST_Buffer still works because the change of the ST_Buffer interface is adding 3 optional strategy arguments, when non added, ST_Buffer is used like before, however the behavior in this case may not be exactly the same as the old GIS algorithm, this is determined by the BG algorithm and our default values. Note that the removal of ST_GIS_DEBUG is NOT an interface change because this function is only used internally and is only effective in debug builds, and it's not publicly known and not documented. I-3: No new commands. I-4: No new tools. I-5: No impact on existing functionality.
Copyright (c) 2000, 2019, Oracle Corporation and/or its affiliates. All rights reserved.