Skip Headers
Oracle® Spatial Developer's Guide
11g Release 1 (11.1)

Part Number B28400-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

24 SDO_GEOM Package (Geometry)

This chapter contains descriptions of the geometry-related PL/SQL subprograms in the SDO_GEOM package, which can be grouped into the following categories:

The geometry subprograms are listed Table 24-1, and some usage information follows the table.

Table 24-1 Geometry Subprograms

Subprogram Description

SDO_GEOM.RELATE


Determines how two objects interact.

SDO_GEOM.SDO_ARC_DENSIFY


Changes each circular arc into an approximation consisting of straight lines, and each circle into a polygon consisting of a series of straight lines that approximate the circle.

SDO_GEOM.SDO_AREA


Computes the area of a two-dimensional polygon.

SDO_GEOM.SDO_BUFFER


Generates a buffer polygon around or inside a geometry.

SDO_GEOM.SDO_CENTROID


Returns the centroid of a polygon.

SDO_GEOM.SDO_CLOSEST_POINTS


Computes the minimum distance between two geometries and the points (one on each geometry) that are the minimum distance apart.

SDO_GEOM.SDO_CONVEXHULL


Returns a polygon-type object that represents the convex hull of a geometry object.

SDO_GEOM.SDO_DIFFERENCE


Returns a geometry object that is the topological difference (MINUS operation) of two geometry objects.

SDO_GEOM.SDO_DISTANCE


Computes the distance between two geometry objects.

SDO_GEOM.SDO_INTERSECTION


Returns a geometry object that is the topological intersection (AND operation) of two geometry objects.

SDO_GEOM.SDO_LENGTH


Computes the length or perimeter of a geometry.

SDO_GEOM.SDO_MAX_MBR_ORDINATE


Returns the maximum value for the specified ordinate (dimension) of the minimum bounding rectangle of a geometry object.

SDO_GEOM.SDO_MBR


Returns the minimum bounding rectangle of a geometry.

SDO_GEOM.SDO_MIN_MBR_ORDINATE


Returns the minimum value for the specified ordinate (dimension) of the minimum bounding rectangle of a geometry object.

SDO_GEOM.SDO_POINTONSURFACE


Returns a point that is guaranteed to be on the surface of a polygon.

SDO_GEOM.SDO_UNION


Returns a geometry object that is the topological union (OR operation) of two geometry objects.

SDO_GEOM.SDO_VOLUME


Computes the volume of a three-dimensional solid geometry.

SDO_GEOM.SDO_XOR


Returns a geometry object that is the topological symmetric difference (XOR operation) of two geometry objects.

SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT


Determines if a geometry is valid, and returns context information if the geometry is invalid.

SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT


Determines if all geometries stored in a column are valid, and returns context information about any invalid geometries.

SDO_GEOM.WITHIN_DISTANCE


Determines if two geometries are within a specified distance from one another.


The following usage information applies to the geometry subprograms. (See also the Usage Notes under the reference information for each subprogram.)


SDO_GEOM.RELATE

Format

SDO_GEOM.RELATE(

     geom1 IN SDO_GEOMETRY,

     dim1 IN SDO_DIM_ARRAY,

     mask IN VARCHAR2,

     geom2 IN SDO_GEOMETRY,

     dim2 IN SDO_DIM_ARRAY

     ) RETURN VARCHAR2;

or

SDO_GEOM.RELATE(

     geom1 IN SDO_GEOMETRY,

     mask IN VARCHAR2,

     geom2 IN SDO_GEOMETRY,

     tol IN NUMBER

     ) RETURN VARCHAR2;

Description

Examines two geometry objects to determine their spatial relationship.

Parameters

geom1

Geometry object.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

mask

Specifies a list of relationships to check. See the list of keywords in the Usage Notes.

geom2

Geometry object.

dim2

Dimensional information array corresponding to geom2, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

Usage Notes

For better performance, use the SDO_RELATE operator or one of its convenience operator formats (all described in Chapter 19) instead of the SDO_GEOM.RELATE function, unless you need to use the function. For example, the DETERMINE mask keyword does not apply with the SDO_RELATE operator. For more information about performance considerations with operators and functions, see Section 1.9.

The SDO_GEOM.RELATE function can return the following types of answers:

The following mask relationships can be tested:

Values for mask can be combined using the logical Boolean operator OR. For example, 'INSIDE + TOUCH' returns 'INSIDE + TOUCH' or 'FALSE' depending on the outcome of the test.

An exception is raised if geom1 and geom2 are based on different coordinate systems.

Examples

The following example finds the relationship between each geometry in the SHAPE column and the cola_b geometry. (The example uses the definitions and data from Section 2.1. The output is reformatted for readability.)

SELECT c.name,
  SDO_GEOM.RELATE(c.shape, 'determine', c_b.shape, 0.005) relationship 
  FROM cola_markets c, cola_markets c_b WHERE c_b.name = 'cola_b';

NAME     RELATIONSHIP 
---------------------------                                  cola_a   TOUCH
cola_b   EQUAL
cola_c   OVERLAPBDYINTERSECT
cola_d   DISJOINT 

Related Topics


SDO_GEOM.SDO_ARC_DENSIFY

Format

SDO_GEOM.SDO_ARC_DENSIFY(

     geom IN SDO_GEOMETRY,

     dim IN SDO_DIM_ARRAY

     params IN VARCHAR2

     ) RETURN SDO_GEOMETRY;

or

SDO_GEOM.SDO_ARC_DENSIFY(

     geom IN SDO_GEOMETRY,

     tol IN NUMBER

     params IN VARCHAR2

     ) RETURN SDO_GEOMETRY;

Description

Returns a geometry in which each circular arc in the input geometry is changed into an approximation of the circular arc consisting of straight lines, and each circle is changed into a polygon consisting of a series of straight lines that approximate the circle.

Parameters

geom

Geometry object.

dim

Dimensional information array corresponding to geom, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

params

A quoted string containing an arc tolerance value and optionally a unit value. See the Usage Notes for an explanation of the format and meaning.

Usage Notes

If you have geometries in a projected coordinate system that contain circles or circular arcs, you can use this function to densify them into regular polygons. You can then use the resulting straight-line polygon geometries for any Spatial operations, or you can transform them to any projected or geodetic coordinate system.

