16.5. Analyzing Spatial Information

MySQL 5.0

16.5. Analyzing Spatial Information

After populating spatial columns with values, you are ready to query and analyze them. MySQL provides a set of functions to perform various operations on spatial data. These functions can be grouped into four major categories according to the type of operation they perform:

  • Functions that convert geometries between various formats

  • Functions that provide access to qualitative or quantitative properties of a geometry

  • Functions that describe relations between two geometries

  • Functions that create new geometries from existing ones

Spatial analysis functions can be used in many contexts, such as:

  • Any interactive SQL program, such as mysql or MySQL Query Browser

  • Application programs written in any language that supports a MySQL client API

16.5.1. Geometry Format Conversion Functions

MySQL supports the following functions for converting geometry values between internal format and either WKT or WKB format:

  • )

    Converts a value in internal geometry format to its WKB representation and returns the binary result.

    SELECT AsBinary(g) FROM geom;
    
  • )

    Converts a value in internal geometry format to its WKT representation and returns the string result.

    mysql> 
    mysql> 
    +--------------------------+
    | AsText(GeomFromText(@g)) |
    +--------------------------+
    | LINESTRING(1 1,2 2,3 3)  |
    +--------------------------+
    
  • [,])

    Converts a string value from its WKT representation into internal geometry format and returns the result. A number of type-specific functions are also supported, such as and . See Section 16.4.2.1, “Creating Geometry Values Using WKT Functions”.

  • [,])

    Converts a binary value from its WKB representation into internal geometry format and returns the result. A number of type-specific functions are also supported, such as and . See Section 16.4.2.2, “Creating Geometry Values Using WKB Functions”.

16.5.2. Geometry Functions

Each function that belongs to this group takes a geometry value as its argument and returns some quantitative or qualitative property of the geometry. Some functions restrict their argument type. Such functions return if the argument is of an incorrect geometry type. For example, returns if the object type is neither nor .

16.5.2.1. General Geometry Functions

The functions listed in this section do not restrict their argument and accept a geometry value of any type.

  • )

    Returns the inherent dimension of the geometry value . The result can be –1, 0, 1, or 2. The meaning of these values is given in Section 16.2.2, “Class .

    mysql> 
    +------------------------------------------------+
    | Dimension(GeomFromText('LineString(1 1,2 2)')) |
    +------------------------------------------------+
    |                                              1 |
    +------------------------------------------------+
    
  • )

    Returns the Minimum Bounding Rectangle (MBR) for the geometry value . The result is returned as a value.

    The polygon is defined by the corner points of the bounding box:

    POLYGON((MINX MINY, MAXX MINY, MAXX MAXY, MINX MAXY, MINX MINY))
    
    mysql> 
    +-------------------------------------------------------+
    | AsText(Envelope(GeomFromText('LineString(1 1,2 2)'))) |
    +-------------------------------------------------------+
    | POLYGON((1 1,2 1,2 2,1 2,1 1))                        |
    +-------------------------------------------------------+
    
  • )

    Returns as a string the name of the geometry type of which the geometry instance is a member. The name corresponds to one of the instantiable subclasses.

    mysql> 
    +------------------------------------------+
    | GeometryType(GeomFromText('POINT(1 1)')) |
    +------------------------------------------+
    | POINT                                    |
    +------------------------------------------+
    
  • )

    Returns an integer indicating the Spatial Reference System ID for the geometry value .

    In MySQL, the SRID value is just an integer associated with the geometry value. All calculations are done assuming Euclidean (planar) geometry.

    mysql> 
    +-----------------------------------------------+
    | SRID(GeomFromText('LineString(1 1,2 2)',101)) |
    +-----------------------------------------------+
    |                                           101 |
    +-----------------------------------------------+
    

The OpenGIS specification also defines the following functions, which MySQL does not implement:

  • )

    Returns a geometry that is the closure of the combinatorial boundary of the geometry value .

  • )

    Returns 1 if the geometry value is the empty geometry, 0 if it is not empty, and –1 if the argument is . If the geometry is empty, it represents the empty point set.

  • )

    Currently, this function is a placeholder and should not be used. If implemented, its behavior will be as described in the next paragraph.

    Returns 1 if the geometry value has no anomalous geometric points, such as self-intersection or self-tangency. returns 0 if the argument is not simple, and –1 if it is .

    The description of each instantiable geometric class given earlier in the chapter includes the specific conditions that cause an instance of that class to be classified as not simple. (See Section 16.2.1, “The Geometry Class Hierarchy”.)

16.5.2.2.  Functions

A consists of X and Y coordinates, which may be obtained using the following functions:

  • )

    Returns the X-coordinate value for the point as a double-precision number.

    mysql> 
    mysql> 
    +----------------------+
    | X(GeomFromText(@pt)) |
    +----------------------+
    |                 56.7 |
    +----------------------+
    
  • )

    Returns the Y-coordinate value for the point as a double-precision number.

    mysql> 
    mysql> 
    +----------------------+
    | Y(GeomFromText(@pt)) |
    +----------------------+
    |                53.34 |
    +----------------------+
    

