SDO_GEOM.VALIDATE_GEOMETRY_WITH

Format

SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(     
  theGeometry  IN SDO_GEOMETRY,      
  theDimInfo   IN SDO_DIM_ARRAY,      
  conditional  IN VARCHAR2 DEFAULT 'TRUE' ,      
  flag10g      IN VARCHAR2 DEFAULT 'FALSE'       
) RETURN VARCHAR2;

or

SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(     
  theGeometry  IN SDO_GEOMETRY,      
  tolerance    IN NUMBER,      
  conditional  IN VARCHAR2 DEFAULT 'TRUE' ,      
  flag10g      IN VARCHAR2 DEFAULT 'FALSE'       
) RETURN VARCHAR2;

Description

Performs a consistency check for valid geometry types and returns context information if the geometry is invalid. The function checks the representation of the geometry from the tables against the element definitions.

Parameters

theGeometry: Geometry object.
theDimInfo: Dimensional information array corresponding to theGeometry, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Geometry Metadata Views).
tolerance: Tolerance value (see Tolerance).
conditional: Conditional flag; relevant only for a three-dimensional composite surface or composite solid. A string value of TRUE (the default) causes validation to fail if two outer rings are on the same plane and share an edge; a string value of FALSE does not cause validation to fail if two outer rings are on the same plane and share an edge.
flag10g: Oracle Database 10g compatibility flag. A string value of TRUE causes only validation checks specific to two-dimensional geometries to be performed, and no 3D-specific validation checks to be performed. A string value of FALSE (the default) performs all validation checks that are relevant for the geometry. (See the Usage Notes for more information about the flag10g parameter.)

Usage Notes

You should validate all geometry data, and fix any validation errors, before performing any spatial operations on the data, as explained in Recommendations for Loading and Validating Spatial Data.

If the geometry is valid, this function returns TRUE. (For a user-defined geometry, that is, a geometry with an SDO_GTYPE value of 2000, this function returns the string NULL.)

If the geometry is not valid, this function returns the following:

An Oracle error message number based on the specific reason the geometry is invalid, or FALSE if the geometry fails for some other reason
The context of the error (the coordinate, edge, or ring that causes the geometry to be invalid). (See Context of Errors: Details in this section.)

This function checks for type consistency and geometry consistency.

For type consistency, the function checks for the following:

The SDO_GTYPE is valid.
The SDO_ETYPE values are consistent with the SDO_GTYPE value. For example, if the SDO_GTYPE is 2003, there should be at least one element of type POLYGON in the geometry.
The SDO_ELEM_INFO_ARRAY has valid triplet values.

For geometry consistency, the function checks for the following, as appropriate for the specific geometry type:

Polygons have at least four points, which includes the point that closes the polygon. (The last point is the same as the first.)
Polygons are not self-crossing.
No two consecutive vertices on a line or polygon are the same.
Polygons are oriented correctly. (Exterior ring boundaries must be oriented counterclockwise, and interior ring boundaries must be oriented clockwise.)
The interior of a polygon is connected.
Line strings have at least two points.
SDO_ETYPE 1-digit and 4-digit values are not mixed (that is, both used) in defining polygon ring elements.
Points on an arc are not colinear (that is, are not on a straight line) and are not the same point.
Geometries are within the specified bounds of the applicable DIMINFO column value (from the USER_SDO_GEOM_METADATA view).
LRS geometries (see Linear Referencing System) have three or four dimensions and a valid measure dimension position (3 or 4, depending on the number of dimensions).

For COLLECTION type geometries, some of the preceding checks mentioned above are not performed. Specifically, interior ring checks and polygon-polygon overlap checks are not performed for polygon elements of the COLLECTION type geometry.

For multipoint geometries, this function checks for duplicate vertices with three-dimensional geometries, but not with two-dimensional geometries.

For three-dimensional geometries, this function also performs the checks described in Validation Checks for Three-Dimensional Geometries.

In checking for geometry consistency, the function considers the geometry's tolerance value in determining if lines touch or if points are the same.

If the function format with tolerance is used, no checking is done to validate that the geometry is within the coordinate system bounds as stored in the DIMINFO field of the USER_SDO_GEOM_METADATA view. If this check is required for your usage, use the function format with theDimInfo.