The params parameter is a quoted string that can contain the arc_tolerance keyword, as well as the unit keyword to identify the unit of measurement associated with the arc_tolerance value. For example:

'arc_tolerance=0.05 unit=km'

The arc_tolerance keyword specifies, for each arc in the geometry, the maximum length of the perpendicular line between the surface of the arc and the straight line between the start and end points of the arc. Figure 24-1 shows a line whose length is the arc_tolerance value for the arc between points A and B.

Figure 24-1 Arc Tolerance

Description of Figure 24-1 follows
Description of "Figure 24-1 Arc Tolerance"

The arc_tolerance keyword value must be greater than the tolerance value associated with the geometry. (The default value for arc_tolerance is 20 times the tolerance value.) As you increase the arc_tolerance keyword value, the resulting polygon has fewer sides and a smaller area; as you decrease the arc_tolerance keyword value, the resulting polygon has more sides and a larger area (but never larger than the original geometry).

If the unit keyword is specified, the value must be an SDO_UNIT value from the MDSYS.SDO_DIST_UNITS table (for example, 'unit=KM'). If the unit keyword is not specified, the unit of measurement associated with the geometry is used. See Section 2.10 for more information about unit of measurement specification.

Examples

The following example returns the geometry that results from the arc densification of cola_d, which is a circle. (The example uses the definitions and data from Section 2.1.)

-- Arc densification of the circle cola_d
SELECT c.name, SDO_GEOM.SDO_ARC_DENSIFY(c.shape, m.diminfo, 
                                       'arc_tolerance=0.05') 
  FROM cola_markets c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c.name = 'cola_d';

NAME
--------------------------------
SDO_GEOM.SDO_ARC_DENSIFY(C.SHAPE,M.DIMINFO,'ARC_TOLERANCE=0.05')(SDO_GTYPE, SDO_
--------------------------------------------------------------------------------
cola_d
SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR
AY(8, 7, 8.76536686, 7.15224093, 9.41421356, 7.58578644, 9.84775907, 8.23463314,
 10, 9, 9.84775907, 9.76536686, 9.41421356, 10.4142136, 8.76536686, 10.8477591,
8, 11, 7.23463314, 10.8477591, 6.58578644, 10.4142136, 6.15224093, 9.76536686, 6
, 9, 6.15224093, 8.23463314, 6.58578644, 7.58578644, 7.23463314, 7.15224093, 8,
7))

Related Topics


SDO_GEOM.SDO_AREA

Format

SDO_GEOM.SDO_AREA(

     geom IN SDO_GEOMETRY,

     dim IN SDO_DIM_ARRAY

     [, unit IN VARCHAR2]

     ) RETURN NUMBER;

or

SDO_GEOM.SDO_AREA(

     geom IN SDO_GEOMETRY,

     tol IN NUMBER

     [, unit IN VARCHAR2]

     ) RETURN NUMBER;

Description

Returns the area of a two-dimensional polygon.

Parameters

geom

Geometry object.

dim

Dimensional information array corresponding to geom, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

unit

Unit of measurement: a quoted string with unit= and an SDO_UNIT value from the MDSYS.SDO_AREA_UNITS table (for example, 'unit=SQ_KM'). See Section 2.10 for more information about unit of measurement specification.

If this parameter is not specified, the unit of measurement associated with the data is assumed. For geodetic data, the default unit of measurement is square meters.

tol

Tolerance value (see Section 1.5.5).

Usage Notes

This function works with any polygon, including polygons with holes.

Lines that close to form a ring have no area.

Examples

The following example returns the areas of geometry objects stored in the COLA_MARKETS table. The first statement returns the areas of all objects; the second returns just the area of cola_a. (The example uses the definitions and data from Section 2.1.)

-- Return the areas of all cola markets.
SELECT name, SDO_GEOM.SDO_AREA(shape, 0.005) FROM cola_markets;

NAME                             SDO_GEOM.SDO_AREA(SHAPE,0.005)
-------------------------------- ------------------------------
cola_a                                                       24
cola_b                                                     16.5
cola_c                                                        5
cola_d                                               12.5663706

-- Return the area of just cola_a.
SELECT c.name, SDO_GEOM.SDO_AREA(c.shape, 0.005) FROM cola_markets c 
   WHERE c.name = 'cola_a';

NAME                             SDO_GEOM.SDO_AREA(C.SHAPE,0.005)
-------------------------------- --------------------------------
cola_a                                                         24

Related Topics

None.


SDO_GEOM.SDO_BUFFER

Format

SDO_GEOM.SDO_BUFFER(

     geom IN SDO_GEOMETRY,

     dim IN SDO_DIM_ARRAY,

     dist IN NUMBER

     [, params IN VARCHAR2]

     ) RETURN SDO_GEOMETRY;

or

SDO_GEOM.SDO_BUFFER(

     geom IN SDO_GEOMETRY,

     dist IN NUMBER,

     tol IN NUMBER

     [, params IN VARCHAR2]

     ) RETURN SDO_GEOMETRY;

Description

Generates a buffer polygon around or inside a geometry object.

Parameters

geom

Geometry object.

dim

Dimensional information array corresponding to geom, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

dist

Distance value. If the value is positive, the buffer is generated around the geometry; if the value is negative (valid only for polygons), the buffer is generated inside the geometry. The absolute value of this parameter must be greater than the tolerance value, as specified in the dimensional array (dim parameter) or in the tol parameter.

tol

Tolerance value (see Section 1.5.5).

params

A quoted string that can contain one or both of the following keywords:

  • unit and an SDO_UNIT value from the MDSYS.SDO_DIST_UNITS table. It identifies the unit of measurement associated with the dist parameter value, and also with the arc tolerance value if the arc_tolerance keyword is specified. See Section 2.10 for more information about unit of measurement specification.

  • arc_tolerance and an arc tolerance value. See the Usage Notes for the SDO_GEOM.SDO_ARC_DENSIFY function in this chapter for more information about the arc_tolerance keyword.

For example: 'unit=km arc_tolerance=0.05'

If the input geometry is geodetic data and if arc_tolerance is not specified, the default value is the tolerance value multiplied by 20. Spatial uses the arc_tolerance value to perform arc densification in computing the result. If the input geometry is Cartesian or projected data, arc_tolerance has no effect and should not be specified.

