WL#8034: More user friendly GIS functions

Status: Complete   —   Priority: Medium

We need some more GIS functions which are not defined by OGC, to make MySQL GIS
more user friendly by helping out potential MySQL GIS users with the most
frequent/common problem or issues they can have when using MySQL GIS. Currently
in the list are:

ST_Distance_Sphere(geom1, geom2, earth-radius) — Returns the minimum distance on
the earth in meters between two lon/lat
geometries. Uses a spherical earth and a configurable radius, which is 6370986
meters by default. For now we only support point/multipoint arguments.

ST_MakeEnvelope(bottom-left-point, top-right-point) --- Makes a rectangle using
bottom left and top right points. This is done on an abstract plane rather than
on a sphere, spheroid or on earth.

ST_IsValid: check whether a geometry is valid, the validity is defined by OGC
standard documents.

ST_Validate: check whether a geometry byte string is valid (validity defined as
above), if so return it, otherwise return NULL. this can be used to filter out
invalid geometry data at an noticeable cost. we don't do so by default in
geometry calculations because of the cost, but some users may be willing to take
the cost to get more precise results and completely eliminate invalid geometry
data from the result.
F-1: All functions should return NULL if any of the geometry arguments is NULL.

F-2: ST_IsValid should return NULL if the geometry argument is NULL, and should not return NULL otherwise. It should return false if the argument isn't a valid GEOMETRY string, or it's not geometrically valid. It should return true if the argument is a valid geometry byte string and it is geometrically valid.

F-3: ST_Validate should return NULL if the argument is NULL, or if the geometry byte string isn't a valid GEOMETRY(SRID+WKB) byte string, or if the geometry is not geometrically valid as defined by OGC.
If the geometry argument is valid, it should be returned as is.

F-4: Given an empty geometry, and any empty geometry collection, ST_IsValid should return true and ST_Validate should simply return it directly without further checks, that is, they should be considered valid by the two functions;

Given a non-empty geometry collection, it's valid if and only if all its components are valid;

Given any non-empty geometries that are not geometry collections , the validity is defined by OGC standard, against which ST_IsValid and ST_Validate should check the geometry argument.

F-5: ST_MakeEnvelope should return NULL if the point argument is NULL; it should return ER_GIS_INVALID_DATA if any of the point arguments isn't valid GEOMETRY byte string;

It should report ER_WRONG_ARGUMENTS if the geometry argument isn't a point; 
And it should not return NULL if neither arguments is NULL and both arguments are valid point data.

ST_MakeEnvelope SHOULD report ER_WRONG_ARGUMENTS if p1.x > p2.x or p1.y > p2.y
,it should report ER_GIS_DIFFERENT_SRIDS if the two points have different SRIDs.

F-6: ST_MakeEnvelope should create the result rectangle on an abstract plane like this:

given the bottom left point p1 and top right point p2, the result should be:
polygon((p1.x p1.y, p2.x p1.y, p2.x p2.y, p1.x p2.y, p1.x p1.y))

The result polygon should be given the same srid as the point argument.

F-7: ST_Distance_Sphere should return NULL if any of the two arguments is NULL or empty; it should return ER_GIS_INVALID_DATA if any of the two arguments isn't valid GEOMETRY byte string.
It should return ER_GIS_UNSUPPORTED_ARGUMENT if any of the two arguments is neither a point nor a multipoint.

F-8: The points in geometry arguments of ST_Distance_Sphere should be (longitude, latitude) points, it's 2D and the longitude and latitude are valid (validity defined below). Longtitude is the 1st coordinate of the point, and latitude is the 2nd coordinate of the point, both coordinate are degree values.

F-9: Valid longitude values MUST be in the range (-180,180]. Positive values
are east of the prime meridian.

F-10: Valid latitude values MUST be in the range [-90,90]. Positive values are
north of the equator. 

F-11: ST_Distance_Sphere should use a spherical earth and radius of 6370986 meters by default, its returned value should be the minimum distance on the earth in meters between the two geometries. 

If user specifies the optional earth radius argument, it's used to
compute the distance. If this radius argument isn't positive, this function
reports ER_WRONG_ARGUMENTS.


Changes to the interface specification:

I-1: No new files.

I-2: New syntax: Four new functions:

          = ST_Distance_Sphere(, , )

          = ST_MakeEnvelope(, )

          = ST_IsValid()
          = ST_Validate()

I-3: No new commands.

I-4: No new tools.

I-5: No impact on existing functionality.