16.5.2.3.  Functions

A consists of values. You can extract particular points of a , count the number of points that it contains, or obtain its length.

  • )

    Returns the that is the endpoint of the value .

    mysql> 
    mysql> 
    +-------------------------------------+
    | AsText(EndPoint(GeomFromText(@ls))) |
    +-------------------------------------+
    | POINT(3 3)                          |
    +-------------------------------------+
    
  • )

    Returns as a double-precision number the length of the value in its associated spatial reference.

    mysql> 
    mysql> 
    +----------------------------+
    | GLength(GeomFromText(@ls)) |
    +----------------------------+
    |            2.8284271247462 |
    +----------------------------+
    

    is a non-standard name. It corresponds to the OpenGIS function.

  • )

    Returns the number of objects in the value .

    mysql> 
    mysql> 
    +------------------------------+
    | NumPoints(GeomFromText(@ls)) |
    +------------------------------+
    |                            3 |
    +------------------------------+
    
  • ,)

    Returns the -th in the value . Points are numbered beginning with 1.

    mysql> 
    mysql> 
    +-------------------------------------+
    | AsText(PointN(GeomFromText(@ls),2)) |
    +-------------------------------------+
    | POINT(2 2)                          |
    +-------------------------------------+
    
  • )

    Returns the that is the start point of the value .

    mysql> 
    mysql> 
    +---------------------------------------+
    | AsText(StartPoint(GeomFromText(@ls))) |
    +---------------------------------------+
    | POINT(1 1)                            |
    +---------------------------------------+
    

The OpenGIS specification also defines the following function, which MySQL does not implement:

  • )

    Returns 1 if the value is closed (that is, its and values are the same) and is simple (does not pass through the same point more than once). Returns 0 if is not a ring, and –1 if it is .

16.5.2.4.  Functions

  • )

    Returns as a double-precision number the length of the value . The length of is equal to the sum of the lengths of its elements.

    mysql> 
    mysql> 
    +-----------------------------+
    | GLength(GeomFromText(@mls)) |
    +-----------------------------+
    |             4.2426406871193 |
    +-----------------------------+
    

    is a non-standard name. It corresponds to the OpenGIS function.

  • )

    Returns 1 if the value is closed (that is, the and values are the same for each in ). Returns 0 if is not closed, and –1 if it is .

    mysql> 
    mysql> 
    +------------------------------+
    | IsClosed(GeomFromText(@mls)) |
    +------------------------------+
    |                            0 |
    +------------------------------+
    

16.5.2.5.  Functions

  • )

    Returns as a double-precision number the area of the value , as measured in its spatial reference system.

    mysql> 
    mysql> 
    +---------------------------+
    | Area(GeomFromText(@poly)) |
    +---------------------------+
    |                         4 |
    +---------------------------+
    
  • )

    Returns the exterior ring of the value as a .

    mysql> 
        -> 
    mysql> 
    +-------------------------------------------+
    | AsText(ExteriorRing(GeomFromText(@poly))) |
    +-------------------------------------------+
    | LINESTRING(0 0,0 3,3 3,3 0,0 0)           |
    +-------------------------------------------+
    
  • ,)

    Returns the -th interior ring for the value as a . Rings are numbered beginning with 1.

    mysql> 
        -> 
    mysql> 
    +----------------------------------------------+
    | AsText(InteriorRingN(GeomFromText(@poly),1)) |
    +----------------------------------------------+
    | LINESTRING(1 1,1 2,2 2,2 1,1 1)              |
    +----------------------------------------------+
    
  • )

    Returns the number of interior rings in the value .

    mysql> 
        -> 
    mysql> 
    +---------------------------------------+
    | NumInteriorRings(GeomFromText(@poly)) |
    +---------------------------------------+
    |                                     1 |
    +---------------------------------------+
    

16.5.2.6.  Functions

  • )

    Returns as a double-precision number the area of the value , as measured in its spatial reference system.

    mysql> 
        -> 
    mysql> 
    +----------------------------+
    | Area(GeomFromText(@mpoly)) |
    +----------------------------+
    |                          8 |
    +----------------------------+
    

The OpenGIS specification also defines the following functions, which MySQL does not implement:

  • )

    Returns the mathematical centroid for the value as a . The result is not guaranteed to be on the .

  • )

    Returns a value that is guaranteed to be on the value .