If this parameter is not specified for a Cartesian or projected geometry, or if the arc_tolerance keyword is specified for a geodetic geometry but the unit keyword is not specified, the unit of measurement associated with the data is assumed.

Usage Notes

This function returns a geometry object representing the buffer polygon.

This function creates a rounded buffer around a point, line, or polygon, or inside a 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-7 for an illustration.

If the buffer polygon geometry is in a projected coordinate system, it will contain arcs; and if you want to transform that geometry to a geodetic coordinate system, you must first densify it using the SDO_GEOM.SDO_ARC_DENSIFY function, and then transform the densified geometry.

With geodetic data, this function is supported by approximations, as explained in Section 6.10.3.

With geodetic data, this function should be used only for relatively small geometries: geometries for which the local tangent plane projection that is used for internal computations does not introduce significant distortions or errors. This limits the applicable domain of source geometries, whether line strings or polygons, to approximately the area of Texas (United States), France, or Manchuria province (China).

Examples

The following example returns a polygon representing a buffer of 1 around cola_a. Note the rounded corners (for example, at .292893219,.292893219) in the returned polygon. (The example uses the non-geodetic definitions and data from Section 2.1.)

-- Generate a buffer of 1 unit around a geometry.
SELECT c.name, SDO_GEOM.SDO_BUFFER(c.shape, m.diminfo, 1) 
  FROM cola_markets c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS'  AND m.column_name = 'SHAPE' 
  AND c.name = 'cola_a';

NAME                                                                            
--------------------------------                                                
SDO_GEOM.SDO_BUFFER(C.SHAPE,M.DIMINFO,1)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z)
--------------------------------------------------------------------------------
cola_a                                                                          
SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1005, 8, 1, 2, 2, 5, 2, 1,
 7, 2, 2, 11, 2, 1, 13, 2, 2, 17, 2, 1, 19, 2, 2, 23, 2, 1), SDO_ORDINATE_ARRAY(
0, 1, .292893219, .292893219, 1, 0, 5, 0, 5.70710678, .292893219, 6, 1, 6, 7, 5.
70710678, 7.70710678, 5, 8, 1, 8, .292893219, 7.70710678, 0, 7, 0, 1))

The following example returns a polygon representing a buffer of 1 around cola_a using the geodetic definitions and data from Section 6.12.

-- Generate a buffer of 1 kilometer around a geometry.
SELECT c.name, SDO_GEOM.SDO_BUFFER(c.shape, m.diminfo, 1, 
                                  'unit=km arc_tolerance=0.05')
 FROM cola_markets c, user_sdo_geom_metadata m 
 WHERE m.table_name = 'COLA_MARKETS' 
 AND m.column_name = 'SHAPE' AND c.name = 'cola_a';

NAME                                                                            
--------------------------------                                                
SDO_GEOM.SDO_BUFFER(C.SHAPE,M.DIMINFO,1,'UNIT=KMARC_TOLERANCE=0.05')(SDO_GTYPE, 
--------------------------------------------------------------------------------
cola_a                                                                          
SDO_GEOMETRY(2003, 8307, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR
AY(.991023822, 1.00002073, .992223711, .995486419, .99551726, .99217077, 1.00001
929, .990964898, 4.99998067, .990964929, 5.00448268, .9921708, 5.00777624, .9954
86449, 5.00897618, 1.00002076, 5.00904194, 6.99997941, 5.00784065, 7.00450033, 5
.00454112, 7.00781357, 5.00002479, 7.009034, .999975166, 7.00903403, .995458814,
 7.00781359, .992159303, 7.00450036, .990958058, 6.99997944, .991023822, 1.00002
073))

Related Topics


SDO_GEOM.SDO_CENTROID

Format

SDO_GEOM.SDO_CENTROID(

     geom1 IN SDO_GEOMETRY,

     dim1 IN SDO_DIM_ARRAY

     ) RETURN SDO_GEOMETRY;

or

SDO_GEOM.SDO_CENTROID(

     geom1 IN SDO_GEOMETRY,

     tol IN NUMBER

     ) RETURN SDO_GEOMETRY;

Description

Returns a point geometry that is the centroid of a polygon, multipolygon, point, or point cluster. (The centroid is also known as the "center of gravity.")

For an input geometry consisting of multiple objects, the result is weighted by the area of each polygon in the geometry objects. If the geometry objects are a mixture of polygons and points, the points are not used in the calculation of the centroid. If the geometry objects are all points, the points have equal weight.

Parameters

geom1

Geometry object.

dim1

Dimensional information array corresponding to geom, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

Usage Notes

The function returns a null value if geom1 is not a polygon, multipolygon, point, or point cluster, as identified by the SDO_GTYPE value in the SDO_GEOMETRY object.

If geom1 is a point, the function returns the point (the input geometry).

With geodetic data, this function is supported by approximations, as explained in Section 6.10.3.

Depending on the shape and complexity of the input geometry, the returned point might not be on the surface of the input geometry.

Examples

The following example returns a geometry object that is the centroid of cola_c. (The example uses the definitions and data from Section 2.1.)

-- Return the centroid of a geometry.
SELECT c.name, SDO_GEOM.SDO_CENTROID(c.shape, m.diminfo) 
  FROM cola_markets c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c.name = 'cola_c';

NAME                                                                            
--------------------------------                                                
SDO_GEOM.SDO_CENTROID(C.SHAPE,M.DIMINFO)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z)
--------------------------------------------------------------------------------
cola_c                                                                          
SDO_GEOMETRY(2001, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(
4.73333333, 3.93333333))

Related Topics

None.


SDO_GEOM.SDO_CLOSEST_POINTS

Format

SDO_GEOM.SDO_CLOSEST_POINTS(

     geom1 IN SDO_GEOMETRY,

     geom2 IN SDO_GEOMETRY,

     tolerance IN NUMBER,

     unit IN VARCHAR2,

     dist OUT NUMBER,

     geoma OUT SDO_GEOMETRY,

     geomb OUT SDO_GEOMETRY);

Description

Computes the minimum distance between two geometries and the points (one on each geometry) that are the minimum distance apart.

Parameters

