7
Geometry Functions for Object-Relational Model
This chapter contains descriptions of the geometry functions shown in Table 7-1.
SDO_GEOM.AREA
Purpose
This function computes the area of a two-dimensional polygon.
Syntax
SDO_GEOM.AREA (geometry, dim_array)
Keywords and Parameters
geometry |
Specifies the geometry object to analyze. Data type is MDSYS.SDO_GEOMETRY. |
dim_array |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
Returns
This function returns the area of a polygon.
Data type is NUMBER.
Usage Notes
This function works with any polygon, including polygons with holes.
Related Topics
None.
SDO_GEOM.LENGTH
Purpose
This function computes the length or perimeter of a geometry.
Syntax
SDO_GEOM.LENGTH (geometry, dim_array)
Keywords and Parameters
geometry |
Specifies the geometry object to analyze. Data type is MDSYS.SDO_GEOMETRY. |
dim_array |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
Returns
This function returns the length or perimeter of an object.
Data type is NUMBER.
Usage Notes
If the input polygon contains one or more holes, this function calculates the perimeters of the exterior boundary and all of the holes. It returns the sum of all the perimeters.
Related Topics
None.
SDO_GEOM.RELATE
Purpose
This function examines two geometry objects to determine their spatial relationship.
Syntax
SDO_GEOM.RELATE (geometry1, dim_array1, mask, geometry2, dim_array2)
Keywords and Parameters
geometry1, geometry2 |
Specifies the geometry objects to compare. Data type is MDSYS.SDO_GEOMETRY. |
dim_array1, dim_array2 |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
mask |
Specifies a list of relationships to check. See the list of keywords in the Usage Notes. |
Returns
The MDSYS.SDO_GEOM.RELATE()
function can return three types of answers:
- If you pass a mask listing one or more relationships, the function returns the name of the relationship if it is true for the pair of geometries. If all of the relationships are false, the procedure returns FALSE.
- If you pass the DETERMINE keyword in the mask, the function returns the one relationship keyword that best matches the geometries. DETERMINE can only be used when
SDO_GEOM.RELATE()
is in the SELECT clause of the SQL statement.
- If you pass the ANYINTERACT keyword in the mask, the function returns TRUE if the two geometries are not disjoint.
The data type is VARCHAR2.
Usage Notes
The following relationships can be tested:
- ANYINTERACT - Returns TRUE if the objects are not disjoint.
- CONTAINS - Returns CONTAINS if the second object is entirely within the first object and the object boundaries do not touch; otherwise, returns FALSE.
- COVEREDBY - Returns COVEREDBY if the first object is entirely within the second object and the object boundaries touch at one or more points; otherwise, returns FALSE.
- COVERS - Returns COVERS if the second object is entirely within the first object and the boundaries touch in one or more places; otherwise, returns FALSE.
- DISJOINT - Returns DISJOINT if the objects have no common boundary or interior points; otherwise, returns FALSE.
- EQUAL - Returns EQUAL if the objects share every point of their boundaries and interior, including any holes in the objects; otherwise, returns FALSE.
- INSIDE - Returns INSIDE if the first object is entirely within the second object and the object boundaries do not touch; otherwise, returns FALSE.
- OVERLAPBDYDISJOINT - Returns OVERLAPBDYDISJOINT if the objects overlap, but their boundaries do not interact; otherwise, returns FALSE.
- OVERLAPBDYINTERSECT - Returns OVERLAPBDYINTERSECT if the objects overlap, and their boundaries intersect in one or more places; otherwise, returns FALSE.
- TOUCH - Returns TOUCH if the two objects share a common boundary point, but no interior points; otherwise, returns FALSE.
Mask values can be combined using a logical Boolean operator OR. For example, `INSIDE + TOUCH' returns either 'INSIDE', 'TOUCH', or 'FALSE' depending on the outcome of the test.
Related Topics
None.
SDO_GEOM.SDO_BUFFER
Purpose
This function generates a buffer polygon around a geometry object.
Syntax
SDO_GEOM.SDO_BUFFER (geometry, dim_array, distance)
Keywords and Parameters
geometry |
Specifies the geometry objects to compare. Data type is MDSYS.SDO_GEOMETRY. |
dim_array |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
distance |
Specifies the Euclidean distance value. Data type is NUMBER. |
Returns
This function returns a geometry object representing the buffer polygon.
Data type is MDSYS.SDO_GEOMETRY.
Usage Notes
This function creates a rounded buffer around a point, line, or polygon. The buffer within a void is also rounded, and is the same distance from the inner boundary as the outer buffer is from the outer boundary. See Figure 1-11 for an illustration.
Related Topics
- SDO_TUNE.EXTENT_OF
- SDO_GEOM.SDO_POLY_DIFFERENCE
- SDO_GEOM.SDO_POLY_INTERSECTION
- SDO_GEOM.SDO_POLY_UNION
- SDO_GEOM.SDO_POLY_XOR
SDO_GEOM.SDO_POLY_DIFFERENCE
Purpose
This function computes the difference (A minus B) of two polygon objects.
Syntax
SDO_GEOM.SDO_POLY_DIFFERENCE (geometry1, dim_array1, geometry2, dim_array2)
Keywords and Parameters
geometry1, geometry2 |
Specifies the geometry objects to compare. Data type is MDSYS.SDO_GEOMETRY. |
dim_array1, dim_array2 |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
Returns
This function returns a geometry object representing the difference of two polygon objects.
Data type is MDSYS.SDO_GEOMETRY.
Usage Notes
None.
Related Topics
- SDO_GEOM.SDO_POLY_BUFFER
- SDO_GEOM.SDO_POLY_INTERSECTION
- SDO_GEOM.SDO_POLY_UNION
- SDO_GEOM.SDO_POLY_XOR
SDO_GEOM.SDO_POLY_INTERSECTION
Purpose
This function computes the intersection of two polygon objects.
Syntax
SDO_GEOM.SDO_POLY_INTERSECTION (geometry1, dim_array1, geometry2, dim_array2)
Keywords and Parameters
geometry1, geometry2 |
Specifies the geometry objects to compare. Data type is MDSYS.SDO_GEOMETRY. |
dim_array1, dim_array2 |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
Returns
This function returns a geometry object representing the intersection (A and B) of two polygon objects.
Data type is MDSYS.SDO_GEOMETRY.
Usage Notes
None.
Related Topics
- SDO_GEOM.SDO_POLY_BUFFER
- SDO_GEOM.SDO_POLY_DIFFERENCE
- SDO_GEOM.SDO_POLY_UNION
- SDO_GEOM.SDO_POLY_XOR
SDO_GEOM.SDO_POLY_UNION
Purpose
This function computes the union of two polygon objects.
Syntax
SDO_GEOM.SDO_POLY_UNION (geometry1, dim_array1, geometry2, dim_array2)
Keywords and Parameters
geometry1, geometry2 |
Specifies the geometry objects to compare. Data type is MDSYS.SDO_GEOMETRY. |
dim_array1, dim_array2 |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
Returns
This function returns a geometry object representing the union (A or B) of two polygon objects.
Data type is MDSYS.SDO_GEOMETRY.
Usage Notes
None.
Related Topics
- SDO_GEOM.SDO_POLY_BUFFER
- SDO_GEOM.SDO_POLY_DIFFERENCE
- SDO_GEOM.SDO_POLY_INTERSECTION
- SDO_GEOM.SDO_POLY_XOR
SDO_GEOM.SDO_POLY_XOR
Purpose
This function computes the symmetric difference of two polygon objects.
Syntax
SDO_GEOM.SDO_POLY_XOR (geometry1, dim_array1, geometry2, dim_array2)
Keywords and Parameters
geometry1, geometry2 |
Specifies the geometry objects to compare. Data type is MDSYS.SDO_GEOMETRY. |
dim_array1, dim_array2 |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
Returns
This function returns a geometry object representing the symmetric difference (A xor B) of two polygon objects.
Data type is MDSYS.SDO_GEOMETRY.
Usage Notes
None.
Related Topics
- SDO_GEOM.SDO_POLY_BUFFER
- SDO_GEOM.SDO_POLY_DIFFERENCE
- SDO_GEOM.SDO_POLY_INTERSECTION
- SDO_GEOM.SDO_POLY_UNION
SDO_GEOM.VALIDATE_GEOMETRY
Purpose
This function provides a consistency check for valid geometry types. The function checks the representation of the geometry from the tables against the element definitions.
Syntax
SDO_GEOM.VALIDATE_GEOMETRY (geometry, dim_array)
Keywords and Parameters
geometry |
Specifies the geometry object to test. Data type is MDSYS.SDO_GEOMETRY. |
dim_array |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
Returns
This function returns:
- TRUE if the geometry is valid.
- FALSE if the geometry fails for some unknown reason.
- An Oracle error message number based on the specific reason the geometry in invalid.
Data type is VARCHAR2.
Usage Notes
This function checks for the following:
- Polygons have at least four points, which includes the point that closes the polygon. (The last point is the same as the first.)
- Line strings have at least two points.
- In a heterogeneous collection (SDO_GTYPE 4) or multipolygon (SDO_GTYPE 7), all polygons are disjoint.
Example
The following example tests a geometry stored in a table my_geometry_table with one column called "geometry" and another column called "my_id," which is the primary key:
SELECT mdsys.sdo_geom.validate_geometry (a.geometry, b.diminfo)
FROM abi_81_hy a,
sdo_geom_metadata b
WHERE a.gid = 1
AND b.table_name = 'MY_GEOMETRY_TABLE'
AND b.column_name = 'GEOMETRY';
Related Topics
None.
SDO_GEOM.VALIDATE_LAYER
Purpose
This function examines a geometry column to determine if the stored geometries follow the defined rules for geometry objects.
Syntax
SDO_GEOM.VALIDATE_LAYER (table_name, column_name, pkey_column, result_table_name)
Keywords and Parameters
table_name |
Specifies the name of the geometry object table. Data type is VARCHAR2. |
column_name |
Specifies the name of the geometry object column to examine. Data type is VARCHAR2. |
pkey_column |
Specifies the primary key column. This can be the rowid, or any other primary key. Data type is VARCHAR2. |
result_table_name |
Specifies the name of the result table. Data type is VARCHAR2. |
Returns
This function populates the result table with validation results.
Usage Notes
- An empty result table must be created prior to calling this function. The format of the result table is: (sdo_gid number, result varchar2(10)).
- This function returns TRUE in the result table if a geometry is valid. If it is invalid, the result column for that geometry (the pkey_column corresponds to the SDO_GID) contains an Oracle error message number. You can then look up this error message to determine the cause of the failure.
- This function checks for the following:
- Polygons have at least four points, which includes the point that closes the polygon. (The last point is the same as the first.)
- Line strings have at least two points.
- In a heterogeneous collection (SDO_GTYPE 4) or multipolygon (SDO_GTYPE 7), all polygons are disjoint.
Related Topics
None.
SDO_GEOM.WITHIN_DISTANCE
Purpose
This function determines if two spatial objects are within some specified Euclidean distance from each other.
Syntax
SDO_GEOM.WITHIN_DISTANCE (geometry1, dim_array1, distance, geometry2, dim_array2)
Keywords and Parameters
geometry1, geometry2 |
Specifies the geometry objects to compare. Data type is MDSYS.SDO_GEOMETRY. |
dim_array1, dim_array2 |
Specifies the dimensional information array, usually selected from the SDO_GEOM_METADATA table. Data type is MDSYS.SDO_DIM_ARRAY. |
distance |
Specifies the Euclidean distance value. Data type is NUMBER. |
Returns
This function returns TRUE for object pairs that are within the specified distance, and FALSE otherwise.
Usage Notes
The distance between two extended objects (for example, nonpoint objects such as lines and polygons) is defined as the minimum distance between these two objects. Thus the distance between two adjacent polygons is zero.
Related Topics
None.