Oracle8 Spatial Cartridge User's Guide and Reference Release 8.0.4 A53264-02 |
Library | Product | Contents | Index

# 7
Geometry Functions

This chapter contains descriptions of the geometric functions and procedures shown in Table 7-1.:

##### Table 7-1 Geometric Functions and Procedures

Function/Procedure | Description
--- | ---
SDO_GEOM.ADD_NODES | Stores points in the geometry table.
SDO_GEOM.INIT_ELEMENT | Initializes space in the geometry table for a new object.
SDO_GEOM.INTERACT | Determines if two objects are disjoint.
SDO_GEOM.RELATE | Determines how two objects interact.
SDO_GEOM.VALIDATE_GEOMETRY | Determines if a geometry is valid.

## SDO_GEOM.ADD_NODES

### Purpose

This procedure stores coordinate geometry points into the SDOGEOM table.

### Syntax

SDO_GEOM.ADD_NODES (layername, SDO_GID, SDO_ESEQ, SDO_ETYPE, X-ord1,Y-ord1[,...,X125, Y125])

### Keywords and Parameters

#####

layername | Specifies the name of the data set layer. The layername is used to construct the name of the geometry and spatial index tables. Data type is VARCHAR2.
SDO_GID | Specifies the unique geometric object identifier. Data type is NUMBER.
SDO_ESEQ | Specifies the element sequence number. The eseq is unique within an SDO_GID. Data type is NUMBER.
SDO_ETYPE | Specifies the type of geometric element. Data type is INTEGER, corresponding to the following constants: 1 SDO_GEOM.POINT_TYPE 2 SDO_GEOM.LINESTRING_TYPE 3 SDO_GEOM.POLYGON_TYPE
X ordinateN, Y ordinateN | Specifies the X and Y values of a vertex (coordinate pair) in a geometry. Up to 125 pairs may be added in a single call. Data type is NUMBER.

### Usage Notes

Consider the following when using this procedure:

- Use the SQL CREATE TABLE statement to create the geometry table,
  <layername>_SDOGEOM, before calling this procedure.
- Prior to calling this procedure, call the SDO_GEOM.INIT_ELEMENT() function to initialize the geometry element and retrieve the element sequence number (SDO_ESEQ).
- Close a polygon by providing the coordinates of the first vertex as the last vertex.
- Call this procedure iteratively with the same GID to add coordinates to a geometric object. You can add up to 125 coordinate pairs on each call, and there is no limit to how many times you can add more vertices.
- This procedure cannot be used when <layername>_SDOGEOM is a view. For layer objects created as views, you need to explicitly insert new geometries, as opposed to using SDO_GEOM.INIT_ELEMENT() and SDO_GEOM.ADD_NODES().

Example 7-1 adds a polygon element for geometry 25 in the LAYER1 data set. The polygon is a square.

#### Example 7-1