geom1

Geometry object.

geom2

Geometry object.

tolerance

Tolerance value (see Section 1.5.5).

unit

Unit of measurement: a quoted string with unit= and an SDO_UNIT value from the MDSYS.SDO_DIST_UNITS table (for example, 'unit=KM'). See Section 2.10 for more information about unit of measurement specification.

If this parameter is not specified, the unit of measurement associated with the data is assumed.

dist

Output parameter containing the minimum distance between geom1 and geom2. Specifically, the distance between geoma and geomb.

geoma

Output parameter containing the point geometry object on the boundary of geom1 that is closest to the closest point on the boundary of geom2.

geomb

Output parameter containing the point geometry object on the boundary of geom2 that is closest to the closest point on the boundary of geom1.

Usage Notes

This procedure uses output parameters to store the computed minimum distance and the point on each input geometry associated with the minimum distance.

Examples

The following example computes the minimum distance between geometries cola_c and cola_d, as well as the one point on each input geometry associated with the minimum distance. It also inserts the two output point geometries into the table and then selects these point geometries. The minimum distance between the two input geometries is 2.47213595499958, the closest point on cola_c is at (6,5), and the closest point on cola_d is at (7.10557281, 7.21114562). (The example uses the definitions and data from Section 2.1.)

DECLARE
  cola_c_geom SDO_GEOMETRY;
  cola_d_geom SDO_GEOMETRY;
  dist NUMBER;
  geoma SDO_GEOMETRY;
  geomb SDO_GEOMETRY;
  
BEGIN
  
-- Populate geometry variables with cola market shapes.
SELECT c.shape into cola_c_geom FROM cola_markets c
  WHERE c.name = 'cola_c';
SELECT c.shape into cola_d_geom FROM cola_markets c
  WHERE c.name = 'cola_d';
 
SDO_GEOM.SDO_CLOSEST_POINTS(cola_c_geom, cola_d_geom, 0.005, NULL,
  dist, geoma, geomb);
  
INSERT INTO cola_markets VALUES(9901, 'geoma', geoma);
INSERT INTO cola_markets VALUES(9902, 'geomb', geomb);
  
DBMS_OUTPUT.PUT_LINE('dist output parameter value = ' || dist);
END;
/
dist output parameter value = 2.47213595499958                                  
 
PL/SQL procedure successfully completed.
 
SELECT c.shape FROM cola_markets c WHERE c.name = 'geoma';
 
SHAPE(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDINATES)    
--------------------------------------------------------------------------------
SDO_GEOMETRY(2001, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(
6, 5))                                                                          
                                                                                
SELECT c.shape FROM cola_markets c WHERE c.name = 'geomb';
 
SHAPE(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDINATES)    
--------------------------------------------------------------------------------
SDO_GEOMETRY(2001, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(
7.10557281, 7.21114562))

Related Topics

None.


SDO_GEOM.SDO_CONVEXHULL

Format

SDO_GEOM.SDO_CONVEXHULL(

     geom1 IN SDO_GEOMETRY,

     dim1 IN SDO_DIM_ARRAY

     ) RETURN SDO_GEOMETRY;

or

SDO_GEOM.SDO_CONVEXHULL(

     geom1 IN SDO_GEOMETRY,

     tol IN NUMBER

     ) RETURN SDO_GEOMETRY;

Description

Returns a polygon-type object that represents the convex hull of a geometry object.

Parameters

geom1

Geometry object.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

Usage Notes

The convex hull is a simple convex polygon that completely encloses the geometry object. Spatial uses as few straight-line sides as possible to create the smallest polygon that completely encloses the specified object. A convex hull is a convenient way to get an approximation of a complex geometry object.

If the geometry (geom1) contains any arc elements, the function calculates the minimum bounding rectangle (MBR) for each arc element and uses these MBRs in calculating the convex hull of the geometry. If the geometry object (geom1) is a circle, the function returns a square that minimally encloses the circle.

The function returns a null value if geom1 is of point type, has fewer than three points or vertices, or consists of multiple points all in a straight line.

With geodetic data, this function is supported by approximations, as explained in Section 6.10.3.

Examples

The following example returns a geometry object that is the convex hull of cola_c. (The example uses the definitions and data from Section 2.1. This specific example, however, does not produce useful output—the returned polygon has the same vertices as the input polygon—because the input polygon is already a simple convex polygon.)

-- Return the convex hull of a polygon.
SELECT c.name, SDO_GEOM.SDO_CONVEXHULL(c.shape, m.diminfo) 
  FROM cola_markets c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c.name = 'cola_c';

NAME                                                                            
--------------------------------                                                
SDO_GEOM.SDO_CONVEXHULL(C.SHAPE,M.DIMINFO)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, 
--------------------------------------------------------------------------------
cola_c                                                                          
SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR
AY(6, 3, 6, 5, 4, 5, 3, 3, 6, 3))

Related Topics

None.


SDO_GEOM.SDO_DIFFERENCE

Format

SDO_GEOM.SDO_DIFFERENCE(

     geom1 IN SDO_GEOMETRY,

     dim1 IN SDO_DIM_ARRAY,

     geom2 IN SDO_GEOMETRY,

     dim2 IN SDO_DIM_ARRAY

     ) RETURN SDO_GEOMETRY;

or

SDO_GEOM.SDO_DIFFERENCE(

     geom1 IN SDO_GEOMETRY,

     geom2 IN SDO_GEOMETRY,

     tol IN NUMBER

     ) RETURN SDO_GEOMETRY;

Description

Returns a geometry object that is the topological difference (MINUS operation) of two geometry objects.

Parameters

geom1

Geometry object.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

geom2

Geometry object.

dim2

Dimensional information array corresponding to geom2, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

Usage Notes

In Figure 24-2, the shaded area represents the polygon returned when SDO_DIFFERENCE is used with a square (geom1) and another polygon (geom2).

Figure 24-2 SDO_GEOM.SDO_DIFFERENCE

Description of Figure 24-2 follows
Description of "Figure 24-2 SDO_GEOM.SDO_DIFFERENCE"

An exception is raised if geom1 and geom2 are based on different coordinate systems.

Examples

The following example returns a geometry object that is the topological difference (MINUS operation) of cola_a and cola_c. (The example uses the definitions and data from Section 2.1.)