Setting the flag10g parameter value to TRUE causes the validation logic for Oracle Spatial Release 10.2 to be used, irrespective of the dimensionality of the geometry. This can be useful for allowing three-dimensional geometries that contain geometries in pre-Release 11.1 format to pass the validation check when they would otherwise fail. For example, a three-dimensional line is not valid if it contains circular arcs; and setting flag10g to TRUE will allow such geometries to avoid being considered invalid solely because of the circular arcs. (You should later make these geometries valid according to the criteria for the current release, such as by densifying the circular arcs.)

You can use this function in a PL/SQL procedure as an alternative to using the SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT procedure. See the Usage Notes for SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT for more information.

Context of Errors: Details

If a geometry is invalid, the result can include information about a combination of the following: coordinates, elements, rings, and edges.

Coordinates: A coordinate refers to a vertex in a geometry. In a two-dimensional geometry, a vertex is two numbers (X and Y, or Longitude and Latitude). In a three-dimensional geometry, a vertex is defined using three numbers; and in a four-dimensional geometry, a vertex is defined using four numbers. (You can use the SDO_UTIL.GETVERTICES function to return the coordinates in a geometry.)

If you receive a geometry validation error such as 13356 (adjacent points in a geometry are redundant), you can call the SDO_UTIL.GETVERTICES function, specifying a rownum stopping condition to include the coordinate one greater than the coordinate indicated with the error. The last two coordinates shown in the output are the redundant coordinates. These coordinates may be exactly the same, or they may be within the user-specified tolerance and thus are considered the same point. You can remove redundant coordinates by using the SDO_UTIL.REMOVE_DUPLICATE_VERTICES function.
Elements: An element is a point, a line string, or an exterior polygon with zero or more corresponding interior polygons. (That is, a polygon element includes the exterior ring and all interior rings associated with that exterior ring.) If a geometry is a multi-element geometry (for example, multiple points, lines, or polygons), the first element is element 1, the second element is element 2, and so on.
Rings: A ring is only used with polygon elements. Exterior rings in a polygon are considered polygon elements, and an exterior ring can include zero or more interior rings (or holes). Each interior ring has its own ring designation, but Ring 1 is associated with the exterior polygon itself. For example, Element 1, Ring 1 refers to the first exterior polygon in a geometry; Element 1, Ring 2 refers to the first interior polygon of the first exterior polygon; and Element 1, Ring 3 refers to the second interior polygon. If the geometry is a multipolygon, Element 2, Ring 1 is used to refers to the second exterior polygon. If there are interior polygons associated with it, Element 2, Ring 2 refers to the first interior polygon of the second exterior polygon.
Edges: An edge refers to a line segment between two coordinates. Edge 1 refers to the segment between coordinate 1 and coordinate 2, Edge 2 refers to the line segment between coordinates 2 and 3, and so on. The most common place to see edge errors when validating geometries is with self-intersecting polygons. (The Open Geospatial Consortium simple features specification does not allow a polygon to self-intersect.) In such cases, Oracle reports error 13349 (polygon boundary crosses itself), including the Element, Ring, and Edge numbers where self-intersection occurs.

If error 13351 (shared edge) is returned for an optimized rectangle that spans more than 119 degrees in longitude, some queries on this rectangle will return correct results, as explained in Geodetic MBRs.

Examples

The following example validates a geometry (deliberately created as invalid) named cola_invalid_geom.

-- Validate; provide context if invalid
SELECT c.name, SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(c.shape, 0.005)
   FROM cola_markets c WHERE c.name = 'cola_invalid_geom';

NAME                                                                            
--------------------------------                                                
SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(C.SHAPE,0.005)                          
--------------------------------------------------------------------------------
cola_invalid_geom                                                               
13349 [Element <1>] [Ring <1>][Edge <1>][Edge <3>]

In the output for this example, 13349 indicates the error ORA-13349: polygon boundary crosses itself. The first ring of the first element has edges that intersect. The edges that intersect are edge 1 (the first and second vertices) and edge 3 (the third and fourth vertices).