SQL> EXECUTE SDO_GEOM.ADD_NODES (`LAYER1', 25,2> SDO_GEOM.POLYGON_TYPE,3> 3,3, 7,3, 4> 7,7, 3,7,5> 3,3);

### Related Topics

- SDO_GEOM.INIT_ELEMENT() function

## SDO_GEOM.INIT_ELEMENT

### Purpose

This function initializes elements in the SDOINFO table or view for a new geometry element.

### Syntax

SDO_GEOM.INIT_ELEMENT (layername, SDO_GID)

### Keywords and Parameters

#####

layername | Specifies the name of the data set layer. The layername is used to construct the name of the geometry and spatial index tables. Data type is VARCHAR2.
SDO_GID | Specifies the geometric object identifier. Data type is NUMBER.

### Returns

This function returns the next element sequence number. The data type is INTEGER.

### Usage Notes

This function initializes the element to be stored, but does not actually insert coordinates into the SDOGEOM table. The SDO_GEOM.ADD_NODES() procedure is used to insert associated coordinate data.

For layer objects created as views, you need to explicitly insert new geometries, as opposed to using SDO_GEOM.INIT_ELEMENT() and SDO_GEOM.ADD_NODES().

### Related Topics

- SDO_GEOM.ADD_NODES() procedure

## SDO_GEOM.INTERACT

### Purpose

This function determines if two geometry objects interact.

### Syntax

SDO_GEOM.INTERACT (layername1, SDO_GID1, [layername2,] SDO_GID2)

SDO_GEOM.INTERACT (layername1, SDO_GID1, X_tolerance, Y_tolerance, SDO_ETYPE, num_ordinates, X_ordinate1, Y_ordinate1 [, ..., Xn, Yn]
[,SDO_ETYPE, num_ordinates, X_ordinate1, Y_ordinate1 [,...Xn,Yn]])

### Keywords and Parameters

#####

layername1, layername2 | Specifies the name of the data set layer. The layername is used to construct the name of the geometry and spatial index tables. Data type is VARCHAR2.
SDO_GID1, SDO_GID2 | Specifies the geometric object identifier. Data type is NUMBER.
X_tolerance, Y_tolerance | Specifies the distance two points can be apart and still be considered the same due to rounding errors. Tolerance must be greater than zero. If you want zero tolerance, enter a number such as 0.000005, where the number of zeroes to the right of the decimal point matches the precision of your data. Data type is NUMBER.
SDO_ETYPE | Specifies the type of geometry object. Data type is INTEGER, corresponding to the following constants: 1 SDO_GEOM.POINT_TYPE 2 SDO_GEOM.LINESTRING_TYPE 3 SDO_GEOM.POLYGON_TYPE
num_ordinates | Specifies the number of ordinates for this element. Data type is NUMBER.
X_ordinateN, Y_ordinateN | Specifies the X and Y values of a vertex (coordinate pair) in a geometry. Data type is NUMBER.

### Returns

This function returns TRUE if the first and second objects interact with each other and are not disjoint. The data type is VARCHAR2.

### Usage Notes

Use the first form of the function to test two stored geometry objects.

Use the second form of the function to compare a stored object against a user-defined object. You can specify up to 123 vertices for a single element geometry. If the geometry has multiple elements, the total number of arguments passed, including SDO_ETYPE, num_ordinates, and the list of vertex coordinates cannot exceed 250 values.

### Related Topics

- SDO_GEOM.RELATE() function

## SDO_GEOM.RELATE

### Purpose

This function examines two geometry objects to determine their spatial relationship.

### Syntax

SDO_GEOM.RELATE (layername1, SDO_GID1, mask, [layername2,] SDO_GID2)

SDO_GEOM.RELATE (layername1, SDO_GID1, mask, X_tolerance, Y_tolerance, SDO_ETYPE, num_ordinates, X_ordinate1, Y_ordinate1 [,...,Xn, Yn] [,SDO_ETYPE, num_ordinates, X_ordinate1, Y_ordinate1 [,...,Xn, Yn]])

### Keywords and Parameters

#####

layername1, layername2 | Specifies the name of the data set layer. The layername is used to construct the name of the geometry and spatial index tables. Data type is VARCHAR2.
SDO_GID1, SDO_GID2 | Specifies the geometry object identifier. Data type is NUMBER.
mask | Specifies the relationship mask. See the list of keywords in the Usage Notes.
X_tolerance, Y_tolerance | Specifies the distance two points can be apart and still be considered the same due to rounding errors. Tolerance must be greater than zero. If you want zero tolerance, enter a number such as 0.000005, where the number of zeroes to the right of the decimal point matches the precision of your data. Data type is NUMBER.
SDO_ETYPE | Specifies the type of geometry element. Data type is INTEGER, corresponding to the following constants: 1 SDO_GEOM.POINT_TYPE 2 SDO_GEOM.LINESTRING_TYPE 3 SDO_GEOM.POLYGON_TYPE
num_ordinates | Specifies the number of ordinates for this element. Data type is NUMBER.
X_ordinateN, Y_ordinateN | Specifies the X and Y values of a vertex (coordinate pair) in a geometry. Data type is NUMBER.

### Returns

The SDO_GEOM.RELATE() function can return three types of answers:

1. If you pass a mask listing one or more relationships, the function returns the names of the relationships if all of them are true. If one or more relationships are false, the procedure returns FALSE.
2. If you pass the DETERMINE keyword in the mask, the function returns the one relationship keyword that best matches the geometries.
3. If you pass the ANYINTERACT keyword in the mask, the function returns TRUE if the two geometries are not disjoint. This is equivalent to the SDO_GEOM.INTERACT() function.

The data type is VARCHAR2.

### Usage Notes

Use the first form of the function to examine two stored geometry objects.

Use the second form of the function to compare a stored object against a user-defined object. You can specify up to 123 vertices for a single-element geometry. If the geometry has multiple elements, the total number of arguments passed, including SDO_ETYPE, num_ordinates, and the list of vertex coordinates cannot exceed 250 values.

The following relationships can be tested:

- ANYINTERACT - Returns TRUE if the objects are not disjoint.
- CONTAINS - Returns TRUE if the second object is entirely within the first object and the object boundaries do not touch.
- COVEREDBY - Returns TRUE if the first object is entirely within the second object and the object boundaries touch at one or more points.
- COVERS - Returns TRUE if the second object is entirely within the first object and the boundaries touch in one or more places.
- DISJOINT - Returns TRUE if the objects have no common boundary or interior points.
- EQUAL - Returns TRUE if the objects share every point of their boundaries and interior, including any holes in the objects.
- INSIDE - Returns TRUE if the first object is entirely within the second object and the object boundaries do not touch.
- OVERLAPBDYDISJOINT - Returns TRUE if the objects overlap, but their boundaries do not interact.
- OVERLAPBDYINTERSECT - Returns TRUE if the object overlap, and their boundaries intersect in one or more places.
- TOUCH - Returns TRUE if the two objects share a common boundary point, but no interior points.

Mask values can be combined using a logical OR. For example, `INSIDE + TOUCH' returns TRUE if the objects pass either test.

### Related Topics

- SDO_GEOM.INTERACT() function

## 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 (layername,SDO_GID)

### Keywords and Parameters

#####

layername | Specifies the name of the data set layer. The layername is used to construct the name of the geometry and spatial index tables. Data type is VARCHAR2.
SDO_GID | Specifies the geometric object identifier. Data type is NUMBER.

### Returns

This function returns TRUE if the geometry is valid. The data type is VARCHAR2.

### Usage Notes

This function checks for the following:

- polygons have at least three points and must be closed
- line strings must have at least two points
- when and SDO_ESEQ spans multiple rows, the last point of the previous row is the first point on the next row

### Related Topics

None

Prev | Next
| Copyright © 1997 Oracle Corporation. All Rights Reserved. |
Library | Product | Contents | Index