16.5.2.7.  Functions

  • ,)

    Returns the -th geometry in the value . Geometries are numbered beginning with 1.

    mysql> 
    mysql> 
    +----------------------------------------+
    | AsText(GeometryN(GeomFromText(@gc),1)) |
    +----------------------------------------+
    | POINT(1 1)                             |
    +----------------------------------------+
    
  • )

    Returns the number of geometries in the value .

    mysql> 
    mysql> 
    +----------------------------------+
    | NumGeometries(GeomFromText(@gc)) |
    +----------------------------------+
    |                                2 |
    +----------------------------------+
    

16.5.3. Functions That Create New Geometries from Existing Ones

16.5.3.1. Geometry Functions That Produce New Geometries

Section 16.5.2, “ Functions”, discusses several functions that construct new geometries from existing ones. See that section for descriptions of these functions:

  • )

  • )

  • )

  • ,)

  • )

  • ,)

  • ,)

16.5.3.2. Spatial Operators

OpenGIS proposes a number of other functions that can produce geometries. They are designed to implement spatial operators.

These functions are not implemented in MySQL. They may appear in future releases.

  • ,)

    Returns a geometry that represents all points whose distance from the geometry value is less than or equal to a distance of .

  • )

    Returns a geometry that represents the convex hull of the geometry value .

  • ,)

    Returns a geometry that represents the point set difference of the geometry value with .

  • ,)

    Returns a geometry that represents the point set intersection of the geometry values with .

  • ,)

    Returns a geometry that represents the point set symmetric difference of the geometry value with .

  • ,)

    Returns a geometry that represents the point set union of the geometry values and .

16.5.4. Functions for Testing Spatial Relations Between Geometric Objects

The functions described in these sections take two geometries as input parameters and return a qualitative or quantitative relation between them.

16.5.5. Relations on Geometry Minimal Bounding Rectangles (MBRs)

MySQL provides several functions that test relations between minimal bounding rectangles of two geometries and . The return values 1 and 0 indicate true and false, respectively.

  • ,)

    Returns 1 or 0 to indicate whether the Minimum Bounding Rectangle of contains the Minimum Bounding Rectangle of .

    mysql> 
    mysql> 
    mysql> 
    ----------------------+----------------------+
    | MBRContains(@g1,@g2) | MBRContains(@g2,@g1) |
    +----------------------+----------------------+
    |                    1 |                    0 |
    +----------------------+----------------------+
    
  • ,)

    Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries and are disjoint (do not intersect).

  • ,)

    Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries and are the same.

  • ,)

    Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries and intersect.

  • ,)

    Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries and overlap.

  • ,)

    Returns 1 or 0 to indicate whether the Minimum Bounding Rectangles of the two geometries and touch.

  • ,)

    Returns 1 or 0 to indicate whether the Minimum Bounding Rectangle of is within the Minimum Bounding Rectangle of .

    mysql> 
    mysql> 
    mysql> 
    +--------------------+--------------------+
    | MBRWithin(@g1,@g2) | MBRWithin(@g2,@g1) |
    +--------------------+--------------------+
    |                  1 |                  0 |
    +--------------------+--------------------+
    

16.5.6. Functions That Test Spatial Relationships Between Geometries

The OpenGIS specification defines the following functions. They test the relationship between two geometry values and .

Currently, MySQL does not implement these functions according to the specification. Those that are implemented return the same result as the corresponding MBR-based functions. This includes functions in the following list other than and .

These functions may be implemented in future releases with full support for spatial analysis, not just MBR-based support.

The return values 1 and 0 indicate true and false, respectively.

  • ,)

    Returns 1 or 0 to indicate whether completely contains .

  • ,)

    Returns 1 if spatially crosses . Returns if is a or a , or if is a or a . Otherwise, returns 0.

    The term spatially crosses denotes a spatial relation between two given geometries that has the following properties:

    • The two geometries intersect

    • Their intersection results in a geometry that has a dimension that is one less than the maximum dimension of the two given geometries

    • Their intersection is not equal to either of the two given geometries

  • ,)

    Returns 1 or 0 to indicate whether is spatially disjoint from (does not intersect) .

  • ,)

    Returns as a double-precision number the shortest distance between any two points in the two geometries.

  • ,)

    Returns 1 or 0 to indicate whether is spatially equal to .

  • ,)

    Returns 1 or 0 to indicate whether spatially intersects .

  • ,)

    Returns 1 or 0 to indicate whether spatially overlaps . The term spatially overlaps is used if two geometries intersect and their intersection results in a geometry of the same dimension but not equal to either of the given geometries.

  • ,,)

    Returns 1 or 0 to indicate whether the spatial relationship specified by exists between and . Returns –1 if the arguments are . The pattern matrix is a string. Its specification will be noted here if this function is implemented.

  • ,)

    Returns 1 or 0 to indicate whether spatially touches . Two geometries spatially touch if the interiors of the geometries do not intersect, but the boundary of one of the geometries intersects either the boundary or the interior of the other.

  • ,)

    Returns 1 or 0 to indicate whether is spatially within .