-- Return the topological difference of two geometries.
SELECT SDO_GEOM.SDO_DIFFERENCE(c_a.shape, m.diminfo, c_c.shape, m.diminfo) 
  FROM cola_markets c_a, cola_markets c_c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c_a.name = 'cola_a' AND c_c.name = 'cola_c';

SDO_GEOM.SDO_DIFFERENCE(C_A.SHAPE,M.DIMINFO,C_C.SHAPE,M.DIMINFO)(SDO_GTYPE, SDO_
--------------------------------------------------------------------------------
SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR
AY(1, 7, 1, 1, 5, 1, 5, 3, 3, 3, 4, 5, 5, 5, 5, 7, 1, 7)

Note that in the returned polygon, the SDO_ORDINATE_ARRAY starts and ends at the same point (1, 7).

Related Topics


SDO_GEOM.SDO_DISTANCE

Format

SDO_GEOM.SDO_DISTANCE(

     geom1 IN SDO_GEOMETRY,

     dim1 IN SDO_DIM_ARRAY,

     geom2 IN SDO_GEOMETRY,

     dim2 IN SDO_DIM_ARRAY

     [, unit IN VARCHAR2]

     ) RETURN NUMBER;

or

SDO_GEOM.SDO_DISTANCE(

     geom1 IN SDO_GEOMETRY,

     geom2 IN SDO_GEOMETRY,

     tol IN NUMBER

     [, unit IN VARCHAR2]

     ) RETURN NUMBER;

Description

Computes the distance between two geometry objects. The distance between two geometry objects is the distance between the closest pair of points or segments of the two objects.

Parameters

geom1

Geometry object whose distance from geom2 is to be computed.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

geom2

Geometry object whose distance from geom1 is to be computed.

dim2

Dimensional information array corresponding to geom2, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

unit

Unit of measurement: a quoted string with unit= and an SDO_UNIT value from the MDSYS.SDO_DIST_UNITS table (for example, 'unit=KM'). See Section 2.10 for more information about unit of measurement specification.

If this parameter is not specified, the unit of measurement associated with the data is assumed.

tol

Tolerance value (see Section 1.5.5).

Usage Notes

An exception is raised if geom1 and geom2 are based on different coordinate systems.

Examples

The following example returns the shortest distance between cola_b and cola_d. (The example uses the definitions and data from Section 2.1.)

-- Return the distance between two geometries.
SELECT SDO_GEOM.SDO_DISTANCE(c_b.shape, c_d.shape, 0.005)
   FROM cola_markets c_b, cola_markets c_d
   WHERE c_b.name = 'cola_b' AND c_d.name = 'cola_d';

SDO_GEOM.SDO_DISTANCE(C_B.SHAPE,C_D.SHAPE,0.005)
------------------------------------------------
                                      .846049894

Related Topics


SDO_GEOM.SDO_INTERSECTION

Format

SDO_GEOM.SDO_INTERSECTION(

     geom1 IN SDO_GEOMETRY,

     dim1 IN SDO_DIM_ARRAY,

     geom2 IN SDO_GEOMETRY,

     dim2 IN SDO_DIM_ARRAY

     ) RETURN SDO_GEOMETRY;

or

SDO_GEOM.SDO_INTERSECTION(

     geom1 IN SDO_GEOMETRY,

     geom2 IN SDO_GEOMETRY,

     tol IN NUMBER

     ) RETURN SDO_GEOMETRY;

Description

Returns a geometry object that is the topological intersection (AND operation) of two geometry objects.

Parameters

geom1

Geometry object.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

geom2

Geometry object.

dim2

Dimensional information array corresponding to geom2, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

Usage Notes

In Figure 24-3, the shaded area represents the polygon returned when SDO_INTERSECTION is used with a square (geom1) and another polygon (geom2).

Figure 24-3 SDO_GEOM.SDO_INTERSECTION

Description of Figure 24-3 follows
Description of "Figure 24-3 SDO_GEOM.SDO_INTERSECTION"

An exception is raised if geom1 and geom2 are based on different coordinate systems.

Examples

The following example returns a geometry object that is the topological intersection (AND operation) of cola_a and cola_c. (The example uses the definitions and data from Section 2.1.)

-- Return the topological intersection of two geometries.
SELECT SDO_GEOM.SDO_INTERSECTION(c_a.shape, c_c.shape, 0.005)
   FROM cola_markets c_a, cola_markets c_c 
   WHERE c_a.name = 'cola_a' AND c_c.name = 'cola_c';

SDO_GEOM.SDO_INTERSECTION(C_A.SHAPE,C_C.SHAPE,0.005)(SDO_GTYPE, SDO_SRID, SDO_PO
--------------------------------------------------------------------------------
SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR
AY(4, 5, 3, 3, 5, 3, 5, 5, 4, 5))

Note that in the returned polygon, the SDO_ORDINATE_ARRAY starts and ends at the same point (4, 5).

Related Topics


SDO_GEOM.SDO_LENGTH

Format

SDO_GEOM.SDO_LENGTH(

     geom IN SDO_GEOMETRY,

     dim IN SDO_DIM_ARRAY

     [, unit IN VARCHAR2]

     ) RETURN NUMBER;

or

SDO_GEOM.SDO_LENGTH(

     geom IN SDO_GEOMETRY,

     tol IN NUMBER

     [, unit IN VARCHAR2]

     ) RETURN NUMBER;

Description

Returns the length or perimeter of a geometry object.

Parameters

geom

Geometry object.

dim

Dimensional information array corresponding to geom, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

unit

Unit of measurement: a quoted string with unit= and an SDO_UNIT value from the MDSYS.SDO_DIST_UNITS table (for example, 'unit=KM'). See Section 2.10 for more information about unit of measurement specification.

If this parameter is not specified, the unit of measurement associated with the data is assumed. For geodetic data, the default unit of measurement is meters.

tol

Tolerance value (see Section 1.5.5).

Usage Notes

If the input polygon contains one or more holes, this function calculates the perimeters of the exterior boundary and all holes. It returns the sum of all perimeters.

Examples

The following example returns the perimeters of geometry objects stored in the COLA_MARKETS table. The first statement returns the perimeters of all objects; the second returns just the perimeter of cola_a. (The example uses the definitions and data from Section 2.1.)

-- Return the perimeters of all cola markets.
SELECT c.name, SDO_GEOM.SDO_LENGTH(c.shape, m.diminfo) 
  FROM cola_markets c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE';

NAME                             SDO_GEOM.SDO_LENGTH(C.SHAPE,M.DIMINFO)         
-------------------------------- --------------------------------------         
cola_a                                                               20         
cola_b                                                       17.1622777         
cola_c                                                       9.23606798         
cola_d                                                       12.5663706

-- Return the perimeter of just cola_a.
SELECT c.name, SDO_GEOM.SDO_LENGTH(c.shape, m.diminfo) 
  FROM cola_markets c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c.name = 'cola_a';

NAME                             SDO_GEOM.SDO_LENGTH(C.SHAPE,M.DIMINFO)         
-------------------------------- --------------------------------------         
cola_a                                                               20

Related Topics

None.


SDO_GEOM.SDO_MAX_MBR_ORDINATE

Format

SDO_GEOM.SDO_MAX_MBR_ORDINATE(

     geom IN SDO_GEOMETRY,

     ordinate_pos IN NUMBER

     ) RETURN NUMBER;

or

SDO_GEOM.SDO_MAX_MBR_ORDINATE(

     geom IN SDO_GEOMETRY,

     dim IN SDO_DIM_ARRAY,

     ordinate_pos IN NUMBER

     ) RETURN NUMBER;

Description

Returns the maximum value for the specified ordinate (dimension) of the minimum bounding rectangle of a geometry object.

Parameters

geom

Geometry object.

dim

Dimensional information array corresponding to geom, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

ordinate_pos

Position of the ordinate (dimension) in the definition of the geometry object: 1 for the first ordinate, 2 for the second ordinate, and so on. For example, if geom has X, Y ordinates, 1 identifies the X ordinate and 2 identifies the Y ordinate.

Usage Notes

None.

Examples

The following example returns the maximum X (first) ordinate value of the minimum bounding rectangle of the cola_d geometry in the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1. The minimum bounding rectangle of cola_d is returned in the example for the SDO_GEOM.SDO_MBR function.)

SELECT SDO_GEOM.SDO_MAX_MBR_ORDINATE(c.shape, m.diminfo, 1)
  FROM cola_markets c, user_sdo_geom_metadata m
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c.name = 'cola_d';

SDO_GEOM.SDO_MAX_MBR_ORDINATE(C.SHAPE,M.DIMINFO,1)                              
--------------------------------------------------                              
                                                10

Related Topics


SDO_GEOM.SDO_MBR

Format

SDO_GEOM.SDO_MBR(

     geom IN SDO_GEOMETRY

     [, dim IN SDO_DIM_ARRAY]

     ) RETURN SDO_GEOMETRY;

Description

Returns the minimum bounding rectangle of a geometry object, that is, a single rectangle that minimally encloses the geometry.

Parameters

geom

Geometry object.

dim

Dimensional information array corresponding to geom, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

Usage Notes

This function does not return an MBR geometry if a proper MBR cannot be constructed. Specifically:

Examples

The following example returns the minimum bounding rectangle of the cola_d geometry in the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1. Because cola_d is a circle, the minimum bounding rectangle in this case is a square.)

-- Return the minimum bounding rectangle of cola_d (a circle).
SELECT SDO_GEOM.SDO_MBR(c.shape, m.diminfo) 
  FROM cola_markets c, user_sdo_geom_metadata m
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c.name = 'cola_d';

SDO_GEOM.SDO_MBR(C.SHAPE,M.DIMINFO)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO
--------------------------------------------------------------------------------
SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 3), SDO_ORDINATE_ARR
AY(6, 7, 10, 11))

Related Topics


SDO_GEOM.SDO_MIN_MBR_ORDINATE

Format

SDO_GEOM.SDO_MIN_MBR_ORDINATE(

     geom IN SDO_GEOMETRY,

     ordinate_pos IN NUMBER

     ) RETURN NUMBER;

or

SDO_GEOM.SDO_MIN_MBR_ORDINATE(

     geom IN SDO_GEOMETRY,

     dim IN SDO_DIM_ARRAY,

     ordinate_pos IN NUMBER

     ) RETURN NUMBER;

Description

Returns the minimum value for the specified ordinate (dimension) of the minimum bounding rectangle of a geometry object.

Parameters

geom

Geometry object.

dim

Dimensional information array corresponding to geom, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

ordinate_pos

Position of the ordinate (dimension) in the definition of the geometry object: 1 for the first ordinate, 2 for the second ordinate, and so on. For example, if geom has X, Y ordinates, 1 identifies the X ordinate and 2 identifies the Y ordinate.

Usage Notes

None.

Examples

The following example returns the minimum X (first) ordinate value of the minimum bounding rectangle of the cola_d geometry in the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1. The minimum bounding rectangle of cola_d is returned in the example for the SDO_GEOM.SDO_MBR function.)

SELECT SDO_GEOM.SDO_MIN_MBR_ORDINATE(c.shape, m.diminfo, 1)
  FROM cola_markets c, user_sdo_geom_metadata m
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c.name = 'cola_d';

SDO_GEOM.SDO_MIN_MBR_ORDINATE(C.SHAPE,M.DIMINFO,1)                              
--------------------------------------------------                              
                                                 6 

Related Topics


SDO_GEOM.SDO_POINTONSURFACE

Format

SDO_GEOM.SDO_POINTONSURFACE(

     geom1 IN SDO_GEOMETRY,

     dim1 IN SDO_DIM_ARRAY

     ) RETURN SDO_GEOMETRY;

or

SDO_GEOM.SDO_POINTONSURFACE(

     geom1 IN SDO_GEOMETRY,

     tol IN NUMBER

     ) RETURN SDO_GEOMETRY;

Description

Returns a point that is guaranteed to be on the surface of a polygon geometry object.

Parameters

geom1

Polygon geometry object.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

Usage Notes

This function returns a point geometry object representing a point that is guaranteed to be on the surface of geom1.

The returned point can be any point on the surface. You should not make any assumptions about where on the surface the returned point is, or about whether the point is the same or different when the function is called multiple times with the same input parameter values.

Examples

The following example returns a geometry object that is a point on the surface of cola_a. (The example uses the definitions and data from Section 2.1.)

-- Return a point on the surface of a geometry.
SELECT SDO_GEOM.SDO_POINTONSURFACE(c.shape, m.diminfo) 
  FROM cola_markets c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c.name = 'cola_a';

SDO_GEOM.SDO_POINTONSURFACE(C.SHAPE,M.DIMINFO)(SDO_GTYPE, SDO_SRID, SDO_POINT(X,
--------------------------------------------------------------------------------
SDO_GEOMETRY(2001, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(
1, 1))

Related Topics

None.


SDO_GEOM.SDO_UNION

Format

SDO_GEOM.SDO_UNION(

     geom1 IN SDO_GEOMETRY,

     dim1 IN SDO_DIM_ARRAY,

     geom2 IN SDO_GEOMETRY,

     dim2 IN SDO_DIM_ARRAY

     ) RETURN SDO_GEOMETRY;

or

SDO_GEOM.SDO_UNION(

     geom1 IN SDO_GEOMETRY,

     geom2 IN SDO_GEOMETRY,

     tol IN NUMBER

     ) RETURN SDO_GEOMETRY;

Description

Returns a geometry object that is the topological union (OR operation) of two geometry objects.

Parameters

geom1

Geometry object.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

geom2

Geometry object.

dim2

Dimensional information array corresponding to geom2, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

Usage Notes

In Figure 24-4, the shaded area represents the polygon returned when SDO_UNION is used with a square (geom1) and another polygon (geom2).

Figure 24-4 SDO_GEOM.SDO_UNION

Description of Figure 24-4 follows
Description of "Figure 24-4 SDO_GEOM.SDO_UNION"

If it is sufficient to append one geometry to another geometry without performing a topological union operation, and if both geometries are disjoint, using the SDO_UTIL.APPEND function (described in Chapter 32) is faster than using the SDO_UNION function.

An exception is raised if geom1 and geom2 are based on different coordinate systems.

Examples

The following example returns a geometry object that is the topological union (OR operation) of cola_a and cola_c. (The example uses the definitions and data from Section 2.1.)

-- Return the topological union of two geometries.
SELECT SDO_GEOM.SDO_UNION(c_a.shape, m.diminfo, c_c.shape, m.diminfo) 
  FROM cola_markets c_a, cola_markets c_c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c_a.name = 'cola_a' AND c_c.name = 'cola_c';

SDO_GEOM.SDO_UNION(C_A.SHAPE,M.DIMINFO,C_C.SHAPE,M.DIMINFO)(SDO_GTYPE, SDO_SRID,
--------------------------------------------------------------------------------
SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR
AY(5, 5, 5, 7, 1, 7, 1, 1, 5, 1, 5, 3, 6, 3, 6, 5, 5, 5))

Note that in the returned polygon, the SDO_ORDINATE_ARRAY starts and ends at the same point (5, 5).

Related Topics


SDO_GEOM.SDO_VOLUME

Format

SDO_GEOM.SDO_VOLUME(

     geom IN SDO_GEOMETRY,

     tol IN NUMBER

     [, unit IN VARCHAR2]

     ) RETURN NUMBER;

Description

Returns the volume of a three-dimensional solid.

Parameters

geom

Geometry object.

tol

Tolerance value (see Section 1.5.5).

unit

Unit of measurement: a quoted string with unit= and volume unit (for example, 'unit=CUBIC_FOOT' or 'unit=CUBIC_METER'). For a list of volume units, enter the following query:

SELECT short_name FROM mdsys.sdo_units_of_measure WHERE unit_of_meas_type = 'volume';

See Section 2.10 for more information about unit of measurement specification.

If this parameter is not specified, the unit of measurement associated with the data is assumed.

Usage Notes

This function works with any solid, including solids with holes.

This function is not supported with geodetic data.

For information about support for three-dimensional geometries, see Section 1.11.

Examples

The following example returns the volume of a solid geometry object.

-- Return the volume of a solid geometry.
SELECT p.id, SDO_GEOM.SDO_VOLUME(p.geometry, 0.005) FROM polygons3d p
  WHERE p.id = 12;

        ID SDO_GEOM.SDO_VOLUME(P.GEOMETRY,0.005)
---------- -------------------------------------
        12                                     6

Related Topics

None.


SDO_GEOM.SDO_XOR

Format

SDO_GEOM.SDO_XOR(

     geom1 IN SDO_XOR,

     dim1 IN SDO_DIM_ARRAY,

     geom2 IN SDO_GEOMETRY,

     dim2 IN SDO_DIM_ARRAY

     ) RETURN SDO_GEOMETRY;

or

SDO_GEOM.SDO_XOR(

     geom1 IN SDO_GEOMETRY,

     geom2 IN SDO_GEOMETRY,

     tol IN NUMBER

     ) RETURN SDO_GEOMETRY;

Description

Returns a geometry object that is the topological symmetric difference (XOR operation) of two geometry objects.

Parameters

geom1

Geometry object.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

geom2

Geometry object.

dim2

Dimensional information array corresponding to geom2, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

Usage Notes

In Figure 24-5, the shaded area represents the polygon returned when SDO_XOR is used with a square (geom1) and another polygon (geom2).

Figure 24-5 SDO_GEOM.SDO_XOR

Description of Figure 24-5 follows
Description of "Figure 24-5 SDO_GEOM.SDO_XOR"

An exception is raised if geom1 and geom2 are based on different coordinate systems.

Examples

The following example returns a geometry object that is the topological symmetric difference (XOR operation) of cola_a and cola_c. (The example uses the definitions and data from Section 2.1.)

-- Return the topological symmetric difference of two geometries.
SELECT SDO_GEOM.SDO_XOR(c_a.shape, m.diminfo, c_c.shape, m.diminfo) 
  FROM cola_markets c_a, cola_markets c_c, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c_a.name = 'cola_a' AND c_c.name = 'cola_c';

SDO_GEOM.SDO_XOR(C_A.SHAPE,M.DIMINFO,C_C.SHAPE,M.DIMINFO)(SDO_GTYPE, SDO_SRID, S
--------------------------------------------------------------------------------
SDO_GEOMETRY(2007, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1, 19, 1003, 1), SDO
_ORDINATE_ARRAY(1, 7, 1, 1, 5, 1, 5, 3, 3, 3, 4, 5, 5, 5, 5, 7, 1, 7, 5, 5, 5, 3
, 6, 3, 6, 5, 5, 5))

Note that the returned polygon is a multipolygon (SDO_GTYPE = 2007), and the SDO_ORDINATE_ARRAY describes two polygons: one starting and ending at (1, 7) and the other starting and ending at (5, 5).

Related Topics


SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT

Format

SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(

     theGeometry IN SDO_GEOMETRY,

     theDimInfo IN SDO_DIM_ARRAY

     ) RETURN VARCHAR2;

or

SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(

     theGeometry IN SDO_GEOMETRY,

     tolerance IN NUMBER

     ) 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 Section 2.8).

tolerance

Tolerance value (see Section 1.5.5).

Usage Notes

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:

This function checks for type consistency and geometry consistency.

For type consistency, the function checks for the following:

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

For three-dimensional geometries, this function also performs the checks described in Section 1.11.3.

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.

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.

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).

Related Topics


SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT

Format

SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT(

     geom_table IN VARCHAR2,

     geom_column IN VARCHAR2,

     result_table IN VARCHAR2

     [, commit_interval IN NUMBER]);

Description

Examines a geometry column to determine if the stored geometries follow the defined rules for geometry objects, and returns context information about any invalid geometries.

Parameters

geom_table

Spatial geometry table.

geom_column

Geometry object column to be examined.

result_table

Result table to hold the validation results. A row is added to result_table for each invalid geometry. If there are no invalid geometries, one or more (depending on the commit_interval value) rows with a result of DONE are added.

commit_interval

Number of geometries to validate before Spatial performs an internal commit operation and writes a row with a result of DONE to result_table (if no rows for invalid geometries have been written since the last commit operation). If commit_interval is not specified, no internal commit operations are performed during the validation.

The commit_interval option is helpful if you want to look at the contents of result_table while the validation is in progress.

Usage Notes

This procedure loads the result table with validation results.

An empty result table (result_table parameter) must be created before calling this procedure. The format of the result table is: (sdo_rowid ROWID, result VARCHAR2(2000)). If result_table is not empty, you should truncate the table before calling the procedure; otherwise, the procedure appends rows to the existing data in the table.

The result table contains one row for each invalid geometry. A row is not written if a geometry is valid, except as follows:

In each row for an invalid geometry, the SDO_ROWID column contains the ROWID value of the row containing the invalid geometry, and the RESULT column contains an Oracle error message number and the context of the error (the coordinate, edge, or ring that causes the geometry to be invalid). You can then look up the error message for more information about the cause of the failure.

This procedure performs the following checks on each geometry in the layer (geom_column):

Examples

The following example validates the geometry objects stored in the SHAPE column of the COLA_MARKETS table. The example includes the creation of the result table. For this example, a deliberately invalid geometry was inserted into the table before the validation was performed.

-- Is a layer valid? (First, create the result table.)
CREATE TABLE val_results (sdo_rowid ROWID, result varchar2(1000));
-- (Next statement must be on one command line.)
CALL SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT('COLA_MARKETS','SHAPE','VAL_RESULTS');

Call completed.

SQL> SELECT * from val_results;

SDO_ROWID                                                                       
------------------                                                              
RESULT                                                                          
--------------------------------------------------------------------------------
                                                                                
Rows Processed <12>                                                             
                                                                                
AAABXNAABAAAK+YAAC                                                              
13349 [Element <1>] [Ring <1>][Edge <1>][Edge <3>] 

Related Topics


SDO_GEOM.WITHIN_DISTANCE

Format

SDO_GEOM.WITHIN_DISTANCE(

     geom1 IN SDO_GEOMETRY,

     dim1 IN SDO_DIM_ARRAY,

     dist IN NUMBER,

     geom2 IN SDO_GEOMETRY,

     dim2 IN SDO_DIM_ARRAY

     [, units IN VARCHAR2]

     ) RETURN VARCHAR2;

or

SDO_GEOM.WITHIN_DISTANCE(

     geom1 IN SDO_GEOMETRY,

     dist IN NUMBER,

     geom2 IN SDO_GEOMETRY,

     tol IN NUMBER

     [, units IN VARCHAR2]

     ) RETURN VARCHAR2;

Description

Determines if two spatial objects are within some specified distance from each other.

Parameters

geom1

Geometry object.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

dist

Distance value.

geom2

Geometry object.

dim2

Dimensional information array corresponding to geom2, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).

tol

Tolerance value (see Section 1.5.5).

units

Unit of measurement: a quoted string with unit= and an SDO_UNIT value from the MDSYS.SDO_AREA_UNITS table (for example, 'unit=KM'). See Section 2.10 for more information about unit of measurement specification.

If this parameter is not specified, the unit of measurement associated with the data is assumed. For geodetic data, the default unit of measurement is meters.

Usage Notes

For better performance, use the SDO_WITHIN_DISTANCE operator (described in Chapter 19) instead of the SDO_GEOM.WITHIN_DISTANCE function. For more information about performance considerations with operators and functions, see Section 1.9.

This function returns TRUE for object pairs that are within the specified distance, and FALSE otherwise.

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.

An exception is raised if geom1 and geom2 are based on different coordinate systems.

Examples

The following example checks if cola_b and cola_d are within 1 unit apart at the shortest distance between them. (The example uses the definitions and data from Section 2.1.)

-- Are two geometries within 1 unit of distance apart?
SELECT SDO_GEOM.WITHIN_DISTANCE(c_b.shape, m.diminfo, 1,
     c_d.shape, m.diminfo) 
  FROM cola_markets c_b, cola_markets c_d, user_sdo_geom_metadata m 
  WHERE m.table_name = 'COLA_MARKETS' AND m.column_name = 'SHAPE' 
  AND c_b.name = 'cola_b' AND c_d.name = 'cola_d';

SDO_GEOM.WITHIN_DISTANCE(C_B.SHAPE,M.DIMINFO,1,C_D.SHAPE,M.DIMINFO)        
--------------------------------------------------------------------------------
TRUE   

Related Topics