The SDO_MIGRATE.TO_CURRENT subprogram described in this chapter has both procedure and function interfaces. As a procedure, it lets you upgrade spatial geometry tables from previous releases of Spatial; and as a function, it lets you upgrade a single SDO_GEOMETRY object.
This subprogram has very limited uses, as explained in the Usage Notes for its documentation.
Format (Any ObjectRelational Model Implementation to Current)
SDO_MIGRATE.TO_CURRENT(
tabname IN VARCHAR2
[, column_name IN VARCHAR2]);
or
SDO_MIGRATE.TO_CURRENT(
tabname IN VARCHAR2,
column_name IN VARCHAR2
[, commit_int IN NUMBER]);
Format (Single ObjectRelational Model Geometry to Current)
SDO_MIGRATE.TO_CURRENT(
geom IN SDO_GEOMETRY,
dim IN SDO_DIM_ARRAY
) RETURN SDO_GEOMETRY;
Format (Any Relational Model Implementation to Current)
SDO_MIGRATE.TO_CURRENT(
layer IN VARCHAR2,
newtabname IN VARCHAR2,
gidcolumn IN VARCHAR2,
geocolname IN VARCHAR2,
layer_gtype IN VARCHAR2,
updateflag IN VARCHAR2);
Description
Upgrades data from the obsolete Spatial relational model (release 8.1.5 or earlier) to the current release, or upgrades one or more objectrelational model (release 8.1.6 or later) geometries that need to be upgraded (as explained in the Usage Notes). As a procedure, TO_CURRENT upgrades an entire layer (all geometries in a column); as a function, TO_CURRENT upgrades a single geometry object, which must be of type SDO_GEOMETRY.
For upgrading a layer, the procedure format depends on whether you are upgrading from the Spatial relational model (release 8.1.5 or earlier) or objectrelational model (release 8.1.6 or later). See the Usage Notes for the model that applies to you.
Note: This procedure applies to twodimensional geometries only. It is not supported for threedimensional geometries. 
Parameters
Table with geometry objects.
Column in tabname
that contains geometry objects. If column_name
is not specified or is specified as null, the column containing geometry objects is upgraded.
Number of geometries to upgrade before Spatial performs an internal commit operation. If commit_int
is not specified, no internal commit operations are performed during the upgrade.
If you specify a commit_int
value, you can use a smaller rollback segment than would otherwise be needed.
Single geometry object to be upgraded to the current release.
Dimensional information array for the geometry object to be upgraded. The SDO_DIM_ARRAY type is explained in Section 2.8.3.
Name of the layer to be upgraded.
Name of the new table to which you are upgrading the data.
Name of the column in which to store the GID from the old table.
Name of the column in the new table where the geometry objects will be inserted.
One of the following values: POINT or NOTPOINT (default).
If the layer you are upgrading is composed solely of point data, set this parameter to POINT for optimal performance; otherwise, set this parameter to NOTPOINT. If you set the value to POINT and the layer contains any nonpoint geometries, the upgrade might produce invalid data.
One of the following values: UPDATE or INSERT (default).
If you are upgrading the layer into an existing populated attribute table, set this parameter to UPDATE; otherwise, set this parameter to INSERT.
Usage Notes for ObjectRelational Model Layer and Single Geometry Upgrade
This subprogram is not needed for normal upgrades of Oracle Spatial. It is sometimes needed if spatial data is loaded using a thirdparty loader and if the resulting geometries have the wrong orientation or invalid ETYPE or GTYPE values. For information about using this subprogram as part of the recommended procedure for loading and validating spatial data, see Section 4.3.
This subprogram upgrades the specified geometry or all geometry objects in the specified layer so that their SDO_GTYPE and SDO_ETYPE values are in the format of the current release:
SDO_GTYPE values of 4 digits are created, using the format (DLTT) shown in Table 21 in Section 2.2.1.
SDO_ETYPE values are as discussed in Section 2.2.4.
Geometries are ordered so that exterior rings are followed by their interior rings, and coordinates are saved in the correct rotation (counterclockwise for exterior rings, and clockwise for interior rings).
Usage Notes for Relational Model Upgrade
If you are you upgrading from the Spatial relational model (release 8.1.5 or earlier), consider the following when using this procedure:
The new table must be created before you call this procedure.
If the data to be upgraded is geodetic, the tolerance value (SDO_TOLERANCE column value in the <layername>_SDODIM table or view) must be expressed in decimal degrees (for example, 0.00000005).
The procedure converts geometries from the relational model to the objectrelational model.
A commit operation is performed by this procedure.
If any of the upgrade steps fails, nothing is upgraded for the layer.
layer
is the underlying layer name, without the _SDOGEOM suffix.
The old SDO_GID is stored in gidcolumn
.
SDO_GTYPE values of 4 digits are created, using the format (DLTT) shown in Table 21 in Section 2.2.1.
SDO_ETYPE values are created, using the values discussed in Section 2.2.4.
The procedure orders geometries so that exterior rings are followed by their interior rings, and it saves coordinates in the correct rotation (counterclockwise for exterior rings, and clockwise for interior rings).
The MDSYS.SDO_CSW_PROCESS package contains subprograms for various processing operations related to support for Catalog Services for the Web (CSW).
To use the subprograms in this chapter, you must understand the conceptual and usage information about Catalog Services for the Web in Chapter 16.
Table 221 lists the CSW processing subprograms.
Table 221 Subprograms for CSW Processing Operations
Subprogram  Description 

SDO_CSW_PROCESS.DeleteCapabilitiesInfo 
Deletes the capabilities information that had been set by the SDO_CSW_PROCESS.InsertCapabilitiesInfo procedure. 
SDO_CSW_PROCESS.DeleteDomainInfo 
Deletes domain information related to a record type. 
SDO_CSW_PROCESS.DeletePluginMap 
Unregisters a plugin for processing and extracting spatial content for a record type. 
SDO_CSW_PROCESS.DeleteRecordViewMap 
Deletes information related to record view transformation. 
SDO_CSW_PROCESS.GetRecordTypeId 
Gets the record type ID for a type (specified by namespace and type name). 
SDO_CSW_PROCESS.InsertCapabilitiesInfo 
Inserts the capabilities template information. 
SDO_CSW_PROCESS.InsertDomainInfo 
Inserts domain information related to a record type. 
SDO_CSW_PROCESS.InsertPluginMap 
Registers a plugin for processing and extracting spatial content for a record type. 
SDO_CSW_PROCESS.InsertRecordViewMap 
Inserts information related to record view transformation. 
SDO_CSW_PROCESS.InsertRtDataUpdated 
Inserts a notification that the data for a record type was updated in the database. 
SDO_CSW_PROCESS.InsertRtMDUpdated 
Inserts a notification that the metadata for a record type was updated in the database. 
The rest of this chapter provides reference information on the subprograms, listed in alphabetical order.
Description
Deletes the capabilities information that had been set by the SDO_CSW_PROCESS.InsertCapabilitiesInfo procedure.
Examples
The following example deletes the capabilities information that had been set by the SDO_CSW_PROCESS.InsertCapabilitiesInfo procedure.
BEGIN SDO_CSW_PROCESS.DeleteCapabilitiesInfo; END; /
Format
SDO_CSW_PROCESS.DeleteDomainInfo(
recordTypeId IN NUMBER,
propertyName IN VARCHAR2,
parameterName IN VARCHAR2);
Parameters
ID of the record type.
Name of the property.
Name of domain parameter to be deleted.
Examples
The following example deletes domain information about the resultType
parameter for a specified record type.
DECLARE rtId NUMBER; BEGIN rtId := sdo_csw_process.getRecordTypeId('http://www.opengis.net/cat/csw', 'Record'); sdo_csw_process.deleteDomainInfo(rtId, null, 'GetRecords.resultType'); END; /
Description
Unregisters a plugin for processing and extracting nonGML spatial content for a record type.
Parameters
Uniform resource locator of namespace of the record type.
Name of the record type.
Usage Notes
To register a plugin, which is a userdefined implementation of the extractSDO
function, use the SDO_CSW_PROCESS.InsertPluginMap procedure.
For information about creating and using the extractSDO
function, see Section 16.2.2.
For information about support for Catalog Services for the Web, see Chapter 16.
Format
SDO_CSW_PROCESS.DeleteRecordViewMap(
recordTypeNs IN VARCHAR2,
viewSrcName IN VARCHAR2,
targetTypeName IN VARCHAR2);
Parameters
XML document for the capabilities template, which is used at runtime to generate capabilities documents.
Usage Notes
At runtime, the capabilities document is dynamically generated by binding feature type information from the CSW metadata with the capabilities template. For information about capabilities documents, see Section 16.2.1.
For information about support for Catalog Services for the Web, see Chapter 16.
Format
SDO_CSW_PROCESS.InsertDomainInfo(
recordTypeId IN NUMBER,
propertyName IN VARCHAR2,
parameterName IN VARCHAR2,
pValue IN MDSYS.STRINGLIST);
Parameters
ID of the record type
Name of a domain property.
Name of a domain parameter
An array of strings containing parameter values for parameterName
. The MDSYS.STRINGLIST type is defined as VARRAY(1000000) OF VARCHAR2(4000)
.
Examples
The following example inserts domain information for the record type named Record
.
DECLARE rtId NUMBER; BEGIN rtId := SDO_CSW_PROCESS.getRecordTypeId( 'http://www.opengis.net/cat/csw', 'Record'); SDO_CSW_PROCESS.insertDomainInfo(rtId, null, 'GetRecords.resultType', MDSYS.STRINGLIST('hits', 'results', 'validate')); END; /
Format
SDO_CSW_PROCESS.InsertPluginMap(
rtnsUrl IN VARCHAR2,
rtName IN VARCHAR2,
pluginPackageName IN VARCHAR2);
Description
Registers a plugin for processing and extracting nonGML spatial content for a record type.
Parameters
Uniform resource locator of the namespace of the record type.
Name of the record type.
Name of the PL/SQL package object for the plugin.
Usage Notes
The plugin must contain the userdefined implementation of the extractSDO
function. A plugin is needed if the records are not in GML format. For detailed information about creating and using the extractSDO
function, see Section 16.2.2.
You must grant EXECUTE access on the plugin package (pluginPackageName
parameter) to user MDSYS and to the CSW administrative user.
For information about support for Catalog Services for the Web, see Chapter 16.
Format
SDO_CSW_PROCESS.InsertRecordViewMap(
recordTypeNs IN VARCHAR2,
viewSrcName IN VARCHAR2,
targetTypeName IN VARCHAR2,
mapInfo IN XMLTYPE,
mapType IN VARCHAR2);
Parameters
URL of the namespace of the record type.
Name of the source record type (for example, BriefRecord
, DCMIRecord
, Record
, or SummaryRecord
).
Name of the destination of the record type (for example, BriefRecord
, DCMIRecord
, Record
, or SummaryRecord
).
XSLT definition of the mapping. (See the comments in the example at the end of this section for a transformation from BriefRecord
type to Record
type.)
Map type (brief, summary, and so on)
Examples
The following example inserts information related to transformation from BriefRecord
type to Record
type.
create or replace directory CSWUSERDIR as 'dir_path_where_mapinfo.xsl_file_is_located' ; /* // Content of mapinfo.xsl could be that which transforms // all <csw:BriefRecord> node to <csw:Record> node, where csw is // the namespace alias for "http://www.opengis.net/cat/csw" <?xml version="1.0" encoding="UTF8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:csw="http://www.opengis.net/cat/csw"> <xsl:output method="xml" version="1.0" encoding="UTF8" indent="yes" /> <xsl:template match="/"> <csw:Record xmlns:csw="http://www.opengis.net/cat/csw" xmlns:dc="http://www.purl.org/dc/elements/1.1/" xmlns:ows="http://www.opengis.net/ows" xmlns:dct="http://www.purl.org/dc/terms/"> <xsl:applytemplates select="@*node()"/> </csw:Record> </xsl:template> <xsl:template match="csw:BriefRecord"> <xsl:applytemplates select="@*node()"/> </xsl:template> <xsl:template match="@*node()"> <xsl:copy> <xsl:applytemplates select="@*node()"/> </xsl:copy> </xsl:template> </xsl:stylesheet> */ DECLARE rtId NUMBER; BEGIN SDO_CSW_PROCESS.insertRecordViewMap('http://www.opengis.net/cat/csw', 'BriefRecord', 'Record', xmltype(bfilename('CSWUSERDIR', 'mapinfo.xsl'), nls_charset_id('AL32UTF8')), 'brief'); END; /
Format
SDO_CSW_PROCESS.InsertRtDataUpdated(
ns IN VARCHAR2,
name IN VARCHAR2,
updatedRowList IN ROWPOINTERLIST,
updateTs IN TIMESTAMP);
Parameters
Namespace of the record type.
Name of the record type.
List of rowids of rows that have been updated.
Timestamp value indicating when the data was updated.
Usage Notes
This procedure is used for CSW cache data synchronization. It queries the MDSYS.CSW_RECORD_TYPES$ system table.
For information about support for Catalog Services for the Web, see Chapter 16.
Examples
The following example inserts a notification for a specified record type that the data was updated for the rows associated with specific rowids.
BEGIN updatedRowIdList:= . . .  list of rowIds that have been updated  in the table referred to by the dataPointer column of the  mdsys.CSW_Record_Types$ table for the row whose  typeNameNS column value is 'http://www.opengis.net/cat/csw' and  typeName column value is 'Record' . . . SDO_CSW_PROCESS.insertRtDataUpdated('http://www.opengis.net/cat/csw', 'Record', updatedRowIdList, sysdate); . . . END; /
Parameters
Namespace of the record type.
Name of the record type.
Date and time when the metadata was updated.
Usage Notes
This procedure is used for WFS cache metadata synchronization.
For information about support for Catalog Services for the Web, see Chapter 16.
This chapter contains descriptions of the point cloud subprograms shown in Table 281.
Table 281 Point Cloud Subprograms
Subprogram  Description 


Performs a clip operation on a point cloud. 

Creates a point cloud using the points specified in the 

Drops the dependencies between a point cloud block table and a specified base table and column. 

Initializes a point cloud. 

Returns a geometry object representing all or part of a point cloud. 
To use the subprograms in this package, you must understand the main concepts related to threedimensional geometries, including the use of point clouds to model solids. Section 1.11 describes support for threedimensional geometries, Section 1.11.2 describes the use of point clouds to model solids, and Section 2.6 describes data types related to point clouds.
Format
SDO_PC_PKG.CLIP_PC(
inp IN SDO_PC,
ind_dimqry IN SDO_GEOMETRY,
other_dimqry IN SDO_MBR,
qry_min_res IN NUMBER,
qry_max_res IN NUMBER,
blkno IN NUMBER DEFAULT NULL
) RETURN SDO_PC_BLK_TYPE;
Parameters
Point cloud on which to perform the clip operation.
For querying the indexed dimensions of the point cloud: window from which to select objects to be returned; typically a polygon for twodimensional geometries or a frustum for threedimensional geometries.
For querying the nonindexed dimensions of the point cloud: window from which to select objects to be returned; typically a polygon for twodimensional geometries or a frustum for threedimensional geometries. The nonindexed dimensions are those that are included in the total dimensionality but are not indexed. For an explanation of index dimensionality and total dimensionality, see the explanation of the pc_tot_dimensions
parameter of the SDO_PC_PKG.INIT function.
The SDO_MBR type is defined as (LOWER_LEFT SDO_VPOINT_TYPE, UPPER_RIGHT SDO_VPOINT_TYPE)
and SDO_V_POINT_TYPE is defined as VARRAY(64) OF NUMBER
.
Minimum resolution value. Objects in qry
with resolutions equal to or greater than qry_min_res
and less than or equal to qry_max_res
are returned by the clip operation.
Maximum resolution value. Objects in qry
with resolutions equal to or greater than qry_min_res
and less than or equal to qry_max_res
are returned by the clip operation.
Block ID number of the block to which to restrict the objects returned by the clip operation. If this parameter is null, all objects that satisfy the other parameters are returned.
Usage Notes
This function returns points from a point cloud that are within a specified query window and that satisfy any other requirements specified by the parameters. A common use of this function is to perform queries on point clouds. You can maximize the performance of a point cloud query by minimizing the number of objects that the function needs to consider for the operation.
The SDO_PC and SDO_PC_BLK_TYPE data types are described in Section 2.6.
Section 1.11.2 describes how to use point clouds to model solids.
Examples
The following example performs a clip operation on a point cloud. It is taken from the sdo_pc.sql
example program, which is under $ORACLE_HOME
/md/demo/examples/PointCloud/plsql/
if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).
. . . declare inp sdo_pc; begin select pc INTO inp from base where rownum=1; insert into restst select * from table(sdo_pc_pkg.clip_pc ( inp,  Input point cloud object sdo_geometry(2003, 8307, null, sdo_elem_info_array(1, 1003, 3), sdo_ordinate_array(175.86157, 14.60521, 0,0)),  Query null, null, null)); end; / . . .
Format
SDO_PC_PKG.CREATE_PC(
inp IN SDO_PC,
inptable IN VARCHAR2,
clstPcdataTbl IN VARCHAR2 DEFAULT NULL);
Parameters
SDO_PC object to be used. This object must have been created by the SDO_PC_PKG.INIT function.
Name of the table or view containing the input point cloud data. This table or view should have the following columns:
RID (VARCHAR2(24)): Unique ID for each point
VAL_D1 (NUMBER): Ordinate in dimension 1
VAL_D2 (NUMBER): Ordinate in dimension 2
. . .
VAL_Dn (NUMBER): Ordinate in dimension n, where n is the highestnumbered dimension. n should match the pc_tot_dimensions
parameter value in the call to the SDO_PC_PKG.INIT function when the point cloud was initialized.
Name of the table for storing the resulting point data. If you do not specify a value, this table is not created. For more information about the table, see the Usage Notes.
Usage Notes
The first few dimensions of the point cloud are indexed and can later be searched using the SDO_PC_PKG.CLIP_PC function. The exact number of dimensions to index is determined by the dimensionality of the point cloud extent in the initialized point cloud object, specifically: inp.pc_extent.sdo_gtype/1000
If you specify a view name in the inptable
parameter, the query SELECT ROWID FROM <viewname>
must not return any errors.
If you specify a table name in the clstPcdataTbl
parameter, the table must exist and have the following columns:
PTN_ID (NUMBER)
POINT_ID (NUMBER)
RID (VARCHAR2(24): Unique ID for each point
VAL_D1 (NUMBER): Ordinate in dimension 1
VAL_D2 (NUMBER): Ordinate in dimension 2
. . .
VAL_Dn (NUMBER): Ordinate in dimension n, where n is the highestnumbered dimension. n should match the pc_tot_dimensions
parameter value in the call to the SDO_PC_PKG.INIT function when the point cloud was initialized.
If a value is specified for the clstPcdataTbl
parameter, this function populates the table by assigning appropriate values for PTN_ID and POINT_ID and by copying the values from the inptable
table or view for other attributes. This table can be created as an index organized table. It can be used in applications for searching using SQL queries on dimensions other than those reflected in the index dimensionality. (For an explanation of index dimensionality and total dimensionality, see the explanation of the pc_tot_dimensions
parameter of the SDO_PC_PKG.INIT function.)
The SDO_PC and SDO_PC_BLK_TYPE data types are described in Section 2.6.
Section 1.11.2 describes how to use point clouds to model solids.
Examples
The following example creates a point cloud. It is taken from the sdo_pc.sql
example program, which is under $ORACLE_HOME
/md/demo/examples/PointCloud/plsql/
if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).
. . .  Create the blocks for the point cloud. sdo_pc_pkg.create_pc( pc,  Initialized PointCloud object 'INPTAB',  Name of input table to ingest into the pointcloud 'RES'  Name of output table that stores the points (with ptn_id,pt_id) ); . . .
Description
Drops the dependencies between a point cloud block table and a specified base table and column.
Parameters
Name of a base table that was specified (in the basetable
parameter of the SDO_PC_PKG.INIT function) when the point cloud was initialized.
Name of a column in base table that was specified in the basecol
parameter of the SDO_PC_PKG.INIT function.
Usage Notes
This procedure truncates the point cloud block table and removes the association between the block table and the base table and column combination.
After you execute this procedure, you can drop the point cloud block table or associate the table with another base table and column combination. For more information, see the Usage Notes for the SDO_PC_PKG.INIT function.
Format
SDO_PC_PKG.GET_PT_IDS(
pts IN BLOB,
num_pts IN NUMBER,
pc_tot_dim IN NUMBER,
blk_domain IN SDO_ORGSCL_TYPE DEFAULT NULL,
) RETURN SDO_NUMBER_ARRAY;
Parameters
Binary large object (BLOB) containing the point cloud block.
Number of points in the point cloud block. For a point cloud block, the number of points is stored in the NUM_POINTS column of the point cloud block table, which is described in Table 27 in Section 2.6.1.
Number of dimensions for the points in the point cloud block.
(Not currently used.)
Usage Notes
This function returns an SDO_NUMBER_ARRAY object. The array contains multiple pairs of numbers, with each pair identifying the block ID and point ID of a point. For any specific call to this function, the block ID values associated with all points in the returned array will be the same. The SDO_NUMBER_ARRAY type is defined as VARRAY(1048576) OF NUMBER
.
Section 1.11.2 describes how to use point clouds to model solids.
Examples
The following example returns the block ID and point ID values of points in a point cloud block. It is taken from the sdo_pc.sql
example program, which is under $ORACLE_HOME
/md/demo/examples/PointCloud/plsql/
if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).
SELECT SDO_PC_PKG.GET_PT_IDS( a.points,  LOB containing the points a.num_points,  # of points in the LOB 3  Total dimensionality of the points in the LOB ) FROM restst a WHERE num_points >0;
Format
SDO_PC_PKG.INIT(
basetable IN VARCHAR2,
basecol IN VARCHAR2,
blktable IN VARCHAR2,
ptn_params IN VARCHAR2,
pc_extent IN SDO_GEOMETRY,
pc_tol IN NUMBER DEFAULT 0.0000000000005,
pc_tot_dimensions IN NUMBER DEFAULT 2,
pc_domain IN SDO_ORGSCL_TYPE DEFAULT NULL,
pc_val_attr_tables IN SDO_STRING_ARRAY DEFAULT NULL,
pc_other_attrs IN XMLTYPE DEFAULT NULL,
) RETURN SDO_PC;
Parameters
Name of the base table containing a column of type SDO_PC.
Name of the column of type SDO_PC in the base table.
Name of the point cloud block table, which is used for storing the blocks of point cloud. This table must exist, and must have been created by a statement in the following form: CREATE TABLE <tablename> AS select * from mdsys.sdo_pc_blk_table;
Each point cloud block table can only be associated with only one basetable
and basecol
combination.
Parameters for partitioning the point cloud, specified as a quoted string with keywords delimited by commas. For example: 'blk_capacity=1000,work_tablespace=my_work_ts'
. If this parameter is null, the point cloud is not partitioned. The following keywords are permitted:
blk_capacity=n
, where n is the maximum number of rows in each partition. The default value is 5000. If specified, must be a number greater than or equal to 50.
work_tablespace=x
, where x is the name of the tablespace in which to create temporary tables during the partitioning operations.
SDO_GEOMETRY object representing the spatial extent of the point cloud (the minimum bounding object enclosing all objects in the point cloud). This parameter must not be null.
For geodetic data, this geometry must have two dimensions; otherwise, it can have up to four dimensions. The dimensionality of this geometry is used as the minimum value permitted for the pc_tot_dimensions
parameter, as explained in the description of that parameter.
Tolerance value for objects in the point cloud. (For information about spatial tolerance, see Section 1.5.5.) If this parameter is null, the default value is 0.0000000000005.
A number specifying the total dimensionality of the point cloud object. For each point in the point cloud blocks, pc_tot_dimensions
ordinates (values) are stored.
The total dimensionality must be greater than or equal to the index dimensionality, which is the number of dimensions in the pc_extent
geometry. Specifying total dimensionality greater than index dimensionality enables necessary nonspatial attributes to be retrieved in the same fetch operation with spatial data. The maximum total dimensionality value is 8. The default value for this parameter is 2.
(Not currently used.)
SDO_STRING_ARRAY object specifying the names of any value attribute tables for the point cloud. If this parameter is null, the point cloud has no associated value attribute tables. Type SDO_STRING_ARRAY is defined as VARRAY(1048576) OF VARCHAR2(32).
XMLTYPE object specifying any other attributes of the point cloud. If this parameter is null, the point cloud has no other attributes.
Usage Notes
After you use this function to create an SDO_PC object, you can create a point cloud by specifying this object as input to the SDO_PC_PKG.CREATE_PC procedure.
The SDO_PC data type is described in Section 2.5.
Section 1.11.2 describes how to use point clouds to model solids.
After you use this function, the blktable table is kept in synchronization with the base table. For example, if a row is deleted from the basetable, the corresponding blocks of the point cloud object in that row are also deleted from the block table; and if the base table base table is truncated, the block table is truncated also.
The block table can be dropped only after either of the following occurs: the base table is dropped, or the SDO_PC_PKG.DROP_DEPENDENCIES procedure is executed.
Examples
The following example initializes a point cloud by creating an SDO_PC object, and it displays the ID of the object. It is taken from the sdo_pc.sql
example program, which is under $ORACLE_HOME
/md/demo/examples/PointCloud/plsql/
if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide)a.
. . . declare pc sdo_pc; begin  Initialize the point cloud object. pc := sdo_pc_pkg.init( 'BASE',  Table that has the SDO_POINT_CLOUD column defined 'PC',  Column name of the SDO_POINT_CLOUD object 'BLKTAB',  Table to store blocks of the point cloud 'blk_capacity=1000',  max # of points per block mdsys.sdo_geometry(2003, 8307, null, mdsys.sdo_elem_info_array(1,1003,3), mdsys.sdo_ordinate_array(180, 90, 180, 90)),  Extent 0.5,  Tolerance for point cloud 3,  Total number of dimensions null); . . .
Format
SDO_PC_PKG.TO_GEOMETRY(
pts IN BLOB,
num_pts IN NUMBER,
tin_tot_dim IN NUMBER,
srid IN NUMBER DEFAULT NULL,
blk_domain IN SDO_ORGSCL_TYPE DEFAULT NULL
) RETURN SDO_GEOMETRY;
Parameters
BLOB containing the points.
Maximum number of points to be included in the resulting geometry.
Number of spatial dimensions defined for the data.
Spatial reference (coordinate system) ID associated with the data. If this parameter is null, no SRID value is associated with the data.
(Not currently used.)
Usage Notes
This function returns a single multipoint SDO_GEOMETRY object that represents all point geometries in the pts
parameter. For example, the points could reflect the result of a clip operation or the contents of an entire block.
Section 1.11.2 describes how to use point clouds to model solids.
Examples
The following example returns a multipoint collection geometry object representing a point cloud. It is taken from the sdo_pc.sql
example program, which is under $ORACLE_HOME
/md/demo/examples/PointCloud/plsql/
if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).
. . .  Return points in blk_id of the point cloud as a multipoint collection. select sdo_pc_pkg.to_geometry( a.points,  point LOB a.num_points,  # of points in the LOB 3,  total dimensionality 8307  SRID ) from blktab a where blk_id=0; . . .
Linear referencing is a natural and convenient means to associate attributes or events to locations or portions of a linear feature. It has been widely used in transportation applications (such as for highways, railroads, and transit routes) and utilities applications (such as for gas and oil pipelines). The major advantage of linear referencing is its capability of locating attributes and events along a linear feature with only one parameter (usually known as measure) instead of two (such as longitude/latitude or x/y in Cartesian space). Sections of a linear feature can be referenced and created dynamically by indicating the start and end locations along the feature without explicitly storing them.
The linear referencing system (LRS) application programming interface (API) in Oracle Spatial provides serverside LRS capabilities at the cartographic level. The linear measure information is directly integrated into the Oracle Spatial geometry structure. The Oracle Spatial LRS API provides support for dynamic segmentation, and it serves as a groundwork for thirdparty or middletier application development for virtually any linear referencing methods and models in any coordinate system.
For an example of LRS, see Section 7.7. However, you may want to read the rest of this chapter first, to understand the concepts that the example illustrates.
For reference information about LRS functions and procedures, see Chapter 25.
This chapter contains the following major sections:
This section explains important terms and concepts related to linear referencing support in Oracle Spatial.
Geometric segments are basic LRS elements in Oracle Spatial. A geometric segment can be any of the following:
Line string: an ordered, nonbranching, and continuous geometry (for example, a simple road)
Multiline string: nonconnected line strings (for example, a highway with a gap caused by a lake or a bypass road)
Polygon (for example, a racetrack or a scenic tour route that starts and ends at the same point)
A geometric segment must contain at least start and end measures for its start and end points. Measures of points of interest (such as highway exits) on the geometric segments can also be assigned. These measures are either assigned by users or derived from existing geometric segments. Figure 71 shows a geometric segment with four line segments and one arc. Points on the geometric segment are represented by triplets (x, y, m), where x and y describe the location and m denotes the measure (with each measure value underlined in Figure 71).
Shape points are points that are specified when an LRS segment is constructed, and that are assigned measure information. In Oracle Spatial, a line segment is represented by its start and end points, and an arc is represented by three points: start, middle, and end points of the arc. You must specify these points as shape points, but you can also specify other points as shape points if you need measure information stored for these points (for example, an exit in the middle of a straight part of the highway).
Thus, shape points can serve one or both of the following purposes: to indicate the direction of the segment (for example, a turn or curve), and to identify a point of interest for which measure information is to be stored.
Shape points might not directly relate to mileposts or reference posts in LRS; they are used as internal reference points. The measure information of shape points is automatically populated when you define the LRS segment using the SDO_LRS.DEFINE_GEOM_SEGMENT procedure, which is described in Chapter 25.
The direction of a geometric segment is indicated from the start point of the geometric segment to the end point. The direction is determined by the order of the vertices (from start point to end point) in the geometry definition. Measures of points on a geometric segment always either increase or decrease along the direction of the geometric segment.
The measure of a point along a geometric segment is the linear distance (in the measure dimension) to the point measured from the start point (for increasing values) or end point (for decreasing values) of the geometric segment. The measure information does not necessarily have to be of the same scale as the distance. However, the linear mapping relationship between measure and distance is always preserved.
Some LRS functions use offset instead of measure to represent measured distance along linear features. Although some other linear referencing systems might use offset to mean what the Oracle Spatial LRS refers to as measure, offset has a different meaning in Oracle Spatial from measure, as explained in Section 7.1.5.
The offset of a point along a geometric segment is the perpendicular distance between the point and the geometric segment. Offsets are positive if the points are on the left side along the segment direction and are negative if they are on the right side. Points are on a geometric segment if their offsets to the segment are zero.
The unit of measurement for an offset is the same as for the coordinate system associated with the geometric segment. For geodetic data, the default unit of measurement is meters.
Figure 72 shows how a point can be located along a geometric segment with measure and offset information. By assigning an offset together with a measure, it is possible to locate not only points that are on the geometric segment, but also points that are perpendicular to the geometric segment.
Any unassigned measures of a geometric segment are automatically populated based upon their distance distribution. This is done before any LRS operations for geometric segments with unknown measures (NULL in Oracle Spatial). The resulting geometric segments from any LRS operations return the measure information associated with geometric segments. The measure of a point on the geometric segment can be obtained based upon a linear mapping relationship between its previous and next known measures or locations. See the algorithm representation in Figure 73 and the example in Figure 74.
Measures are evenly spaced between assigned measures. However, the assigned measures for points of interest on a geometric segment do not need to be evenly spaced. This could eliminate the problem of error accumulation and account for inaccuracy of data source.
Moreover, the assigned measures do not even need to reflect actual distances (for example, they can reflect estimated driving time); they can be any valid values within the measure range. Figure 75 shows the measure population that results when assigned measure values are not proportional and reflect widely varying gaps.
In all cases, measure populating is done in an incremental fashion along the segment direction. This improves the performance of current and subsequent LRS operations.
The start and end measures of a geometric segment define the linear measure range of the geometric segment. Any valid LRS measures of a geometric segment must fall within its linear measure range.
The projection of a point along a geometric segment is the point on the geometric segment with the minimum distance to the specified point. The measure information of the resulting point is also returned in the point geometry.
LRS points are points with linear measure information along a geometric segment. A valid LRS point is a point geometry with measure information.
All LRS point data must be stored in the SDO_ELEM_INFO_ARRAY and SDO_ORDINATE_ARRAY, and cannot be stored in the SDO_POINT field in the SDO_GEOMETRY definition of the point.
Linear features are any spatial objects that can be treated as a logical set of linear segments. Examples of linear features are highways in transportation applications and pipelines in utility industry applications. The relationship of linear features, geometric segments, and LRS points is shown in Figure 76, where a single linear feature consists of three geometric segments, and three LRS points are shown on the first segment.
With a multiline string or polygon with hole LRS geometry, the SDO_LRS.DEFINE_GEOM_SEGMENT procedure and SDO_LRS.CONVERT_TO_LRS_GEOM function by default assign the same measure value to the end point of one segment and the start point (separated by a gap) of the next segment, although you can later assign different measure values to points. Thus, by default there will duplicate measure values in different segments for such geometries. In such cases, LRS subprograms use the first point with a specified measure, except when doing so would result in an invalid geometry.
For example, assume that in a multiline string LRS geometry, the first segment is from measures 0 through 100 and the second segment is from measures 100 through 150. If you use the SDO_LRS.LOCATE_PT function to find the point at measure 100, the returned point will be at measure 100 in the first segment. If you use the SDO_LRS.CLIP_GEOM_SEGMENT, SDO_LRS.DYNAMIC_SEGMENT, or SDO_LRS.OFFSET_GEOM_SEGMENT function to return the geometry object between measures 75 and 125, the result is a multiline string geometry consisting of two segments. If you use the same function to return the geometry object between measures 100 and 125, the point at measure 100 in the first segment is ignored, and the result is a line string along the second segment from measures 100 through 125.
The Oracle Spatial LRS data model incorporates measure information into its geometry representation at the point level. The measure information is directly integrated into the Oracle Spatial model. To accomplish this, an additional measure dimension must be added to the Oracle Spatial metadata.
Oracle Spatial LRS support affects the Spatial metadata and data (the geometries). Example 71 shows how a measure dimension can be added to twodimensional geometries in the Spatial metadata. The measure dimension must be the last element of the SDO_DIM_ARRAY in a spatial object definition (shown in bold in Example 71).
Example 71 Including LRS Measure Dimension in Spatial Metadata
INSERT INTO user_sdo_geom_metadata
(TABLE_NAME,
COLUMN_NAME,
DIMINFO,
SRID)
VALUES(
'LRS_ROUTES',
'GEOMETRY',
SDO_DIM_ARRAY (
SDO_DIM_ELEMENT('X', 0, 20, 0.005),
SDO_DIM_ELEMENT('Y', 0, 20, 0.005),
SDO_DIM_ELEMENT('M', 0, 100, 0.005)),
NULL);
After adding the new measure dimension, geometries with measure information such as geometric segments and LRS points can be represented. An example of creating a geometric segment with three line segments is shown in Figure 77.
In Figure 77, the geometric segment has the following definition (with measure values underlined):
SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1,2,1), SDO_ORDINATE_ARRAY(5,10,0, 20,5,NULL, 35,10,NULL, 55,10,100))
Whenever a geometric segment is defined, its start and end measures must be defined or derived from some existing geometric segment. The unsigned measures of all shape points on a geometric segment will be automatically populated.
The SDO_GTYPE of any point geometry used with an LRS function must be 3301.
If LRS data has four dimensions (three plus the M dimension) and if you need to index all three nonmeasure dimensions, you must use a spatial Rtree index to index the data, and you must specify PARAMETERS('sdo_indx_dims=3') in the CREATE INDEX statement to ensure that the first three dimensions are indexed. Note, however, that if you specify an sdo_indx_dims
value of 3 or higher, only those operators listed in Section 1.11 as considering all three dimensions can be used on the indexed geometries; the other operators described in Chapter 19 cannot be used. (The default value for the sdo_indx_dims
keyword is 2, which would cause only the first two dimensions to be indexed.) For example, if the dimensions are X, Y, Z, and M, specify sdo_indx_dims=3
to index the X, Y, and Z dimensions, but not the measure (M) dimension. Do not include the measure dimension in a spatial index, because this causes additional processing overhead and produces no benefit.
Information about the CREATE INDEX statement and its parameters and keywords is in Chapter 18.
Most LRS functions have formats that end in _3D: for example, DEFINE_GEOM_SEGMENT_3D, CLIP_GEOM_SEGMENT_3D, FIND_MEASURE_3D, and LOCATE_PT_3D. If a function has a 3D format, it is identified in the Usage Notes for the function in Chapter 25.
The 3D formats are supported only for line string and multiline string geometries. The 3D formats should be used only when the geometry object has four dimensions and the fourth dimension is the measure (for example, X, Y, Z, and M), and only when you want the function to consider the first three dimensions (for example, X, Y, and Z). If the standard format of a function (that is, without the _3D) is used on a geometry with four dimensions, the function considers only the first two dimensions (for example, X and Y).
For example, the following format considers the X, Y, and Z dimensions of the specified GEOM object in performing the clip operation:
SELECT SDO_LRS.CLIP_GEOM_SEGMENT_3D(a.geom, m.diminfo, 5, 10) FROM routes r, user_sdo_geom_metadata m WHERE m.table_name = 'ROUTES' AND m.column_name = 'GEOM' AND r.route_id = 1;
However, the following format considers only the X and Y dimensions, and ignores the Z dimension, of the specified GEOM object in performing the clip operation:
SELECT SDO_LRS.CLIP_GEOM_SEGMENT(a.geom, m.diminfo, 5, 10) FROM routes r, user_sdo_geom_metadata m WHERE m.table_name = 'ROUTES' AND m.column_name = 'GEOM' AND r.route_id = 1;
The parameters for the standard and 3D formats of any function are the same, and the Usage Notes apply to both formats.
The 3D formats are not supported with the following:
Geodetic data
Polygons, arcs, or circles
This section describes several linear referencing operations supported by the Oracle Spatial LRS API.
There are two ways to create a geometric segment with measure information:
Construct a geometric segment and assign measures explicitly.
Define a geometric segment with specified start and end, and any other measures, in an ascending or descending order. Measures of shape points with unknown (unassigned) measures (null values) in the geometric segment will be automatically populated according to their locations and distance distribution.
Figure 78 shows different ways of defining a geometric segment:
An LRS segment must be defined (or must already exist) before any LRS operations can proceed. That is, the start, end, and any other assigned measures must be present to derive the location from a specified measure. The measure information of intermediate shape points will automatically be populated if measure values are not assigned.
You can redefine a geometric segment to replace the existing measures of all shape points between the start and end point with automatically calculated measures. Redefining a segment can be useful if errors have been made in one or more explicit measure assignments, and you want to start over with proportionally assigned measures.
Figure 79 shows the redefinition of a segment where the existing (before) assigned measure values are not proportional and reflect widely varying gaps.
After the segment redefinition in Figure 79, the populated measures reflect proportional distances along the segment.
You can clip a geometric segment to create a new geometric segment out of an existing geometric segment, as shown in Figure 710, part a.
In Figure 710, part a, a segment is created from part of a larger segment. The new segment has its own start and end points, and the direction is the same as in the original larger segment.
You can create two new geometric segments by splitting a geometric segment, as shown in Figure 710, part b. The direction of each new segment is the same as in the original segment.
Note: In Figure 710 and several figures that follow, small gaps between segments are used in illustrations of segment splitting and concatenation. Each gap simply reinforces the fact that two different segments are involved. However, the two segments (such as segment 1 and segment 2 in Figure 710, parts b and c) are actually connected. The tolerance (see Section 1.5.5) is considered in determining whether or not segments are connected. 
You can create a new geometric segment by concatenating two geometric segments, as shown in Figure 710, part c. The geometric segments do not need to be spatially connected, although they are connected in the illustration in Figure 710, part c. (If the segments are not spatially connected, the concatenated result is a multiline string.) The measures of the second geometric segment are shifted so that the end measure of the first segment is the same as the start measure of the second segment. The direction of the segment resulting from the concatenation is the same as in the two original segments.
Measure assignments for the clipping, splitting, and concatenating operations in Figure 710 are shown in Figure 711. Measure information and segment direction are preserved in a consistent manner. The assignment is done automatically when the operations have completed.
The direction of the geometric segment resulting from concatenation is always the direction of the first segment (geom_segment1
in the call to the SDO_LRS.CONCATENATE_GEOM_SEGMENTS function), as shown in Figure 712.
In addition to explicitly concatenating two connected segments using the SDO_LRS.CONCATENATE_GEOM_SEGMENTS function, you can perform aggregate concatenation: that is, you can concatenate all connected geometric segments in a column (layer) using the SDO_AGGR_LRS_CONCAT spatial aggregate function. (See the description and example of the SDO_AGGR_LRS_CONCAT spatial aggregate function in Chapter 20.)
You can create a new geometric segment by performing a linear scaling operation on a geometric segment. Figure 713 shows the mapping relationship for geometric segment scaling.
In general, scaling a geometric segment only involves rearranging measures of the newly created geometric segment. However, if the scaling factor is negative, the order of the shape points needs to be reversed so that measures will increase along the geometric segment's direction (which is defined by the order of the shape points).
A scale operation can perform any combination of the following operations:
Translating (shifting) measure information. (For example, add the same value to Ms and Me to get M's and M'e.)</p>
Reversing measure information. (Let M's = Me, M'e = Ms, and Mshift = 0.)
Performing simple scaling of measure information. (Let Mshift = 0.)
For examples of these operations, see the Usage Notes and Examples for theSDO_LRS.SCALE_GEOM_SEGMENT, SDO_LRS.TRANSLATE_MEASURE, SDO_LRS.REVERSE_GEOMETRY, and SDO_LRS.REDEFINE_GEOM_SEGMENT subprograms in Chapter 25.
You can create a new geometric segment by performing an offsetting operation on a geometric segment. Figure 714 shows the mapping relationship for geometric segment offsetting.
In the offsetting operation shown in Figure 714, the resulting geometric segment is offset by 5 units from the specified start and end measures of the original segment.
For more information, see the Usage Notes and Examples for the SDO_LRS.OFFSET_GEOM_SEGMENT function in Chapter 25.
You can find the position of a point described by a measure and an offset on a geometric segment (see Figure 715).
There is always a unique location with a specific measure on a geometric segment. Ambiguity arises when offsets are given and the points described by the measures fall on shape points of the geometric segment (see Figure 716).
As shown in Figure 716, an offset arc of a shape point on a geometric segment is an arc on which all points have the same minimum distance to the shape point. As a result, all points on the offset arc are represented by the same (measure, offset) pair. To resolve this onetomany mapping problem, the middle point on the offset arc is returned.
You can find the projection point of a point with respect to a geometric segment. The point to be projected can be on or off the segment. If the point is on the segment, the point and its projection point are the same.
Projection is a reverse operation of the pointlocating operation shown in Figure 715. Similar to a pointlocating operation, all points on the offset arc of a shape point will have the same projection point (that is, the shape point itself), measure, and offset (see Figure 716). If there are multiple projection points for a point, the first one from the start point is returned (Projection Point 1 in both illustrations in Figure 717).
You can convert geometries from standard line string format to LRS format, and the reverse. The main use of conversion functions will probably occur if you have a large amount of existing line string data, in which case conversion is a convenient alternative to creating all of the LRS segments manually. However, if you need to convert LRS segments to standard line strings for certain applications, that capability is provided also.
Functions are provided to convert:
Individual line strings or points
For conversion from standard format to LRS format, a measure dimension (named M by default) is added, and measure information is provided for each point. For conversion from LRS format to standard format, the measure dimension and information are removed. In both cases, the dimensional information (DIMINFO) metadata in the USER_SDO_GEOM_METADATA view is not affected.
Layers (all geometries in a column)
For conversion from standard format to LRS format, a measure dimension (named M by default) is added, but no measure information is provided for each point. For conversion from LRS format to standard format, the measure dimension and information are removed. In both cases, the dimensional information (DIMINFO) metadata in the USER_SDO_GEOM_METADATA view is modified as needed.
Dimensional information (DIMINFO)
The dimensional information (DIMINFO) metadata in the USER_SDO_GEOM_METADATA view is modified as needed. For example, converting a standard dimensional array with X and Y dimensions (SDO_DIM_ELEMENT) to an LRS dimensional array causes an M dimension (SDO_DIM_ELEMENT) to be added.
Figure 718 shows the addition of measure information when a standard line string is converted to an LRS line string (using the SDO_LRS.CONVERT_TO_LRS_GEOM function). The measure dimension values are underlined in Figure 718.
For conversions of point geometries, the SDO_POINT attribute (described in Section 2.2.3) in the returned geometry is affected as follows:
If a standard point is converted to an LRS point, the SDO_POINT attribute information in the input geometry is used to set the SDO_ELEM_INFO and SDO_ORDINATES attributes (described in Section 2.2.4 and Section 2.2.5) in the resulting geometry, and the SDO_POINT attribute in the resulting geometry is set to null.
If an LRS point is converted to a standard point, the information in the SDO_ELEM_INFO and SDO_ORDINATES attributes (described in Section 2.2.4 and Section 2.2.5) in the input geometry is used to set the SDO_POINT attribute information in the resulting geometry, and the SDO_ELEM_INFO and SDO_ORDINATES attributes in the resulting geometry are set to null.
The conversion functions are listed in Table 253 in Chapter 25. See also the reference information in Chapter 25 about each conversion function.
Many LRS functions require that you specify a tolerance value or one or more dimensional arrays. Thus, you can control whether to specify a single tolerance value for all nonmeasure dimensions or to use the tolerance associated with each nonmeasure dimension in the dimensional array or arrays. The tolerance is applied only to the geometry portion of the data, not to the measure dimension. The tolerance value for geodetic data is in meters, and for nongeodetic data it is in the unit of measurement associated with the data. (For a detailed discussion of tolerance, see Section 1.5.5.)
Be sure that the tolerance value used is appropriate to the data and your purpose. If the results of LRS functions seem imprecise or incorrect, you may need to specify a smaller tolerance value.
For clip operations (see Section 7.5.3) and offset operations (see Section 7.5.7), if the returned segment has any shape points within the tolerance value of the input geometric segment from what would otherwise be the start point or end point of the returned segment, the shape point is used as the start point or end point of the returned segment. This is done to ensure that the resulting geometry does not contain any redundant vertices, which would cause the geometry to be invalid. For example, assume that the tolerance associated with the geometric segment (nongeodetic data) in Figure 719 is 0.5.
If you request a clip operation to return the segment between measure values 0 (the start point) and 61.5 in Figure 719, and if the distance between the points associated with measure values 61.5 and 61.257 is less than the 0.5 tolerance value, the end point of the returned segment is (35, 10, 61.257).
This section presents a simplified example that uses LRS functions. It refers to concepts that are explained in this chapter and uses functions documented in Chapter 25.
This example uses the road that is illustrated in Figure 720.
In Figure 720, the highway (Route 1) starts at point 2,2 and ends at point 5,14, follows the path shown, and has six entranceexit points (Exit 1 through Exit 6). For simplicity, each unit on the graph represents one unit of measure, and thus the measure from start to end is 27 (the segment from Exit 5 to Exit 6 being the hypotenuse of a 345 right triangle).
Each row in Table 71 lists an actual highwayrelated feature and the LRS feature that corresponds to it or that can be used to represent it.
Table 71 Highway Features and LRS Counterparts
Highway Feature  LRS Feature 

Named route, road, or street 
LRS segment, or linear feature (logical set of segments) 
Mile or kilometer marker 
Measure 
Accident reporting and location tracking 
SDO_LRS.LOCATE_PT function 
Construction zone (portion of a road) 
SDO_LRS.CLIP_GEOM_SEGMENT function 
Road extension (adding at the beginning or end) or combination (designating or renaming two roads that meet as one road) 
SDO_LRS.CONCATENATE_GEOM_SEGMENTS function 
Road reconstruction or splitting (resulting in two named roads from one named road) 
SDO_LRS.SPLIT_GEOM_SEGMENT procedure 
Finding the closest point on the road to a point off the road (such as a building) 
SDO_LRS.PROJECT_PT function 
Guard rail or fence alongside a road 
SDO_LRS.OFFSET_GEOM_SEGMENT function 
Example 72 does the following:
Creates a table to hold the segment depicted in Figure 720
Inserts the definition of the highway depicted in Figure 720 into the table
Inserts the necessary metadata into the USER_SDO_GEOM_METADATA view
Uses PL/SQL and SQL statements to define the segment and perform operations on it
Example 73 includes the output of the SELECT statements in Example 72.
Example 72 Simplified Example: Highway
 Create a table for routes (highways). CREATE TABLE lrs_routes ( route_id NUMBER PRIMARY KEY, route_name VARCHAR2(32), route_geometry SDO_GEOMETRY);  Populate table with just one route for this example. INSERT INTO lrs_routes VALUES( 1, 'Route1', SDO_GEOMETRY( 3302,  line string, 3 dimensions: X,Y,M NULL, NULL, SDO_ELEM_INFO_ARRAY(1,2,1),  one line string, straight segments SDO_ORDINATE_ARRAY( 2,2,0,  Start point  Exit1; 0 is measure from start. 2,4,2,  Exit2; 2 is measure from start. 8,4,8,  Exit3; 8 is measure from start. 12,4,12,  Exit4; 12 is measure from start. 12,10,NULL,  Not an exit; measure automatically calculated and filled. 8,10,22,  Exit5; 22 is measure from start. 5,14,27)  End point (Exit6); 27 is measure from start. ) );  Update the Spatial metadata. INSERT INTO user_sdo_geom_metadata (TABLE_NAME, COLUMN_NAME, DIMINFO, SRID) VALUES ( 'lrs_routes', 'route_geometry', SDO_DIM_ARRAY(  20X20 grid SDO_DIM_ELEMENT('X', 0, 20, 0.005), SDO_DIM_ELEMENT('Y', 0, 20, 0.005), SDO_DIM_ELEMENT('M', 0, 20, 0.005)  Measure dimension ), NULL  SRID );  Create the spatial index. CREATE INDEX lrs_routes_idx ON lrs_routes(route_geometry) INDEXTYPE IS MDSYS.SPATIAL_INDEX;  Test the LRS procedures. DECLARE geom_segment SDO_GEOMETRY; line_string SDO_GEOMETRY; dim_array SDO_DIM_ARRAY; result_geom_1 SDO_GEOMETRY; result_geom_2 SDO_GEOMETRY; result_geom_3 SDO_GEOMETRY; BEGIN SELECT a.route_geometry into geom_segment FROM lrs_routes a WHERE a.route_name = 'Route1'; SELECT m.diminfo into dim_array from user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY';  Define the LRS segment for Route1. This will populate any null measures.  No need to specify start and end measures, because they are already defined  in the geometry. SDO_LRS.DEFINE_GEOM_SEGMENT (geom_segment, dim_array); SELECT a.route_geometry INTO line_string FROM lrs_routes a WHERE a.route_name = 'Route1';  Split Route1 into two segments. SDO_LRS.SPLIT_GEOM_SEGMENT(line_string,dim_array,5,result_geom_1,result_geom_2);  Concatenate the segments that were just split. result_geom_3 := SDO_LRS.CONCATENATE_GEOM_SEGMENTS(result_geom_1, dim_array, result_geom_2, dim_array);  Update and insert geometries into table, to display later. UPDATE lrs_routes a SET a.route_geometry = geom_segment WHERE a.route_id = 1; INSERT INTO lrs_routes VALUES( 11, 'result_geom_1', result_geom_1 ); INSERT INTO lrs_routes VALUES( 12, 'result_geom_2', result_geom_2 ); INSERT INTO lrs_routes VALUES( 13, 'result_geom_3', result_geom_3 ); END; /  First, display the data in the LRS table. SELECT route_id, route_name, route_geometry FROM lrs_routes;  Are result_geom_1 and result_geom2 connected? SELECT SDO_LRS.CONNECTED_GEOM_SEGMENTS(a.route_geometry, b.route_geometry, 0.005) FROM lrs_routes a, lrs_routes b WHERE a.route_id = 11 AND b.route_id = 12;  Is the Route1 segment valid? SELECT SDO_LRS.VALID_GEOM_SEGMENT(route_geometry) FROM lrs_routes WHERE route_id = 1;  Is 50 a valid measure on Route1? (Should return FALSE; highest Route1 measure is 27.) SELECT SDO_LRS.VALID_MEASURE(route_geometry, 50) FROM lrs_routes WHERE route_id = 1;  Is the Route1 segment defined? SELECT SDO_LRS.IS_GEOM_SEGMENT_DEFINED(route_geometry) FROM lrs_routes WHERE route_id = 1;  How long is Route1? SELECT SDO_LRS.GEOM_SEGMENT_LENGTH(route_geometry) FROM lrs_routes WHERE route_id = 1;  What is the start measure of Route1? SELECT SDO_LRS.GEOM_SEGMENT_START_MEASURE(route_geometry) FROM lrs_routes WHERE route_id = 1;  What is the end measure of Route1? SELECT SDO_LRS.GEOM_SEGMENT_END_MEASURE(route_geometry) FROM lrs_routes WHERE route_id = 1;  What is the start point of Route1? SELECT SDO_LRS.GEOM_SEGMENT_START_PT(route_geometry) FROM lrs_routes WHERE route_id = 1;  What is the end point of Route1? SELECT SDO_LRS.GEOM_SEGMENT_END_PT(route_geometry) FROM lrs_routes WHERE route_id = 1;  Translate (shift measure values) (+10).  First, display the original segment; then, translate. SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; SELECT SDO_LRS.TRANSLATE_MEASURE(a.route_geometry, m.diminfo, 10) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1;  Redefine geometric segment to "convert" miles to kilometers DECLARE geom_segment SDO_GEOMETRY; dim_array SDO_DIM_ARRAY; BEGIN SELECT a.route_geometry into geom_segment FROM lrs_routes a WHERE a.route_name = 'Route1'; SELECT m.diminfo into dim_array from user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY';  "Convert" mile measures to kilometers (27 * 1.609 = 43.443). SDO_LRS.REDEFINE_GEOM_SEGMENT (geom_segment, dim_array, 0,  Zero starting measure: LRS segment starts at start of route. 43.443);  End of LRS segment. 27 miles = 43.443 kilometers.  Update and insert geometries into table, to display later. UPDATE lrs_routes a SET a.route_geometry = geom_segment WHERE a.route_id = 1; END;/  Display the redefined segment, with all measures "converted." SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1;  Clip a piece of Route1. SELECT SDO_LRS.CLIP_GEOM_SEGMENT(route_geometry, 5, 10) FROM lrs_routes WHERE route_id = 1;  Point (9,3,NULL) is off the road; should return (9,4,9). SELECT SDO_LRS.PROJECT_PT(route_geometry, SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(9, 3, NULL)) ) FROM lrs_routes WHERE route_id = 1;  Return the measure of the projected point. SELECT SDO_LRS.GET_MEASURE( SDO_LRS.PROJECT_PT(a.route_geometry, m.diminfo, SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(9, 3, NULL)) ), m.diminfo ) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1;  Is point (9,3,NULL) a valid LRS point? (Should return TRUE.) SELECT SDO_LRS.VALID_LRS_PT( SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(9, 3, NULL)), m.diminfo) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1;  Locate the point on Route1 at measure 9, offset 0. SELECT SDO_LRS.LOCATE_PT(route_geometry, 9, 0) FROM lrs_routes WHERE route_id = 1;
Example 73 shows the output of the SELECT statements in Example 72.
Example 73 Simplified Example: Output of SELECT Statements
SQL>  First, display the data in the LRS table. SQL> SELECT route_id, route_name, route_geometry FROM lrs_routes; ROUTE_ID ROUTE_NAME   ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  1 Route1 SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 8, 4, 8, 12, 4, 12, 12, 10, 18, 8, 10, 22, 5, 14, 27)) 11 result_geom_1 SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 5, 4, 5)) 12 result_geom_2 ROUTE_ID ROUTE_NAME   ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 5, 4, 5, 8, 4, 8, 12, 4, 12, 12, 10, 18, 8, 10, 22, 5, 14, 27)) 13 result_geom_3 SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 5, 4, 5, 8, 4, 8, 12, 4, 12, 12, 10, 18, 8, 10, 22, 5, 14, 27) ) SQL>  Are result_geom_1 and result_geom2 connected? SQL> SELECT SDO_LRS.CONNECTED_GEOM_SEGMENTS(a.route_geometry, 2 b.route_geometry, 0.005) 3 FROM lrs_routes a, lrs_routes b 4 WHERE a.route_id = 11 AND b.route_id = 12; SDO_LRS.CONNECTED_GEOM_SEGMENTS(A.ROUTE_GEOMETRY,B.ROUTE_GEOMETRY,0.005)  TRUE SQL>  Is the Route1 segment valid? SQL> SELECT SDO_LRS.VALID_GEOM_SEGMENT(route_geometry) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.VALID_GEOM_SEGMENT(ROUTE_GEOMETRY)  TRUE SQL>  Is 50 a valid measure on Route1? (Should return FALSE; highest Route1 measure is 27.) SQL> SELECT SDO_LRS.VALID_MEASURE(route_geometry, 50) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.VALID_MEASURE(ROUTE_GEOMETRY,50)  FALSE SQL>  Is the Route1 segment defined? SQL> SELECT SDO_LRS.IS_GEOM_SEGMENT_DEFINED(route_geometry) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.IS_GEOM_SEGMENT_DEFINED(ROUTE_GEOMETRY)  TRUE SQL>  How long is Route1? SQL> SELECT SDO_LRS.GEOM_SEGMENT_LENGTH(route_geometry) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_LENGTH(ROUTE_GEOMETRY)  27 SQL>  What is the start measure of Route1? SQL> SELECT SDO_LRS.GEOM_SEGMENT_START_MEASURE(route_geometry) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_START_MEASURE(ROUTE_GEOMETRY)  0 SQL>  What is the end measure of Route1? SQL> SELECT SDO_LRS.GEOM_SEGMENT_END_MEASURE(route_geometry) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_END_MEASURE(ROUTE_GEOMETRY)  27 SQL>  What is the start point of Route1? SQL> SELECT SDO_LRS.GEOM_SEGMENT_START_PT(route_geometry) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_START_PT(ROUTE_GEOMETRY)(SDO_GTYPE, SDO_SRID, SDO_POINT(X,  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 2, 2, 0)) SQL>  What is the end point of Route1? SQL> SELECT SDO_LRS.GEOM_SEGMENT_END_PT(route_geometry) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_END_PT(ROUTE_GEOMETRY)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y,  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 5, 14, 27)) SQL>  Translate (shift measure values) (+10). SQL>  First, display the original segment; then, translate. SQL> SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 8, 4, 8, 12, 4, 12, 12, 10, 18, 8, 10, 22, 5, 14, 27)) SQL> SELECT SDO_LRS.TRANSLATE_MEASURE(a.route_geometry, m.diminfo, 10) 2 FROM lrs_routes a, user_sdo_geom_metadata m 3 WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' 4 AND a.route_id = 1; SDO_LRS.TRANSLATE_MEASURE(A.ROUTE_GEOMETRY,M.DIMINFO,10)(SDO_GTYPE, SDO_SRID, SD  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 10, 2, 4, 12, 8, 4, 18, 12, 4, 22, 12, 10, 28, 8, 10, 32, 5, 14, 37)) SQL>  Redefine geometric segment to "convert" miles to kilometers SQL> DECLARE 2 geom_segment SDO_GEOMETRY; 3 dim_array SDO_DIM_ARRAY; 4 5 BEGIN 6 7 SELECT a.route_geometry into geom_segment FROM lrs_routes a 8 WHERE a.route_name = 'Route1'; 9 SELECT m.diminfo into dim_array from 10 user_sdo_geom_metadata m 11 WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY'; 12 13  "Convert" mile measures to kilometers (27 * 1.609 = 43.443). 14 SDO_LRS.REDEFINE_GEOM_SEGMENT (geom_segment, 15 dim_array, 16 0,  Zero starting measure: LRS segment starts at start of route. 17 43.443);  End of LRS segment. 27 miles = 43.443 kilometers. 18 19  Update and insert geometries into table, to display later. 20 UPDATE lrs_routes a SET a.route_geometry = geom_segment 21 WHERE a.route_id = 1; 22 23 END; 24 / PL/SQL procedure successfully completed. SQL>  Display the redefined segment, with all measures "converted." SQL> SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 3.218, 8, 4, 12.872, 12, 4, 19.308, 12, 10, 28.962, 8, 10, 35.398 , 5, 14, 43.443)) SQL>  Clip a piece of Route1. SQL> SELECT SDO_LRS.CLIP_GEOM_SEGMENT(route_geometry, 5, 10) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.CLIP_GEOM_SEGMENT(ROUTE_GEOMETRY,5,10)(SDO_GTYPE, SDO_SRID, SDO_POINT(X,  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 5, 4, 5, 8, 4, 8, 10, 4, 10)) SQL>  Point (9,3,NULL) is off the road; should return (9,4,9). SQL> SELECT SDO_LRS.PROJECT_PT(route_geometry, 2 SDO_GEOMETRY(3301, NULL, NULL, 3 SDO_ELEM_INFO_ARRAY(1, 1, 1), 4 SDO_ORDINATE_ARRAY(9, 3, NULL)) ) 5 FROM lrs_routes WHERE route_id = 1; SDO_LRS.PROJECT_PT(ROUTE_GEOMETRY,SDO_GEOMETRY(3301,NULL,NULL,SDO_EL  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 9, 4, 9)) SQL>  Return the measure of the projected point. SQL> SELECT SDO_LRS.GET_MEASURE( 2 SDO_LRS.PROJECT_PT(a.route_geometry, m.diminfo, 3 SDO_GEOMETRY(3301, NULL, NULL, 4 SDO_ELEM_INFO_ARRAY(1, 1, 1), 5 SDO_ORDINATE_ARRAY(9, 3, NULL)) ), 6 m.diminfo ) 7 FROM lrs_routes a, user_sdo_geom_metadata m 8 WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' 9 AND a.route_id = 1; SDO_LRS.GET_MEASURE(SDO_LRS.PROJECT_PT(A.ROUTE_GEOMETRY,M.DIMINFO,SDO_GEOM  9 SQL>  Is point (9,3,NULL) a valid LRS point? (Should return TRUE.) SQL> SELECT SDO_LRS.VALID_LRS_PT( 2 SDO_GEOMETRY(3301, NULL, NULL, 3 SDO_ELEM_INFO_ARRAY(1, 1, 1), 4 SDO_ORDINATE_ARRAY(9, 3, NULL)), 5 m.diminfo) 6 FROM lrs_routes a, user_sdo_geom_metadata m 7 WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' 8 AND a.route_id = 1; SDO_LRS.VALID_LRS_PT(SDO_GEOMETRY(3301,NULL,NULL,SDO_ELEM_INFO_ARRAY  TRUE SQL>  Locate the point on Route1 at measure 9, offset 0. SQL> SELECT SDO_LRS.LOCATE_PT(route_geometry, 9, 0) 2 FROM lrs_routes WHERE route_id = 1; SDO_LRS.LOCATE_PT(ROUTE_GEOMETRY,9,0)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), S  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 9, 4, 9))
The Java Shapefile converter transforms an ESRI Shapefile into an Oracle Database table for use with Oracle Spatial and Locator. The Shapefile converter uses the Oracle Spatial Javabased Shapefile AdapterShapefileJGeom
and SampleShapefileToJGeomFeature
classes to load a Shapefile directly into a database table, with the Oracleequivalent .dbf
data types for the attribute columns and the SDO_GEOMETRY data type for the geometry column.
To load a Shapefile into the database, use the converter as described in this appendix. (You can also use the Adapter
class to create your own applications and interfaces that transform Shapefiles to SDO_GEOMETRY or JGeometry data types; however, doing this is beyond the scope of this manual. For information about Shapefilerelated classes, see Oracle Spatial Java API Reference).
To use the Shapefile converter, you must have the following:
The following Oracle utilities and JDBC libraries: ojdbc14.jar
or ojdbc5.jar
, sdoutl.jar
, and sdoapi.jar
One or more ESRI Shapefiles (.shp
, .shx
, .and .dbf
files) to be converted
The following is the syntax for the Shapefile converter. (Enter the command all on a single line.)
> java cp [ORACLE_HOME]/jdbc/lib/ojdbc5.jar:[ORACLE_HOME]/md/jlib/sdoutl.jar:[ORACLE_HOME]/md/jlib/sdoapi.jar oracle.spatial.util.SampleShapefileToJGeomFeature h db_host p db_port s db_sid u db_username d db_password t db_table f shapefile_name [i table_id_column_name][r srid][g db_geometry_column][x max_x,min_x][y max_y,min_y][o tolerance]
Parameters
h
: Host machine with an existing Oracle database
p
: Port on the host machine (for example, 1521)
s
: SID (database name) on the host machine
u
: Database user
d
: Password for the database use
t
: Table name for the converted Shapefile
f
: File name of an input Shapefile (with or without extension)
i
: Column name for unique numeric ID, if required
r
: Valid Oracle SRID for coordinate system; use 0 if unknown
g
: Preferred SDO_GEOMETRY column name
x
: Bounds for the X dimension; use 180,180 if unknown
y
: Bounds for the Y dimension; use 90,90 if unknown
o
: Load tolerance fields (x and y) in metadata; if not specified, tolerance fields are 0.05
a
: Append Shapefile data to an existing table
n
: Start ID for column specified in i parameter
c
: Commit interval; by default, commits occur every 1000 conversions and at the end
v
: Println interval; by default, a display every 10 conversions
The following examples show the use of the Shapefile converter to transform a file named shapes
to a table named shapes
containing an SDO_GEOMETRY column named geom
. The SRID for the Longitude/Latitude (WGS 84) coordinate system is used (8307).
Linux Example
> setenv clpath $ORACLE_HOME/jdbc/lib/ojdbc5.jar:$ORACLE_HOME/md/jlib/sdoutl.jar:$ORACLE_HOME/md/jlib/sdoapi.jar
> java cp $clpath oracle.spatial.util.SampleShapefileToJGeomFeature h gis01 p 1521 s orcl u scott d <passwordforscott> t shapes f shapes.shp r 8307 g geom
Windows Example
> java classpath %ORACLE_HOME%\jdbc\lib\ojdbc5.jar;%ORACLE_HOME%\md\jlib\sdoutl.jar;%ORACLE_HOME%\md\jlib\sdoapi.jar oracle.spatial.util.SampleShapefileToJGeomFeature h gis01 p 1521 s orcl u scott d <passwordforscott> t shapes f shapes.shp r 8307 g geom
This appendix provides examples, with explanations, of queries that are more complex than the examples in the reference chapters in Part III, "Reference Information". This appendix focuses on operators that are frequently used in Spatial applications, such as SDO_WITHIN_DISTANCE and SDO_NN.
This appendix is based on input from Oracle personnel who provide support and training to Spatial users. The Oracle Spatial training course covers many of these examples, and provides additional examples and explanations.
Before you use any of the examples in this appendix, be sure you understand the usage and reference information for the relevant operator or function in Part I, "Conceptual and Usage Information" and Part III, "Reference Information".
This appendix contains the following major sections:
The examples in this appendix refer to tables named GEOD_CITIES, GEOD_COUNTIES, and GEOD_INTERSTATES, which are defined as follows:
CREATE TABLE GEOD_CITIES( LOCATION SDO_GEOMETRY, CITY VARCHAR2(42), STATE_ABRV VARCHAR2(2), POP90 NUMBER, RANK90 NUMBER); CREATE TABLE GEOD_COUNTIES( COUNTY_NAME VARCHAR2(40), STATE_ABRV VARCHAR2(2), GEOM SDO_GEOMETRY); CREATE TABLE GEOD_INTERSTATES( HIGHWAY VARCHAR2(35), GEOM SDO_GEOMETRY);
The SDO_WITHIN_DISTANCE operator identifies the set of spatial objects that are within some specified distance of a given object. You can indicate that the distance is approximate or exact. If you specify querytype=FILTER
, the distance is approximate because only a primary filter operation is performed; otherwise, the distance is exact because both primary and secondary filtering operations are performed.
Example C1 finds all cities within 15 miles of the interstate highway I170.
Example C1 Finding All Cities Within a Distance of a Highway
SELECT /*+ ORDERED */ c.city FROM geod_interstates i, geod_cities c WHERE i.highway = 'I170' AND sdo_within_distance ( c.location, i.geom, 'distance=15 unit=mile') = 'TRUE';
Example C1 finds all cities within 15 miles ('distance=15 unit=mile'
) of the specified highway (i.highway = 'I170'
), and by default the result is exact (because the querytype
parameter was not used to limit the query to a primary filter operation). In the WHERE
clause of this example:
i.highway
refers to the HIGHWAY column of the INTERSTATES table, and I170
is a value from the HIGHWAY column.
c.location
specifies the search column (geometry1
). This is the LOCATION column of the GEOD_CITIES table.
i.geom
specifies the query window (aGeom
). This is the spatial geometry in the GEOM column of the GEOD_INTERSTATES table, in the row whose HIGHWAY column contains the value I170
.
Example C2 finds all interstate highways within 15 miles of the city of Tampa.
Example C2 Finding All Highways Within a Distance of a City
SELECT /*+ ORDERED */ i.highway FROM geod_cities c, geod_interstates i WHERE c.city = 'Tampa' AND sdo_within_distance ( i.geom, c.location, 'distance=15 unit=mile') = 'TRUE';
Example C2 finds all highways within 15 miles ('distance=15 unit=mile'
) of the specified city (c.city = 'Tampa'
), and by default the result is exact (because the querytype
parameter was not used to limit the query to a primary filter operation). In the WHERE
clause of this example:
c.city
refers to the CITY column of the GEOD_CITIES table, and Tampa
is a value from the CITY column.
i.geom
specifies the search column (geometry1
). This is the GEOM column of the GEOD_INTERSTATES table.
c.location
specifies the query window (aGeom
). This is the spatial geometry in the LOCATION column of the GEOD_CITIES table, in the row whose CITY column contains the value Tampa
.
The SDO_NN operator determines the nearest neighbor geometries to a geometry. No assumptions should be made about the order of the returned results, unless you specify the SDO_NN_DISTANCE ancillary operator in the ORDER BY clause to have the results returned in distance order. If you specify no optional parameters, one nearest neighbor geometry is returned.
If you specify the optional sdo_num_res
keyword, you can request how many nearest neighbors you want, but no other conditions in the WHERE clause are evaluated. For example, assume that you want the five closest banks from an intersection, but only where the bank name is CHASE
. If the five closest banks are not named CHASE
, SDO_NN with sdo_num_res=5
will return no rows because the sdo_num_res
keyword only takes proximity into account, and not any other conditions in the WHERE clause.
If you specify the optional sdo_batch_size
keyword, any sdo_num_res
specification is ignored, and SDO_NN keeps returning neighbor geometries in distance order to the WHERE clause. If the WHERE clause specifies bank_name = 'CHASE' AND rownum < 6
, you can return the five closest banks with bank_name = 'CHASE'
.
SDO_NN_DISTANCE is an ancillary operator to the SDO_NN operator. It returns the distance of an object returned by the SDO_NN operator and is valid only within a call to the SDO_NN operator.
Example C3 finds the five cities nearest to the interstate highway I170 and the distance in miles from the highway for each city, ordered by distance in miles.
Example C3 Finding the Cities Nearest to a Highway
SELECT /*+ ORDERED */ c.city, sdo_nn_distance (1) distance_in_miles FROM geod_interstates i, geod_cities c WHERE i.highway = 'I170' AND sdo_nn(c.location, i.geom, 'sdo_num_res=5 unit=mile', 1) = 'TRUE' ORDER BY distance_in_miles;
In Example C3, because the /*+ ORDERED*/
optimizer hint is used, it is important to have an index on the GEOD_INTERSTATES.HIGHWAY column. In this example, the hint forces the query to locate highway I170 before it tries to find nearest neighbor geometries. In the WHERE
clause of this example:
i.highway
refers to the HIGHWAY column of the GEOD_INTERSTATES table, and I170
is a value from the HIGHWAY column.
c.location
specifies the search column (geometry1
). This is the LOCATION column of the GEOD_CITIES table.
i.geom
specifies the query window (geometry2
). This is the spatial geometry in the GEOM column of the GEOD_INTERSTATES table, in the row whose HIGHWAY column contains the value I170
.
sdo_num_res=5
specifies how many nearest neighbor geometries to find.
unit=mile
specifies the unit of measurement to associate with distances returned by the SDO_NN_DISTANCE ancillary operator.
1
(in sdo_nn_distance (1)
and 'sdo_num_res=5 unit=mile', 1
) is the number
parameter value that associates the call to SDO_NN with the call to SDO_NN_DISTANCE.
In Example C3, ORDER BY distance_in_miles
orders the results from the WHERE clause by distance in miles.
The statement in Example C3 produces the following output (slightly reformatted for readability):
CITY DISTANCE_IN_MILES   St Louis 5.36297295 Springfield 78.7997464 Peoria 141.478022 Evansville 158.22422 Springfield 188.508631
Example C4 extends Example C3 by limiting the results to cities with a 1990 population over a certain number. It finds the five cities nearest to the interstate highway I170 that have a population greater than 300,000, the 1990 population for each city, and the distance in miles from the highway for each city, ordered by distance in miles.
Example C4 Finding the Cities Above a Specified Population Nearest to a Highway
SELECT /*+ ORDERED NO_INDEX(c pop90_idx) */ c.city, pop90, sdo_nn_distance (1) distance_in_miles FROM geod_interstates i, geod_cities c WHERE i.highway = 'I170' AND sdo_nn(c.location, i.geom, 'sdo_batch_size=10 unit=mile', 1) = 'TRUE' AND c.pop90 > 300000 AND rownum < 6 ORDER BY distance_in_miles;
In Example C4, because the ORDERED
optimizer hint is used, it is important to have an index on the GEOD_INTERSTATES.HIGHWAY column. In this example, the hint forces the query to locate highway I170 before it tries to find nearest neighbor geometries.
To ensure correct results, disable all nonspatial indexes on columns that come from the same table as the SDO_NN search column (geometry1
). In this example, the NO_INDEX(c pop90_idx)
optimizer hint disables the nonspatial index on the POP90 column.
In the WHERE
clause of this example:
sdo_batch_size=10
causes geometries to be returned continually (in distance order, in batches of 10 geometries), to be checked to see if they satisfy the other conditions in the WHERE clause.
c.pop90 > 300000
restricts the results to rows where the POP90 column value is greater than 300000.
rownum < 6
limits the number of results returned to five.
In Example C4, ORDER BY distance_in_miles
orders the results from the WHERE clause by distance in miles.
The statement in Example C4 produces the following output (slightly reformatted for readability):
CITY POP90 DISTANCE_IN_MILES    St Louis 396685 5.36297295 Kansas City 435146 227.404883 Indianapolis 741952 234.708666 Memphis 610337 244.202072 Chicago 2783726 253.547961
If many rows are being aggregated, a single SDO_AGGR_UNION aggregate function may take a long time to run. This is because SDO_AGGR_UNION aggregates the first two geometries passed in, then aggregates the result to the next geometry, then aggregates the result to the next one, and so on. The reason this will eventually run slowly is that the result will very quickly grow to a geometry with many vertices, and every subsequent aggregation will include this very complex geometry.
For better performance when aggregating many rows, break your aggregation into groupings so that each is always 50 geometries or fewer. Example C5 shows the following:
An initial SELECT statement to determine how many groupings of 50 (as a power of 2) are needed for the geometries you want to aggregate (in this case, ZIP code geometries in the US states of California, Oregon, and Washington). If there are 5000 such geometries, the POWER function result is 128, which you should use use for the innermost GROUP BY clause in the next SELECT statement.
A SELECT statement that uses nested aggregates and GROUP BY clauses. For best performance, "skip" power of 2 values in the GROUP BY clauses as you go down to 2. This example has clauses using 128, 32, 8, and 2; but it does not have clauses using 64, 16, or 4.
Example C5 Aggregate Union with Groupings for Many Rows
 Determine how many groupings of 50 are needed. Assume 5000 rows in  all. 5000/50 = 100; and 128 is the next higher power of 2. SELECT POWER(2, CEIL( LOG(2, COUNT(*)/50))) FROM ZIP_CODES z WHERE z.state_code IN ('CA', 'OR', 'WA');  Perform the aggregate union operation, using 128 in the  innermost GROUP BY clause. SELECT sdo_aggr_union(sdoaggrtype(aggr_geom,0.5)) aggr_geom FROM (SELECT sdo_aggr_union(sdoaggrtype(aggr_geom,0.5)) aggr_geom FROM (SELECT sdo_aggr_union(sdoaggrtype(aggr_geom,0.5)) aggr_geom FROM (SELECT sdo_aggr_union(sdoaggrtype(aggr_geom,0.5)) aggr_geom FROM (SELECT sdo_aggr_union(mdsys.sdoaggrtype(geom,0.5)) aggr_geom FROM ZIP_CODES z WHERE z.state_code IN ('CA', 'OR', 'WA') GROUP BY mod(rownum,128)) GROUP BY mod (rownum, 32)) GROUP BY mod (rownum, 8)) GROUP BY mod (rownum, 2) );
This chapter contains descriptions of the triangulated irregular network (TIN) subprograms shown in Table 301.
Table 301 TIN Subprograms
Subprogram  Description 


Performs a clip operation on a TIN. 

Creates a TIN using the points specified in the 

Drops the dependencies between a TIN block table and a specified base table and column. 

Initializes a TIN. 

Returns a geometry object representing all or part of a TIN. 
To use the subprograms in this package, you must understand the main concepts related to threedimensional geometries, including the use of triangulated irregular networks (TINs) to model surfaces. Section 1.11 describes support for threedimensional geometries, Section 1.11.1 describes the use of TINs to model surfaces, and Section 2.5 describes data types related to TINs.
Format
SDO_TIN_PKG.CLIP_TIN(
inp IN SDO_TIN,
qry IN SDO_GEOMETRY,
qry_min_res IN NUMBER,
qry_max_res IN NUMBER,
blkid IN NUMBER DEFAULT NULL
) RETURN SDO_TIN_BLK_TYPE;
Parameters
TIN on which to perform the clip operation.
Window from which to select objects to be returned; typically a polygon for twodimensional geometries or a frustum for threedimensional geometries.
Minimum resolution value. Objects in qry
with resolutions equal to or greater than qry_min_res
and less than or equal to qry_max_res
are returned by the clip operation.
Maximum resolution value. Objects in qry
with resolutions equal to or greater than qry_min_res
and less than or equal to qry_max_res
are returned by the clip operation.
Block ID number of the block to which to restrict the objects returned by the clip operation. If this parameter is null, all objects that satisfy the other parameters are returned.
Usage Notes
This function returns triangles from a TIN that are within a specified query window and that satisfy any other requirements specified by the parameters. A common use of this function is to perform queries on TINs. You can maximize the performance of a TIN query by minimizing the number of objects that the function needs to consider for the operation.
The SDO_TIN and SDO_TIN_BLK_TYPE data types are described in Section 2.5.
Section 1.11.1 describes how to use TINs to model surfaces.
Examples
The following example performs a clip operation on a TIN. It is taken from the sdo_tin.sql
example program, which is under $ORACLE_HOME
/md/demo/examples/TIN/plsql/
if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).
. . . declare inp sdo_tin; begin select tin INTO inp from base where rownum=1; insert into restst select * from table(sdo_tin_pkg.clip_tin ( inp,  Input TIN object sdo_geometry(2003, null, null, mdsys.sdo_elem_info_array(1, 1003, 3), mdsys.sdo_ordinate_array(74.1, 73.9, 39.99999,40.00001)),  Query null, null)); end; . . .
Format
SDO_TIN_PKG.CREATE_TIN(
inp IN SDO_TIN,
inptable IN VARCHAR2,
clstPcdataTbl IN VARCHAR2 DEFAULT NULL);
Parameters
SDO_TIN object to be used. This object must have been created by the SDO_TIN_PKG.INIT function
Name of the table or view containing the input TIN data. This table or view should have the following columns:
RID (VARCHAR2(24)): Unique ID for each point
VAL_D1 (NUMBER): Ordinate in dimension 1
VAL_D2 (NUMBER): Ordinate in dimension 2
. . .
VAL_Dn (NUMBER): Ordinate in dimension n, where n is the highestnumbered dimension. n should match the tin_tot_dimensions
parameter value in the call to the SDO_TIN_PKG.INIT function when the TIN was initialized.
Name of the table for storing the resulting point data. If you do not specify a value, this table is not created. For more information about the table, see the Usage Notes.
Usage Notes
The first few dimensions of the TIN are indexed and can later be searched using the SDO_TIN_PKG.CLIP_TIN function. The exact number of dimensions to index is determined by the dimensionality of the TIN extent in the initialized TIN object, specifically: inp.tin_extent.sdo_gtype/1000
If you specify a view name in the inptable
parameter, the query SELECT ROWID FROM <viewname>
must not return any errors.
If you specify a table name in the clstPcdataTbl
parameter, the table must exist and have the following columns:
PTN_ID (NUMBER)
POINT_ID (NUMBER)
RID (VARCHAR2(24): Unique ID for each point
VAL_D1 (NUMBER): Ordinate in dimension 1
VAL_D2 (NUMBER): Ordinate in dimension 2
. . .
VAL_Dn (NUMBER): Ordinate in dimension n, where n is the highestnumbered dimension. n should match the tin_tot_dimensions
parameter value in the call to the SDO_TIN_PKG.INIT function when the TIN was initialized.
If a value is specified for the clstPcdataTbl
parameter, this function populates the table by assigning appropriate values for PTN_ID and POINT_ID and by copying the values from the inptable
table or view for other attributes. This table can be created as an index organized table. It can be used in applications for searching using SQL queries on dimensions other than those reflected in the index dimensionality. (For an explanation of index dimensionality and total dimensionality, see the explanation of the tin_tot_dimensions
parameter of the SDO_TIN_PKG.INIT function.)
The SDO_TIN data type is described in Section 2.5.
Section 1.11.1 describes how to use TINs to model surfaces.
Examples
The following example creates a TIN. It is taken from the sdo_tin.sql
example program, which is under $ORACLE_HOME
/md/demo/examples/TIN/plsql/
if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).
. . .  Create the blocks for the TIN. sdo_tin_pkg.create_tin( tin,  Initialized TIN object 'INPTAB',  Name of input table to ingest into the pointcloud 'RES'  Name of output table that stores the points (with ptn_id,pt_id) ); / . . .
Parameters
Name of a base table that was specified (in the basetable
parameter of the SDO_TIN_PKG.INIT function) when the TIN was initialized.
Name of a column in base table that was specified in the basecol
parameter of the SDO_TIN_PKG.INIT function.
Usage Notes
This procedure truncates the TIN block table and removes the association between the block table and the base table and column combination.
After you execute this procedure, you can drop the TIN block table or associate the table with another base table and column combination. For more information, see the Usage Notes for the SDO_TIN_PKG.INIT function.
Format
SDO_TIN_PKG.INIT(
basetable IN VARCHAR2,
basecol IN VARCHAR2,
blktable IN VARCHAR2,
ptn_params IN VARCHAR2,
tin_extent IN SDO_GEOMETRY,
tin_tol IN NUMBER DEFAULT 0.000000000000005,
tin_tot_dimensions IN NUMBER DEFAULT 2,
tin_domain IN SDO_ORGSCL_TYPE DEFAULT NULL,
tin_break_lines IN SDO_GEOMETRY DEFAULT NULL,
tin_stop_lines IN SDO_GEOMETRY DEFAULT NULL,
tin_void_rgns IN SDO_GEOMETRY DEFAULT NULL,
tin_val_attr_tables IN SDO_STRING_ARRAY DEFAULT NULL,
tin_other_attrs IN XMLTYPE DEFAULT NULL,
) RETURN SDO_TIN;
Parameters
Name of the base table containing a column of type SDO_TIN.
Name of the column of type SDO_TIN in the base table.
Name of the TIN block table, which is used for storing the blocks of the TIN. This table must exist, and must have been created by a statement in the following form: CREATE TABLE <tablename> AS select * from mdsys.sdo_tin_blk_table;
Each TIN block table can only be associated with only one basetable
and basecol
combination.
Parameters for partitioning the TIN, specified as a quoted string with keywords delimited by commas. For example: 'blk_capacity=1000,work_tablespace=my_work_ts'
. If this parameter is null, the TIN is not partitioned. The following keywords are permitted:
blk_capacity=n
, where n is the maximum number of rows in each partition. The default value is 5000. If specified, must be a number greater than or equal to 50.
work_tablespace=x
, where x is the name of the tablespace in which to create temporary tables during the partitioning operations.
SDO_GEOMETRY object representing the spatial extent of the TIN (the minimum bounding object enclosing all objects in the TIN. This parameter must not be null.
For geodetic data, this geometry must have two dimensions; otherwise, it can have up to four dimensions. The dimensionality of this geometry is used as the minimum value permitted for the tin_tot_dimensions
parameter, as explained in the description of that parameter.
Tolerance value for objects in the TIN. (For information about spatial tolerance, see Section 1.5.5.) If this parameter is null, the default value is 0.0000000000005.
A number specifying the total dimensionality of the TIN object. For each point in the TIN blocks, tin_tot_dimensions
ordinates (values) are stored.
The total dimensionality must be greater than or equal to the index dimensionality, which is the number of dimensions in the tin_extent
geometry. Specifying total dimensionality greater than index dimensionality enables necessary nonspatial attributes to be retrieved in the same fetch operation with spatial data. The maximum total dimensionality value is 8. The default value for this parameter is 2.
(Not currently used.)
(Not currently used.)
(Not currently used.)
(Not currently used.)
SDO_STRING_ARRAY object specifying the names of any value attribute tables for the TIN. If this parameter is null, the TIN has no associated value attribute tables. Type SDO_STRING_ARRAY is defined as VARRAY(1048576) OF VARCHAR2(32).
XMLTYPE object specifying any other attributes of the TIN. If this parameter is null, the TIN has no other attributes.
Usage Notes
After you use this function to create an SDO_TIN object, you can create a TIN by specifying this object as input to the SDO_TIN_PKG.CREATE_TIN procedure.
The SDO_TIN data type is described in Section 2.5.
Section 1.11.1 describes how to use TINs to model surfaces.
Examples
The following example initializes a TIN by creating an SDO_TIN object. It is taken from the sdo_tin.sql
example program, which is under $ORACLE_HOME
/md/demo/examples/TIN/plsql/
if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).
declare tin sdo_tin; begin  Initialize the TIN object. tin := sdo_tin_pkg.init( 'BASE',  Table that has the SDO_TIN column defined 'TIN',  Column name of the SDO_TIN object 'BLKTAB',  Table to store blocks of the TIN 'blk_capacity=1000',  max # of points per block mdsys.sdo_geometry(2003, null, null, mdsys.sdo_elem_info_array(1,1003,3), mdsys.sdo_ordinate_array(180, 90, 180, 90)),  Extent 0.0000000005,  Tolerance for TIN 3,  Total number of dimensions null); . . .
Format
SDO_TIN_PKG.TO_GEOMETRY(
pts IN BLOB,
trs IN BLOB,
num_pts IN NUMBER,
num_trs IN NUMBER,
tin_tot_dim IN NUMBER,
srid IN NUMBER DEFAULT NULL,
blk_domain IN SDO_ORGSCL_TYPE DEFAULT NULL
) RETURN SDO_GEOMETRY;
Parameters
BLOB containing points.
BLOB containing triangles.
Maximum number of points to be included in the resulting geometry.
Maximum number of triangles to be included in the resulting geometry.
Number of spatial dimensions defined for the data.
Spatial reference (coordinate system) ID associated with the data. If this parameter is null, no SRID value is associated with the data.
(Not currently used.)
Usage Notes
This function returns a single collection SDO_GEOMETRY object that represents all point geometries in the pts
parameter and all triangle geometries in the trs
parameter. For example, the points and triangles could reflect the result of a clip operation or the contents of an entire block.
Section 1.11.1 describes how to use TINs to model surfaces.
Examples
The following example returns a multipoint collection geometry object representing a TIN. It is taken from the sdo_tin.sql
example program, which is under $ORACLE_HOME
/md/demo/examples/TIN/plsql/
if you installed the files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide).
. . .  Return points in blk_id of the TIN as a multipoint collection. select sdo_tin_pkg.to_geometry( a.points,  point LOB a.triangles,  point LOB a.num_points,  # of points in the LOB a.num_triangles,  # of points in the LOB 2,  index dimensionality (gtype dim in extent in INIT) 3,  total dimensionality null  SRID ) from blktab a where blk_id=0; . . .
This chapter describes how to load spatial data into a database, including storing the data in a table with a column of type SDO_GEOMETRY. After you have loaded spatial data, you can create a spatial index for it and perform queries on it, as described in Chapter 5.
The process of loading data can be classified into two categories:
Bulk loading of data (see Section 4.1)
This process is used to load large volumes of data into the database and uses the SQL*Loader utility to load the data.
Transactional insert operations (see Section 4.2)
This process is typically used to insert relatively small amounts of data into the database using the INSERT statement in SQL.
Recommendations for loading and validating spatial data are described in Section 4.3.
Bulk loading can import large amounts of data into an Oracle database. Bulk loading is accomplished with the SQL*Loader utility. (For information about SQL*Loader, see Oracle Database Utilities.)
Example 41 is the SQL*Loader control file for loading four geometries. When this control file is used with SQL*Loader, it loads the same cola market geometries that are inserted using SQL statements in Example 21 in Section 2.1.
Example 41 Control File for a Bulk Load of Cola Market Geometries
LOAD DATA INFILE * TRUNCATE CONTINUEIF NEXT(1:1) = '#' INTO TABLE COLA_MARKETS FIELDS TERMINATED BY '' TRAILING NULLCOLS ( mkt_id INTEGER EXTERNAL, name CHAR, shape COLUMN OBJECT ( SDO_GTYPE INTEGER EXTERNAL, SDO_ELEM_INFO VARRAY TERMINATED BY '/' (elements FLOAT EXTERNAL), SDO_ORDINATES VARRAY TERMINATED BY '/' (ordinates FLOAT EXTERNAL) ) ) begindata 1cola_a #2003110033/ #1157/ 2cola_b #2003110031/ #5181865751/ 3cola_c #2003110031/ #3363654533/ 4cola_d #2003110034/ #87109811/
Notes on Example 41:
The EXTERNAL
keyword in the definition mkt_id INTEGER EXTERNAL
means that each value to be inserted into the MKT_ID column (1, 2, 3, and 4 in this example) is an integer in humanreadable form, not binary format.
In the data after begindata
, each MKT_ID value is preceded by one space, because the CONTINUEIF NEXT(1:1) = '#'
specification causes the first position of each data line to be ignored unless it is the number sign (#) continuation character.
Example 42 assumes that a table named POLY_4PT was created as follows:
CREATE TABLE POLY_4PT (GID VARCHAR2(32), GEOMETRY SDO_GEOMETRY);
Assume that the ASCII data consists of a file with delimited columns and separate rows fixed by the limits of the table with the following format:
geometry rows: GID, GEOMETRY
The coordinates in the GEOMETRY column represent polygons. Example 42 shows the control file for loading the data.
Example 42 Control File for a Bulk Load of Polygons
LOAD DATA INFILE * TRUNCATE CONTINUEIF NEXT(1:1) = '#' INTO TABLE POLY_4PT FIELDS TERMINATED BY '' TRAILING NULLCOLS ( GID INTEGER EXTERNAL, GEOMETRY COLUMN OBJECT ( SDO_GTYPE INTEGER EXTERNAL, SDO_ELEM_INFO VARRAY TERMINATED BY '/' (elements FLOAT EXTERNAL), SDO_ORDINATES VARRAY TERMINATED BY '/' (ordinates FLOAT EXTERNAL) ) ) begindata 12003110031/ #122.421537.7862122.42237.7869122.42137.789122.4237.7866 #122.421537.7862/ 22003110031/ #122.401937.8052122.402737.8055122.403137.806122.401237.8052 #122.401937.8052/ 32003110031/ #122.42637.803122.424237.8053122.4235537.8044122.423537.8025 #122.42637.803/
Example 43 shows a control file for loading a table with point data.
Example 43 Control File for a Bulk Load of PointOnly Data
LOAD DATA INFILE * TRUNCATE CONTINUEIF NEXT(1:1) = '#' INTO TABLE POINT FIELDS TERMINATED BY '' TRAILING NULLCOLS ( GID INTEGER EXTERNAL, GEOMETRY COLUMN OBJECT ( SDO_GTYPE INTEGER EXTERNAL, SDO_POINT COLUMN OBJECT (X FLOAT EXTERNAL, Y FLOAT EXTERNAL) ) ) BEGINDATA 1 2001 122.4215 37.7862 2 2001 122.4019 37.8052 3 2001 122.426 37.803 4 2001 122.4171 37.8034 5 2001 122.416151 37.8027228
Oracle Spatial uses standard Oracle tables that can be accessed or loaded with standard SQL syntax. This section contains examples of transactional insertions into columns of type SDO_GEOMETRY. This process is typically used to add relatively small amounts of data into the database.
The INSERT statement in Oracle SQL has a limit of 999 arguments. Therefore, you cannot create a variablelength array of more than 999 elements using the SDO_GEOMETRY constructor inside a transactional INSERT statement; however, you can insert a geometry using a host variable, and the host variable can be built using the SDO_GEOMETRY constructor with more than 999 values in the SDO_ORDINATE_ARRAY specification. (The host variable is an OCI, PL/SQL, or Java program variable.)
To perform transactional insertions of geometries, you can create a procedure to insert a geometry, and then invoke that procedure on each geometry to be inserted. Example 44 creates a procedure to perform the insert operation.
Example 44 Procedure to Perform a Transactional Insert Operation
CREATE OR REPLACE PROCEDURE INSERT_GEOM(GEOM SDO_GEOMETRY) IS BEGIN INSERT INTO TEST_1 VALUES (GEOM); COMMIT; END; /
Using the procedure created in Example 44, you can insert data by using a PL/SQL block, such as the one in Example 45, which loads a geometry into the variable named geom
and then invokes the INSERT_GEOM procedure to insert that geometry.
Example 45 PL/SQL Block Invoking a Procedure to Insert a Geometry
DECLARE geom SDO_geometry := SDO_geometry (2003, null, null, SDO_elem_info_array (1,1003,3), SDO_ordinate_array (109,37,102,40)); BEGIN INSERT_GEOM(geom); COMMIT; END; /
For additional examples with various geometry types, see the following:
Rectangle: Example 26 in Section 2.7.1
Polygon with a hole: Example 27 in Section 2.7.2
Compound line string: Example 28 in Section 2.7.3
Compound polygon: Example 29 in Section 2.7.4
Point: Example 210 and Example 211 in Section 2.7.5
Oriented point: Example 212 in Section 2.7.6
Type 0 (zero) element: Example 214 in Section 2.7.7
The recommended procedure for loading and validating spatial data is as follows:
Load the data, using a method described in Section 4.1 or Section 4.2.
Use the SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT function or the SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT procedure on all spatial data loaded into the database.
For any geometries with the wrong orientation or an invalid ETYPE or GTYPE value, use SDO_MIGRATE.TO_CURRENT on these invalid geometries to fix them.
For any geometries that are invalid for other reasons, use SDO_UTIL.RECTIFY_GEOMETRY to fix these geometries.
For detailed information about using any of these subprograms, see the usage notes in its reference information section.
Oracle Spatial is an integrated set of functions and procedures that enables spatial data to be stored, accessed, and analyzed quickly and efficiently in an Oracle database.
Spatial data represents the essential location characteristics of real or conceptual objects as those objects relate to the real or conceptual space in which they exist.
This chapter contains the following major sections:
Section 1.13, "Spatial Java Application Programming Interface"
Section 1.20, "Spatial Application Hardware Requirement Considerations"
Section 1.23, "README File for Spatial and Related Features"
Oracle Spatial, often referred to as Spatial, provides a SQL schema and functions that facilitate the storage, retrieval, update, and query of collections of spatial features in an Oracle database. Spatial consists of the following:
A schema (MDSYS) that prescribes the storage, syntax, and semantics of supported geometric data types
A spatial indexing mechanism
Operators, functions, and procedures for performing areaofinterest queries, spatial join queries, and other spatial analysis operations
Functions and procedures for utility and tuning operations
Topology data model for working with data about nodes, edges, and faces in a topology (described in Oracle Spatial Topology and Network Data Models Developer's Guide).
Network data model for representing capabilities or objects that are modeled as nodes and links in a network (described in Oracle Spatial Topology and Network Data Models Developer's Guide).
GeoRaster, a feature that lets you store, index, query, analyze, and deliver GeoRaster data, that is, raster image and gridded data and its associated metadata (described in Oracle Spatial GeoRaster Developer's Guide).
The spatial component of a spatial feature is the geometric representation of its shape in some coordinate space. This is referred to as its geometry.
Caution: Do not modify any packages, tables, or other objects under the MDSYS schema. (The only exception is if you need to create a userdefined coordinate reference system, as explained in Section 6.9.) 
Spatial supports the objectrelational model for representing geometries. This model stores an entire geometry in the Oracle native spatial data type for vector data, SDO_GEOMETRY. An Oracle table can contain one or more SDO_GEOMETRY columns. The objectrelational model corresponds to a "SQL with Geometry Types" implementation of spatial feature tables in the Open GIS ODBC/SQL specification for geospatial features.
The benefits provided by the objectrelational model include:
Support for many geometry types, including arcs, circles, compound polygons, compound line strings, and optimized rectangles
Ease of use in creating and maintaining indexes and in performing spatial queries
Index maintenance by the Oracle database
Geometries modeled in a single column
Optimal performance
Oracle Spatial is designed to make spatial data management easier and more natural to users of locationenabled applications and geographic information system (GIS) applications. Once spatial data is stored in an Oracle database, it can be easily manipulated, retrieved, and related to all other data stored in the database.
A common example of spatial data can be seen in a road map. A road map is a twodimensional object that contains points, lines, and polygons that can represent cities, roads, and political boundaries such as states or provinces. A road map is a visualization of geographic information. The location of cities, roads, and political boundaries that exist on the surface of the Earth are projected onto a twodimensional display or piece of paper, preserving the relative positions and relative distances of the rendered objects.
The data that indicates the Earth location (such as longitude and latitude) of these rendered objects is the spatial data. When the map is rendered, this spatial data is used to project the locations of the objects on a twodimensional piece of paper. A GIS is often used to store, retrieve, and render this Earthrelative spatial data.
Types of spatial data (other than GIS data) that can be stored using Spatial include data from computeraided design (CAD) and computeraided manufacturing (CAM) systems. Instead of operating on objects on a geographic scale, CAD/CAM systems work on a smaller scale, such as for an automobile engine or printed circuit boards.
The differences among these systems are in the size and precision of the data, not the data's complexity. The systems might all involve the same number of data points. On a geographic scale, the location of a bridge can vary by a few tenths of an inch without causing any noticeable problems to the road builders, whereas if the diameter of an engine's pistons is off by a few tenths of an inch, the engine will not run.
In addition, the complexity of data is independent of the absolute scale of the area being represented. For example, a printed circuit board is likely to have many thousands of objects etched on its surface, containing in its small area information that may be more complex than the details shown on a road builder's blueprints.
These applications all store, retrieve, update, or query some collection of features that have both nonspatial and spatial attributes. Examples of nonspatial attributes are name, soil_type, landuse_classification, and part_number. The spatial attribute is a coordinate geometry, or vectorbased representation of the shape of the feature.
A geometry is an ordered sequence of vertices that are connected by straight line segments or circular arcs. The semantics of the geometry are determined by its type. Spatial supports several primitive types, and geometries composed of collections of these types, including twodimensional:
Points and point clusters
Line strings
npoint polygons
Arc line strings (All arcs are generated as circular arcs.)
Arc polygons
Compound polygons
Compound line strings
Circles
Optimized rectangles
Twodimensional points are elements composed of two ordinates, X and Y, often corresponding to longitude and latitude. Line strings are composed of one or more pairs of points that define line segments. Polygons are composed of connected line strings that form a closed ring, and the area of the polygon is implied. For example, a point might represent a building location, a line string might represent a road or flight path, and a polygon might represent a state, city, zoning district, or city block.
Selfcrossing polygons are not supported, although selfcrossing line strings are supported. If a line string crosses itself, it does not become a polygon. A selfcrossing line string does not have any implied area.
Figure 11 illustrates the geometric types.
Spatial also supports the storage and indexing of threedimensional and fourdimensional geometric types, where three or four coordinates are used to define each vertex of the object being defined. For information about support for threedimensional geometries, see Section 1.11.
The Spatial data model is a hierarchical structure consisting of elements, geometries, and layers. Layers are composed of geometries, which in turn are made up of elements.
An element is the basic building block of a geometry. The supported spatial element types are points, line strings, and polygons. For example, elements might model star constellations (point clusters), roads (line strings), and county boundaries (polygons). Each coordinate in an element is stored as an X,Y pair. The exterior ring and zero or more interior rings (holes) of a complex polygon are considered a single element.
Point data consists of one coordinate. Line data consists of two coordinates representing a line segment of the element. Polygon data consists of coordinate pair values, one vertex pair for each line segment of the polygon. Coordinates are defined in order around the polygon (counterclockwise for an exterior polygon ring, clockwise for an interior polygon ring).
A geometry (or geometry object) is the representation of a spatial feature, modeled as an ordered set of primitive elements. A geometry can consist of a single element, which is an instance of one of the supported primitive types, or a homogeneous or heterogeneous collection of elements. A multipolygon, such as one used to represent a set of islands, is a homogeneous collection. A heterogeneous collection is one in which the elements are of different types, for example, a point and a polygon.
An example of a geometry might describe the buildable land in a town. This could be represented as a polygon with holes where water or zoning prevents construction.
A layer is a collection of geometries having the same attribute set. For example, one layer in a GIS might include topographical features, while another describes population density, and a third describes the network of roads and bridges in the area (lines and points). The geometries and associated spatial index for each layer are stored in the database in standard tables.
A coordinate system (also called a spatial reference system) is a means of assigning coordinates to a location and establishing relationships between sets of such coordinates. It enables the interpretation of a set of coordinates as a representation of a position in a real world space.
Any spatial data has a coordinate system associated with it. The coordinate system can be georeferenced (related to a specific representation of the Earth) or not georeferenced (that is, Cartesian, and not related to a specific representation of the Earth). If the coordinate system is georeferenced, it has a default unit of measurement (such as meters) associated with it, but you can have Spatial automatically return results in another specified unit (such as miles). (For more information about unit of measurement support, see Section 2.10.)
Spatial data can be associated with a Cartesian, geodetic (geographical), projected, or local coordinate system:
Cartesian coordinates are coordinates that measure the position of a point from a defined origin along axes that are perpendicular in the represented twodimensional or threedimensional space.
If a coordinate system is not explicitly associated with a geometry, a Cartesian coordinate system is assumed.
Geodetic coordinates (sometimes called geographic coordinates) are angular coordinates (longitude and latitude), closely related to spherical polar coordinates, and are defined relative to a particular Earth geodetic datum. (A geodetic datum is a means of representing the figure of the Earth and is the reference for the system of geodetic coordinates.)
Projected coordinates are planar Cartesian coordinates that result from performing a mathematical mapping from a point on the Earth's surface to a plane. There are many such mathematical mappings, each used for a particular purpose.
Local coordinates are Cartesian coordinates in a nonEarth (nongeoreferenced) coordinate system. Local coordinate systems are often used for CAD applications and local surveys.
When performing operations on geometries, Spatial uses either a Cartesian or curvilinear computational model, as appropriate for the coordinate system associated with the spatial data.
For more information about coordinate system support in Spatial, including geodetic, projected, and local coordinates and coordinate system transformation, see Chapter 6.
Tolerance is used to associate a level of precision with spatial data. Tolerance reflects the distance that two points can be apart and still be considered the same (for example, to accommodate rounding errors). The tolerance value must be a positive number greater than zero. The significance of the value depends on whether or not the spatial data is associated with a geodetic coordinate system. (Geodetic and other types of coordinate systems are described in Section 1.5.4.)
For geodetic data (such as data identified by longitude and latitude coordinates), the tolerance value is a number of meters. For example, a tolerance value of 100 indicates a tolerance of 100 meters. The tolerance value for geodetic data must be 0.05 (5 centimeters) or greater. Spatial uses 0.05 as the tolerance value for geodetic data if you specify a smaller value with the following functions: SDO_GEOM.RELATE, SDO_GEOM.SDO_DIFFERENCE, SDO_GEOM.SDO_INTERSECTION, SDO_GEOM.SDO_UNION, and SDO_GEOM.SDO_XOR; however, the geometries must be valid at the 0.05 tolerance.
For nongeodetic data, the tolerance value is a number of the units that are associated with the coordinate system associated with the data. For example, if the unit of measurement is miles, a tolerance value of 0.005 indicates a tolerance of 0.005 (that is, 1/200) mile (approximately 26 feet or 7.9 meters), and a tolerance value of 2 indicates a tolerance of 2 miles.
In both cases, the smaller the tolerance value, the more precision is to be associated with the data.
For geometries that have 16 or more digits of precision, Spatial boolean operations (such as SDO_GEOM.SDO_UNION and SDO_GEOM.SDO_INTERSECTION) and the SDO_GEOM.RELATE function might produce inconsistent results due to the loss of precision in floating point arithmetic. The number of digits of precision is calculated as in the following example: if the tolerance is set to 0.0000000005 and the coordinates have 6 digits to the left of decimal (for example, 123456.4321), the precision is 10 + 6 digits (16). In such cases, it is better to use a larger tolerance value (fewer leading zeros after the decimal) to get consistent results using Spatial operations.
A tolerance value is specified in two cases:
In the geometry metadata definition for a layer (see Section 1.5.5.1)
As an input parameter to certain functions (see Section 1.5.5.2)
For additional information about tolerance with linear referencing system (LRS) data, see Section 7.6.
The dimensional information for a layer includes a tolerance value. Specifically, the DIMINFO column (described in Section 2.8.3) of the xxx_SDO_GEOM_METADATA views includes an SDO_TOLERANCE value for each dimension, and the value should be the same for each dimension.
If a function accepts an optional tolerance
parameter and this parameter is null or not specified, the SDO_TOLERANCE value of the layer is used. Using the nongeodetic data from the example in Section 2.1, the actual distance between geometries cola_b
and cola_d
is 0.846049894. If a query uses the SDO_GEOM.SDO_DISTANCE function to return the distance between cola_b
and cola_d
and does not specify a tolerance
parameter value, the result depends on the SDO_TOLERANCE value of the layer. For example:
If the SDO_TOLERANCE value of the layer is 0.005, this query returns .846049894.
If the SDO_TOLERANCE value of the layer is 0.5, this query returns 0.
The zero result occurs because Spatial first constructs an imaginary buffer of the tolerance value (0.5) around each geometry to be considered, and the buffers around cola_b
and cola_d
overlap in this case. (If the two geometries being considered have different tolerance values, the higher value is used for the imaginary buffer.)
You can, therefore, take either of two approaches in selecting an SDO_TOLERANCE value for a layer:
The value can reflect the desired level of precision in queries for distances between objects. For example, if two nongeodetic geometries 0.8 units apart should be considered as separated, specify a small SDO_TOLERANCE value such as 0.05 or smaller.
The value can reflect the precision of the values associated with geometries in the layer. For example, if all geometries in a nongeodetic layer are defined using integers and if two objects 0.8 units apart should not be considered as separated, an SDO_TOLERANCE value of 0.5 is appropriate. To have greater precision in any query, you must override the default by specifying the tolerance
parameter.
With nongeodetic data, the guideline to follow for most instances of the second case (precision of the values of the geometries in the layer) is: take the highest level of precision in the geometry definitions, and use .5 at the next level as the SDO_TOLERANCE value. For example, if geometries are defined using integers (as in the simplified example in Section 2.1), the appropriate value is 0.5; however, if geometries are defined using numbers up to four decimal positions (for example, 31.2587), the appropriate value is 0.00005.
Note: This guideline should not be used if the geometries include any polygons that are so narrow at any point that the distance between facing sides is less than the proposed tolerance value. Be sure that the tolerance value is less than the shortest distance between any two sides in any polygon.Moreover, if you encounter "invalid geometry" errors with inserted or updated geometries, and if the geometries are in fact valid, consider increasing the precision of the tolerance value (for example, changing 0.00005 to 0.000005). 
Many Spatial functions accept a tolerance
parameter, which (if specified) overrides the default tolerance value for the layer (explained in Section 1.5.5.1). If the distance between two points is less than or equal to the tolerance value, Spatial considers the two points to be a single point. Thus, tolerance is usually a reflection of how accurate or precise users perceive their spatial data to be.
For example, assume that you want to know which restaurants are within 5 kilometers of your house. Assume also that Maria's Pizzeria is 5.1 kilometers from your house. If the spatial data has a geodetic coordinate system and if you ask, Find all restaurants within 5 kilometers and use a tolerance of 100 (or greater, such as 500), Maria's Pizzeria will be included, because 5.1 kilometers (5100 meters) is within 100 meters of 5 kilometers (5000 meters). However, if you specify a tolerance less than 100 (such as 50), Maria's Pizzeria will not be included.
Tolerance values for Spatial functions are typically very small, although the best value in each case depends on the kinds of applications that use or will use the data. See also the tolerance guidelines in Section 1.5.5.1, and ensure that all input geometries are valid. (Spatial functions may not work as expected if the geometry data is not valid.)
If you explicitly want to use the tolerance value from the dimensional information array for the geometry layer, and if a subprogram has separate formats with tolerance
(or tol
) and dim
parameters, use the format with dim
. In the following example, the first statement uses the tolerance value from the dimensional information array, and the second statement specifies a numeric tolerance value (0.005):
 Return the area of the cola_a geometry. SELECT c.name, SDO_GEOM.SDO_AREA(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'; SELECT c.name, SDO_GEOM.SDO_AREA(c.shape, 0.005) FROM cola_markets c WHERE c.name = 'cola_a';
Spatial uses a twotier query model to resolve spatial queries and spatial joins. The term is used to indicate that two distinct operations are performed to resolve queries. The output of the two combined operations yields the exact result set.
The two operations are referred to as primary and secondary filter operations.
The primary filter permits fast selection of candidate records to pass along to the secondary filter. The primary filter compares geometry approximations to reduce computation complexity and is considered a lowercost filter. Because the primary filter compares geometric approximations, it returns a superset of the exact result set.
The secondary filter applies exact computations to geometries that result from the primary filter. The secondary filter yields an accurate answer to a spatial query. The secondary filter operation is computationally expensive, but it is only applied to the primary filter results, not the entire data set.
Figure 12 illustrates the relationship between the primary and secondary filters.
As shown in Figure 12, the primary filter operation on a large input data set produces a smaller candidate set, which contains at least the exact result set and may contain more records. The secondary filter operation on the smaller candidate set produces the exact result set.
Spatial uses a spatial index to implement the primary filter. Spatial does not require the use of both the primary and secondary filters. In some cases, just using the primary filter is sufficient. For example, a zoom feature in a mapping application queries for data that has any interaction with a rectangle representing visible boundaries. The primary filter very quickly returns a superset of the query. The mapping application can then apply clipping routines to display the target area.
The purpose of the primary filter is to quickly create a subset of the data and reduce the processing burden on the secondary filter. The primary filter, therefore, should be as efficient (that is, selective yet fast) as possible. This is determined by the characteristics of the spatial index on the data.
For more information about querying spatial data, see Section 5.2.
The introduction of spatial indexing capabilities into the Oracle database engine is a key feature of the Spatial product. A spatial index, like any other index, provides a mechanism to limit searches, but in this case the mechanism is based on spatial criteria such as intersection and containment. A spatial index is needed to:
Find objects within an indexed data space that interact with a given point or area of interest (window query)
Find pairs of objects from within two indexed data spaces that interact spatially with each other (spatial join)
Testing of spatial indexes with many workloads and operators is ongoing, and results and recommendations will be documented as they become available.
The following sections explain the concepts and options associated with Rtree indexing.
A spatial Rtree index can index spatial data of up to four dimensions. An Rtree index approximates each geometry by a single rectangle that minimally encloses the geometry (called the minimum bounding rectangle, or MBR), as shown in Figure 13.
For a layer of geometries, an Rtree index consists of a hierarchical index on the MBRs of the geometries in the layer, as shown in Figure 14.
In Figure 14:
1 through 9 are geometries in a layer.
a, b, c, and d are the leaf nodes of the Rtree index, and contain minimum bounding rectangles of geometries, along with pointers to the geometries. For example, a contains the MBR of geometries 1 and 2, b contains the MBR of geometries 3 and 4, and so on.
A contains the MBR of a and b, and B contains the MBR of c and d.
The root contains the MBR of A and B (that is, the entire area shown).
An Rtree index is stored in the spatial index table (SDO_INDEX_TABLE in the USER_SDO_INDEX_METADATA view, described in Section 2.9). The Rtree index also maintains a sequence object (SDO_RTREE_SEQ_NAME in the USER_SDO_INDEX_METADATA view) to ensure that simultaneous updates by concurrent users can be made to the index.
A substantial number of insert and delete operations affecting an Rtree index may degrade the quality of the Rtree structure, which may adversely affect query performance.
The Rtree is a hierarchical tree structure with nodes at different heights of the tree. The performance of an Rtree index structure for queries is roughly proportional to the area and perimeter of the index nodes of the Rtree. The area covered at level 0 represents the area occupied by the minimum bounding rectangles of the data geometries, the area at level 1 indicates the area covered by leaflevel Rtree nodes, and so on. The original ratio of the area at the root (topmost level) to the area at level 0 can change over time based on updates to the table; and if there is a degradation in that ratio (that is, if it increases significantly), rebuilding the index may help the performance of queries.
If the performance of SDO_FILTER operations has degraded, and if there have been a large number of insert, update, or delete operations affecting geometries, the performance degradation may be due to a degradation in the quality of the associated Rtree index. You can check for degradation of index quality by using the SDO_TUNE.QUALITY_DEGRADATION function (described in Chapter 31); and if the function returns a number greater than 2, consider rebuilding the index. Note, however, that the Rtree index quality degradation number may not be significant in terms of overall query performance due to Oracle caching strategies and other significant Oracle capabilities, such as table pinning, which can essentially remove I/O overhead from Rtree index queries.
To rebuild an Rtree index, use the ALTER INDEX REBUILD statement, which is described in Chapter 18.
Spatial uses secondary filters to determine the spatial relationship between entities in the database. The spatial relationship is based on geometry locations. The most common spatial relationships are based on topology and distance. For example, the boundary of an area consists of a set of curves that separates the area from the rest of the coordinate space. The interior of an area consists of all points in the area that are not on its boundary. Given this, two areas are said to be adjacent if they share part of a boundary but do not share any points in their interior.
The distance between two spatial objects is the minimum distance between any points in them. Two objects are said to be within a given distance of one another if their distance is less than the given distance.
To determine spatial relationships, Spatial has several secondary filter methods:
The SDO_RELATE operator evaluates topological criteria.
The SDO_WITHIN_DISTANCE operator determines if two spatial objects are within a specified distance of each other.
The SDO_NN operator identifies the nearest neighbors for a spatial object.
The syntax of these operators is given in Chapter 19.
The SDO_RELATE operator implements a nineintersection model for categorizing binary topological relationships between points, lines, and polygons. Each spatial object has an interior, a boundary, and an exterior. The boundary consists of points or lines that separate the interior from the exterior. The boundary of a line string consists of its end points; however, if the end points overlap (that is, if they are the same point), the line string has no boundary. The boundaries of a multiline string are the end points of each of the component line strings; however, if the end points overlap, only the end points that overlap an odd number of times are boundaries. The boundary of a polygon is the line that describes its perimeter. The interior consists of points that are in the object but not on its boundary, and the exterior consists of those points that are not in the object and are not on its boundary.
Given that an object A has three components (a boundary Ab, an interior Ai, and an exterior Ae), any pair of objects has nine possible interactions between their components. Pairs of components have an empty (0) or not empty (1) set intersection. The set of interactions between two geometries is represented by a nineintersection matrix that specifies which pairs of components intersect and which do not. Figure 15 shows the nineintersection matrix for two polygons that are adjacent to one another. This matrix yields the following bit mask, generated in rowmajor form: "101001111".
Some of the topological relationships identified in the seminal work by Professor Max Egenhofer (University of Maine, Orono) and colleagues have names associated with them. Spatial uses the following names:
TOUCH: The boundaries intersect but the interiors do not intersect.
OVERLAPBDYDISJOINT: The interior of one object intersects the boundary and interior of the other object, but the two boundaries do not intersect. This relationship occurs, for example, when a line originates outside a polygon and ends inside that polygon.
OVERLAPBDYINTERSECT: The boundaries and interiors of the two objects intersect.
CONTAINS: The interior and boundary of one object is completely contained in the interior of the other object.
COVERS: The interior of one object is completely contained in the interior or the boundary of the other object and their boundaries intersect.
INSIDE: The opposite of CONTAINS. A INSIDE B implies B CONTAINS A.
COVEREDBY: The opposite of COVERS. A COVEREDBY B implies B COVERS A.
ON: The interior and boundary of one object is on the boundary of the other object. This relationship occurs, for example, when a line is on the boundary of a polygon.
Figure 16 illustrates these topological relationships.
The SDO_WITHIN_DISTANCE operator determines if two spatial objects, A and B, are within a specified distance of one another. This operator first constructs a distance buffer, D_{b}, around the reference object B. It then checks that A and D_{b} are nondisjoint. The distance buffer of an object consists of all points within the given distance from that object. Figure 17 shows the distance buffers for a point, a line, and a polygon.
In the point, line, and polygon geometries shown in Figure 17:
The dashed lines represent distance buffers. Notice how the buffer is rounded near the corners of the objects.
The geometry on the right is a polygon with a hole: the large rectangle is the exterior polygon ring and the small rectangle is the interior polygon ring (the hole). The dashed line outside the large rectangle is the buffer for the exterior ring, and the dashed line inside the small rectangle is the buffer for the interior ring.
The SDO_NN operator returns a specified number of objects from a geometry column that are closest to a specified geometry (for example, the five closest restaurants to a city park). In determining how close two geometry objects are, the shortest possible distance between any two points on the surface of each object is used.
The Spatial PL/SQL application programming interface (API) includes several operators and many procedures and functions.
Spatial operators, such as SDO_FILTER and SDO_RELATE, provide optimum performance because they use the spatial index. (Spatial operators require that the geometry column in the first parameter have a spatial index defined on it.) Spatial operators must be used in the WHERE clause of a query. The first parameter of any operator specifies the geometry column to be searched, and the second parameter specifies a query window. If the query window does not have the same coordinate system as the geometry column, Spatial performs an implicit coordinate system transformation. For detailed information about the spatial operators, see Chapter 19.
Spatial procedures and functions are provided as subprograms in PL/SQL packages, such as SDO_GEOM, SDO_CS, and SDO_LRS. These subprograms do not require that a spatial index be defined, and they do not use a spatial index if it is defined. These subprograms can be used in the WHERE clause or in a subquery. If two geometries are input parameters to a Spatial procedure or function, both must have the same coordinate system.
Note: For any numbers in string (VARCHAR2) parameters to Spatial and Graph operators and subprograms, the period (.) must be used for any decimal points regardless of the locale. Example:'distance=3.7' 
The following performancerelated guidelines apply to the use of spatial operators, procedures, and functions:
If an operator and a procedure or function perform comparable operations, and if the operator satisfies your requirements, use the operator. For example, unless you need to do otherwise, use SDO_RELATE instead of SDO_GEOM.RELATE, and use SDO_WITHIN_DISTANCE instead of SDO_GEOM.WITHIN_DISTANCE.
With operators, always specify TRUE
in uppercase. That is, specify = 'TRUE'
, and do not specify <> 'FALSE'
or = 'true'
.
With operators, use the /*+ ORDERED */
optimizer hint if the query window comes from a table. (You must use this hint if multiple windows come from a table.) See the Usage Notes and Examples for specific operators for more information.
For information about using operators with topologies, see Oracle Spatial Topology and Network Data Models Developer's Guide.
SQL has long had aggregate functions, which are used to aggregate the results of a SQL query. The following example uses the SUM aggregate function to aggregate employee salaries by department:
SELECT SUM(salary), dept FROM employees GROUP BY dept;
Oracle Spatial aggregate functions aggregate the results of SQL queries involving geometry objects. Spatial aggregate functions return a geometry object of type SDO_GEOMETRY. For example, the following statement returns the minimum bounding rectangle of all geometries in a table (using the definitions and data from Section 2.1):
SELECT SDO_AGGR_MBR(shape) FROM cola_markets;
The following example returns the union of all geometries except cola_d
:
SELECT SDO_AGGR_UNION(SDOAGGRTYPE(c.shape, 0.005)) FROM cola_markets c WHERE c.name <> 'cola_d';
For reference information about the spatial aggregate functions and examples of their use, see Chapter 20.
Note: Spatial aggregate functions are supported for twodimensional geometries only, except for SDO_AGGR_MBR, which is supported for both twodimensional and threedimensional geometries. 
Many spatial aggregate functions accept an input parameter of type SDOAGGRTYPE. Oracle Spatial defines the object type SDOAGGRTYPE as:
CREATE TYPE sdoaggrtype AS OBJECT ( geometry SDO_GEOMETRY, tolerance NUMBER);
Note: Do not use SDOAGGRTYPE as the data type for a column in a table. Use this type only in calls to spatial aggregate functions. 
The tolerance
value in the SDOAGGRTYPE definition should be the same as the SDO_TOLERANCE value specified in the DIMINFO column in the xxx_SDO_GEOM_METADATA views for the geometries, unless you have a specific reason for wanting a different value. For more information about tolerance, see Section 1.5.5; for information about the xxx_SDO_GEOM_METADATA views, see Section 2.8.
The tolerance
value in the SDOAGGRTYPE definition can affect the result of a spatial aggregate function. Figure 18 shows a spatial aggregate union (SDO_AGGR_UNION) operation of two geometries using two different tolerance values: one smaller and one larger than the distance between the geometries.
In the first aggregate union operation in Figure 18, where the tolerance is less than the distance between the rectangles, the result is a compound geometry consisting of two rectangles. In the second aggregate union operation, where the tolerance is greater than the distance between the rectangles, the result is a single geometry.
Effective with Oracle Database Release 11.1, Oracle Spatial supports the storage and retrieval of threedimensional spatial data, which can include points, point clouds (collections of points), lines, polygons, surfaces, and solids. Table 11 show the SDO_GTYPE and elementrelated attributes of the SDO_GEOMETRY type that are relevant to threedimensional geometries. (The SDO_GEOMETRY type is explained in Section 2.2.)
Table 11 SDO_GEOMETRY Attributes for ThreeDimensional Geometries
Type of 3D Data  SDO_GTYPE  Element Type, Interpretation in SDO_ELEM_INFO 

Point 
3001 
Does not apply. Specify all 3 dimension values in the SDO_POINT_TYPE attribute. 
Line 
3002 
2, 1 
Polygon 
3003 
1003, 1: planar exterior polygon 2003, 1: planar interior polygon 1003, 3: planar exterior rectangle 2003, 3: planar interior rectangle 
Surface 
3003 
1006, 1: surface (followed by element information for the polygons) 
Collection 
3004 
Same considerations as for twodimensional 
Multipoint (point cloud) 
3005 
1, n (where n is the number of points) 
Multiline 
3006 
Same considerations as for twodimensional 
Multisurface 
3007 
Element definitions for one or more surfaces 
Solid 
3008 
Simple solid formed by a single closed surface: one element type 1007, followed by one element type 1006 (the external surface) and optionally one or more element type 2006 (internal surfaces) Composite solid formed by multiple adjacent simple solids: one element type 1008 (holding the count of simple solids), followed by any number of element type 1007 (each describing one simple solid) 
Multisolid 
3009 
Element definitions for one or more simple solids (element type 1007) or composite solids (element type 1008) 
The following Spatial operators consider all three dimensions in their computations:
SDO_INSIDE (for solid geometries only)
The other operators consider only the first two dimensions. For some of preceding operators the height information is ignored when dealing with geodetic data, as explained later in this section. (Spatial operators are described in Chapter 19.)
The SDO_GEOM.SDO_VOLUME function applies only to solid geometries, which are by definition threedimensional; however, this function cannot be used with geodetic data. (This function is described in Chapter 24.) For information about support for threedimensional geometries with other SDO_GEOM subprograms, see the usage information after Table 241, "Geometry Subprograms".
For distance computations with threedimensional geometries:
If the data is geodetic (geographic 3D), the distance computations are done on the geodetic surface.
If the data is nongeodetic (projected or local), the distance computations are valid only if the unit of measure is the same for all three dimensions.
To have any functions, procedures, or operators consider all three dimensions, you must specify PARAMETERS ('sdo_indx_dims=3')
in the CREATE INDEX statement when you create the spatial index on a spatial table containing Geographic3D data (longitude, latitude, ellipsoidal height). If you do not specify that parameter in the CREATE INDEX statement, a twodimensional index is created.
For Spatial functions, procedures, and operators that consider all three dimensions, distance and length computations correctly factor in the height or elevation. For example, consider two threedimensional points, one at the origin of a Cartesian space (0,0,0), and the other at X=3 on the Y axis and a height (Z) of 4 (3,0,4).
If the operation considers all three dimensions, the distance between the two points is 5. (Think of the hypotenuse of a 345 right triangle.)
If the operation considers only two dimensions, the distance between the two points is 3. (That is, the third dimension, or height, is ignored.)
However, for the following operators and subprograms, when dealing with geodetic data, the distances with threedimensional geometries are computed between the "ground" representations (for example, the longitude/latitude extent of the footprint of a building), and the height information is ignored:
SDO_NN operator
SDO_WITHIN_DISTANCE operator
SDO_GEOM.SDO_DISTANCE function
SDO_GEOM.WITHIN_DISTANCE function
For a twodimensional query window with threedimensional data, you can use the SDO_FILTER operator, but not any other spatial operators.
For examples of creating different types of threedimensional spatial geometries, see Section 2.7.9. That section also includes an example showing how to update the spatial metadata and create spatial indexes for threedimensional geometries.
For information about support for threedimensional coordinate reference systems, see Section 6.5.
Threedimensional support does not apply to many spatial aggregate functions and PL/SQL packages and subprograms. The following are supported for twodimensional geometries only:
Spatial aggregate functions, except for SDO_AGGR_MBR, which is supported for both twodimensional and threedimensional geometries.
SDO_GEOM (geometry) subprograms, except for the following, which are supported for both twodimensional and threedimensional geometries:
SDO_GEOM.RELATE with the ANYINTERACT mask
SDO_SAM (spatial analysis and mining) subprograms
SDO_MIGRATE.TO_CURRENT procedure
A surface contains an area but not a volume, and it can have two or three dimensions. A surface is often constructed by a set of planar regions.
Surfaces can be modeled as surfacetype SDO_GEOMETRY objects or, if they are very large, as SDO_TIN objects. The surfacetype in SDO_GEOMETRY can be an arbitrary surface defining a contiguous area bounded by adjacent threedimensional polygons. The number of polygons in the SDO_GEOMETRY is limited by the number of ordinates that can be in the SDO_ORDINATES_ARRAY. An SDO_TIN object, on the other hand, models the surface as a network of triangles with no explicit limit on the number of triangles.
Surfaces are stored as a network of triangles, called triangulated irregular networks, or TINs. The TIN model represents a surface as a set of contiguous, nonoverlapping triangles. Within each triangle the surface is represented by a plane. The triangles are made from a set of points called mass points. If mass points are carefully selected, the TIN represents an accurate representation of the model of the surface. Wellplaced mass points occur where there is a major change in the shape of the surface, for example, at the peak of a mountain, the floor of a valley, or at the edge (top and bottom) of cliffs.
TINs are generally computed from a set of threedimensional points specifying coordinate values in the longitude (x), latitude (y), and elevation (z) dimensions. Oracle TIN generation software uses the Delaunay triangulation algorithm, but it is not required that TIN data be formed using only Delaunay triangulation techniques.
The general process for working with a TIN is as follows:
Initialize the TIN, using the SDO_TIN_PKG.INIT function.
Create the TIN, using the SDO_TIN_PKG.CREATE_TIN procedure.
As needed for queries, clip the TIN, using the SDO_TIN_PKG.CLIP_TIN function.
If necessary, use the SDO_TIN_PKG.TO_GEOMETRY function (for example, to convert the result of a clip operation into a single SDO_GEOMETRY object).
The PL/SQL subprograms for working with TINs are described in Chapter 30.
For a Java example of working with TINs, see the following files:
$ORACLE_HOME/md/demo/TIN/examples/java/README.txt $ORACLE_HOME/md/demo/TIN/examples/java/readTIN.java
The simplest types of solids can be represented as cuboids, such as a cube or a brick. A more complex solid is a frustum, which is a pyramid formed by cutting a larger pyramid (with three or more faces) by a plane parallel to the base of that pyramid. Frustums can only be used as query windows to spatial operators. Frustums and cubes are typically modeled as solidtype SDO_GEOMETRY objects. Figure 19 shows a frustum as a query window, with two spatial objects at different distances from the view point.
Point clouds, which are large collections of points, can sometimes be used to model the shape or structure of solid and surface geometries. Most applications that use point cloud data contain one or both of the following kinds of spatial queries: queries based on location, and queries based on both location and visibility (that is, visibility queries).
Most applications that use point cloud data seek to minimize data transfer by retrieving objects based on their distance from a view point. For example, in Figure 19, object B is farther from the view point than object A, and therefore the application might retrieve object A in great detail (high resolution) and object B in less detail (low resolution). In most scenarios, the number of objects increases significantly as the distance from the view point increases; and if farther objects are retrieved at lower resolutions than nearer objects, the number of bytes returned by the query and the rendering time for the objects decrease significantly.
The general process for working with a point cloud is as follows:
Initialize the point cloud, using the SDO_PC_PKG.INIT function.
Create the point cloud, using the SDO_PC_PKG.CREATE_PC procedure.
As needed for queries, clip the point cloud, using the SDO_PC_PKG.CLIP_PC function.
If necessary, use the SDO_PC_PKG.TO_GEOMETRY function (for example, to convert the result of a clip operation into a single SDO_GEOMETRY object).
The PL/SQL subprograms for working with point clouds are described in Chapter 28.
For a Java example of working with point clouds, see the following files:
$ORACLE_HOME/md/demo/PointCloud/examples/java/README.txt $ORACLE_HOME/md/demo/PointCloud/examples/java/readPointCloud.java
Instead of specifying all the vertices for a threedimensional rectangle (a polygon in the shape of rectangle in threedimensional space), you can represent the rectangle by specifying just the two corners corresponding to the minimum ordinate values (mincorner) and the maximum ordinate values (maxcorner) for the X, Y, and Z dimensions.
The orientation of a threedimensional rectangle defined in this way is as follows:
If the rectangle is specified as <mincorner, maxcorner>, the normal points in the positive direction of the perpendicular third dimension.
If the rectangle is specified as <maxcorner, mincorner>, the normal points in the negative direction of the perpendicular third dimension.
For example, if the rectangle is in the XY plane and the order of the vertices is <mincorner, maxcorner>, the normal is along the positive Zaxis; but if the order is <maxcorner, mincorner>, the normal is along the negative Zaxis.
Using these orientation rules for rectangles, you can specify the order of the mincorner and maxcorner vertices for a rectangle appropriately so that the following requirements are met:
The normal for each polygon in a solid always points outward from the solid when the rectangle is part of the solid.
An inner rectangle polygon is oriented in the reverse direction as its outer when the rectangle is part of a surface.
Note: This section describes concepts that you will need to understand for using texture data with Spatial. However, the texture metadata is not yet fully implemented in Oracle Spatial, and a viewer is not yet supported. This section will be updated when texture support is released. 
A texture is an image that represents one or more parts of a feature. Textures are commonly used with visualizer applications (viewers) that display objects stored as spatial geometries. For example, a viewer might display an office building (threedimensional solid) using textures, to allow a more realistic visualization than using just colors. Textures can be used with twodimensional and threedimensional geometries.
In the simplest case, a rectangular geometry can be draped with a texture bitmap. However, often only a subregion of a texture bitmap is used, as in the following example cases:
If the texture bitmap contains multiple sides of the same building, as well as the roof and rood gables. In this case, each bitmap portion is draped over one of the geometry faces.
If the texture bitmap represents a single panel or window on the building surface, and a geometric face represents a wall with 15 such panels or windows (five on each of three floors). In this case, the single texture bitmap is tiled 15 times over the face.
If the face is nonrectangular subfaces, such as roof gables. In this case, only a portion (possible triangular) of the texture bitmap is used.
Figure 110 shows a large rectangular surface that, when viewed, appears to consist of three textures, each of which is repeated multiple times in various places on the surface.
As shown in Figure 110:
The entire image is a large surface that consists of 12 smaller rectangular faces (surface geometries), each of which can be represented by one of three images (labeled A, B, and C).
Three texture bitmaps (labeled A, B, and C) can be used to visualize all of the faces. In this case, bitmap A is used 3 times, bitmap B is used 6 times, and bitmap C is used 3 times.
Figure 111 shows a texture bitmap mapped to a triangular face.
As shown in Figure 111:
The face (surface geometry) is a triangle. (For example, a side or roof of a building may contain several occurrences of this face.)
The texture bitmap (image) is a rectangle, shown in the box in the middle.
A portion of the texture bitmap represents an image of the face. This portion is shown by a dashed line in the box on the right.
In your application, you will need to specify coordinates within the texture bitmap to map the appropriate portion to the face geometry.
To minimize the storage requirements for image data representing surfaces, you should store images for only the distinct textures that will be needed. The data type for storing a texture is SDO_ORDINATE_ARRAY, which is used in the SDO_GEOMETRY type definition (explained in Section 2.2).
For example, assume that the large surface in Figure 110 has the following definition:
SDO_GEOMETRY( 2003,  twodimensional polygon NULL, NULL, SDO_ELEM_INFO_ARRAY(1,1003,1),  one polygon (exterior polygon ring) SDO_ORDINATE_ARRAY(1,1. 1,13, 13,13, 1,13, 1,1) )
Assume that you have a MY_TEXTURE_COORDINATES table with the following definition:
CREATE TABLE my_texture_coordinates ( texture_coord_id NUMBER PRIMARY KEY, texture_name VARCHAR2(32), texture_coordinates SDO_ORDINATE_ARRAY);
Example 11 inserts three texture coordinate definitions into this table. For each texture, its coordinates reflect one of the appropriate smaller rectangles shown in Figure 110; however, you can choose any one of the appropriate rectangles for each texture. In Example 11, the SDO_ORDINATE_ARRAY definitions for each texture reflect a polygon near the top of Figure 110.
Example 11 Inserting Texture Coordinate Definitions
INSERT INTO my_texture_coordinates VALUES( 1, 'Texture_A', SDO_ORDINATE_ARRAY(1,9, 1,5, 5,12, 1,12, 1,9) ); INSERT INTO my_texture_coordinates VALUES( 2, 'Texture_B', SDO_ORDINATE_ARRAY(5,9, 9,9, 9,12, 5,12, 5,9) ); INSERT INTO my_texture_coordinates VALUES( 3, 'Texture_C', SDO_ORDINATE_ARRAY(1,12, 13,12, 13,13, 1,13, 1,12) );
Texture bitmaps (stored as BLOBs or as URLs in VARCHAR2 format) and texture coordinate arrays (stored using type SDO_ORDINATE_ARRAY) can be stored in the same table as the SDO_GEOMETRY column or in separate tables; however, especially for the texture bitmaps, it is usually better to use separate tables. Texture bitmaps are likely to be able to be shared among features (such as different office buildings), but texture coordinate definitions are less likely to be shareable among features. (For example, many office buildings may share the same general type of glass exterior, but few of the buildings have the same number of windows and floors. In designing your textures and applications, you must consider how many buildings use the same texture subregion or drape the texture in the same size of repetitive matrix.)
An exception is a texture coordinate array that drapes an entire texture bitmap over a rectangular geometric face. In this case, the texture coordinate array can be specified as (0,0, 1,0, 1,1, 0,1, 1,1), defined by vertices "lower left", "lower right", "upper right", "upper left", and closing with "lower left". Many data sets use this texture coordinate array extensively, because they have primarily rectangular faces and they store one facade for each texture bitmap.
If you used separate tables, you could link them to the surface geometries using foreign keys, as in Example 12.
Example 12 Creating Tables for Texture Coordinates, Textures, and Surfaces
 One row for each texture coordinates definition. CREATE TABLE my_texture_coordinates ( texture_coord_id NUMBER PRIMARY KEY, texture_coordinates SDO_ORDINATE_ARRAY);  One row for each texture. CREATE TABLE my_textures( texture_id NUMBER PRIMARY KEY, texture BLOB);  One row for each surface (each individual "piece" of a  potentially larger surface). CREATE TABLE my_surfaces( surface_id NUMBER PRIMARY KEY, surface_geometry SDO_GEOMETRY, texture_id NUMBER, texture_coord_id NUMBER, CONSTRAINT texture_id_fk FOREIGN KEY (texture_id) REFERENCES my_textures(texture_id), CONSTRAINT texture_coord_id_fk FOREIGN KEY (texture_coord_id) REFERENCES my_texture_coordinates(texture_coord_id));
The SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT and SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT subprograms can validate twodimensional and threedimensional geometries. For a threedimensional geometry, these subprograms perform any necessary checks on any twodimensional geometries (see the Usage Notes for SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT) within the overall threedimensional geometry, but also several checks specific to the threedimensional nature of the overall object.
For a simple solid (one outer surface and any number of inner surfaces), these subprograms perform the following checks:
Closedness: The solid must be closed.
Reachability: Each face of a solid must have a fulledge intersection with its neighboring faces, and all faces must be reachable from any face.
Innerouter disjointedness: An inner surface must not intersect the outer surface at more than a point or a line; that is, there must be no overlapping areas with inner surfaces.
No surface patch: No additional surfaces can be defined on the surfaces that make up the solid.
Orientation: For all surfaces, the vertices must be aligned so that the normal vector (or surface normal, or "the normal") points to the outside of (away from) the outer solid. Thus, the volume of the outer solid must be greater than zero, and the volume of any inner solid must be less than zero.
For a composite solid (one or more solids connected to each other), these subprograms perform the following checks:
Connectedness: All solids of a composite solid must share at least one face.
Zerovolume intersections: Any intersections of the solids in a composite solid must have a volume of zero.
For a multisolid (one or more solids, each of which is a simple or composite solid), these subprograms perform the following check:
Disjointedness: Any two solids of a multisolid can share points or lines, but must not intersect in any other manner.
Geocoding is the process of converting tables of address data into standardized address, location, and possibly other data. The result of a geocoding operation includes the pair of longitude and latitude coordinates that correspond with the input address or location. For example, if the input address is 22 Monument Square, Concord, MA 01742, the longitude and latitude coordinates in the result of the geocoding operation may be (depending on the geocoding data provider) 71.34937 and 42.46101, respectively.
Given a geocoded address, you can perform proximity or location queries using a spatial engine, such as Oracle Spatial, or demographic analysis using tools and data from Oracle's business partners. In addition, you can use geocoded data with other spatial data such as block group, postal code, and county code for association with demographic information. Results of analyses or queries can be presented as maps, in addition to tabular formats, using thirdparty software integrated with Oracle Spatial.
For conceptual and usage information about the geocoding capabilities of Oracle Spatial, see Chapter 11. For reference information about the MDSYS.SDO_GCDR PL/SQL package, see Chapter 23.
Oracle Spatial provides a Java application programming interface (API) that includes the following packages:
oracle.spatial.geometry
provides support for the Spatial SQL SDO_GEOMETRY data type, which is documented in this guide.
oracle.spatial.georaster
provides support for the core GeoRaster features, which are documented in Oracle Spatial GeoRaster Developer's Guide.
oracle.spatial.georaster.image
provides support for generating Java images from a GeoRaster object or subset of a GeoRaster object, and for processing the images. These features are documented in Oracle Spatial GeoRaster Developer's Guide.
oracle.spatial.georaster.sql
provides support for wrapping the GeoRaster PL/SQL API, which is documented in Oracle Spatial GeoRaster Developer's Guide.
oracle.spatial.network
provides support for the Oracle Spatial network data model, which is documented in Oracle Spatial Topology and Network Data Models Developer's Guide.
oracle.spatial.network.lod
provides support for the loadondemand (LOD) approach of network analysis in the Oracle Spatial network data model, which is documented in Oracle Spatial Topology and Network Data Models Developer's Guide.
oracle.spatial.network.lod.config
provides support for the configuration of loadondemand (LOD) network analysis in the Oracle Spatial network data model, which is documented in Oracle Spatial Topology and Network Data Models Developer's Guide.
oracle.spatial.topo
provides support for the Oracle Spatial topology data model, which is documented in Oracle Spatial Topology and Network Data Models Developer's Guide.
oracle.spatial.util
provides classes that perform miscellaneous operations.
For detailed reference information about the classes and interfaces in these packages, see Oracle Spatial Java API Reference (Javadoc).
The Spatial Java class libraries are in .jar
files under the <ORACLE_HOME>/md/jlib/
directory.
During installation, Spatial creates user accounts that have the minimum privileges needed to perform their jobs. These accounts are created locked and expired; so if you need to use the accounts, you must unlock them. Table 12 lists the predefined user accounts created by Spatial.
Table 12 Predefined User Accounts Created by Spatial
User Account  Description 

MDDATA 
The schema used by Oracle Spatial for storing data used by geocoding and routing applications. This is the default schema for Oracle software that accesses geocoding and routing data. 
SPATIAL_CSW_ADMIN_USR 
The Catalog Services for the Web (CSW) account. It is used by the Oracle Spatial CSW cache manager to load all record type metadata and all record instances from the database into main memory for the record types that are cached. 
SPATIAL_WFS_ADMIN_USR 
The Web Feature Service (WFS) account. It is used by the Oracle Spatial WFS cache manager to load all feature type metadata and all feature instances from the database into main memory for the feature types that are cached. 
For information about Oracle Database predefined user accounts, including how to secure these accounts, see Oracle Database 2 Day + Security Guide.
Many factors can affect the performance of Oracle Spatial applications, such as the use of optimizer hints to influence the plan for query execution. This guide contains some information about performance and tuning where it is relevant to a particular topic. For example, Section 1.7.2 discusses Rtree quality and its possible effect on query performance, and Section 1.9 explains why spatial operators provide better performance than procedures and functions.
In addition, more Spatial performance and tuning information is available in one or more white papers through the Oracle Technology Network (OTN). That information is often more detailed than what is in this guide, and it is periodically updated as a result of internal testing and consultations with Spatial users. To find that information on the OTN, go to
http://www.oracle.com/technetwork/database/options/spatialandgraph/
Look for material relevant to Spatial performance and tuning.
Oracle Spatial is conformant with Open Geospatial Consortium (OGC) Simple Features Specification 1.1.1 (Document 99049), starting with Oracle Database release 10g (version 10.1.0.4). Conformance with the Geometry Types Implementation means that Oracle Spatial supports all the types, functions, and language constructs detailed in Section 3.2 of the specification.
Synonyms are created to match all OGC function names except for X(p Point)
and Y(p Point)
. For these functions, you must use the names OGC_X
and OGC_Y
instead of just X
and Y
.
Oracle Spatial is conformant with the following International Organization for Standardization (ISO) standards:
ISO 132493 SQL Multimedia and Application Packages  Part 3: Spatial
ISO 19101: Geographic information  Reference model (definition of terms and approach)
ISO 19109: Geographic information  Rules for application schema (called the General Feature Model)
ISO 19111: Geographic information  Spatial referencing by coordinates (also OGC Abstract specification for coordinate reference systems)
ISO 19118: Geographic information  Encoding (GML 2.1 and GML 3.1.1)
ISO 19107: Geographic information  Spatial schema (also OGC Abstract specification for Geometry)
However, standards compliance testing for Oracle Spatial and Graph is ongoing, and compliance with more recent versions of standards or with new standards might be announced at any time. For current information about compliance with standards, see http://www.oracle.com/technetwork/database/options/spatialandgraph/documentation/
.
To check which release of Spatial you are running, use the SDO_VERSION function. For example:
SELECT SDO_VERSION FROM DUAL; SDO_VERSION  11.2.0.2.0
If you have a regular Oracle table without an SDO_GEOMETRY column, but containing locationrelated information (such as latitude/longitude values for points), you can spatially enable the table by adding an SDO_GEOMETRY column and using existing (and future) locationrelated information in records to populate the SDO_GEOMETRY column values.
The following are the basic steps for spatially enabling a regular table. They assume that the regular table has columns that contain locationrelated values associated with each record in the table.
Alter the table to add a geometry (SDO_GEOMETRY) column.
Update the table to populate the SDO_GEOMETRY objects using existing locationrelated data values.
Update the spatial metadata (USER_SDO_GEOM_METADATA).
Create the spatial index on the table.
Example 13 creates a table (CITY_POINTS) that initially does not contain an SDO_GEOMETRY column but does contain latitude and longitude values for each record (a point in or near a specified city). It spatially enables the table, updating the existing records to include the SDO_GEOMETRY information, and it also inserts new records and updates those.
Example 13 Spatially Enabling a Table
 Original table without a spatial geometry column. CREATE TABLE city_points ( city_id NUMBER PRIMARY KEY, city_name VARCHAR2(25), latitude NUMBER, longitude NUMBER);  Original data for the table.  (The sample coordinates are for a random point in or near the city.) INSERT INTO city_points (city_id, city_name, latitude, longitude) VALUES (1, 'Boston', 42.207905, 71.015625); INSERT INTO city_points (city_id, city_name, latitude, longitude) VALUES (2, 'Raleigh', 35.634679, 78.618164); INSERT INTO city_points (city_id, city_name, latitude, longitude) VALUES%6 (3, 'San Francisco', 37.661791, 122.453613); INSERT INTO city_points (city_id, city_name, latitude, longitude) VALUES (4, 'Memphis', 35.097140, 90.065918);  Add a spatial geometry column. ALTER TABLE city_points ADD (shape SDO_GEOMETRY);  Update the table to populate geometry objects using existing  latutide and longitude coordinates. UPDATE city_points SET shape = SDO_GEOMETRY( 2001, 8307, SDO_POINT_TYPE(LONGITUDE, LATITUDE, NULL), NULL, NULL );  Update the spatial metadata. INSERT INTO user_sdo_geom_metadata VALUES ( 'city_points', 'SHAPE', SDO_DIM_ARRAY( SDO_DIM_ELEMENT('Longitude',180,180,0.5), SDO_DIM_ELEMENT('Latitude',90,90,0.5) ), 8307 );  Create the spatial index. CREATE INDEX city_points_spatial_idx on city_points(SHAPE) INDEXTYPE IS MDSYS.SPATIAL_INDEX;  Later, add new records to the table, using original INSERT format  (latitude and longitude, no spatial geometry object data).  Then update to include spatial geometry object information.  Tip: For efficiency, keep track of existing and new records, and use  a WHERE clause to restrict the UPDATE to new records (not shown here). INSERT INTO city_points (city_id, city_name, latitude, longitude) VALUES (5, 'Chicago', 41.848832, 87.648926); INSERT INTO city_points (city_id, city_name, latitude, longitude) VALUES (6, 'Miami', 25.755043, 80.200195); UPDATE city_points SET shape = SDO_GEOMETRY( 2001, 8307, SDO_POINT_TYPE(LONGITUDE, LATITUDE, NULL), NULL, NULL );
Notes on Example 13:
It does not matter that the original table has the LATITUDE and LONGITUDE values in that order, as long as the column names are specified in the correct order in the geometry constructor (SDO_POINT in this case) in the UPDATE statement. (SDO_GEOMETRY objects have longitude first, then latitude for points.)
Geometry validation is not included in the example because validation is not relevant for points. However, if you spatially enable a table with other types of geometries, you should validate all initial and added geometries. (To perform validation, use SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT or SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT.)
Database administrators (DBAs) can use the MDSYS.MOVE_SDO procedure to move all Oracle Spatial metadata tables to a specified target tablespace. By default, the Spatial metadata tables are created in the SYSAUX
tablespace in Release 11.1 and later releases, and in the SYSTEM
tablespace in releases before 11.1.
The MDSYS.MOVE_SDO procedure has the following syntax:
MDSYS.MOVE_SDO( target_tablespace_name IN VARCHAR2);
The required target_tablespace_name
parameter specifies the name of the tablespace to which to move the Spatial metadata tables.
This procedure should be used only by DBAs.
During the move operation, all other Oracle Spatial capabilities are disabled.
The following example moves the Spatial metadata tables to the SYSAUX
tablespace.
EXECUTE MDSYS.MOVE_SDO('SYSAUX');
This section discusses some general guidelines that affect the amount of disk storage space and CPU power needed for applications that use Oracle Spatial. These guidelines are intended to supplement, not replace, any other guidelines you use for general application sizing.
The following characteristics of spatial applications can affect the need for storage space and CPU power:
Data volumes: The amount of storage space needed for spatial objects depends on their complexity (precision of representation and number of points for each object). For example, storing one million point objects takes less space than storing one million road segments or land parcels. Complex natural features such as coastlines, seismic fault lines, rivers, and land types can require significant storage space if they are stored at a high precision.
Query complexity: The CPU requirements for simple mapping queries, such as Select all features in this rectangle, are lower than for more complex queries, such as Find all seismic fault lines that cross this coastline.
Spatial error messages are documented in Oracle Database Error Messages.
Oracle error message documentation is only available in HTML. If you only have access to the Oracle Documentation DVD, you can browse the error messages by range. Once you find the specific range, use your browser's "find in page" feature to locate the specific message. When connected to the Internet, you can search for a specific error message using the error message search feature of the Oracle online documentation.
Oracle Spatial provides examples that you can use to reinforce your learning and to create models for coding certain operations. If you installed the demo files from the Oracle Database Examples media (see Oracle Database Examples Installation Guide), several examples are provided in the following directory:
$ORACLE_HOME/md/demo/examples
The following files in that directory are helpful for applications that use the Oracle Call Interface (OCI):
readgeom.c
and readgeom.h
writegeom.c
and writegeom.h
This guide also includes many examples in SQL and PL/SQL. One or more examples are usually provided with the reference information for each function or procedure, and several simplified examples are provided that illustrate table and index creation, combinations of functions and procedures, and advanced features:
Inserting, indexing, and querying spatial data (Section 2.1)
Coordinate systems (spatial reference systems) (Section 6.13)
Linear referencing system (LRS) (Section 7.7)
SDO_GEOMETRY objects in functionbased indexes (Section 9.2)
Complex queries (Appendix C)
A README.txt
file supplements the information in the following manuals: Oracle Spatial Developer's Guide (this manual), Oracle Spatial GeoRaster Developer's Guide, and Oracle Spatial Topology and Network Data Models Developer's Guide. This file is located at:
$ORACLE_HOME/md/doc/README.txt
This chapter contains descriptions of the spatial utility subprograms shown in Table 321.
Table 321 Spatial Utility Subprograms
Subprogram  Description 


Returns a geometry that reflects an affine transformation of the input geometry. 

Appends one geometry to another geometry to create a new geometry. 
SDO_UTIL.BEARING_TILT_FOR_POINTS 
Computes the bearing and tilt from a start point to an end point. 

Returns the polygon geometry that approximates and is covered by a specified circle. 

Concatenates two line or multiline twodimensional geometries to create a new geometry. 

Converts values from one angle, area, or distance unit of measure to another. 

Returns the polygon geometry that approximates and is covered by a specified ellipse. 

Returns the twodimensional geometry that represents a specified element (and optionally a ring) of the input twodimensional geometry. 

Returns all elements and subelements of the input twodimensional geometry, as an array of one or more geometries. 

Returns the threedimensional geometry that represents a specified subset of the input threedimensional geometry. 

Returns the threedimensional extrusion solid geometry from an input twodimensional polygon geometry. 

Converts a geography markup language (GML 3.1.1) fragment to a Spatial geometry object. 

Converts a geography markup language (GML 2.0) fragment to a Spatial geometry object. 

Converts a KML (Keyhole Markup Language) document to a Spatial geometry object. 

Converts a geometry in the wellknown binary (WKB) format to a Spatial geometry object. 

Converts a geometry in the wellknown text (WKT) format to a Spatial geometry object. 

Returns the number of elements in the input geometry. 

Returns the number of vertices in the input geometry. 

Returns the coordinates of the vertices of the input geometry. 
SDO_UTIL.INITIALIZE_INDEXES_FOR_TTS 
Initializes all spatial indexes in a tablespace that was transported to another database. 

Returns a point that is guaranteed to be an interior point (not on the boundary or edge) on the surface of a polygon geometry object. 

Returns a point geometry that is at the specified distance and bearing from the start point. 

Converts all polygontype elements in a geometry to linetype elements, and sets the SDO_GTYPE value accordingly. 

Prepares a tablespace to be transported to another database, so that spatial indexes will be preserved during the transport operation. 

Fixes certain problems with the input geometry, and returns a valid geometry. 
SDO_UTIL.REMOVE_DUPLICATE_VERTICES 
Removes duplicate (redundant) vertices from a geometry. 

Returns a line string geometry with the vertices of the input geometry in reverse order. 

Simplifies the input geometry, based on a threshold value, using the DouglasPeucker algorithm. 

Converts a Spatial geometry object to a geography markup language (GML 3.1.1) fragment based on the geometry types defined in the Open GIS 

Converts a Spatial geometry object to a geography markup language (GML 2.0) fragment based on the geometry types defined in the Open GIS 

Converts a Spatial geometry object to a KML (Keyhole Markup Language) document. 

Converts a Spatial geometry object to the wellknown binary (WKB) format. 

Converts a Spatial geometry object to the wellknown text (WKT) format. 

Validates the input geometry, which is in the standard wellknown binary (WKB) format; returns the string 

Validates the input geometry, which is of type CLOB or VARCHAR2 and in the standard wellknown text (WKT) format; returns the string 
Format
SDO_UTIL.AFFINETRANSFORMS(
geometry IN SDO_GEOMETRY,
translation IN VARCHAR2,
tx IN NUMBER,
ty IN NUMBER,
tz IN NUMBER,
scaling IN VARCHAR2,
psc1 IN SDO_GEOMETRY
sx IN NUMBER,
sy IN NUMBER,
sz IN NUMBER,
rotation IN VARCHAR2,
p1 IN SDO_GEOMETRY,
line1 IN SDO_GEOMETRY,
angle IN NUMBER,
dir IN NUMBER,
shearing IN VARCHAR2
shxy IN NUMBER,
shyx IN NUMBER,
shxz IN NUMBER,
shzx IN NUMBER,
shyz IN NUMBER,
shzy IN NUMBER,
reflection IN VARCHAR2
pref IN SDO_GEOMETRY,
lineR IN SDO_GEOMETRY,
dirR IN NUMBER,
planeR IN VARCHAR2,
n IN SDO_NUMBER_ARRAY,
bigD IN SDO_NUMBER_ARRAY,
) RETURN SDO_GEOMETRY;
Parameters
Input geometry on which to perform the affine transformation.
A string value of TRUE causes translation to be performed; a string value of FALSE causes translation not to be performed. If this parameter is TRUE, translation is performed about the point at (tx,ty) or (tx,ty,tz).
Xaxis value for translation.
Yaxis value for translation.
Zaxis value for translation.
A string value of TRUE causes scaling to be performed; a string value of FALSE causes scaling not to be performed.
Point on the input geometry about which to perform the scaling. If scaling
is TRUE
, this geometry should be either a zero point (point geometry with 0,0 or 0,0,0 ordinates for scaling about the origin) or a nonzero point (point geometry with ordinates for scaling about a point other than the origin). If scaling
is FALSE
, psc1
can be a null value.
Xaxis value for scaling (about either the point specified in the psc1
parameter or the origin).
Yaxis value for scaling (about either the point specified in the psc1
parameter or the origin).
Zaxis value for scaling (about either the point specified in the psc1
parameter or the origin).
A string value of TRUE causes rotation to be performed; a string value of FALSE causes rotation not to be performed.
For twodimensional geometries, rotation uses the p1
and angle
values. For threedimensional geometries, rotation uses either the angle
and dir
values or the line1
and angle
values.
Point for twodimensional geometry rotation about a specified point.
Line for rotation about a specified axis.
Angle rotation parameter (in radians) for rotation about a specified axis or about the X, Y, or Z axis.
Rotation parameter for x(0), y(1), or z(2)axis roll. If the rotation
parameter value is TRUE
but the dir
parameter is not used, specify a value of 1.
A string value of TRUE causes shearing to be performed; a string value of FALSE causes shearing not to be performed.
For twodimensional geometries, shearing uses the shxy
and shyx
parameter values. For threedimensional geometries, shearing uses the shxy
, shyx
, shxz
, shzx
, shyz
, and shzy
parameter values.
Value for shearing due to X along the Y direction.
Value for shearing due to Y along the X direction.
Value for shearing due to X along the Z direction (threedimensional geometries only).
Value for shearing due to Z along the X direction (threedimensional geometries only).
Value for shearing due to Y along the Z direction (threedimensional geometries only).
Value for shearing due to Z along the Y direction (threedimensional geometries only).
A string value of TRUE causes reflection to be performed; a string value of FALSE causes reflection not to be performed.
For twodimensional geometries, reflection uses the lineR
value for reflection about an axis and the pref
value for the centroid for selfreflection. For threedimensional geometries, reflection uses the lineR
value for reflection about an axis; the dirR
value for reflection about the yz, xz, and xy planes; the planeR
, n
, and bigD
values for reflection about a specified plane; and the pref
value for the centroid for selfreflection.
Point through which to perform reflection.
Line along which to perform reflection.
Number indicating the plane about (through) which to perform reflection: 0 for the yz plane, 1 for the xz plane, or 2 for the xy plane. If the reflection
parameter value is TRUE
but the dirR
parameter is not used, specify a value of 1.
A string value of TRUE causes reflection about an arbitrary plane to be performed; a string value of FALSE causes reflection about an arbitrary plane not to be performed.
Normal vector of the plane.
Delta value for the plane equation in threedimensional geometries.
For threedimensional geometries, bigD = delta and n = (A,B,C) where n is the normal of the plane in threedimensional space. Thus, the plane equation is:
Ax+By+Cz+bigD = 3DDotProd(n,anypointonplane)+bigD = 0
Usage Notes
The order of affine transforms matter because these are matrix and vector multiplications.
You should validate the resulting geometry using the SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT function.
Examples
The following example performs an affine transformation on a twodimensional geometry.
 Polygon reflection in 2D about a specified line segment SELECT SDO_UTIL.AFFINETRANSFORMS( geometry => MDSYS.SDO_GEOMETRY(2003, NULL, NULL, MDSYS.SDO_ELEM_INFO_ARRAY(1,1003,1), MDSYS.SDO_ORDINATE_ARRAY( 1.5,0, 2.5,1, 1.5,2, 0.5,2, 0.5,0, 1.5,0)), translation => 'FALSE', tx => 0.0, ty => 0.0, tz => 0.0, scaling => 'FALSE', psc1 => NULL, sx => 0.0, sy => 0.0, sz => 0.0, rotation => 'FALSE', p1 => NULL, line1 => NULL, angle => 0.0, dir => 0, shearing => 'FALSE', shxy => 0.0, shyx => 0.0, shxz => 0.0, shzx => 0.0, shyz => 0.0, shzy => 0.0, reflection => 'TRUE', pref => NULL, lineR => MDSYS.SDO_GEOMETRY(2002,0,NULL, MDSYS.SDO_ELEM_INFO_ARRAY(1,2,1), MDSYS.SDO_ORDINATE_ARRAY(2.5,0.0,2.5,2.0)), dirR => 1, planeR => 'FALSE', n => NULL, bigD => NULL ) FROM DUAL; SDO_UTIL.AFFINETRANSFORMS(GEOMETRY=>MDSYS.SDO_GEOMETRY(2003,NULL,NULL,MDSYS.SDO_  SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR AY(3.5, 0, 2.5, 1, 3.5, 2, 4.5, 2, 4.5, 0, 3.5, 0))
The following example performs an affine transformation on a threedimensional geometry.
 Polygon reflection in 3D about a specified plane (z=1 plane in this example) SELECT SDO_UTIL.AFFINETRANSFORMS( geometry => MDSYS.SDO_GEOMETRY(3003, 0, NULL, MDSYS.SDO_ELEM_INFO_ARRAY(1,1003,1), MDSYS.SDO_ORDINATE_ARRAY( 1.5,0,0, 2.5,1,0, 1.5,2,0, 0.5,2,0, 0.5,0,0, 1.5,0,0)), translation => 'FALSE', tx => 0.0, ty => 0.0, tz => 0.0, scaling => 'FALSE', psc1 => NULL, sx => 0.0, sy => 0.0, sz => 0.0, rotation => 'FALSE', p1 => NULL, line1 => NULL, angle => 0.0, dir => 0, shearing => 'FALSE', shxy => 0.0, shyx => 0.0, shxz => 0.0, shzx => 0.0, shyz => 0.0, shzy => 0.0, reflection => 'TRUE', pref => NULL, lineR => NULL, dirR => 1, planeR => 'TRUE', n => SDO_NUMBER_ARRAY(0.0, 0.0, 1.0), bigD => SDO_NUMBER_ARRAY(1.0) ) FROM DUAL; SDO_UTIL.AFFINETRANSFORMS(GEOMETRY=>MDSYS.SDO_GEOMETRY(3003,0,NULL,MDSYS.SDO_ELE  SDO_GEOMETRY(3003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR AY(1.5, 0, 2, 2.5, 1, 2, 1.5, 2, 2, .5, 2, 2, .5, 0, 2, 1.5, 0, 2))
Parameters
Geometry object to which geometry2
is to be appended.
Geometry object to append to geometry1
.
Usage Notes
This function should be used only on geometries that do not have any spatial interaction (that is, on disjoint objects). If the input geometries are not disjoint, the resulting geometry might be invalid.
This function does not perform a union operation or any other computational geometry operation. To perform a union operation, use the SDO_GEOM.SDO_UNION function, which is described in Chapter 24. The APPEND function executes faster than the SDO_GEOM.SDO_UNION function.
The geometry type (SDO_GTYPE value) of the resulting geometry reflects the types of the input geometries and the append operation. For example, if the input geometries are twodimensional polygons (SDO_GTYPE = 2003), the resulting geometry is a twodimensional multipolygon (SDO_GTYPE = 2007).
An exception is raised if geometry1
and geometry2
are based on different coordinate systems.
Examples
The following example appends the cola_a
and cola_c
geometries. (The example uses the definitions and data from Section 2.1.)
SELECT SDO_UTIL.APPEND(c_a.shape, c_c.shape) FROM cola_markets c_a, cola_markets c_c WHERE c_a.name = 'cola_a' AND c_c.name = 'cola_c'; SDO_UTIL.APPEND(C_A.SHAPE,C_C.SHAPE)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SD  SDO_GEOMETRY(2007, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 3, 5, 1003, 1), SDO_ ORDINATE_ARRAY(1, 1, 5, 7, 3, 3, 6, 3, 6, 5, 4, 5, 3, 3))
Format
SDO_UTIL.BEARING_TILT_FOR_POINTS(
start_point IN SDO_GEOMETRY,
end_point IN SDO_GEOMETRY,
tol IN NUMBER,
bearing OUT NUMBER,
tilt OUT NUMBER
) RETURN SDO_GEOMETRY;
Parameters
Starting point geometry object from which to compute the bearing and tilt. The point geometry must be based on a geodetic coordinate system.
Ending point geometry object to use in computing the bearing and tilt. The point geometry must be based on the same geodetic coordinate system as start_point
.
Tolerance value (see Section 1.5.5).
Number of radians, measured clockwise from North.
Number of radians, measured from the normal.
Usage Notes
The input point geometries must be based on the same geodetic coordinate system. If they are based on a nongeodetic coordinate system, the output bearing is a null value.
The tilt is computed as the arctangent of the difference between the height values divided by the distance between the points (with height excluded from the distance calculation). That is: tilt = atan(height_difference/distance)
To convert radians to decimal degrees or decimal degrees to radians, you can use the SDO_UTIL.CONVERT_UNIT function. To return a point geometry that is at a specified distance and bearing from a start point, you can use the SDO_UTIL.POINT_AT_BEARING function.
Examples
The following example computes the bearing and tilt for two longitude/latitude points, where the elevation of the start point is 0 (zero) and the elevation of the end point is 5000 meters. This example displays the bearing and tilt values in radians.
DECLARE bearing NUMBER; tilt NUMBER; BEGIN SDO_UTIL.BEARING_TILT_FOR_POINTS( SDO_GEOMETRY(2001, 8307, SDO_POINT_TYPE(71.5, 43, 0), NULL, NULL),  start_point SDO_GEOMETRY(2001, 8307, SDO_POINT_TYPE(71, 43.5, 5000), NULL, NULL),  end_point 0.05, tolerance bearing, tilt); DBMS_OUTPUT.PUT_LINE('Bearing = '  bearing); DBMS_OUTPUT.PUT_LINE('Tilt = '  tilt); END; / Bearing = .628239101930666 Tilt = .0725397288678286910476298724869396973718
The following example is the same as the preceding one, except that it displays the bearing and tilt in decimal degrees instead of radians.
DECLARE bearing NUMBER; tilt NUMBER; BEGIN SDO_UTIL.BEARING_TILT_FOR_POINTS( SDO_GEOMETRY(2001, 8307, SDO_POINT_TYPE(71.5, 43, 0), NULL, NULL),  start_point SDO_GEOMETRY(2001, 8307, SDO_POINT_TYPE(71, 43.5, 5000), NULL, NULL),  end_point 0.05, tolerance bearing, tilt); DBMS_OUTPUT.PUT_LINE('Bearing in degrees = '  bearing * 180 / 3.1415926535897932384626433832795); DBMS_OUTPUT.PUT_LINE('Tilt in degrees = '  tilt * 180 / 3.1415926535897932384626433832795); END; / Bearing in degrees = 35.99544906571628894295547577999851892359 Tilt in degrees = 4.15622031114988533540349823511872120415
Format
SDO_UTIL.CIRCLE_POLYGON(
center_longitude IN NUMBER,
center_latitude IN NUMBER,
radius IN NUMBER,
arc_tolerance IN NUMBER
) RETURN SDO_GEOMETRY;
Parameters
Center longitude (in degrees) of the circle to be used to create the returned geometry.
Center latitude (in degrees) of the circle to be used to create the returned geometry.
Length (in meters) of the radius of the circle to be used to create the returned geometry.
A numeric value to be used to construct the polygon geometry. The arc_tolerance
parameter value has the same meaning and usage guidelines as the arc_tolerance
keyword value in the params
parameter string for the SDO_GEOM.SDO_ARC_DENSIFY function. The unit of measurement associated with the geometry is associated with the arc_tolerance
parameter value. (For more information, see the Usage Notes for the SDO_GEOM.SDO_ARC_DENSIFY function in Chapter 24.)
Usage Notes
This function is useful for creating a circlelike polygon around a specified center point when a true circle cannot be used (a circle is not valid for geodetic data with Oracle Spatial). The returned geometry has an SDO_SRID value of 8307 (for Longitude / Latitude (WGS 84)
).
Examples
The following example returns a circlelike polygon around a point near the center of Concord, Massachusetts. A radius
value of 100 meters and an arc_tolerance
value of 5 meters are used in computing the polygon vertices.
SELECT SDO_UTIL.CIRCLE_POLYGON(71.34937, 42.46101, 100, 5) FROM DUAL; SDO_UTIL.CIRCLE_POLYGON(71.34937,42.46101,100,5)(SDO_GTYPE, SDO_SRID, SDO_POINT  SDO_GEOMETRY(2003, 8307, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR AY(71.34937, 42.4601107, 71.348653, 42.4602824, 71.348211, 42.4607321, 71.34 8211, 42.4612879, 71.348653, 42.4617376, 71.34937, 42.4619093, 71.350087, 42. 4617376, 71.350529, 42.4612879, 71.350529, 42.4607321, 71.350087, 42.4602824, 71.34937, 42.4601107))
Format
SDO_UTIL.CONCAT_LINES(
geometry1 IN SDO_GEOMETRY,
geometry2 IN SDO_GEOMETRY
) RETURN SDO_GEOMETRY;
Parameters
First geometry object for the concatenation operation.
Second geometry object for the concatenation operation.
Usage Notes
Each input geometry must be a twodimensional line or multiline geometry (that is, the SDO_GTYPE value must be 2002 or 2006). This function is not supported for LRS geometries. To concatenate LRS geometric segments, use the SDO_LRS.CONCATENATE_GEOM_SEGMENTS function (described in Chapter 25).
The input geometries must be line strings whose vertices are connected by straight line segments. Circular arcs and compound line strings are not supported.
If an input geometry is a multiline geometry, the elements of the geometry must be disjoint. If they are not disjoint, this function may return incorrect results.
The topological relationship between geometry1
and geometry2
must be DISJOINT or TOUCH; and if the relationship is TOUCH, the geometries must intersect only at two end points.
You can use the SDO_AGGR_CONCAT_LINES spatial aggregate function (described in Chapter 20) to concatenate multiple twodimensional line or multiline geometries.
An exception is raised if geometry1
and geometry2
are based on different coordinate systems.
Examples
The following example concatenates two simple line string geometries.
 Concatenate two touching lines: one from (1,1) to (5,1) and the  other from (5,1) to (8,1). SELECT SDO_UTIL.CONCAT_LINES( SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1,2,1), SDO_ORDINATE_ARRAY(1,1, 5,1)), SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1,2,1), SDO_ORDINATE_ARRAY(5,1, 8,1)) ) FROM DUAL; SDO_UTIL.CONCAT_LINES(SDO_GEOMETRY(2002,NULL,NULL,SDO_ELEM_INFO_ARRAY(1,2,1),SDO  SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 1, 1, 5, 1, 8, 1))
Format
SDO_UTIL.CONVERT_UNIT(
ivalue IN NUMBER,
in_unit IN VARCHAR2,
out_unit IN VARCHAR2
) RETURN NUMBER;
Parameters
Number of units to be converted. For example, to convert 10 decimal degrees to radians, specify 10
.
The unit of measure from which to convert the input value. Must be a value from the SDO_UNIT column of the MDSYS.SDO_ANGLE_UNITS table (described in Section 6.8.2), the MDSYS.SDO_AREA_UNITS table (described in Section 2.10), or the MDSYS.SDO_DIST_UNITS table (described in Section 2.10). For example, to convert decimal degrees to radians, specify Degree
.
The unit of measure into which to convert the input value. Must be a value from the SDO_UNIT column of the same table used for in_unit
. For example, to convert decimal degrees to radians, specify Radian
.
Usage Notes
The value returned by this function might not be correct at an extremely high degree of precision because of the way internal mathematical operations are performed, especially if they involve small numbers or irrational numbers (such as pi). For example, converting 1 decimal degree into decimal minutes results in the value 60.0000017.
Description
Drops any transient ("scratch") tables and views in the current schema that were created during the creation of a point cloud or TIN.
Parameters
Object ID string representing a hexadecimal number. Use the string given in the error message that indicated that scratch tables need to be dropped.
Usage Notes
If scratch tables still exist from a previous SDO_PC_PKG.CREATE_PC or SDO_TIN_PKG.CREATE_TIN operation when you try to create a point cloud or TIN, an error message is displayed indicating that you must first drop the scratch tables. Use the SDO_UTIL.DROP_WORK_TABLES procedure to drop these scratch tables.
This procedure drops all tables and views that match 'M%_<oidstr>$$%'
.
Examples
The following example drops the scratch tables from a previous SDO_PC_PKG.CREATE_PC or SDO_TIN_PKG.CREATE_TIN operation, using an OID string specified in a previous error message.
EXECXUTE SDO_UTIL.DROP_WORK_TABLES('A1B2C3');
Format
SDO_UTIL.ELLIPSE_POLYGON(
center_longitude IN NUMBER,
center_latitude IN NUMBER,
semi_major_axis IN NUMBER,
semi_minor_axis IN NUMBER,
azimuth IN NUMBER,
arc_tolerance IN NUMBER
) RETURN SDO_GEOMETRY;
Parameters
Center longitude (in degrees) of the ellipse to be used to create the returned geometry.
Center latitude (in degrees) of the ellipse to be used to create the returned geometry.
Length (in meters) of the semimajor axis of the ellipse to be used to create the returned geometry.
Length (in meters) of the semiminor axis of the ellipse to be used to create the returned geometry.
Number of degrees of the azimuth (clockwise rotation of the major axis from north) of the ellipse to be used to create the returned geometry. Must be from 0 to 180. The returned geometry is rotated by the specified number of degrees.
A numeric value to be used to construct the polygon geometry. The arc_tolerance
parameter value has the same meaning and usage guidelines as the arc_tolerance
keyword value in the params
parameter string for the SDO_GEOM.SDO_ARC_DENSIFY function. The unit of measurement associated with the geometry is associated with the arc_tolerance
parameter value. (For more information, see the Usage Notes for the SDO_GEOM.SDO_ARC_DENSIFY function in Chapter 24.)
Usage Notes
This function is useful for creating an ellipselike polygon around a specified center point when a true ellipse cannot be used (an ellipse is not valid for geodetic data with Oracle Spatial). The returned geometry has an SDO_SRID value of 8307 (for Longitude / Latitude (WGS 84)
).
Examples
The following example returns an ellipselike polygon, oriented eastwest (azimuth
= 90), around a point near the center of Concord, Massachusetts. An arc_tolerance
value of 5 meters is used in computing the polygon vertices.
SELECT SDO_UTIL.ELLIPSE_POLYGON(71.34937, 42.46101, 100, 50, 90, 5) FROM DUAL; SDO_UTIL.ELLIPSE_POLYGON(71.34937,42.46101,100,50,90,5)(SDO_GTYPE, SDO_SRID, SD  SDO_GEOMETRY(2003, 8307, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR AY(71.350589, 42.46101, 71.350168, 42.4606701, 71.349708, 42.460578, 71.3493 7, 42.4605603, 71.349032, 42.460578, 71.348572, 42.4606701, 71.348151, 42.461 01, 71.348572, 42.4613499, 71.349032, 42.461442, 71.34937, 42.4614597, 71.34 9708, 42.461442, 71.350168, 42.4613499, 71.350589, 42.46101))
Format
SDO_UTIL.EXTRACT(
geometry IN SDO_GEOMETRY,
element IN NUMBER,
ring IN NUMBER DEFAULT 0
) RETURN SDO_GEOMETRY;
Description
Returns the twodimensional geometry that represents a specified element (and optionally a ring) of the input twodimensional geometry.
Parameters
Geometry from which to extract the geometry to be returned. Must be a twodimensional geometry.
Number of the element in the geometry: 1 for the first element, 2 for the second element, and so on. Geometries with SDO_GTYPE values (explained in Section 2.2.1) ending in 1, 2, or 3 have one element; geometries with SDO_GTYPE values ending in 4, 5, 6, or 7 can have more than one element. For example, a multipolygon with an SDO_GTYPE of 2007 might contain three elements (polygons).
Number of the subelement (ring) within element
: 1 for the first subelement, 2 for the second subelement, and so on. This parameter is valid only for specifying a subelement of a polygon with one or more holes or of a point cluster:
For a polygon with holes, its first subelement is its exterior ring, its second subelement is its first interior ring, its third subelement is its second interior ring, and so on. For example, in the polygon with a hole shown in Figure 24 in Section 2.7.2, the exterior ring is subelement 1 and the interior ring (the hole) is subelement 2.
For a point cluster, its first subelement is the first point in the point cluster, its second subelement is the second point in the point cluster, and so on.
The default is 0, which causes the entire element to be extracted.
Usage Notes
This function applies to twodimensional geometries only. For threedimensional geometries, use the SDO_UTIL.EXTRACT3D function.
This function is useful for extracting a specific element or subelement from a complex geometry. For example, if you have identified a geometry as invalid by using the SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT function or the SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT procedure (both of which are documented in Chapter 24), you can use the EXTRACT function to extract the invalid geometry in order to examine it.
For a polygon with one or more holes, the returned geometry representing an extracted interior ring is reoriented so that its vertices are presented in counterclockwise order (as opposed to the clockwise order within an interior ring).
If geometry
is null or has an SDO_GTYPE value ending in 0, this function returns a null geometry.
geometry
cannot contain a type 0 (zero) element. Type 0 elements are described in Section 2.7.7.
This function is not intended for use with geometries that have any null ordinate values. Any null ordinate values in the returned geometry are replaced by 0 (zero).
An exception is raised if element
or ring
is an invalid number for geometry
.
Examples
The following example extracts the first (and only) element in the cola_c
geometry. (The example uses the definitions and data from Section 2.1.)
SELECT c.name, SDO_UTIL.EXTRACT(c.shape, 1) FROM cola_markets c WHERE c.name = 'cola_c'; NAME  SDO_UTIL.EXTRACT(C.SHAPE,1)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_IN  cola_c SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR AY(3, 3, 6, 3, 6, 5, 4, 5, 3, 3))
The following example inserts a polygon with a hole (using the same INSERT statement as in Example 27 in Section 2.7.2), and extracts the geometry representing the hole (the second subelement). Notice that in the geometry returned by the EXTRACT function, the vertices are in counterclockwise order, as opposed to the clockwise order in the hole (second subelement) in the input geometry.
 Insert polygon with hole. INSERT INTO cola_markets VALUES( 10, 'polygon_with_hole', SDO_GEOMETRY( 2003,  twodimensional polygon NULL, NULL, SDO_ELEM_INFO_ARRAY(1,1003,1, 19,2003,1),  polygon with hole SDO_ORDINATE_ARRAY(2,4, 4,3, 10,3, 13,5, 13,9, 11,13, 5,13, 2,11, 2,4, 7,5, 7,10, 10,10, 10,5, 7,5) ) ); 1 row created.  Extract the hole geometry (second subelement). SELECT SDO_UTIL.EXTRACT(c.shape, 1, 2) FROM cola_markets c WHERE c.name = 'polygon_with_hole'; SDO_UTIL.EXTRACT(C.SHAPE,1,2)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_  SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR AY(7, 5, 10, 5, 10, 10, 7, 10, 7, 5))
Format
SDO_UTIL.EXTRACT_ALL(
geometry IN SDO_GEOMETRY,
flatten IN NUMBER DEFAULT 1
) RETURN SDO_GEOMETRY_ARRAY;
Description
Returns all elements and subelements of the input twodimensional geometry, as an array of one or more geometries. Returns an object of type SDO_GEOMETRY_ARRAY, which is defined as VARRAY OF SDO_GEOMETRY
.
Parameters
Geometry from which to extract all elements and subelements. Must be a twodimensional geometry.
A flag indicating whether to "flatten" rings into individual geometries for geometries that contain an exterior ring and one or more interior rings:
0
(zero) returns one geometry for each element, but does not flatten rings into individual geometries. (A geometry will still be returned for each element of the input geometry.)
1
(the default) or any other nonzero value flattens rings into individual geometries.
For example, if a polygon contains an outer ring and an inner ring, a value of 0
returns a single geometry containing both rings, and a value of 1
returns two geometries, each containing a ring as a geometry.
This parameter is ignored for geometries that do not contain an exterior ring and one or more interior rings.
Usage Notes
This function applies to twodimensional geometries only. For threedimensional geometries, use the SDO_UTIL.EXTRACT3D function.
This function enables you to extract all elements and subelements from a geometry, regardless of how many elements and subelements the geometry has. Geometries with SDO_GTYPE values (explained in Section 2.2.1) ending in 1, 2, or 3 have one element; geometries with SDO_GTYPE values ending in 4, 5, 6, or 7 can have more than one element. For example, a multipolygon with an SDO_GTYPE of 2007 might contain three elements (polygons). To extract individual elements, use the SDO_UTIL.EXTRACT function instead.
For a polygon with one or more holes, with the default value for the flatten
parameter, the returned geometry representing an extracted interior ring is reoriented so that its vertices are presented in counterclockwise order (as opposed to the clockwise order within an interior ring). However, if the flatten
parameter value is 0, no reorientation is performed.
If geometry
is null or has an SDO_GTYPE value ending in 0, this function returns a null geometry.
geometry
cannot contain a type 0 (zero) element. Type 0 elements are described in Section 2.7.7.
This function is not intended for use with geometries that have any null ordinate values. Any null ordinate values in the returned geometry are replaced by 0 (zero).
Examples
The following example extracts all elements from the cola_b
geometry. (The example uses the definitions and data from Section 2.1.)
SELECT * FROM TABLE( SELECT SDO_UTIL.EXTRACT_ALL(c.shape) FROM cola_markets c WHERE c.name = 'cola_b'); SDO_GTYPE SDO_SRID   SDO_POINT(X, Y, Z)  SDO_ELEM_INFO  SDO_ORDINATES  2003 SDO_ELEM_INFO_ARRAY(1, 1003, 1) SDO_ORDINATE_ARRAY(5, 1, 8, 1, 8, 6, 5, 7, 5, 1)
The following example inserts a polygon with a hole (using the same INSERT statement as in Example 27 in Section 2.7.2), and extracts all elements and subelements from the polygon_with_hole
geometry. Notice that because the flatten
parameter is not specified, in the second geometry returned by the EXTRACT_ALL function the vertices are in counterclockwise order, as opposed to the clockwise order in the hole (second subelement) in the input geometry.
 Insert polygon with hole. INSERT INTO cola_markets VALUES( 10, 'polygon_with_hole', SDO_GEOMETRY( 2003,  twodimensional polygon NULL, NULL, SDO_ELEM_INFO_ARRAY(1,1003,1, 19,2003,1),  polygon with hole SDO_ORDINATE_ARRAY(2,4, 4,3, 10,3, 13,5, 13,9, 11,13, 5,13, 2,11, 2,4, 7,5, 7,10, 10,10, 10,5, 7,5) ) ); 1 row created.  Extract all, with default for flatten. SELECT * FROM TABLE( SELECT SDO_UTIL.EXTRACT_ALL(c.shape) FROM cola_markets c WHERE c.name = 'polygon_with_hole'); SDO_GTYPE SDO_SRID   SDO_POINT(X, Y, Z)  SDO_ELEM_INFO  SDO_ORDINATES  2003 SDO_ELEM_INFO_ARRAY(1, 1003, 1) SDO_ORDINATE_ARRAY(2, 4, 4, 3, 10, 3, 13, 5, 13, 9, 11, 13, 5, 13, 2, 11, 2, 4) SDO_GTYPE SDO_SRID   SDO_POINT(X, Y, Z)  SDO_ELEM_INFO  SDO_ORDINATES  2003 SDO_ELEM_INFO_ARRAY(1, 1003, 1) SDO_ORDINATE_ARRAY(7, 5, 10, 5, 10, 10, 7, 10, 7, 5)
The following example extracts all elements and subelements from the polygon_with_hole
geometry (inserted in the preceding example), and it specifies the flatten
parameter value as 0 (zero). This causes the returned array to contain a single geometry that is the same as the input geometry; thus, in the geometry returned by the EXTRACT_ALL function, the vertices are in same clockwise order in the hole (second subelement) as in the input geometry.
 Extract all, with flatten = 0. SELECT * FROM TABLE( SELECT SDO_UTIL.EXTRACT_ALL(c.shape, 0) FROM cola_markets c WHERE c.name = 'polygon_with_hole'); SDO_GTYPE SDO_SRID   SDO_POINT(X, Y, Z)  SDO_ELEM_INFO  SDO_ORDINATES  2003 SDO_ELEM_INFO_ARRAY(1, 1003, 1, 19, 2003, 1) SDO_ORDINATE_ARRAY(2, 4, 4, 3, 10, 3, 13, 5, 13, 9, 11, 13, 5, 13, 2, 11, 2, 4, 7, 5, 7, 10, 10, 10, 10, 5, 7, 5) SDO_GTYPE SDO_SRID   SDO_POINT(X, Y, Z)  SDO_ELEM_INFO  SDO_ORDINATES 
Description
Returns the threedimensional geometry that represents a specified subset of the input threedimensional geometry.
Parameters
Geometry from which to extract the geometry to be returned. Must be a threedimensional geometry
A commadelimited string of numbers that identify the subset geometry to be returned. Each number identifies the relative position of a geometry item within the input geometry. The items and their positions within the label
string are:
pointID
: Point number
edgeID
: Edge number
ringID
: Ring number
polygonID
: Polygon number
csurfID
: Composite surface number
solidID
: Solid number
multiID
: Multisolid number
A value of 0 (zero) means that the item does not apply, and you can omit trailing items that do not apply. For example, '0,2,1,4,1'
means that point number does not apply, and it specifies the second edge of the first ring of the fourth polygon of the first composite surface.
Usage Notes
This function applies to threedimensional geometries only. For twodimensional geometries, use the SDO_UTIL.EXTRACT function.
This function uses the getElementByLabel
method of the oracle.spatial.geometry.ElementExtractor
Java class, which is described in Oracle Spatial Java API Reference.
Examples
The following example extracts, from a specified threedimensional geometry, the subset geometry consisting of the following: edge 2 of ring 1 of polygon 4 of composite surface 1 of the input geometry.
SELECT SDO_UTIL.EXTRACT3D( SDO_GEOMETRY (3008,NULL,NULL , SDO_ELEM_INFO_ARRAY( 1,1007,1, 1,1006,6, 1,1003,1, 16,1003,1, 31,1003,1, 46,1003,1, 61,1003,1, 76,1003,1), SDO_ORDINATE_ARRAY( 1.0,0.0,1.0, 1.0,1.0,1.0, 1.0,1.0,1.0, 1.0,0.0,1.0, 1.0,0.0,1.0, 1.0,0.0,1.0, 0.0,0.0,1.0, 0.0,0.0,1.0, 1.0,0.0,1.0, 1.0,0.0,1.0, 0.0,1.0,1.0, 0.0,1.0,1.0, 0.0,0.0,1.0, 0.0,0.0,1.0, 0.0,1.0,1.0, 1.0,1.0,1.0, 0.0,1.0,1.0, 0.0,1.0,1.0, 1.0,1.0,1.0, 1.0,1.0,1.0, 1.0,1.0,1.0, 0.0,1.0,1.0, 0.0,0.0,1.0, 1.0,0.0,1.0, 1.0,1.0,1.0, 1.0,1.0,1.0, 1.0,0.0,1.0, 0.0,0.0,1.0, 0.0,1.0,1.0, 1.0,1.0,1.0 ) ), '0,2,1,4,1') FROM DUAL; SDO_UTIL.EXTRACT3D(SDO_GEOMETRY(3008,NULL,NULL,SDO_ELEM_INFO_ARRAY(1,1007,1,1,10  SDO_GEOMETRY(3002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 0, 1, 1, 0, 1, 1))
Format
SDO_UTIL.EXTRUDE(
geometry IN SDO_GEOMETRY,
grdheight IN SDO_NUMBER_ARRAY,
height IN SDO_NUMBER_ARRAY,
tol IN NUMBER,
optional3dSrid IN NUMBER DEFAULT NULL
) RETURN SDO_GEOMETRY;
Description
Returns the threedimensional extrusion solid geometry from an input twodimensional polygon geometry.
Parameters
Twodimensional polygon geometry from which to return the extrusion geometry. This geometry forms the "base" of the returned geometry.
Ground heights as a set of Z (height) values at the base of the solid. The numbers in this array should be the Z (height) values at the base of each vertex in the input geometry.
Height values for the extrusion geometry. The numbers in this array should be the Z (height) values at the "top" of each corresponding point in the grdheight array. For example, if the ground height at the base of the first vertex is 0 and the height at that vertex is 10, the solid at that point along the base extends 10 units high.
Tolerance value (see Section 1.5.5).
Threedimensional coordinate system (SRID) to be assigned to the returned geometry. If you do not specify this parameter, Spatial automatically assigns a threedimensional SRID value based on the SRID value of the input geometry.
Usage Notes
The input geometry must be a twodimensional polygon geometry.
If the input geometry is a polygon with multiple inner rings, this function internally combines these inner rings to make them one inner ring, producing a new geometry that approximately represents the original appearance; the function then performs the extrusion process on this new geometry, and returns the result.
Examples
The following example returns the threedimensional solid geometry representing an extrusion from a twodimensional polygon geometry.
SELECT SDO_UTIL.EXTRUDE( SDO_GEOMETRY( 2003, null, null, SDO_ELEM_INFO_ARRAY(1,1003,1), SDO_ORDINATE_ARRAY(5, 1,8,1,8,6,5,7,5,1)), SDO_NUMBER_ARRAY(0,0,0,0,0), SDO_NUMBER_ARRAY(5,10,10,5,5), 0.005) from dual; SDO_UTIL.EXTRUDE(SDO_GEOMETRY(2003,NULL,NULL,SDO_ELEM_INFO_ARRAY(1,1003,1),SDO_O  SDO_GEOMETRY(3008, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1007, 1, 1, 1006, 6, 1, 10 03, 1, 16, 1003, 1, 31, 1003, 1, 46, 1003, 1, 61, 1003, 1, 76, 1003, 1), SDO_ORD INATE_ARRAY(5, 1, 0, 5, 7, 0, 8, 6, 0, 8, 1, 0, 5, 1, 0, 5, 1, 5, 8, 1, 10, 8, 6 , 10, 5, 7, 5, 5, 1, 5, 5, 1, 0, 8, 1, 0, 8, 1, 10, 5, 1, 5, 5, 1, 0, 8, 1, 0, 8 , 6, 0, 8, 6, 10, 8, 1, 10, 8, 1, 0, 8, 6, 0, 5, 7, 0, 5, 7, 5, 8, 6, 10, 8, 6, 0, 5, 7, 0, 5, 1, 0, 5, 1, 5, 5, 7, 5, 5, 7, 0))
The following example returns the threedimensional composite solid geometry representing an extrusion from a twodimensional polygon geometry with inner rings.
SELECT SDO_UTIL.EXTRUDE( SDO_GEOMETRY( 2003, null, null, SDO_ELEM_INFO_ARRAY(1, 1003, 1, 11, 2003, 1, 21, 2003,1, 31,2003,1, 41, 2003, 1), SDO_ORDINATE_ARRAY(0,0, 8,0, 8,8, 0,8, 0,0, 1,3, 1,4, 2,4, 2,3, 1,3, 1,1, 1,2, 2,2, 2,1, 1,1, 1,6, 1,7, 2,7, 2,6, 1,6, 3,2, 3,4, 4,4, 4,2, 3,2)), SDO_NUMBER_ARRAY(1.0), SDO_NUMBER_ARRAY(1.0), 0.0001) from dual; SDO_UTIL.EXTRUDE(SDO_GEOMETRY(2003,NULL,NULL,SDO_ELEM_INFO_ARRAY(1,1003,1,11,200  SDO_GEOMETRY(3008, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1008, 4, 1, 1007, 1, 1, 10 06, 16, 1, 1003, 1, 46, 1003, 1, 91, 1003, 1, 106, 1003, 1, 121, 1003, 1, 136, 1 003, 1, 151, 1003, 1, 166, 1003, 1, 181, 1003, 1, 196, 1003, 1, 211, 1003, 1, 22 6, 1003, 1, 241, 1003, 1, 256, 1003, 1, 271, 1003, 1, 286, 1003, 1, 301, 1007, 1 , 301, 1006, 10, 301, 1003, 1, 328, 1003, 1, 355, 1003, 1, 370, 1003, 1, 385, 10 03, 1, 400, 1003, 1, 415, 1003, 1, 430, 1003, 1, 445, 1003, 1, 460, 1003, 1, 475 , 1007, 1, 475, 1006, 6, 475, 1003, 1, 490, 1003, 1, 505, 1003, 1, 520, 1003, 1, 535, 1003, 1, 550, 1003, 1, 565, 1007, 1, 565, 1006, 10, 565, 1003, 1, 592, 100 3, 1, 619, 1003, 1, 634, 1003, 1, 649, 1003, 1, 664, 1003, 1, 679, 1003, 1, 694, 1003, 1, 709, 1003, 1, 724, 1003, 1), SDO_ORDINATE_ARRAY(4, 0, 1, 4, 2, 1, 4, 4, 1, 3, 4, 1, 2, 4, 1, 2, 7, 1, 1, 7, 1, 1, 6, 1, 1, 4, 1, 1, 3, 1, 0, 3, 1, 0, 8, 1, 8, 8, 1, 8, 0, 1, 4, 0, 1, 4, 0, 1, 8, 0, 1, 8, 8, 1, 0, 8, 1, 0, 3, 1, 1, 3, 1, 1, 4, 1, 1, 6, 1, 1, 7, 1, 2, 7, 1, 2, 4, 1, 3, 4, 1, 4, 4 , 1, 4, 2, 1, 4, 0, 1, 4, 0, 1, 8, 0, 1, 8, 0, 1, 4, 0, 1, 4, 0, 1, 8, 0, 1, 8, 8, 1, 8, 8, 1, 8, 0, 1, 8, 0, 1, 8, 8, 1, 0, 8, 1, 0, 8, 1, 8, 8, 1, 8, 8, 1, 0, 8, 1, 0, 3, 1, 0, 3, 1, 0, 8, 1, 0, 8, 1, 0, 3, 1, 1, 3, 1, 1, 3, 1, 0, 3, 1, 0, 3, 1, 1, 3, 1, 1, 4, 1, 1, 4, 1, 1, 3, 1, 1, 3, 1, 1, 4, 1, 1, 6, 1, 1, 6, 1, 1, 4, 1, 1, 4, 1, 1, 6, 1, 1, 7, 1, 1, 7, 1, 1, 6, 1, 1, 6, 1, 1, 7, 1, 2, 7, 1, 2, 7, 1, 1, 7, 1, 1, 7, 1, 2, 7, 1, 2, 4, 1, 2, 4, 1, 2, 7, 1, 2, 7, 1, 2, 4, 1, 3, 4, 1, 3, 4, 1, 2, 4, 1, 2, 4, 1, 3, 4, 1, 4, 4, 1, 4, 4, 1, 3, 4, 1, 3, 4, 1, 4, 4, 1, 4, 2, 1, 4, 2, 1, 4, 4, 1, 4, 4, 1, 4, 2, 1, 4, 0, 1, 4, 0, 1, 4, 2, 1, 4, 2, 1, 0, 3, 1, 1, 3, 1, 1, 1, 1, 2, 1, 1, 3, 2, 1, 4, 2, 1, 4, 0, 1, 0, 0, 1, 0, 3, 1, 0, 3, 1, 0, 0, 1, 4, 0, 1, 4, 2, 1, 3, 2, 1, 2, 1, 1, 1, 1, 1, 1, 3, 1, 0, 3, 1, 0, 3, 1, 0, 0 , 1, 0, 0, 1, 0, 3, 1, 0, 3, 1, 0, 0, 1, 4, 0, 1, 4, 0, 1, 0, 0, 1, 0, 0, 1 , 4, 0, 1, 4, 2, 1, 4, 2, 1, 4, 0, 1, 4, 0, 1, 4, 2, 1, 3, 2, 1, 3, 2, 1, 4 , 2, 1, 4, 2, 1, 3, 2, 1, 2, 1, 1, 2, 1, 1, 3, 2, 1, 3, 2, 1, 2, 1, 1, 1, 1 , 1, 1, 1, 1, 2, 1, 1, 2, 1, 1, 1, 1, 1, 1, 3, 1, 1, 3, 1, 1, 1, 1, 1, 1, 1 , 1, 3, 1, 0, 3, 1, 0, 3, 1, 1, 3, 1, 1, 3, 1, 1, 6, 1, 2, 6, 1, 2, 4, 1, 1, 4, 1, 1, 6, 1, 1, 6, 1, 1, 4, 1, 2, 4, 1, 2, 6, 1, 1, 6, 1, 1, 6, 1, 1, 4, 1, 1, 4, 1, 1, 6, 1, 1, 6, 1, 1, 4, 1, 2, 4, 1, 2, 4, 1, 1, 4, 1, 1, 4, 1, 2, 4, 1, 2, 6, 1, 2, 6, 1, 2, 4, 1, 2, 4, 1, 2, 6, 1, 1, 6, 1, 1, 6, 1, 2, 6, 1, 2, 6, 1, 1, 3, 1, 2, 3, 1, 2, 4, 1, 3, 4, 1, 3, 2, 1, 2, 1, 1, 2, 2, 1, 1, 2, 1, 1, 3, 1, 1, 3, 1, 1, 2, 1, 2, 2, 1, 2, 1, 1, 3, 2, 1, 3, 4, 1, 2, 4, 1, 2, 3, 1, 1, 3, 1, 1, 3, 1, 1, 2, 1, 1, 2, 1, 1, 3, 1, 1, 3, 1, 1, 2 , 1, 2, 2, 1, 2, 2, 1, 1, 2, 1, 1, 2, 1, 2, 2, 1, 2, 1, 1, 2, 1, 1, 2, 2, 1 , 2, 2, 1, 2, 1, 1, 3, 2, 1, 3, 2, 1, 2, 1, 1, 2, 1, 1, 3, 2, 1, 3, 4, 1, 3, 4, 1, 3, 2, 1, 3, 2, 1, 3, 4, 1, 2, 4, 1, 2, 4, 1, 3, 4, 1, 3, 4, 1, 2, 4 , 1, 2, 3, 1, 2, 3, 1, 2, 4, 1, 2, 4, 1, 2, 3, 1, 1, 3, 1, 1, 3, 1, 2, 3, 1 , 2, 3, 1))
Format
SDO_UTIL.FROM_GML311GEOMETRY(
geometry IN CLOB,
srsNamespace IN VARCHAR2 DEFAULT NULL
) RETURN SDO_GEOMETRY;
or
SDO_UTIL.FROM_GML311GEOMETRY(
geometry IN VARCHAR2,
srsNamespace IN VARCHAR2 DEFAULT NULL
) RETURN SDO_GEOMETRY;
Parameters
Geometry in GML version 3.1.1 format to be converted to SDO_GEOMETRY format.
(Reserved for Oracle use.)
Usage Notes
The input geometry must be a valid GML fragment describing a GML version 3.1.1 geometry type defined in the Open GIS Implementation Specification.
Examples
The following example shows conversion to and from GML version 3.1.1 format. (The example uses the definitions and data from Section 2.1, specifically the cola_b
geometry from the COLA_MARKETS table.)
DECLARE gmlgeom CLOB; geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_b';  To GML 3.1.1 geometry gmlgeom := SDO_UTIL.TO_GML311GEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To GML 3.1.1 geometry result = '  TO_CHAR(gmlgeom));  From GML 3.1.3 geometry geom_result := SDO_UTIL.FROM_GML311GEOMETRY(gmlgeom); END; / To GML 3.1.1 geometry result = <gml:Polygon srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"><gml:exterior><gml:LinearRing><gml:posLis t srsDimension="2">5.0 1.0 8.0 1.0 8.0 6.0 5.0 7.0 5.0 1.0 </gml:posList></gml:LinearRing></gml:exterior></gml:Polygon> PL/SQL procedure successfully completed.
Format
SDO_UTIL.FROM_GMLGEOMETRY(
geometry IN CLOB,
srsNamespace IN VARCHAR2 DEFAULT NULL
) RETURN SDO_GEOMETRY;
or
SDO_UTIL.FROM_GMLGEOMETRY(
geometry IN VARCHAR2,
srsNamespace IN VARCHAR2 DEFAULT NULL
) RETURN SDO_GEOMETRY;
Parameters
Geometry in GML version 2.0 format to be converted to SDO_GEOMETRY format.
(Reserved for Oracle use.)
Usage Notes
The input geometry must be a valid GML fragment describing a GML version 2.0 geometry type defined in the Open GIS Implementation Specification.
Examples
The following example shows conversion to and from GML version 2.0 format. (The example uses the definitions and data from Section 2.1, specifically the cola_b
geometry from the COLA_MARKETS table.)
DECLARE gmlgeom CLOB; geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_b';  To GML geometry gmlgeom := SDO_UTIL.TO_GMLGEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To GML geometry result = '  TO_CHAR(gmlgeom));  From GML geometry geom_result := SDO_UTIL.FROM_GMLGEOMETRY(gmlgeom); END; / To GML geometry result = <gml:Polygon srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"><gml:outerBoundaryIs><gml:LinearRing><gml :coordinates decimal="." cs="," ts=" ">5.0,1.0 8.0,1.0 8.0,6.0 5.0,7.0 5.0,1.0 </gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Polygon> PL/SQL procedure successfully completed.
Format
SDO_UTIL.FROM_KMLGEOMETRY(
geometry IN CLOB
) RETURN SDO_GEOMETRY;
or
SDO_UTIL.FROM_KMLGEOMETRY(
geometry IN VARCHAR2
) RETURN SDO_GEOMETRY;
Parameters
Geometry in KML format of type CLOB or VARCHAR2 to be converted to SDO_GEOMETRY format.
Usage Notes
The input geometry must be a valid document conforming to the KML 2.1 specification.
This function does not process the whole KML document; it only processes the KML geometry tags.
Examples
The following example shows conversion to and from KML format. (The example uses the definitions and data from Section 2.1, specifically the cola_c
geometry from the COLA_MARKETS table.)
 Convert cola_c geometry to a KML document; convert that result to  a spatial geometry. DECLARE kmlgeom CLOB; val_result VARCHAR2(5); geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_c';  To KML geometry kmlgeom := SDO_UTIL.TO_KMLGEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To KML geometry result = '  TO_CHAR(kmlgeom));  From KML geometry geom_result := SDO_UTIL.FROM_KMLGEOMETRY(kmlgeom);  Validate the returned geometry val_result := SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(geom_result, 0.005); DBMS_OUTPUT.PUT_LINE('Validation result = '  val_result); END; / To KML geometry result = <Polygon><extrude>0</extrude><tessellate>0</tessellate><altitudeMode>relativeToG round</altitudeMode><outerBoundaryIs><LinearRing><coordinates>3.0,3.0 6.0,3.0 6.0,5.0 4.0,5.0 3.0,3.0 </coordinates></LinearRing></outerBoundaryIs></Polygon> Validation result = TRUE
Usage Notes
The input geometry must be in the wellknown binary (WKB) format, as defined by the Open Geospatial Consortium and the International Organization for Standardization (ISO).
This function is patterned after the SQL Multimedia recommendations in ISO 132493, Information technology  Database languages  SQL Multimedia and Application Packages  Part 3: Spatial.
To convert an SDO_GEOMETRY object to WKB format, use the SDO_UTIL.TO_WKBGEOMETRY function.
Examples
The following example shows conversion to and from WKB and WKT format, and validation of WKB and WKT geometries. (The example uses the definitions and data from Section 2.1, specifically the cola_b
geometry from the COLA_MARKETS table.)
DECLARE wkbgeom BLOB; wktgeom CLOB; val_result VARCHAR2(5); geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_b';  To WBT/WKT geometry wkbgeom := SDO_UTIL.TO_WKBGEOMETRY(geom); wktgeom := SDO_UTIL.TO_WKTGEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To WKT geometry result = '  TO_CHAR(wktgeom));  From WBT/WKT geometry geom_result := SDO_UTIL.FROM_WKBGEOMETRY(wkbgeom); geom_result := SDO_UTIL.FROM_WKTGEOMETRY(wktgeom);  Validate WBT/WKT geometry val_result := SDO_UTIL.VALIDATE_WKBGEOMETRY(wkbgeom); DBMS_OUTPUT.PUT_LINE('WKB validation result = '  val_result); val_result := SDO_UTIL.VALIDATE_WKTGEOMETRY(wktgeom); DBMS_OUTPUT.PUT_LINE('WKT validation result = '  val_result); END;/ To WKT geometry result = POLYGON ((5.0 1.0, 8.0 1.0, 8.0 6.0, 5.0 7.0, 5.0 1.0)) WKB validation result = TRUE WKT validation result = TRUE
Format
SDO_UTIL.FROM_WKTGEOMETRY(
geometry IN CLOB
) RETURN SDO_GEOMETRY;
or
SDO_UTIL.FROM_WKTGEOMETRY(
geometry IN VARCHAR2
) RETURN SDO_GEOMETRY;
Usage Notes
The input geometry must be in the wellknown text (WKT) format, as defined by the Open Geospatial Consortium and the International Organization for Standardization (ISO).
This function is patterned after the SQL Multimedia recommendations in ISO 132493, Information technology  Database languages  SQL Multimedia and Application Packages  Part 3: Spatial.
To convert an SDO_GEOMETRY object to a CLOB in WKT format, use the SDO_UTIL.TO_WKTGEOMETRY function. (You can use the SQL function TO_CHAR to convert the resulting CLOB to VARCHAR2 type.)
Examples
The following example shows conversion to and from WKB and WKT format, and validation of WKB and WKT geometries. (The example uses the definitions and data from Section 2.1, specifically the cola_b
geometry from the COLA_MARKETS table.)
DECLARE wkbgeom BLOB; wktgeom CLOB; val_result VARCHAR2(5); geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_b';  To WBT/WKT geometry wkbgeom := SDO_UTIL.TO_WKBGEOMETRY(geom); wktgeom := SDO_UTIL.TO_WKTGEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To WKT geometry result = '  TO_CHAR(wktgeom));  From WBT/WKT geometry geom_result := SDO_UTIL.FROM_WKBGEOMETRY(wkbgeom); geom_result := SDO_UTIL.FROM_WKTGEOMETRY(wktgeom);  Validate WBT/WKT geometry val_result := SDO_UTIL.VALIDATE_WKBGEOMETRY(wkbgeom); DBMS_OUTPUT.PUT_LINE('WKB validation result = '  val_result); val_result := SDO_UTIL.VALIDATE_WKTGEOMETRY(wktgeom); DBMS_OUTPUT.PUT_LINE('WKT validation result = '  val_result); END;/ To WKT geometry result = POLYGON ((5.0 1.0, 8.0 1.0, 8.0 6.0, 5.0 7.0, 5.0 1.0)) WKB validation result = TRUE WKT validation result = TRUE
Examples
The following example returns the number of elements for each geometry in the SHAPE column of the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1.)
SELECT c.name, SDO_UTIL.GETNUMELEM(c.shape) FROM cola_markets c; NAME SDO_UTIL.GETNUMELEM(C.SHAPE)   cola_a 1 cola_b 1 cola_c 1 cola_d 1
Examples
The following example returns the number of vertices for each geometry in the SHAPE column of the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1.)
SELECT c.name, SDO_UTIL.GETNUMVERTICES(c.shape) FROM cola_markets c; NAME SDO_UTIL.GETNUMVERTICES(C.SHAPE)   cola_a 2 cola_b 5 cola_c 5 cola_d 3
Usage Notes
This function returns an object of MDSYS.VERTEX_SET_TYPE, which consists of a table of objects of MDSYS.VERTEX_TYPE. Oracle Spatial defines the type VERTEX_SET_TYPE as:
CREATE TYPE vertex_set_type as TABLE OF vertex_type;
Oracle Spatial defines the object type VERTEX_TYPE as:
CREATE TYPE vertex_type AS OBJECT (x NUMBER, y NUMBER, z NUMBER, w NUMBER, v5 NUMBER, v6 NUMBER, v7 NUMBER, v8 NUMBER, v9 NUMBER, v10 NUMBER, v11 NUMBER, id NUMBER);
Note: The VERTEX_SET_TYPE and VERTEX_TYPE types are intended for use by Oracle only. Do not use these types in column definitions or functions that you create. 
This function can be useful in finding a vertex that is causing a geometry to be invalid. For example, if you have identified a geometry as invalid by using the SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT function or the SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT procedure (both of which are documented in Chapter 24), you can use the GETVERTICES function to view the vertices in tabular format.
Examples
The following example returns the X and Y coordinates and ID
values of the vertices of the geometries in the SHAPE column of the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1.)
SELECT c.mkt_id, c.name, t.X, t.Y, t.id FROM cola_markets c, TABLE(SDO_UTIL.GETVERTICES(c.shape)) t ORDER BY c.mkt_id, t.id; MKT_ID NAME X Y ID      1 cola_a 1 1 1 1 cola_a 5 7 2 2 cola_b 5 1 1 2 cola_b 8 1 2 2 cola_b 8 6 3 2 cola_b 5 7 4 2 cola_b 5 1 5 3 cola_c 3 3 1 3 cola_c 6 3 2 3 cola_c 6 5 3 3 cola_c 4 5 4 3 cola_c 3 3 5 4 cola_d 8 7 1 4 cola_d 10 9 2 4 cola_d 8 11 3 15 rows selected.
Description
Initializes all spatial indexes in a tablespace that was transported to another database.
Usage Notes
This procedure is part of the support for using the Oracle transportable tablespace feature with tablespaces that contain any spatial indexes. Use this procedure only either (A) the import operation of preRelease 11.2 dump files is completed, or (B) after the import operation from different endian platform in Release 11.2 or later is completed. Each user that has a spatial index in the tablespace must call the procedure.
For preRelease 11.2 dump files, after calling the SDO_UTIL.INITIALIZE_INDEXES_FOR_TTS procedure, you must execute a statement in the following format for each index that is in the imported transportable tablespace:
ALTER INDEX spatialindexfromimportedtts PARAMETERS ('CLEAR_TTS=TRUE');
For detailed information about transportable tablespaces and transporting tablespaces to other databases, see Oracle Database Administrator's Guide.
Examples
The following example for an import of preRelease 11.2 dump files initializes all spatial indexes in a tablespace that was transported to another database. It also includes the required ALTER INDEX statement for two hypothetical spatial indexes.
CALL SDO_UTIL.INITIALIZE_INDEXES_FOR_TTS; ALTER INDEX xyz1_spatial_idx PARAMETERS ('CLEAR_TTS=TRUE'); ALTER INDEX xyz2_spatial_idx PARAMETERS ('CLEAR_TTS=TRUE');
In the following example, the owner of the spatial index must call the SDO_UTIL.INITIALIZE_INDEXES_FOR_TTS procedure only if the SELECT statement returns the string Y
, to reflect the fact that the spatial indexes are imported from different endian platforms in Release 11.2.
SELECT DECODE(BITAND(sdo_index_version, 1024), 1024, 'Y', 'N') ENDIAN_FLAG FROM user_sdo_index_metadata WHERE sdo_index_name = :index_name;  If the result is 'Y', perform the next statement. CALL SDO_UTIL.INITIALIZE_INDEXES_FOR_TTS;  No ALTER INDEX statements are needed.
In this example, if you call the SDO_UTIL.INITIALIZE_INDEXES_FOR_TTS procedure when the SELECT statement returns the string N
, the procedure does nothing because there is no need to perform endian conversion.
Format
SDO_UTIL.INTERIOR_POINT(
geom IN SDO_GEOMETRY,
tol IN NUMBER DEFAULT 0.00000000005
) RETURN SDO_GEOMETRY;
Description
Returns a point that is guaranteed to be an interior point (not on the boundary or edge) on the surface of a polygon geometry object.
Parameters
Polygon geometry object. The SDO_GTYPE value of the geometry must be 2003 or 2007. (SDO_GTYPE values are explained in Section 2.2.1.)
Tolerance value (see Section 1.5.5).
Usage Notes
This function returns a point geometry object representing a point that is guaranteed to be an interior point on the surface, but not on the boundary or edge, of geom
. The returned point can be any interior point on the surface; however, if you call the function multiple times with the same geom
and tol
parameter values, the returned point will be the same.
The relationship between the returned point and the original geometry is INSIDE, which you can check using the SDO_RELATE operator with'mask=inside'
.
In most cases this function is more useful than the SDO_GEOM.SDO_POINTONSURFACE function, which returns a point that is not guaranteed to be an interior point.
Examples
The following example returns a geometry object that is an interior point on the surface of cola_a
. (The example uses the definitions and data from Section 2.1.)
 Return an interior point on the surface of a geometry. SELECT SDO_UTIL.INTERIOR_POINT(c.shape, 0.005) FROM cola_markets c WHERE c.name = 'cola_a'; SDO_UTIL.INTERIOR_POINT(C.SHAPE,0.005)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z),  SDO_GEOMETRY(2001, NULL, SDO_POINT_TYPE(2.75, 2.875, NULL), NULL, NULL)
Format
SDO_UTIL.POINT_AT_BEARING(
start_point IN SDO_GEOMETRY,
bearing IN NUMBER,
distance IN NUMBER
) RETURN SDO_GEOMETRY;
Description
Returns a point geometry that is at the specified distance and bearing from the start point.
Parameters
Point geometry object from which to compute the distance at the specified bearing, to locate the desired point. The point geometry must be based on a geodetic coordinate system.
Number of radians, measured clockwise from North. Must be in the range of either pi to pi or 0 to 2*pi. (Either convention on ranges will work).
Number of meters from start_point
and along the initial bearing direction to the computed destination point. Must be less than onehalf the circumference of the Earth.
Usage Notes
The input point geometry must be based on a geodetic coordinate system. If it is based on a nongeodetic coordinate system, this function returns a null value.
To convert decimal degrees to radians or nonmetric distances to meters, you can use the SDO_UTIL.CONVERT_UNIT function. To compute the bearing and tilt from a start point to an end point, you can use the SDO_UTIL.BEARING_TILT_FOR_POINTS procedure.
Examples
The following example returns the point 100 kilometers at a bearing of 1 radian from the point with the longitude and latitude coordinates (72, 43).
SELECT SDO_UTIL.POINT_AT_BEARING( SDO_GEOMETRY(2001, 8307, SDO_POINT_TYPE(72, 43, NULL), NULL, NULL), 1,  1 radian (57.296 degrees clockwise from North) 100000  100 kilometers ) FROM DUAL; SDO_UTIL.POINT_AT_BEARING(SDO_GEOMETRY(2001,8307,SDO_POINT_TYPE(72,43,NULL),NUL  SDO_GEOMETRY(2001, 8307, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 70.957053, 43.4811935))
Description
Converts all polygontype elements in a geometry to linetype elements, and sets the SDO_GTYPE value accordingly.
Usage Notes
The order of the vertices of each resulting linetype element is the same as in the associated polygontype element, and the start and end points of each linetype segment are the same point.
If the input geometry is a line, it is returned.
Examples
The following example converts the input polygon geometry, which is the same geometry as cola_b (see Figure 21 and Example 21 in Section 2.1), to a line string geometry. In the returned geometry, the SDO_GTYPE value (2002) indicates a twodimensional LINE geometry, and the SDO_ETYPE value (2) and SDO_INTERPRETATION value (1) in the SDO_ELEM_INFO array indicate a line string whose vertices are connected by straight line segments.
SELECT SDO_UTIL.POLYGONTOLINE( SDO_GEOMETRY( 2003,  twodimensional polygon NULL, NULL, SDO_ELEM_INFO_ARRAY(1,1003,1),  one polygon (exterior polygon ring) SDO_ORDINATE_ARRAY(5,1, 8,1, 8,6, 5,7, 5,1) ) ) FROM DUAL; SDO_UTIL.POLYGONTOLINE(SDO_GEOMETRY(2003,TWODIMENSIONALPOLYGONNULL,NULL,SDO_E  SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 5, 1, 8, 1, 8, 6, 5, 7, 5, 1))
Description
(Deprecated feature. Previous usage was: "Prepares a tablespace to be transported to another database, so that spatial indexes will be preserved during the transport operation.")
Parameters
Tablespace to be transported. Must be the tablespace containing the spatial table or tables. For a partitioned table, must be the tablespace of one of the partitions.
Usage Notes
Effective with Oracle Database Release 11.2, this procedure is deprecated. You do not need to call the PREPARE_FOR_TTS procedure before performing a transportable tablespace export operation.
For detailed information about transportable tablespaces and transporting tablespaces to other databases, see Oracle Database Administrator's Guide.
Format
SDO_UTIL.RECTIFY_GEOMETRY(
geometry IN SDO_GEOMETRY,
tolerance IN NUMBER
) RETURN SDO_GEOMETRY;
Parameters
Geometry to be checked for problems that can be fixed.
Tolerance value (see Section 1.5.5).
Usage Notes
This function checks for the following problems that can make a geometry invalid, and fixes the problems in the returned geometry:
Duplicate vertices
Polygon boundary intersecting itself
Incorrect orientation of exterior or interior rings (or both) of a polygon
If the input geometry has any other problem that makes it invalid, the function raises an exception.
If the input geometry is valid, the function returns a geometry that is identical to the input geometry.
For information about using this function as part of the recommended procedure for loading and validating spatial data, see Section 4.3.
This function is used internally by the SDO_UTIL.SIMPLIFY function as part of the geometry simplification process.
Examples
The following example checks the cola_b
geometry to see if it has problems that can be fixed. (In this case, the geometry is valid, so the input geometry is returned. The example uses the definitions and data from Section 2.1.)
SELECT SDO_UTIL.RECTIFY_GEOMETRY(shape, 0.005) FROM COLA_MARKETS c WHERE c.name = 'cola_b'; SDO_UTIL.RECTIFY_GEOMETRY(SHAPE,0.005)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z),  SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR AY(5, 1, 8, 1, 8, 6, 5, 7, 5, 1))
Format
SDO_UTIL.REMOVE_DUPLICATE_VERTICES
geometry IN SDO_GEOMETRY,
tolerance IN NUMBER
) RETURN SDO_GEOMETRY;
Parameters
Geometry from which to remove duplicate vertices.
Tolerance value (see Section 1.5.5).
Usage Notes
When two consecutive vertices in a geometry are the same or within the tolerance value associated with the geometry, Spatial considers the geometry to be invalid. The Spatial geometry validation functions return the error ORA13356 in these cases. You can use the REMOVE_DUPLICATE_VERTICES function to change such invalid geometries into valid geometries.
This function also closes polygons so that the first vertex of the ring is the same as the last vertex of the ring.
This function is not supported for any point geometries (including oriented points).
If the input geometry does not contain any duplicate vertices, it is returned.
Examples
The following example removes a duplicate vertex from the input geometry, which is the same geometry as cola_b (see Figure 21 and Example 21 in Section 2.1) except that it has been deliberately made invalid by adding a third vertex that is the same point as the second vertex (8,1).
SELECT SDO_UTIL.REMOVE_DUPLICATE_VERTICES( SDO_GEOMETRY( 2003,  twodimensional polygon NULL, NULL, SDO_ELEM_INFO_ARRAY(1,1003,1),  one polygon (exterior polygon ring) SDO_ORDINATE_ARRAY(5,1, 8,1, 8,1, 8,6, 5,7, 5,1)  2nd and 3rd points  are duplicates. ), 0.005  tolerance value ) FROM DUAL; SDO_UTIL.REMOVE_DUPLICATE_VERTICES(SDO_GEOMETRY(2003,TWODIMENSIONALPOLYGONNUL  SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR AY(5, 1, 8, 1, 8, 6, 5, 7, 5, 1))
Description
Returns a line string geometry with the vertices of the input geometry in reverse order.
Parameters
Line string geometry whose vertices are to be reversed in the output geometry. The SDO_GTYPE value of the input geometry must be 2002. (Section 2.2.1 explains SDO_GTYPE values.)
Usage Notes
Because the SDO_GTYPE value of the input geometry must be 2002, this function cannot be used to reverse LRS geometries. To reverse an LRS geometry, use the SDO_LRS.REVERSE_GEOMETRY function, which is described in Chapter 25.
Examples
The following example returns a line string geometry that reverses the vertices of the input geometry.
SELECT SDO_UTIL.REVERSE_LINESTRING( SDO_GEOMETRY(2002, 8307, NULL, SDO_ELEM_INFO_ARRAY(1,2,1), SDO_ORDINATE_ARRAY(72,43, 71.5,43.5, 71,42, 70,40)) ) FROM DUAL; SDO_UTIL.REVERSE_LINESTRING(SDO_GEOMETRY(2002,8307,NULL,SDO_ELEM_INFO_ARRAY(1,2,  SDO_GEOMETRY(2002, 8307, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 70, 40, 71, 42, 71.5, 43.5, 72, 43))
Format
SDO_UTIL.SIMPLIFY(
geometry IN SDO_GEOMETRY,
threshold IN NUMBER
tolerance IN NUMBER DEFAULT 0.0000005
) RETURN SDO_GEOMETRY;
Description
Simplifies the input geometry, based on a threshold value, using the DouglasPeucker algorithm.
Parameters
Geometry to be simplified.
Threshold value to be used for the geometry simplification. Should be a positive number. (Zero causes the input geometry to be returned.) If the input geometry is geodetic, the value is the number of meters; if the input geometry is nongeodetic, the value is the number of units associated with the data.
As the threshold value is decreased, the returned geometry is likely to be closer to the input geometry; as the threshold value is increased, fewer points are likely to be in the returned geometry. See the Usage Notes for more information.
Tolerance value (see Section 1.5.5). Must not be greater than threshold
; and for better performance, should not be the same as threshold
. If you do not specify a value, the default value is 0.0000005.
Usage Notes
This function also converts arcs to line stings, eliminates duplicate vertices, and corrects many overlapping edge polygon problems. The reason this function sometimes fixes problems is that it internally calls the SDO_UTIL.RECTIFY_GEOMETRY function at the end of the simplification process to ensure that a valid geometry is returned.
This function is useful when you want a geometry with less fine resolution than the original geometry. For example, if the display resolution cannot show the hundreds or thousands of turns in the course of a river or in a political boundary, better performance might result if the geometry were simplified to show only the major turns.
If you use this function with geometries that have more than two dimensions, only the first two dimensions are used in processing the query, and only the first two dimensions in the returned geometry are to be considered valid and meaningful. For example, the measure values in a returned LRS geometry will probably not reflect actual measures in that geometry. In this case, depending on your application needs, you might have several options after the simplification operation, such as ignoring the new measure values or redefining the new LRS geometry to reset the measure values.
This function uses the DouglasPeucker algorithm, which is explained in several cartography textbooks and reference documents. (In some explanations, the term tolerance is used instead of threshold; however, this is different from the Oracle Spatial meaning of tolerance.)
The returned geometry can be a polygon, line, or point, depending on the geometry definition and the threshold value. The following considerations apply:
A polygon can simplify to a line or a point and a line can simplify to a point, if the threshold value associated with the geometry is sufficiently large. For example, a thin rectangle will simplify to a line if the distance between the two parallel long sides is less than the threshold value, and a line will simplify to a point if the distance between the start and end points is less than the threshold value.
In a polygon with a hole, if the exterior ring or the interior ring (the hole) simplifies to a line or a point, the interior ring disappears from (is not included in) the resulting geometry.
Topological characteristics of the input geometry might not be maintained after simplification. For a collection geometry, the number of elements might increase, to prevent overlapping of individual elements. In all cases, this function will not return an invalid geometry.
Examples
The following example simplifies the road shown in Figure 720 in Section 7.7. Because the threshold value (6) is fairly large given the input geometry, the resulting LRS line string has only three points: the start and end points, and (12, 4,12). The measure values in the returned geometry are not meaningful, because this function considers only two dimensions.
SELECT SDO_UTIL.SIMPLIFY( SDO_GEOMETRY( 3302,  line string, 3 dimensions (X,Y,M), 3rd is linear ref. dimension NULL, NULL, SDO_ELEM_INFO_ARRAY(1,2,1),  one line string, straight segments SDO_ORDINATE_ARRAY( 2,2,0,  Starting point  Exit1; 0 is measure from start. 2,4,2,  Exit2; 2 is measure from start. 8,4,8,  Exit3; 8 is measure from start. 12,4,12,  Exit4; 12 is measure from start. 12,10,NULL,  Not an exit; measure automatically calculated and filled. 8,10,22,  Exit5; 22 is measure from start. 5,14,27)  Ending point (Exit6); 27 is measure from start. ), 6,  threshold value for geometry simplification 0.5  tolerance ) FROM DUAL; SDO_UTIL.SIMPLIFY(SDO_GEOMETRY(3302,LINESTRING,3DIMENSIONS(X,Y,M),3RDISLINEARR  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 12, 4, 12, 5, 14, 27))
Figure 321 shows the result of this example. In Figure 321, the thick solid black line is the resulting geometry, the thin solid light line between the start and end points is the input geometry, and the thin dashed line with the arrowhead at the end shows the direction of the segment.
Description
Converts a Spatial geometry object to a geography markup language (GML version 3.1.1) fragment based on the geometry types defined in the Open GIS geometry.xsd
schema document.
Usage Notes
This function does not convert circles, geometries containing any circular arcs, LRS geometries, or geometries with an SDO_ETYPE value of 0 (type 0 elements); it returns an empty CLOB in these cases.
This function converts the input geometry to a GML version 3.1.1 fragment based on some GML geometry types defined in the Open GIS Implementation Specification.
Polygons must be defined using the conventions for Oracle9i and later releases of Spatial. That is, the outer boundary is stored first (with ETYPE=1003) followed by zero or more inner boundary elements (ETYPE=2003). For a polygon with holes, the outer boundary must be stored first in the SDO_ORDINATES definition, followed by coordinates of the inner boundaries.
LRS geometries must be converted to standard geometries (using the SDO_LRS.CONVERT_TO_STD_GEOM or SDO_LRS.CONVERT_TO_STD_LAYER function) before being passed to the TO_GMLGEOMETRY function. (See the Examples section for an example that uses CONVERT_TO_STD_GEOM with the TO_GMLGEOMETRY function.)
Any circular arcs or circles must be densified (using the SDO_GEOM.SDO_ARC_DENSIFY function) or represented as polygons (using the SDO_GEOM.SDO_BUFFER function) before being passed to the TO_GMLGEOMETRY function. (See the Examples section for an example that uses SDO_ARC_DENSIFY with the TO_GMLGEOMETRY function.)
Label points are discarded. That is, if a geometry has a value for the SDO_POINT field and values in SDO_ELEM_INFO and SDO_ORDINATES, the SDO_POINT is not output in the GML fragment.
The SDO_SRID value is output in the form srsName="SDO:<srid>"
. For example, "SDO:8307"
indicates SDO_SRID 8307, and "SDO:"
indicates a null SDO_SRID value. No checks are made for the validity or consistency of the SDO_SRID value. For example, the value is not checked to see if it exists in the MDSYS.CS_SRS table or if it conflicts with the SRID value for the layer in the USER_SDO_GEOM_METADATA view.
Coordinates are always output using the <coordinates>
tag and decimal='.'
, cs=','
(that is, with the comma as the coordinate separator), and ts=' '
(that is, with a space as the tuple separator), even if the NLS_NUMERIC_CHARACTERS setting has ','
(comma) as the decimal character.
The GML output is not formatted; there are no line breaks or indentation of tags. To see the contents of the returned CLOB in SQL*Plus, use the TO_CHAR() function or set the SQL*Plus parameter LONG to a suitable value (for example, SET LONG 40000
). To get formatted GML output or to use the return value of TO_GMLGEOMETRY in SQLX or Oracle XML DB functions such as XMLELEMENT, use the XMLTYPE(clobval CLOB) constructor.
Examples
The following example returns the GML version 3.1.1 fragment for the cola_b
geometry in the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1.)
 Convert cola_b geometry to GML 3.1.1 fragment. SELECT TO_CHAR(SDO_UTIL.TO_GML311GEOMETRY(shape)) AS Gml311Geometry FROM COLA_MARKETS c WHERE c.name = 'cola_b'; GML311GEOMETRY  <gml:Polygon srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"><gml:exterior ><gml:LinearRing><gml:posList srsDimension="2">5.0 1.0 8.0 1.0 8.0 6.0 5.0 7.0 5 .0 1.0 </gml:posList></gml:LinearRing></gml:exterior></gml:Polygon>
The following example returns the GML version 3.1.1 fragment for the arc densification of the cola_d
geometry in the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1.)
SET LONG 40000 SELECT XMLTYPE(SDO_UTIL.TO_GML311GEOMETRY( SDO_GEOM.SDO_ARC_DENSIFY(c.shape, m.diminfo, 'arc_tolerance=0.05'))) AS Gml311Geometry 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'; GML311GEOMETRY  <gml:Polygon srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"> <gml:exterior> <gml:LinearRing> <gml:posList srsDimension="2">8.0 7.0 8.76536686473018 7.15224093497743 9. 4142135623731 7.58578643762691 9.84775906502257 8.23463313526982 10.0 9.0 9.8477 5906502257 9.76536686473018 9.4142135623731 10.4142135623731 8.76536686473018 10 .8477590650226 8.0 11.0 7.23463313526982 10.8477590650226 6.58578643762691 10.41 42135623731 6.15224093497743 9.76536686473018 6.0 9.0 6.15224093497743 8.2346331 3526982 6.58578643762691 7.5857864376269 7.23463313526982 7.15224093497743 8.0 7 .0 </gml:posList> </gml:LinearRing> </gml:exterior> </gml:Polygon>
The following example converts an LRS geometry to a standard geometry and returns the GML version 3.1.1 fragment for the geometry. (The example uses the definitions and data from Section 7.7.)
SET LONG 40000  Convert LRS grometry to standard geometry before using TO_GML311GEOMETRY. SELECT XMLTYPE(SDO_UTIL.TO_GML311GEOMETRY( SDO_LRS.CONVERT_TO_STD_GEOM(route_geometry))) AS Gml311Geometry FROM lrs_routes a WHERE a.route_id = 1; GML311GEOMETRY  <gml:Curve srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"> <gml:segments> <gml:LineStringSegment> <gml:posList srsDimension="2">2.0 2.0 2.0 4.0 8.0 4.0 12.0 4.0 12.0 10.0 8 .0 10.0 5.0 14.0 </gml:posList> </gml:LineStringSegment> </gml:segments> </gml:Curve>
The following examples return GML version 3.1.1 fragments for a variety of geometry types.
 Point geometry with coordinates in SDO_ORDINATES. Note the  coordinates in the GML are (10.0 10.0) and the values in the  SDO_POINT field are discarded. SELECT TO_CHAR( SDO_UTIL.TO_GML311GEOMETRY(sdo_geometry(2001, 8307, sdo_point_type(80, 70, null), sdo_elem_info_array(1,1,1), sdo_ordinate_array(10, 10))) ) AS Gml311Geometry FROM DUAL; GML311GEOMETRY  <gml:Point srsName="SDO:8307" xmlns:gml="http://www.opengis.net/gml"><gml:posLis t srsDimension="2">10.0 10.0 </gml:posList></gml:Point>  Multipolygon SET LONG 40000 SELECT SDO_UTIL.TO_GML311GEOMETRY( sdo_geometry(2007, 8307, null, sdo_elem_info_array(1,1003,1, 13,1003,1, 23,1003,3), sdo_ordinate_array(10.10,10.20, 20.50,20.10, 30.30,30.30, 40.10,40.10, 30.50, 30.20, 10.10, 10.20, 5,5, 5,6, 6,6, 6,5, 5,5, 7,7, 8,8 )) ) AS Gml311Geometry FROM DUAL; GML311GEOMETRY  <gml:MultiSurface srsName="SDO:8307" xmlns:gml="http://www.opengis.net/gml"><gml :surfaceMember><gml:Polygon><gml:exterior><gml:LinearRing><gml:posList srsDimens ion="2">10.1 10.2 20.5 20.1 30.3 30.3 40.1 40.1 30.5 30.2 10.1 10.2 </gml:posLis t></gml:LinearRing></gml:exterior></gml:Polygon></gml:surfaceMember><gml:surface Member><gml:Polygon><gml:exterior><gml:LinearRing><gml:posList srsDimension="2"> 5.0 5.0 5.0 6.0 6.0 6.0 6.0 5.0 5.0 5.0 </gml:posList></gml:LinearRing></gml:ext erior></gml:Polygon></gml:surfaceMember><gml:surfaceMember><gml:Polygon><gml:ext erior><gml:LinearRing><gml:posList srsDimension="2">7.0 7.0 8.0 7.0 8.0 8.0 7.0 8.0 7.0 7.0 </gml:posList></gml:LinearRing></gml:exterior></gml:Polygon></gml:su rfaceMember></gml:MultiSurface> SET LONG 80  Rectangle (geodetic) SELECT TO_CHAR( SDO_UTIL.TO_GML311GEOMETRY(sdo_geometry(2003, 8307, null, sdo_elem_info_array(1,1003,3), sdo_ordinate_array(10.10,10.10, 20.10,20.10 ))) ) AS Gml311Geometry FROM DUAL; GML311GEOMETRY  <gml:Polygon srsName="SDO:8307" xmlns:gml="http://www.opengis.net/gml"><gml:exte rior><gml:LinearRing><gml:posList srsDimension="2">10.1 10.1 20.1 10.1 20.1 20.1 10.1 20.1 10.1 10.1 </gml:posList></gml:LinearRing></gml:exterior></gml:Polygon >  Polygon with holes SELECT TO_CHAR( SDO_UTIL.TO_GML311GEOMETRY(sdo_geometry(2003, 262152, null, sdo_elem_info_array(1,1003,3, 5, 2003, 1, 13, 2003, 1), sdo_ordinate_array(10.10,10.20, 40.50, 41.10, 30.30, 30.30, 30.30, 40.10, 40.10, 40.10, 30.30, 30.30, 5, 5, 5, 6, 6, 6, 6, 5, 5, 5 ))) ) AS Gml311Geometry FROM DUAL; GML311GEOMETRY  <gml:Polygon srsName="SDO:262152" xmlns:gml="http://www.opengis.net/gml"><gml:ex terior><gml:LinearRing><gml:posList srsDimension="2">10.1 10.2 40.5 10.2 40.5 41 .1 10.1 41.1 10.1 10.2 </gml:posList></gml:LinearRing></gml:exterior><gml:interi or><gml:LinearRing><gml:posList srsDimension="2">30.3 30.3 30.3 40.1 40.1 40.1 3 0.3 30.3 </gml:posList></gml:LinearRing></gml:interior><gml:interior><gml:Linear Ring><gml:posList srsDimension="2">5.0 5.0 5.0 6.0 6.0 6.0 6.0 5.0 5.0 5.0 </gml :posList></gml:LinearRing></gml:interior></gml:Polygon>  Creating an XMLTYPE from the GML fragment. Also useful for "pretty  printing" the GML output. SET LONG 40000 SELECT XMLTYPE( SDO_UTIL.TO_GML311GEOMETRY(sdo_geometry(2003, 262152, null, sdo_elem_info_array(1,1003,1, 11, 2003, 1, 21, 2003, 1), sdo_ordinate_array(10.10,10.20, 40.50,10.2, 40.5,41.10, 10.1,41.1, 10.10, 10.20, 30.30,30.30, 30.30, 40.10, 40.10, 40.10, 40.10, 30.30, 30.30, 30.30, 5, 5, 5, 6, 6, 6, 6, 5, 5, 5 ))) ) AS Gml311Geometry FROM DUAL; GML311GEOMETRY  <gml:Polygon srsName="SDO:262152" xmlns:gml="http://www.opengis.net/gml"> <gml:exterior> <gml:LinearRing> <gml:posList srsDimension="2">10.1 10.2 40.5 10.2 40.5 41.1 10.1 41.1 10.1 10.2 </gml:posList> </gml:LinearRing> </gml:exterior> <gml:interior> <gml:LinearRing> <gml:posList srsDimension="2">30.3 30.3 30.3 40.1 40.1 40.1 40.1 30.3 30.3 30.3 </gml:posList> GML311GEOMETRY  </gml:LinearRing> </gml:interior> <gml:interior> <gml:LinearRing> <gml:posList srsDimension="2">5.0 5.0 5.0 6.0 6.0 6.0 6.0 5.0 5.0 5.0 </gm l:posList> </gml:LinearRing> </gml:interior> </gml:Polygon>
Description
Converts a Spatial geometry object to a geography markup language (GML 2.0) fragment based on the geometry types defined in the Open GIS geometry.xsd
schema document.
Usage Notes
This function does not convert circles, geometries containing any circular arcs, LRS geometries, or geometries with an SDO_ETYPE value of 0 (type 0 elements); it returns an empty CLOB in these cases.
This function converts the input geometry to a GML fragment based on some GML geometry types defined in the Open GIS Implementation Specification.
Polygons must be defined using the conventions for Oracle9i and later releases of Spatial. That is, the outer boundary is stored first (with ETYPE=1003) followed by zero or more inner boundary elements (ETYPE=2003). For a polygon with holes, the outer boundary must be stored first in the SDO_ORDINATES definition, followed by coordinates of the inner boundaries.
LRS geometries must be converted to standard geometries (using the SDO_LRS.CONVERT_TO_STD_GEOM or SDO_LRS.CONVERT_TO_STD_LAYER function) before being passed to the TO_GMLGEOMETRY function. (See the Examples section for an example that uses CONVERT_TO_STD_GEOM with the TO_GMLGEOMETRY function.)
Any circular arcs or circles must be densified (using the SDO_GEOM.SDO_ARC_DENSIFY function) or represented as polygons (using the SDO_GEOM.SDO_BUFFER function) before being passed to the TO_GMLGEOMETRY function. (See the Examples section for an example that uses SDO_ARC_DENSIFY with the TO_GMLGEOMETRY function.)
Label points are discarded. That is, if a geometry has a value for the SDO_POINT field and values in SDO_ELEM_INFO and SDO_ORDINATES, the SDO_POINT is not output in the GML fragment.
The SDO_SRID value is output in the form srsName="SDO:<srid>"
. For example, "SDO:8307"
indicates SDO_SRID 8307, and "SDO:"
indicates a null SDO_SRID value. No checks are made for the validity or consistency of the SDO_SRID value. For example, the value is not checked to see if it exists in the MDSYS.CS_SRS table or if it conflicts with the SRID value for the layer in the USER_SDO_GEOM_METADATA view.
Coordinates are always output using the <coordinates>
tag and decimal='.'
, cs=','
(that is, with the comma as the coordinate separator), and ts=' '
(that is, with a space as the tuple separator), even if the NLS_NUMERIC_CHARACTERS setting has ','
(comma) as the decimal character.
The GML output is not formatted; there are no line breaks or indentation of tags. To see the contents of the returned CLOB in SQL*Plus, use the TO_CHAR() function or set the SQL*Plus parameter LONG to a suitable value (for example, SET LONG 40000
). To get formatted GML output or to use the return value of TO_GMLGEOMETRY in SQLX or Oracle XML DB functions such as XMLELEMENT, use the XMLTYPE(clobval CLOB) constructor.
Examples
The following example returns the GML fragment for the cola_b
geometry in the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1.)
 Convert cola_b geometry to GML fragment. SELECT TO_CHAR(SDO_UTIL.TO_GMLGEOMETRY(shape)) AS GmlGeometry FROM COLA_MARKETS c WHERE c.name = 'cola_b'; GMLGEOMETRY  <gml:Polygon srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"><gml:outerBou ndaryIs><gml:LinearRing><gml:coordinates decimal="." cs="," ts=" ">5,1 8,1 8,6 5 ,7 5,1 </gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Polygon>
The following example returns the GML fragment for the arc densification of the cola_d
geometry in the COLA_MARKETS table. (The example uses the definitions and data from Section 2.1.)
SET LONG 40000 SELECT XMLTYPE(SDO_UTIL.TO_GMLGEOMETRY( SDO_GEOM.SDO_ARC_DENSIFY(c.shape, m.diminfo, 'arc_tolerance=0.05'))) AS GmlGeometry 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'; GMLGEOMETRY  <gml:Polygon srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"><gml:outerBou ndaryIs><gml:LinearRing><gml:coordinates decimal="." cs="," ts=" ">8,7 8.7653668 6473018,7.15224093497743 9.4142135623731,7.58578643762691 9.84775906502257,8.234 63313526982 10,9 9.84775906502257,9.76536686473018 9.4142135623731,10.4142135623 731 8.76536686473018,10.8477590650226 8,11 7.23463313526982,10.8477590650226 6.5 8578643762691,10.4142135623731 6.15224093497743,9.76536686473018 6,9 6.152240934 97743,8.23463313526982 6.58578643762691,7.5857864376269 7.23463313526982,7.15224 093497743 8,7 </gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Pol ygon>
The following example converts an LRS geometry to a standard geometry and returns the GML fragment for the geometry. (The example uses the definitions and data from Section 7.7.)
SET LONG 40000  Convert LRS geometry to standard geometry before using TO_GMLGEOMETRY. SELECT XMLTYPE(SDO_UTIL.TO_GMLGEOMETRY( SDO_LRS.CONVERT_TO_STD_GEOM(route_geometry))) AS GmlGeometry FROM lrs_routes a WHERE a.route_id = 1; GMLGEOMETRY  <gml:LineString srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"> <gml:coordinates decimal="." cs="," ts=" ">2,2 2,4 8,4 12,4 12,10 8,10 5,14 </ gml:coordinates> </gml:LineString>
The following examples return GML fragments for a variety of geometry types.
 Point geometry with coordinates in SDO_ORDINATES. Note the  coordinates in the GML are (10,10) and the values in the  SDO_POINT field are discarded. SELECT TO_CHAR( SDO_UTIL.TO_GMLGEOMETRY(sdo_geometry(2001, 8307, sdo_point_type(80, 70, null), sdo_elem_info_array(1,1,1), sdo_ordinate_array(10, 10))) ) AS GmlGeometry FROM DUAL; GMLGEOMETRY  <gml:Point srsName="SDO:8307" xmlns:gml="http://www.opengis.net/gml"><gml:coordi nates decimal="." cs="," ts=" ">10,10 </gml:coordinates></gml:Point>  Multipolygon SET LONG 40000 SELECT SDO_UTIL.TO_GMLGEOMETRY( sdo_geometry(2007, 8307, null, sdo_elem_info_array(1,1003,1, 13,1003,1, 23,1003,3), sdo_ordinate_array(10.10,10.20, 20.50,20.10, 30.30,30.30, 40.10,40.10, 30.50, 30.20, 10.10, 10.20, 5,5, 5,6, 6,6, 6,5, 5,5, 7,7, 8,8 )) ) AS GmlGeometry FROM DUAL; GMLGEOMEtTRY  <gml:MultiPolygon srsName="SDO:8307" xmlns:gml="http://www.opengis.net/gml"><gml :polygonMember><gml:Polygon><gml:outerBoundaryIs><gml:LinearRing><gml:coordinate s decimal="." cs="," ts=" ">10.1,10.2 20.5,20.1 30.3,30.3 40.1,40.1 30.5,30.2 10 .1,10.2 </gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Polygon>< /gml:polygonMember><gml:polygonMember><gml:Polygon><gml:outerBoundaryIs><gml:Lin earRing><gml:coordinates decimal="." cs="," ts=" ">5.0,5.0 5.0,6.0 6.0,6.0 6.0,5 .0 5.0,5.0 </gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Polygo n></gml:polygonMember><gml:polygonMember><gml:Polygon><gml:outerBoundaryIs><gml: LinearRing><gml:coordinates decimal="." cs="," ts=" ">7.0,7.0 8.0,7.0 8.0,8.0 7. 0,8.0 7.0,7.0 </gml:coordinates></gml:LinearRing></gml:outerBoundaryIs></gml:Pol ygon></gml:polygonMember></gml:MultiPolygon> SQL> SET LONG 80  Rectangle (geodetic) SELECT TO_CHAR( SDO_UTIL.TO_GMLGEOMETRY(sdo_geometry(2003, 8307, null, sdo_elem_info_array(1,1003,3), sdo_ordinate_array(10.10,10.10, 20.10,20.10 ))) ) AS GmlGeometry FROM DUAL; GMLGEOMETRY  <gml:Box srsName="SDO:8307" xmlns:gml="http://www.opengis.net/gml"><gml:coordina tes decimal="." cs="," ts=" ">10.1,10.1 20.1,20.1 </gml:coordinates></gml:Box>  Polygon with holes SELECT TO_CHAR( SDO_UTIL.TO_GMLGEOMETRY(sdo_geometry(2003, 262152, null, sdo_elem_info_array(1,1003,3, 5, 2003, 1, 13, 2003, 1), sdo_ordinate_array(10.10,10.20, 40.50, 41.10, 30.30, 30.30, 30.30, 40.10, 40.10, 40.10, 30.30, 30.30, 5, 5, 5, 6, 6, 6, 6, 5, 5, 5 ))) ) AS GmlGeometry FROM DUAL; GMLGEOMETRY  <gml:Polygon srsName="SDO:262152" xmlns:gml="http://www.opengis.net/gml"><gml:ou terBoundaryIs><gml:LinearRing><gml:coordinates decimal="." cs="," ts=" ">10.1,10 .2, 40.5,10.2, 40.5,41.1, 10.1,41.1, 10.1,10.2 </gml:coordinates></gml:LinearRin g></gml:outerBoundaryIs><gml:innerBoundaryIs><gml:LinearRing><gml:coordinates de cimal="." cs="," ts=" ">30.3,30.3 30.3,40.1 40.1,40.1 30.3,30.3 </gml:coordinate s></gml:LinearRing></gml:innerBoundaryIs><gml:innerBoundaryIs><gml:LinearRing><g ml:coordinates decimal="." cs="," ts=" ">5,5 5,6 6,6 6,5 5,5 </gml:coordinates>< /gml:LinearRing></gml:innerBoundaryIs></gml:Polygon>  Creating an XMLTYPE from the GML fragment. Also useful for "pretty  printing" the GML output. SET LONG 40000 SELECT XMLTYPE( SDO_UTIL.TO_GMLGEOMETRY(sdo_geometry(2003, 262152, null, sdo_elem_info_array(1,1003,1, 11, 2003, 1, 21, 2003, 1), sdo_ordinate_array(10.10,10.20, 40.50,10.2, 40.5,41.10, 10.1,41.1, 10.10, 10.20, 30.30,30.30, 30.30, 40.10, 40.10, 40.10, 40.10, 30.30, 30.30, 30.30, 5, 5, 5, 6, 6, 6, 6, 5, 5, 5 ))) ) AS GmlGeometry FROM DUAL; GMLGEOMETRY  <gml:Polygon srsName="SDO:262152" xmlns:gml="http://www.opengis.net/gml"><gml:ou terBoundaryIs><gml:LinearRing><gml:coordinates decimal="." cs="," ts=" ">10.1,10 .2 40.5,10.2 40.5,41.1 10.1,41.1 10.1,10.2 </gml:coordinates></gml:LinearRing></ gml:outerBoundaryIs><gml:innerBoundaryIs><gml:LinearRing><gml:coordinates decima l="." cs="," ts=" ">30.3,30.3 30.3,40.1 40.1,40.1 40.1,30.3 30.3,30.3 </gml:coor dinates></gml:LinearRing></gml:innerBoundaryIs><gml:innerBoundaryIs><gml:LinearR ing><gml:coordinates decimal="." cs="," ts=" ">5,5 5,6 6,6 6,5 5,5 </gml:coordin ates></gml:LinearRing></gml:innerBoundaryIs></gml:Polygon>
The following example uses the TO_GMLGEOMETRY function with the Oracle XML DB XMLTYPE data type and the XMLELEMENT and XMLFOREST functions.
SELECT xmlelement("State", xmlattributes( 'http://www.opengis.net/gml' as "xmlns:gml"), xmlforest(state as "Name", totpop as "Population", xmltype(sdo_util.to_gmlgeometry(geom)) as "gml:geometryProperty")) AS theXMLElements FROM states WHERE state_abrv in ('DE', 'UT'); THEXMLELEMENTS  <State xmlns:gml="http://www.opengis.net/gml"> <Name>Delaware</Name> <Population>666168</Population> <gml:geometryProperty> <gml:Polygon srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"> <gml:outerBoundaryIs> <gml:LinearRing> <gml:coordinates decimal="." cs="," ts=" ">75.788704,39.721699 75.78 8704,39.6479 75.767014,39.377106 75.76033,39.296497 75.756294,39.24585 75.74 8016,39.143196 75.722961,38.829895 75.707695,38.635166 75.701912,38.560619 7 5.693871,38.460011 75.500336,38.454002 75.341614,38.451855 75.049339,38.45165 3 75.053841,38.538429 75.06015,38.605465 75.063263,38.611275 75.065308,38.62 949 75.065887,38.660919 75.078697,38.732403 75.082527,38.772045 75.091667,38 .801208 75.094185,38.803699 75.097572,38.802986 75.094116,38.793579 75.09926 6,38.78756 75.123619,38.781784 75.137962,38.782703 75.18692,38.803772 75.215 019,38.831547 75.23735,38.849014 75.260498,38.875 75.305908,38.914673 75.316 399,38.930309 75.317284,38.93676 75.312851,38.945576 75.312859,38.945618 75. 31205,38.967804 75.31778,38.986012 75.341431,39.021233 75.369606,39.041359 7 5.389229,39.051422 75.40181,39.06702 75.401306,39.097713 75.411369,39.148029 75.407845,39.175201 75.396271,39.187778 75.39225,39.203377 75.40181,39.23104 9 75.402817,39.253189 75.409355,39.264759 75.434006,39.290424 75.439041,39.3 13065 75.453125,39.317093 75.457657,39.326653 75.469231,39.330677 75.486336, 39.341743 75.494888,39.354324 75.504448,39.357346 75.51284,39.366291 75.5129 24,39.366482 75.523773,39.392052 75.538651,39.415707 75.56749,39.436436 75.5 9137,39.463696 75.592941,39.471806 75.590019,39.488026 75.587311,39.496136 7 5.5774,39.508076 75.554192,39.506947 75.528442,39.498005 75.530373,39.510303 75.527145,39.531326 75.52803,39.535168 75.53437,39.540592 75.519386,39.55528 6 75.512291,39.567505 75.515587,39.580639 75.528046,39.584 75.538269,39.5935 67 75.554016,39.601727 75.560143,39.622578 75.556602,39.6348 75.549599,39.63 7699 75.542397,39.645901 75.535507,39.647099 75.514999,39.668499 75.507523,3 9.69685 75.496597,39.701302 75.488914,39.714722 75.477997,39.714901 75.47550 2,39.733501 75.467972,39.746975 75.463707,39.761101 75.448494,39.773857 75.4 38301,39.783298 75.405701,39.796101 75.415405,39.801678 75.454102,39.820202  75.499199,39.833199 75.539703,39.8381 75.5802,39.838417 75.594017,39.837345  75.596107,39.837044 75.639488,39.82893 75.680145,39.813839 75.71096,39.796352 75.739716,39.772881 75.760689,39.74712 75.774101,39.721699 75.788704,39.721 699 </gml:coordinates> </gml:LinearRing> </gml:outerBoundaryIs> </gml:Polygon> </gml:geometryProperty> </State> <State xmlns:gml="http://www.opengis.net/gml"> <Name>Utah</Name> <Population>1722850</Population> <gml:geometryProperty> <gml:Polygon srsName="SDO:" xmlns:gml="http://www.opengis.net/gml"> <gml:outerBoundaryIs> <gml:LinearRing> <gml:coordinates decimal="." cs="," ts=" ">114.040871,41.993805 114. 038803,41.884899 114.041306,41 114.04586,40.116997 114.046295,39.906101 114. 046898,39.542801 114.049026,38.67741 114.049339,38.572968 114.049095,38.14864 114.0476,37.80946 114.05098,37.746284 114.051666,37.604805 114.052025,37.10 3989 114.049797,37.000423 113.484375,37 112.898598,37.000401 112.539604,37.0 00683 112,37.000977 111.412048,37.001514 111.133018,37.00079 110.75,37.00320 1 110.5,37.004265 110.469505,36.998001 110,36.997967 109.044571,36.999088 1 09.045143,37.375 109.042824,37.484692 109.040848,37.881176 109.041405,38.1530 27 109.041107,38.1647 109.059402,38.275501 109.059296,38.5 109.058868,38.719 906 109.051765,39 109.050095,39.366699 109.050697,39.4977 109.050499,39.6605 109.050156,40.222694 109.047577,40.653641 109.0494,41.000702 109.2313,41.00 2102 109.534233,40.998184 110,40.997398 110.047768,40.997696 110.5,40.994801 111.045982,40.998013 111.045815,41.251774 111.045097,41.579899 111.045944,4 2.001633 111.506493,41.999588 112.108742,41.997677 112.16317,41.996784 112.1 72562,41.996643 112.192184,42.001244 113,41.998314 113.875,41.988091 114.040 871,41.993805 </gml:coordinates> </gml:LinearRing> </gml:outerBoundaryIs> </gml:Polygon> </gml:geometryProperty> </State>
Usage Notes
This function does not convert circles, geometries containing any circular arcs, LRS geometries, or geometries with an SDO_ETYPE value of 0 (type 0 elements); it returns an empty CLOB in these cases.
Polygons must be defined using the conventions for Oracle9i and later releases of Spatial. That is, the outer boundary is stored first (with ETYPE=1003) followed by zero or more inner boundary elements (ETYPE=2003). For a polygon with holes, the outer boundary must be stored first in the SDO_ORDINATES definition, followed by coordinates of the inner boundaries.
LRS geometries must be converted to standard geometries (using the SDO_LRS.CONVERT_TO_STD_GEOM or SDO_LRS.CONVERT_TO_STD_LAYER function) before being passed to the TO_KMLGEOMETRY function.
Any circular arcs or circles must be densified (using the SDO_GEOM.SDO_ARC_DENSIFY function) or represented as polygons (using the SDO_GEOM.SDO_BUFFER function) before being passed to the TO_KMLGEOMETRY function.
Label points are discarded. That is, if a geometry has a value for the SDO_POINT field and values in SDO_ELEM_INFO and SDO_ORDINATES, the SDO_POINT is not output in the KML document.
Solid geometries are converted to KML MultiGeometry objects, because KML 2.1 does not support solids. If you then use the SDO_UTIL.FROM_KMLGEOMETRY function on the MultiGeometry, the result is not an Oracle Spatial solid geometry (that is, its SDO_GTYPE value does not reflect a geometry type of SOLID or MULTISOLID).
The KML output is not formatted; there are no line breaks or indentation of tags. To see the contents of the returned CLOB in SQL*Plus, use the TO_CHAR() function or set the SQL*Plus parameter LONG to a suitable value (for example, SET LONG 2000
). To get formatted GML output or to use the return value of TO_KMLGEOMETRY in SQLX or Oracle XML DB functions such as XMLELEMENT, use the XMLTYPE(clobval CLOB) constructor.
Examples
The following example shows conversion to and from KML format. (The example uses the definitions and data from Section 2.1, specifically the cola_c
geometry from the COLA_MARKETS table.)
 Convert cola_c geometry to a KML document; convert that result to  a spatial geometry. set long 2000; DECLARE kmlgeom CLOB; val_result VARCHAR2(5); geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_c';  To KML geometry kmlgeom := SDO_UTIL.TO_KMLGEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To KML geometry result = '  TO_CHAR(kmlgeom));  From KML geometry geom_result := SDO_UTIL.FROM_KMLGEOMETRY(kmlgeom);  Validate the returned geometry. val_result := SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(geom_result, 0.005); DBMS_OUTPUT.PUT_LINE('Validation result = '  val_result); END; / To KML geometry result = <Polygon><extrude>0</extrude><tessellate>0</tessellate><altitudeMode>relativeToG round</altitudeMode><outerBoundaryIs><LinearRing><coordinates>3.0,3.0 6.0,3.0 6.0,5.0 4.0,5.0 3.0,3.0 </coordinates></LinearRing></outerBoundaryIs></Polygon> Validation result = TRUE
Usage Notes
The input geometry is converted to the wellknown binary (WKB) format, as defined by the Open Geospatial Consortium and the International Organization for Standardization (ISO).
This function is patterned after the SQL Multimedia recommendations in ISO 132493, Information technology  Database languages  SQL Multimedia and Application Packages  Part 3: Spatial.
To convert a geometry in WKB format to an SDO_GEOMETRY object, use the SDO_UTIL.FROM_WKBGEOMETRY function.
Examples
The following example shows conversion to and from WKB and WKT format, and validation of WKB and WKT geometries. (The example uses the definitions and data from Section 2.1, specifically the cola_b
geometry from the COLA_MARKETS table.)
DECLARE wkbgeom BLOB; wktgeom CLOB; val_result VARCHAR2(5); geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_b';  To WBT/WKT geometry wkbgeom := SDO_UTIL.TO_WKBGEOMETRY(geom); wktgeom := SDO_UTIL.TO_WKTGEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To WKT geometry result = '  TO_CHAR(wktgeom));  From WBT/WKT geometry geom_result := SDO_UTIL.FROM_WKBGEOMETRY(wkbgeom); geom_result := SDO_UTIL.FROM_WKTGEOMETRY(wktgeom);  Validate WBT/WKT geometry val_result := SDO_UTIL.VALIDATE_WKBGEOMETRY(wkbgeom); DBMS_OUTPUT.PUT_LINE('WKB validation result = '  val_result); val_result := SDO_UTIL.VALIDATE_WKTGEOMETRY(wktgeom); DBMS_OUTPUT.PUT_LINE('WKT validation result = '  val_result); END;/ To WKT geometry result = POLYGON ((5.0 1.0, 8.0 1.0, 8.0 6.0, 5.0 7.0, 5.0 1.0)) WKB validation result = TRUE WKT validation result = TRUE
Usage Notes
The input geometry is converted to the wellknown text (WKT) format, as defined by the Open Geospatial Consortium and the International Organization for Standardization (ISO).
This function is patterned after the SQL Multimedia recommendations in ISO 132493, Information technology  Database languages  SQL Multimedia and Application Packages  Part 3: Spatial.
To convert a geometry in WKT format to an SDO_GEOMETRY object, use the SDO_UTIL.FROM_WKTGEOMETRY function.
Examples
The following example shows conversion to and from WKB and WKT format, and validation of WKB and WKT geometries. (The example uses the definitions and data from Section 2.1, specifically the cola_b
geometry from the COLA_MARKETS table.)
DECLARE wkbgeom BLOB; wktgeom CLOB; val_result VARCHAR2(5); geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_b';  To WBT/WKT geometry wkbgeom := SDO_UTIL.TO_WKBGEOMETRY(geom); wktgeom := SDO_UTIL.TO_WKTGEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To WKT geometry result = '  TO_CHAR(wktgeom));  From WBT/WKT geometry geom_result := SDO_UTIL.FROM_WKBGEOMETRY(wkbgeom); geom_result := SDO_UTIL.FROM_WKTGEOMETRY(wktgeom);  Validate WBT/WKT geometry val_result := SDO_UTIL.VALIDATE_WKBGEOMETRY(wkbgeom); DBMS_OUTPUT.PUT_LINE('WKB validation result = '  val_result); val_result := SDO_UTIL.VALIDATE_WKTGEOMETRY(wktgeom); DBMS_OUTPUT.PUT_LINE('WKT validation result = '  val_result); END;/ To WKT geometry result = POLYGON ((5.0 1.0, 8.0 1.0, 8.0 6.0, 5.0 7.0, 5.0 1.0)) WKB validation result = TRUE WKT validation result = TRUE
Description
Validates the input geometry, which is in the standard wellknown binary (WKB) format; returns the string TRUE
if the geometry is valid or FALSE
if the geometry is not valid.
Usage Notes
To be valid, the input geometry must be in the wellknown binary (WKB) format, as defined by the Open Geospatial Consortium and the International Organization for Standardization (ISO).
This function is patterned after the SQL Multimedia recommendations in ISO 132493, Information technology  Database languages  SQL Multimedia and Application Packages  Part 3: Spatial.
To validate a geometry in the wellknown text (WKT) format, use the SDO_UTIL.VALIDATE_WKTGEOMETRY function.
Examples
The following example shows conversion to and from WKB and WKT format, and validation of WKB and WKT geometries. (The example uses the definitions and data from Section 2.1, specifically the cola_b
geometry from the COLA_MARKETS table.)
DECLARE wkbgeom BLOB; wktgeom CLOB; val_result VARCHAR2(5); geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_b';  To WBT/WKT geometry wkbgeom := SDO_UTIL.TO_WKBGEOMETRY(geom); wktgeom := SDO_UTIL.TO_WKTGEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To WKT geometry result = '  TO_CHAR(wktgeom));  From WBT/WKT geometry geom_result := SDO_UTIL.FROM_WKBGEOMETRY(wkbgeom); geom_result := SDO_UTIL.FROM_WKTGEOMETRY(wktgeom);  Validate WBT/WKT geometry val_result := SDO_UTIL.VALIDATE_WKBGEOMETRY(wkbgeom); DBMS_OUTPUT.PUT_LINE('WKB validation result = '  val_result); val_result := SDO_UTIL.VALIDATE_WKTGEOMETRY(wktgeom); DBMS_OUTPUT.PUT_LINE('WKT validation result = '  val_result); END;/ To WKT geometry result = POLYGON ((5.0 1.0, 8.0 1.0, 8.0 6.0, 5.0 7.0, 5.0 1.0)) WKB validation result = TRUE WKT validation result = TRUE
Format
SDO_UTIL.VALIDATE_WKTGEOMETRY(
geometry IN CLOB
) RETURN VARCHAR2;
or
SDO_UTIL.VALIDATE_WKTGEOMETRY(
geometry IN VARCHAR2
) RETURN VARCHAR2;
Description
Validates the input geometry, which is of type CLOB or VARCHAR2 and in the standard wellknown text (WKT) format; returns the string TRUE
if the geometry is valid or FALSE
if the geometry is not valid.
Usage Notes
To be valid, the input geometry must be in the wellknown text (WKT) format, as defined by the Open Geospatial Consortium and the International Organization for Standardization (ISO).
This function is patterned after the SQL Multimedia recommendations in ISO 132493, Information technology  Database languages  SQL Multimedia and Application Packages  Part 3: Spatial.
To validate a geometry in the wellknown binary (WKB) format, use the SDO_UTIL.VALIDATE_WKBGEOMETRY function.
Examples
The following example shows conversion to and from WKB and WKT format, and validation of WKB and WKT geometries. (The example uses the definitions and data from Section 2.1, specifically the cola_b
geometry from the COLA_MARKETS table.)
DECLARE wkbgeom BLOB; wktgeom CLOB; val_result VARCHAR2(5); geom_result SDO_GEOMETRY; geom SDO_GEOMETRY; BEGIN SELECT c.shape INTO geom FROM cola_markets c WHERE c.name = 'cola_b';  To WBT/WKT geometry wkbgeom := SDO_UTIL.TO_WKBGEOMETRY(geom); wktgeom := SDO_UTIL.TO_WKTGEOMETRY(geom); DBMS_OUTPUT.PUT_LINE('To WKT geometry result = '  TO_CHAR(wktgeom));  From WBT/WKT geometry geom_result := SDO_UTIL.FROM_WKBGEOMETRY(wkbgeom); geom_result := SDO_UTIL.FROM_WKTGEOMETRY(wktgeom);  Validate WBT/WKT geometry val_result := SDO_UTIL.VALIDATE_WKBGEOMETRY(wkbgeom); DBMS_OUTPUT.PUT_LINE('WKB validation result = '  val_result); val_result := SDO_UTIL.VALIDATE_WKTGEOMETRY(wktgeom); DBMS_OUTPUT.PUT_LINE('WKT validation result = '  val_result); END;/ To WKT geometry result = POLYGON ((5.0 1.0, 8.0 1.0, 8.0 6.0, 5.0 7.0, 5.0 1.0)) WKB validation result = TRUE WKT validation result = TRUE
The MDSYS.SDO_OLS package contains subprograms for Spatial OpenLS support.
To use the subprograms in this chapter, you must understand the conceptual and usage information about OpenLS in Chapter 14.
Table 271 lists the OpenLS subprograms.
Table 271 Subprograms for OpenLS Support
Subprogram  Description 


Submits an OpenLS request using a CLOB object, and returns the result as a CLOB object. 

Submits an OpenLS request using an XMLType object, and returns the result as an XMLType object. 
The rest of this chapter provides reference information on the subprograms, listed in alphabetical order.
Usage Notes
To specify the input request as an XMLType object to return an XMLType object, use the SDO_OLS.MakeOpenLSRequest function.
For information about OpenLS support, see Chapter 14.
Examples
The following example requests the nearest business, in a specified category (that is, with specified SIC_code
value), to a specified location (longitude: 122.4083257, latitude: 37.788208).
DECLARE
request CLOB;
result CLOB;
BEGIN
request := TO_CLOB(
'<?xml version="1.0" encoding="UTF8"?>
<XLS xmlns="http://www.opengis.net/xls" xmlns:gml="http://www.opengis.net/gml"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" version="1.1">
<RequestHeader clientName="someName" clientPassword="password"/>
<Request requestID="123" maximumResponses="100" version="1.1"
methodName="DirectoryRequest">
<DirectoryRequest>
<POILocation>
<Nearest nearestCriterion="Proximity">
<Position>
<gml:Point xmlns:gml="http://www.opengis.net/gml">
<gml:pos dimension="2" srsName="4326">122.4083257 37.788208</gml:pos>
</gml:Point>
</Position>
</Nearest>
</POILocation>
<POIProperties>
<POIProperty name="SIC_code" value="1234567890"/>
</POIProperties>
</DirectoryRequest>
</Request>
</XLS>');
result := SDO_OLS.makeOpenLSClobRequest(request);
END;
/
Description
Submits an OpenLS request using an XMLType object, and returns the result as an XMLType object.
Usage Notes
To specify the input request as a CLOB and to return a CLOB, use the SDO_OLS.MakeOpenLSClobRequest function.
For information about OpenLS support, see Chapter 14.
Examples
The following example requests the nearest business, in a specified category (that is, with specified SIC_code
value), to a specified location (longitude: 122.4083257, latitude: 37.788208).
SELECT SDO_OLS.makeOpenLSRequest(XMLTYPE(
'<?xml version="1.0" encoding="UTF8"?>
<XLS xmlns="http://www.opengis.net/xls" xmlns:gml="http://www.opengis.net/gml"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" version="1.1">
<RequestHeader clientName="someName" clientPassword="password"/>
<Request requestID="123" maximumResponses="100" version="1.1"
methodName="DirectoryRequest">
<DirectoryRequest>
<POILocation>
<Nearest nearestCriterion="Proximity">
<Position>
<gml:Point xmlns:gml="http://www.opengis.net/gml">
<gml:pos dimension="2" srsName="4326">122.4083257 37.788208</gml:pos>
</gml:Point>
</Position>
</Nearest>
</POILocation>
<POIProperties>
<POIProperty name="SIC_code" value="1234567890"/>
</POIProperties>
</DirectoryRequest>
</Request>
</XLS>')) "OpenLS Response" FROM DUAL;
This chapter describes Oracle Spatial support for OpenLS business directory (Yellow Pages, or YP) services. It includes the following major sections:
Business directory services provide lists of businesses in a given area and matching a specified name or category.
Business directory data comes from thirdparty providers of such data. These providers probably have different business categories, and even different hierarchical structures. A unifying pattern in the various approaches is that businesses are categorized by subject and location. The location component is well understood; for example, for the United States, either a ZIP code or the combination of a city and state, and optionally a specific address, can be used to determine the location from which to start searching.
The categorization of businesses, on the other hand, is not uniformly implemented. Some providers offer a flat list of categories, userselected by simple substring matching. Others offer a 3level or 4level hierarchical organization of subcategories, often with a fanout (maximum number of child categories at a level) of 20 to 50, and sometimes more than 100. A user might start the hierarchy traversal at the root of the hierarchy (by default). Alternatively, a user might enter a keyword that is matched to an appropriate starting point within the hierarchy. Such keyword matching might go beyond simple substring matching and result in more intelligent choices.
To use the Oracle Spatial business directory capabilities, you must use data provided by a business directory (YP) vendor, and the data must be in the format supported by the Oracle Spatial OpenLS support (see Section 12.3.1, "OPENLS_DIR_BUSINESSES Table").
To submit users' directory services requests and to return the responses, use the OpenLS Web services API, which is introduced in Section 14.2. For information about directory services requests and responses, with examples, see Section 14.3.
After you acquire the business directory data and invoke the appropriate procedure to load it into the database, the procedure populates the following tables, all owned by the MDSYS schema, which are used for business directory support:
OPENLS_DIR_BUSINESSES
OPENLS_DIR_BUSINESS_CHAINS
OPENLS_DIR_CATEGORIES
OPENLS_DIR_CATEGORIZATIONS
OPENLS_DIR_CATEGORY_TYPES
OPENLS_DIR_SYNONYMS
In some tables, some rows have null values for some columns, because the information does not apply in this instance or because the data provider did not supply a value.
The following sections describe these tables, in alphabetical order by table name.
The OPENLS_DIR_BUSINESSES table stores information about each business (that is, each business that has an address). If the business is part of a larger business chain, the CHAIN_ID column is a foreign key to the CHAIN_ID column in the OPENLS_DIR_BUSINESS_CHAINS table (described in Section 12.3.2).
The OPENLS_DIR_BUSINESSES table contains one row for each business, and it contains the columns shown in Table 121.
Table 121 OPENLS_DIR_BUSINESSES Table
Column Name  Data Type  Description 

BUSINESS_ID 
NUMBER 
Business ID number. (Required) 
BUSINESS_NAME 
VARCHAR2(128) 
Area name. (Required) 
CHAIN_ID 
NUMBER 
ID number of the business chain (in the OPENLS_BIR_BUSINESS_CHAIN table), if the business is part of a chain. 
DESCRIPTION 
VARCHAR2(1024) 
Description of the business. 
PHONE 
VARCHAR2(64) 
Phone number, in an appropriate format for the location. 
COUNTRY 
VARCHAR2(64) 
Country code or name. (Required) 
COUNTRY_SUBDIVISION 
VARCHAR2(128) 
Subdivision of the country, if applicable. 
COUNTRY_SECONDARY_SUBDIVISION 
VARCHAR2(128) 
Subdivision within COUNTRY_SUBDIVISION, if applicable. 
MUNICIPALITY 
VARCHAR2(128) 
Municipality name. 
MUNICIPALITY_SUBDIVISION 
VARCHAR2(128) 
Subdivision within MUNICIPALITY, if applicable. 
POSTAL_CODE 
VARCHAR2(32) 
Postal code (for example, 5digit ZIP code in the United Stated and Canada). (Required) 
POSTAL_CODE_EXT 
VARCHAR2(32) 
Postal code extension (for example, 4digit extension if the 54 ZIP code format is used). 
STREET 
VARCHAR2(128) 
Street address, including house or unit number. (Required) 
INTERSECTING_STREET 
VARCHAR2(128) 
Name of the street (if any) that intersects STREET at this address. 
BUILDING 
VARCHAR2(128) 
Name of the building that includes this address. 
PARAMETERS 
XMLTYPE 
XML document with additional information about the business. 
GEOM 
SDO_GEOMETRY 
Point geometry representing the address of the business. 
The OPENLS_DIR_BUSINESS_CHAINS table stores information about each business chain. A business chain is a business that has multiple associated businesses; for example, a restaurant chain has multiple restaurants that have the same name and offer basically the same menu. If the business is part of a business chain, the row for that business in the OPENLS_DIR_BUSINESSES table (described in Section 12.3.1) contains a CHAIN_ID column value that matches a value in the CHAIN_ID column in the OPENLS_DIR_BUSINESS_CHAINS table.
The OPENLS_DIR_BUSINESS_CHAINS table contains one row for each business chain, and it contains the columns shown in Table 122.
The OPENLS_DIR_CATEGORIES table stores information about each category into which a business can be placed. If the data provider uses a category hierarchy, this table contains rows for categories at all levels of the hierarchy, using the PARENT_ID column to indicate the parent category of a child category. For example, a Restaurants category might be the parent of several child categories, one of which might be Chinese.
The OPENLS_DIR_CATEGORIES table contains one row for each category, and it contains the columns shown in Table 123.
Table 123 OPENLS_DIR_CATEGORIES Table
Column Name  Data Type  Description 

CATEGORY_ID 
VARCHAR2(32) 
Category ID string. (Required) 
CATEGORY_TYPE_ID 
NUMBER 
Category type ID number. Must match a value in the CATEGORY_TYPE_ID column of the OPENLS_DIR_CATEGORY_TYPES table (described in Section 12.3.5). (Required) 
CATEGORY_NAME 
VARCHAR2(128) 
Category name. (Required) 
PARENT_ID 
VARCHAR2(32) 
CATEGORY_ID value of the parent category, if any, for this category. 
PARAMETERS 
XMLTYPE 
XML document with additional information about the category. 
The OPENLS_DIR_CATEGORIZATIONS table stores information about associations of businesses with categories. Each business can be in multiple categories; and the categories for a business can be independent of each other or in a parentchild relationship, or both. For example, a store that sells books and music CDs might be in the categories for Bookstores, Music, and its child category Music Stores, in which case there will be three rows for that business in this table.
The OPENLS_DIR_CATEGORIZATIONS table contains one row for each association of a business with a category, and it contains the columns shown in Table 124.
Table 124 OPENLS_DIR_CATEGORIZATIONS Table
Column Name  Data Type  Description 

BUSINESS_ID 
NUMBER 
Business ID. Must match a value in the BUSINESS_ID column of the OPENLS_DIR_BUSNESSES table (described in Section 12.3.1). (Required) 
CATEGORY_ID 
VARCHAR2(32) 
Category ID string. The CATEGORY_ID and CATEGORY_TYPE_ID values must match corresponding column values in a single row in the OPENLS_DIR_CATEGORIES table (described in Section 12.3.3). (Required) 
CATEGORY_TYPE_ID 
NUMBER 
Category type ID number. The CATEGORY_ID and CATEGORY_TYPE_ID values must match corresponding column values in a single row in the OPENLS_DIR_CATEGORIES table (described in Section 12.3.3). (Required) 
CATEGORIZATION_TYPE 
VARCHAR2(8) 

USER_SPECIFIC_CATEGORIZATION 
VARCHAR2(32) 
Userspecified categorization, if any. 
PARAMETERS 
XMLTYPE 
XML document with additional information about the association of the business with the category. 
The OPENLS_DIR_CATEGORY_TYPES table stores information about category types. This table contains the columns shown in Table 125.
The OPENLS_DIR_SYNONYMS table stores information about synonyms for categories. Synonyms can be created to expand the number of terms (strings) associated with a category, so that users get more complete and meaningful results from a search.
The OPENLS_DIR_SYNONYMS table contains one row for each synonym definition, and it contains the columns shown in Table 126.
Table 126 OPENLS_DIR_SYNONYMS Table
Column Name  Data Type  Description 

STANDARD_NAME 
VARCHAR2(128) 
Standard name of a category, as the user might enter it. 
CATEGORY 
VARCHAR2(128) 
Category name, as it appears in the OPENLS_DIR_CATEGORIES table (described in Section 12.3.3). 
AKA 
VARCHAR2(128) 
.Additional or alternate name for the category. ("AKA" stands for "also known as.") 
This chapter shows how to create and use spatial indexes on objects other than a geometry column. In other chapters, the focus is on indexing and querying spatial data that is stored in a single column of type SDO_GEOMETRY. This chapter shows how to:
Embed an SDO_GEOMETRY object in a userdefined object type, and index the geometry attribute of that type (see Section 9.1)
Create and use a functionbased index where the function returns an SDO_GEOMETRY object (see Section 9.2)
The techniques in this chapter are intended for experienced and knowledgeable application developers. You should be familiar with the Spatial concepts and techniques described in other chapters. You should also be familiar with, or able to learn about, relevant Oracle database features, such as userdefined data types and functionbased indexing.
The SDO_GEOMETRY type can be embedded in a userdefined data type definition. The procedure is very similar to that for using the SDO_GEOMETRY type for a spatial data column:
Create the userdefined data type.
Create a table with a column based on that data type.
Insert data into the table.
Update the USER_SDO_GEOM_METADATA view.
Create the spatial index on the geometry attribute.
Perform queries on the data.
For example, assume that you want to follow the cola markets scenario in the simplified example in Section 2.1, but want to incorporate the market name attribute and the geometry attribute in a single type. First, create the userdefined data type, as in the following example that creates an object type named MARKET_TYPE:
CREATE OR REPLACE TYPE market_type AS OBJECT (name VARCHAR2(32), shape SDO_GEOMETRY); /
Create a table that includes a column based on the userdefined type. The following example creates a table named COLA_MARKETS_2 that will contain the same information as the COLA_MARKETS table used in the example in Section 2.1.
CREATE TABLE cola_markets_2 ( mkt_id NUMBER PRIMARY KEY, market MARKET_TYPE);
Insert data into the table, using the object type name as a constructor. For example:
INSERT INTO cola_markets_2 VALUES( 1, MARKET_TYPE('cola_a', SDO_GEOMETRY( 2003,  twodimensional polygon NULL, NULL, SDO_ELEM_INFO_ARRAY(1,1003,3),  one rectangle (1003 = exterior) SDO_ORDINATE_ARRAY(1,1, 5,7)  only 2 points needed to  define rectangle (lower left and upper right) ) ) );
Update the USER_SDO_GEOM_METADATA view, using dotnotation to specify the column name and spatial attribute. The following example specifies MARKET.SHAPE as the COLUMN_NAME (explained in Section 2.8.2) in the metadata view.
INSERT INTO user_sdo_geom_metadata (TABLE_NAME, COLUMN_NAME, DIMINFO, SRID) VALUES ( 'cola_markets_2', 'market.shape', SDO_DIM_ARRAY(  20X20 grid SDO_DIM_ELEMENT('X', 0, 20, 0.005), SDO_DIM_ELEMENT('Y', 0, 20, 0.005) ), NULL  SRID );
Create the spatial index, specifying the column name and spatial attribute using dotnotation. For example.
CREATE INDEX cola_spatial_idx_2 ON cola_markets_2(market.shape) INDEXTYPE IS MDSYS.SPATIAL_INDEX;
Perform queries on the data, using dotnotation to refer to attributes of the userdefined type. The following simple query returns information associated with the cola market named cola_a
.
SELECT c.mkt_id, c.market.name, c.market.shape FROM cola_markets_2 c WHERE c.market.name = 'cola_a';
The following query returns information associated with all geometries that have any spatial interaction with a specified query window, namely, the rectangle with lowerleft coordinates (4,6) and upperright coordinates (8,8).
SELECT c.mkt_id, c.market.name, c.market.shape FROM cola_markets_2 c WHERE SDO_RELATE(c.market.shape, SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1,1003,3), SDO_ORDINATE_ARRAY(4,6, 8,8)), 'mask=anyinteract' = 'TRUE';
A functionbased spatial index facilitates queries that use locational information (of type SDO_GEOMETRY) returned by a function or expression. In this case, the spatial index is created based on the precomputed values returned by the function or expression.
If you are not already familiar with functionbased indexes, see the following for detailed explanations of their benefits, options, and requirements, as well as usage examples:
The procedure for using an SDO_GEOMETRY object in a functionbased index is as follows:
Create the function that returns an SDO_GEOMETRY object.
The function must be declared as DETERMINISTIC.
If the spatial data table does not already exist, create it, and insert data into the table.
Update the USER_SDO_GEOM_METADATA view.
Create the spatial index.
For a functionbased spatial index, the number of parameters must not exceed 32.
Perform queries on the data.
The rest of this section describes two examples of using functionbased indexes. In both examples, a function is created that returns an SDO_GEOMETRY object, and a spatial index is created on that function. In the first example, the input parameters to the function are a standard Oracle data type (NUMBER). In the second example, the input to the function is a userdefined object type.
In the following example, the input parameters to the function used for the functionbased index are standard numeric values (longitude and latitude).
Assume that you want to create a function that returns the longitude and latitude of a point and to use that function in a spatial index. First, create the function, as in the following example that creates a function named GET_LONG_LAT_PT:
 Create a function to return a point geometry (SDO_GTYPE = 2001) with  input of 2 numbers: longitude and latitude (SDO_SRID = 8307, for  "Longitude / Latitude (WGS 84)", probably the most widely used  coordinate system, and the one used for GPS devices.  Specify DETERMINISTIC for the function. create or replace function get_long_lat_pt(longitude in number, latitude in number) return SDO_GEOMETRY deterministic is begin return sdo_geometry(2001, 8307, sdo_point_type(longitude, latitude, NULL),NULL, NULL); end; /
If the spatial data table does not already exist, create the table and add data to it, as in the following example that creates a table named LONG_LAT_TABLE:
create table LONG_LAT_TABLE (lon number, lat number, name varchar2(32)); insert into LONG_LAT_TABLE values (10,10, 'Place1'); insert into LONG_LAT_TABLE values (20,20, 'Place2'); insert into LONG_LAT_TABLE values (30,30, 'Place3');
Update the USER_SDO_GEOM_METADATA view, using dotnotation to specify the schema name and function name. The following example specifies SCOTT.GET_LONG_LAT_PT(LON,LAT) as the COLUMN_NAME (explained in Section 2.8.2) in the metadata view.
 Set up the metadata entry for this table.  The column name sets up the function on top  of the two columns used in this function,  along with the owner of the function. insert into user_sdo_geom_metadata values('LONG_LAT_TABLE', 'scott.get_long_lat_pt(lon,lat)', sdo_dim_array( sdo_dim_element('Longitude', 180, 180, 0.005), sdo_dim_element('Latitude', 90, 90, 0.005)), 8307);
Create the spatial index, specifying the function name with parameters. For example:
create index LONG_LAT_TABLE_IDX on LONG_LAT_TABLE(get_long_lat_pt(lon,lat)) indextype is mdsys.spatial_index;
Perform queries on the data. The following example specifies the userdefined function in a call to the SDO_FILTER operator.
select name from LONG_LAT_TABLE a where sdo_filter( get_long_lat_pt(a.lon,a.lat), sdo_geometry(2001, 8307, sdo_point_type(10,10,NULL), NULL, NULL) )='TRUE'; NAME  Place1
In the following example, the input parameter to the function used for the functionbased index is an object of a userdefined type that includes the longitude and latitude.
Assume that you want to create a function that returns the longitude and latitude of a point and to create a spatial index on that function. First, create the userdefined data type, as in the following example that creates an object type named LONG_LAT and its member function GetGeometry:
create type long_lat as object ( longitude number, latitude number, member function GetGeometry(SELF in long_lat) RETURN SDO_GEOMETRY DETERMINISTIC) / create or replace type body long_lat as member function GetGeometry(self in long_lat) return SDO_GEOMETRY is begin return sdo_geometry(2001, 8307, sdo_point_type(longitude, latitude, NULL), NULL,NULL); end; end; /
If the spatial data table does not already exist, create the table and add data to it, as in the following example that creates a table named TEST_LONG_LAT:
create table test_long_lat (location long_lat, name varchar2(32)); insert into test_long_lat values (long_lat(10,10), 'Place1'); insert into test_long_lat values (long_lat(20,20), 'Place2'); insert into test_long_lat values (long_lat(30,30), 'Place3');
Update the USER_SDO_GEOM_METADATA view, using dotnotation to specify the schema name, table name, and function name and parameter value. The following example specifies SCOTT.LONG_LAT.GetGeometry(LOCATION) as the COLUMN_NAME (explained in Section 2.8.2) in the metadata view.
insert into user_sdo_geom_metadata values('test_long_lat', 'scott.long_lat.GetGeometry(location)', sdo_dim_array( sdo_dim_element('Longitude', 180, 180, 0.005), sdo_dim_element('Latitude', 90, 90, 0.005)), 8307);
Create the spatial index, specifying the column name and function name using dotnotation. For example:
create index test_long_lat_idx on test_long_lat(location.GetGeometry()) indextype is mdsys.spatial_index;
Perform queries on the data. The following query performs a primary filter operation, asking for the names of geometries that are likely to interact spatially with point (10,10).
SELECT a.name FROM test_long_lat a WHERE SDO_FILTER(a.location.GetGeometry(), SDO_GEOMETRY(2001, 8307, SDO_POINT_TYPE(10,10,NULL), NULL, NULL) ) = 'TRUE';
This chapter describes the Oracle Spatial support for spatial analysis and mining in Oracle Data Mining (ODM) applications.
Note: To use the features described in this chapter, you must understand the main concepts and techniques explained in the Oracle Data Mining documentation. 
For reference information about spatial analysis and mining functions and procedures in the SDO_SAM package, see Chapter 29.
Note: SDO_SAM subprograms are supported for twodimensional geometries only. They are not supported for threedimensional geometries. 
This chapter contains the following major sections:
Section 8.1, "Spatial Information and Data Mining Applications"
Section 8.2, "Spatial Binning for Detection of Regional Patterns"
ODM allows automatic discovery of knowledge from a database. Its techniques include discovering hidden associations between different data attributes, classification of data based on some samples, and clustering to identify intrinsic patterns. Spatial data can be materialized for inclusion in data mining applications. Thus, ODM might enable you to discover that sales prospects with addresses located in specific areas (neighborhoods, cities, or regions) are more likely to watch a particular television program or to respond favorably to a particular advertising solicitation. (The addresses are geocoded into longitude/latitude points and stored in an Oracle Spatial geometry object.)
In many applications, data at a specific location is influenced by data in the neighborhood. For example, the value of a house is largely determined by the value of other houses in the neighborhood. This phenomenon is called spatial correlation (or, neighborhood influence), and is discussed further in Section 8.3. The spatial analysis and mining features in Oracle Spatial let you exploit spatial correlation by using the location attributes of data items in several ways: for binning (discretizing) data into regions (such as categorizing data into northern, southern, eastern, and western regions), for materializing the influence of neighborhood (such as number of customers within a twomile radius of each store), and for identifying colocated data items (such as video rental stores and pizza restaurants).
To perform spatial data mining, you materialize spatial predicates and relationships for a set of spatial data using thematic layers. Each layer contains data about a specific kind of spatial data (that is, having a specific "theme"), for example, parks and recreation areas, or demographic income data. The spatial materialization could be performed as a preprocessing step before the application of data mining techniques, or it could be performed as an intermediate step in spatial mining, as shown in Figure 81.
Notes on Figure 81:
The original data, which included spatial and nonspatial data, is processed to produce materialized data.
Spatial data in the original data is processed by spatial mining functions to produce materialized data. The processing includes such operations as spatial binning, proximity, and colocation materialization.
The ODM engine processes materialized data (spatial and nonspatial) to generate mining results.
The following are examples of the kinds of data mining applications that could benefit from including spatial information in their processing:
Business prospecting: Determine if colocation of a business with another franchise (such as colocation of a Pizza Hut restaurant with a Blockbuster video store) might improve its sales.
Store prospecting: Find a good store location that is within 50 miles of a major city and inside a state with no sales tax. (Although 50 miles is probably too far to drive to avoid a sales tax, many customers may live near the edge of the 50mile radius and thus be near the state with no sales tax.)
Hospital prospecting: Identify the best locations for opening new hospitals based on the population of patients who live in each neighborhood.
Spatial regionbased classification or personalization: Determine if southeastern United States customers in a certain age or income category are more likely to prefer "soft" or "hard" rock music.
Automobile insurance: Given a customer's home or work location, determine if it is in an area with high or low rates of accident claims or auto thefts.
Property analysis: Use colocation rules to find hidden associations between proximity to a highway and either the price of a house or the sales volume of a store.
Property assessment: In assessing the value of a house, examine the values of similar houses in a neighborhood, and derive an estimate based on variations and spatial correlation.
Spatial binning (spatial discretization) discretizes the location values into a small number of groups associated with geographical areas. The assignment of a location to a group can be done by any of the following methods:
Reverse geocoding the longitude/latitude coordinates to obtain an address that specifies (for United States locations) the ZIP code, city, state, and country
Checking a spatial bin table to determine which bin this specific location belongs in
You can then apply ODM techniques to the discretized locations to identify interesting regional patterns or association rules. For example, you might discover that customers in area A prefer regular soda, while customers in area B prefer diet soda.
The following functions and procedures, documented in Chapter 29, perform operations related to spatial binning:
Spatial correlation (or, neighborhood influence) refers to the phenomenon of the location of a specific object in an area affecting some nonspatial attribute of the object. For example, the value (nonspatial attribute) of a house at a given address (geocoded to give a spatial attribute) is largely determined by the value of other houses in the neighborhood.
To use spatial correlation in a data mining application, you materialize the spatial correlation by adding attributes (columns) in a data mining table. You use associated thematic tables to add the appropriate attributes. You then perform mining tasks on the data mining table using ODM functions.
The following functions and procedures, documented in Chapter 29, perform operations related to materializing spatial correlation:
Colocation is the presence of two or more spatial objects at the same location or at significantly close distances from each other. Colocation patterns can indicate interesting associations among spatial data objects with respect to their nonspatial attributes. For example, a data mining application could discover that sales at franchises of a specific pizza restaurant chain were higher at restaurants colocated with video stores than at restaurants not colocated with video stores.
Two types of colocation mining are supported:
Colocation of items in a data mining table. Given a data layer, this approach identifies the colocation of multiple features. For example, predator and prey species could be colocated in animal habitats, and highsales pizza restaurants could be colocated with highsales video stores. You can use a referencefeature approach (using one feature as a reference and the other features as thematic attributes, and materializing all neighbors for the reference feature) or a bufferbased approach (materializing all items that are within all windows of a specified size).
Colocation with thematic layers. Given several data layers, this approach identifies colocation across the layers. For example, given a lakes layer and a vegetation layer, lakes could be colocated with areas of high vegetation. You materialize the data, add categorical and numerical spatial relationships to the data mining table, and apply the ODM AssociationRule mechanisms.
The following functions and procedures, documented in Chapter 29, perform operations related to colocation mining:
Spatial clustering returns cluster geometries for a layer of data. An example of spatial clustering is the clustering of crime location data.
The SDO_SAM.SPATIAL_CLUSTERS function, documented in Chapter 29, performs spatial clustering. This function requires a spatial Rtree index on the geometry column of the layer, and it returns a set of SDO_REGION objects where the geometry column specifies the boundary of each cluster and the geometry_key
value is set to null.
You can use the SDO_SAM.BIN_GEOMETRY function, with the returned spatial clusters in the bin table, to identify the cluster to which a geometry belongs.
Location prospecting can be performed by using thematic layers to compute aggregates for a layer, and choosing the locations that have the maximum values for computed aggregates.
The following functions, documented in Chapter 29, perform operations related to location prospecting:
The MDSYS.SDO_WFS_LOCK package contains subprograms for WFS support for registering and unregistering feature tables. Registering a feature table enables the table for WFS transaction locking; unregistering a feature table disables the table for WFS transaction locking.
To use the subprograms in this chapter, you must understand the conceptual and usage information about Web Feature Services (WFS) in Chapter 15.
Table 331 lists the WFS support subprograms.
Table 331 Subprograms for WFS Support
Subprogram  Description 


Enables database transactions on WFS tables. 
SDO_WFS_LOCK.RegisterFeatureTable 
Registers a feature table; that is, enables the feature table for WFS transaction locking. 
SDO_WFS_LOCK.UnRegisterFeatureTable 
Unregisters a feature table; that is, disables the feature table for WFS transaction locking. 
The rest of this chapter provides reference information on the subprograms, listed in alphabetical order.
Usage Notes
This procedure overrides, through the end of the session, the WFST standard restriction against database transactions on WFS tables, so that any transaction with the current session ID can perform update and delete operations on WFS tables. Oracle Database triggers still check the WFS locks before the current transaction is allowed to modify a row; and so if a WFS transaction has a lock on a row, the triggers will not allow the operation to be performed. However, if there is no WFS lock on the current row, the triggers will allow the current transaction to modify the row.
You must call this procedure to perform certain operations when using Oracle Workspace Manager to versionenable a WFS table, as explained in Section 15.5. However, you can also use this procedure even if you do not use Workspace Manager with WFS tables.
For information about support for Web Feature Services, see Chapter 15.
Description
Registers a feature table; that is, enables the feature table for WFS transaction locking.
Parameters
Name of the database user that owns the feature table to be registered.
Name of the feature table to be registered.
Usage Notes
This procedure ensures that the necessary constraints for implementing WFS transaction semantics are associated with the feature table.
For information about support for Web Feature Services, see Chapter 15.
To unregister a table that has not been versionenabled, use the SDO_WFS_LOCK.UnRegisterFeatureTable procedure.
Description
Unregisters a feature table; that is, disables the feature table for WFS transaction locking.
Parameters
Name of the database user that owns the feature table to be unregistered.
Name of the feature table to be unregistered.
Usage Notes
This procedure disables, for the feature table, the constraints for implementing WFS transaction semantics.
The feature table must have been previously registered in a call to the SDO_WFS_LOCK.RegisterFeatureTable procedure.
For information about support for Web Feature Services, see Chapter 15.
If you are upgrading to Oracle Database 11g, Oracle Spatial is automatically upgraded as part of the operation. For information about the upgrade procedure, see Oracle Database Upgrade Guide.
If you need to downgrade Spatial to the previous Oracle Database release, follow the instructions for downgrading a database back to the previous Oracle Database release in Oracle Database Upgrade Guide.
If you need to migrate spatial data from one database to another, see Section A.1.
If you use Oracle Spatial GeoRaster, see Section A.2.
If you are using Spatial Web Feature Service (WFS) or Catalog Services for the Web (CSW) support, and if you have data from a previous release that was indexed using one or more SYS.XMLTABLEINDEX indexes, see Section A.3.
If you need to support geometries with more than 1,048,576 ordinates, see Section A.4.
Migrating spatial data refers to moving or copying Oracle Spatial and Graph geometry objects from one Oracle database to another. (The databases can have the same or different Oracle Database release numbers.)
If you are migrating spatial data using database links, export/import, Oracle Data Pump, or transportable tablespaces, the MDSYS schema must already exist in the destination database.
In limited situations you might also need to use the SDO_MIGRATE.TO_CURRENT subprogram (described in Chapter 26). See the Usage Notes for that subprogram.
To use the GeoRaster feature of Oracle Spatial, Oracle XML DB Repository must be installed properly. (In general, you should ensure that Oracle XML DB Repository is installed before you install Oracle Spatial.)
If Oracle Spatial has been installed (such as during an upgrade) but Oracle XML DB Repository is not installed, you need to install the Oracle XML DB Repository and reload related GeoRaster PL/SQL packages. In this case, follow these steps
Install Oracle XML DB Repository.
For information about installing and uninstalling Oracle XML DB Repository, see Oracle XML DB Developer's Guide.
Go to the $ORACLE_HOME
/md/admin
directory.
Connect to the database as SYS AS SYSDBA
.
Enter the following SQL statements:
ALTER SESSION SET CURRENT_SCHEMA=MDSYS; @prvtgrs.plb @sdogrxml.sql
Effective with Release 11.2, the SYS.XMLTABLEINDEX index type is deprecated, and therefore the Spatial WFS and CSW createXMLTableIndex
methods create indexes of type XDB.XMLINDEX instead of type SYS.XMLTABLEINDEX as in previous releases. However, if you have data from a previous release that was indexed using one or more SYS.XMLTABLEINDEX indexes, you must drop the associated indexes before the upgrade and recreate the indexes after the upgrade, as follows:
Using Oracle Database Release 11.1, call the dropXMLTableIndex
method (in oracle.spatial.csw.CSWAdmin
or oracle.spatial.wfs.WFSAdmin
, as appropriate depending on the application) to drop associated indexes.
Upgrade the database from Release 11.1 to Release 11.2.
Using Oracle Database Release 11.2, call the createXMLTableIndex
(in oracle.spatial.csw.CSWAdmin
or oracle.spatial.wfs.WFSAdmin
, as appropriate depending on the application) to create indexes that were dropped in step 1.
For information about Spatial Web Feature Service (WFS) support, see Chapter 15, and especially the following:
createXMLTableIndex
method (Section 15.4.1)
dropXMLTableIndex
method (Section 15.4.3)
getIsXMLTableIndexCreated
method (Section 15.4.4)
genXMLIndex
and idxPaths
parameters of the publishFeatureType
method (Section 15.4.7)
setXMLTableIndexInfo method (Section 15.4.10)
For information about Spatial Catalog Services for the Web (CSW) support, see Chapter 16, and especially the following:
createXMLTableIndex
method (Section 16.4.1)
dropXMLTableIndex
method (Section 16.4.6)
getIsXMLTableIndexCreated
method (Section 16.4.8)
genXMLIndex
and idxPaths
parameters of the publishRecordType
method (Section 16.4.12)
setXMLTableIndexInfo
method (Section 16.4.19)
If you need to support geometries with more than 1,048,576 ordinates, you must follow the instructions in this section. However, doing so involves significant extra work (running a script, migrating existing spatial data), some database downtime , and some considerations and restrictions. Therefore, you should not perform the actions in this section unless you need to.
To increase the size of ordinate arrays to support geometries with up to 10M ordinates, follow these steps:
Ensure that no users are using any spatial tables or Oracle Spatial or Locator features.
Connect to the database as the SYS user with SYSDBA privileges (SYS AS SYSDBA, and enter the SYS account password when prompted).
Enter the following statement:
Linux: @$ORACLE_HOME/md/admin/sdoupggeom.sql
Windows: @%ORACLE_HOME%\md\admin\sdoupggeom.sql
One of the actions of the sdoupggeom.sql
script is to automatically migrate all spatial data to accommodate the new SDO_ORDINATE_ARRAY definition. This script may take a long time to complete, and the amount of time will depend on the amount of spatial data that exists in the database.
After you perform these steps, the following considerations and restrictions apply:
Any existing transportable tablespaces that were created with the old SDO_ORDINATE_ARRAY definition will not work.
If an export file was created using the Original Export utility on a database with the old SDO_ORDINATE_ARRAY definition, and if that file needs to be imported into a database that is using the new SDO_ORDINATE_ARRAY definition, you must specify the TOID_NOVALIDATE
flag with the Original Import utility, as in the following example:
imp scott/<password> file=states.dmp tables=states TOID_NOVALIDATE=MDSYS.SDO_GEOMETRY,MDSYS.SDO_ORDINATE_ARRAY,MDSYS.SDO_ELEM_INFO_ARRAY
If you plan to use Oracle Data Pump to import data after sdoupggeom.sql
has been executed on a source database, you must also run sdoupggeom.sql
on the target (destination) database after the import operation.
This document has the following parts:
Part I provides conceptual and usage information about Oracle Spatial.
Part II provides conceptual and usage information about Oracle Spatial Web services.
Part III provides reference information about Oracle Spatial operators, functions, and procedures.
Part IV provides supplementary information (appendixes and a glossary).
Part III contains the following chapters with reference information:
To understand the examples in the reference chapters, you must understand the conceptual and data type information in Chapter 2, "Spatial Data Types and Metadata", especially Section 2.2, "SDO_GEOMETRY Object Type".
The Spatial routing engine enables you to host an XMLbased Web service that provides the following features:
For an individual route request (a start location and an end location): route information (driving distances, estimated driving times, and directions) between the two locations
For a batch route request (multiple routes, with the same start location but different end locations): route information (driving distance and estimated driving time) for each route
For any request, the start and end locations are identified by addresses, geocoded results, or longitude/latitude coordinates.
A route can be singleaddress, consisting of the start location and the end location, or multiaddress, consisting of the start location, one or more intermediate locations, and the end location.
Multiaddress routes are explained in Section 13.1.
The routing engine is implemented as a Java 2 Enterprise Edition (J2EE) Web application that you can deploy in an Oracle Weblogic Server, Oracle Application Server, or standalone Oracle Application Server Containers for J2EE (OC4J) environment.
Figure 131 shows the basic flow of action with the routing engine: a client locates a remote routing engine instance, sends a route request, and processes the route response returned by the routing engine instance.
This chapter contains the following major sections:
A multiaddress route contains one or more intermediate locations in addition to the start and end locations. A multiaddress route thus contains subroutes: each subroute covers the path between two locations. A route or subroute contains one or more segments: each segment covers the path between two points along the route or subroute.
For example, assume you want to drive from your workplace to customer A, then to customer B, and then to customer C.
Your route has your workplace as the start location, customers A and B as intermediate locations, and customer C as the end location.
Your route has three subroutes: (1) workplace to customer A, (2) customer A to customer B, and (3) customer B to customer C.
Each subroute probably has multiple segments (each one associated with a specific driving direction step).
A multiaddress route contains a <start_location>
element, one or more <location>
elements, and an <end_location>
element. Several subrouterelated attributes of these elements apply only to multiaddress routing, for example, return_subroutes
, return_subroute_edge_ids
, and return_subroute_geometry
. These elements and attributes are explained in Section 13.3.2.
In multiaddress routing, the route that is returned has the locations in exactly the order specified in the request. Multiaddress routing does not attempt to optimize the route for time or distance by rearranging the locations; specifically, it does not perform any TSP ("traveling salesperson problem") computations.
To enable the routing engine to process routing requests and to generate responses, you must create a network (Oracle Database network data model network) on top of the routing data, and then deploy the routeserver.ear
file using Oracle WebLogic Server, Oracle Application Server, or OC4J. This section describes the basic steps.
To create the network, follow these steps:
If a network with the routing data already exists, drop it, to ensure that all structures are "clean" in the network to be created. To drop the existing network, execute a statement in the following form:
EXECUTE SDO_ROUTER_PARTITION.DELETE_ROUTER_NETWORK('<log_file_name>', '<network_name>');
<log_file_name> is the name of the log file that was specified in the call to SDO_ROUTER_PARTITION.DELETE_ROUTER_NETWORK to create the network to be dropped.
<network_name> is the name of the network to be dropped.
For example:
EXECUTE SDO_ROUTER_PARTITION.DELETE_ROUTER_NETWORK('create_sf_net.log', 'ndm_sf_net');
Create the network for the routing data by executing a statement in the following form:
EXECUTE SDO_ROUTER_PARTITION.CREATE_ROUTER_NETWORK('<log_file_name>', '<network_name>');
<log_file_name> is the name of the log file to use for this network.
<network_name> is the name of the network to be created.
For example:
EXECUTE SDO_ROUTER_PARTITION.CREATE_ROUTER_NETWORK('create_sf_net.log', 'ndm_sf_net');
The log file initially contains messages similar to the following:
INFO: creating the Routeserver network: NDM_SF_NET creating indexes creating views generating metadata
To deploy and configure the routing engine, follow these steps:
Add the following element inside the <website>
element in your httpwebsite.xml
or defaultwebsite.xml
file:
<webapp application="routeserver" name="web" loadonstartup="true" root="/routeserver" maxinactivitytime="no shutdown" shared="false" />
Deploy the routing engine using Oracle WebLogic Server, Oracle Application Server, or OC4J:
Using Oracle WebLogic Server: Unpack the routeserver.ear
file in your $ORACLE_HOME/md/jlib
directory. Rename the routeserver.ear
file and unpack its contents into a directory called ../routeserver.ear
. Rename the web.war
file now found under the $routeserver.ear/ directory
and unpack its contents into a subdirectory called ../web.war
. Your directory structure should therefore be $routeserver.ear/web.war/
.
After unpacking the routeserver.ear and web.war files, copy the xmlparserv2.jar
file in your $ORACLE_HOME/LIB/
directory into the $routeserver.ear/web.war/WEBINF/lib/
directory.
To deploy the routeserver.ear
file, log on to the WLS console (for example, http://
<hostname>
:7001/console
); and from Deployments, install the routeserver.ear
file, accepting the name routeserver
for the deployment and choosing the option to make the deployment accessible from a specified location.
Using Oracle Application Server or OC4J: Deploy the routeserver.ear
file in your $ORACLE_HOME/md/jlib directory
using the OracleAS or the standalone OC4J Application Server Control (for example, http://
<hostname>
:8888/em
). You can deploy the routeserver.ear
file in an existing OC4J instance, or you can create a new OC4J instance for the routing engine. In either case, enter routeserver
for the Application Name during deployment.
Launch the Oracle routing engine welcome page in a Web browser using the URL http://
<hostname>:<port>
/routeserver
. On the welcome page, select the Administration link and enter the administrator (weblogic or oc4jadmin) user name and password.
Note: If you are using WebLogic Server and if you are not using the default WebLogic administrator user name, you will need to edit theweblogic.xml file located in the $routeserver.ear/web.war/WEBINF/ directory. Replace <principalname>weblogic</principalname> with your WebLogic Server administrator user name, for example, <principalname>my_weblogic_admin</principalname> . 
Limit the maximum number of concurrent requests (maxhttpconnections) value to 10. For example, with OC4J add the following element inside the <applicationserver>
element in the server.xml
file:
<maxhttpconnections value="10" />
It is important to limit the number of concurrent requests that the Oracle Route Server can process at any given time to prevent java.lang.OutOfMemoryError
errors.
Configure the web.xml
file, as explained in Section 13.2.1, and save the changes.
If you deployed to Oracle WebLogic Server or Oracle Application Server, restart the routing engine.
If the welcome page is not displayed, ensure that the newly deployed routing engine service was successfully started. It is assumed that you are running WebLogic Server 10.3.1.0 or later with an Oracle Database Release 11.2 or later routeserver.ear
file; or that you are running Oracle AS or OC4J 10.1.3 or later with an Oracle 11g or later routeserver.ear
file.
If you deployed to an OC4J instance, start OC4J using the following command options:
server Xms<HEAP_SIZE> Xmx<HEAP_SIZE> XX:NewSize=<YOUNG_GENERATION_SIZE> XX:MaxNewSize=<YOUNG_GENERATION_SIZE> Dsun.rmi.dgc.server.gcInterval=3600000 Dsun.rmi.dgc.client.gcInterval=3600000 verbose:gc (optional)
<HEAP_SIZE>
must be at least 512 MB, and has a recommended size of at least 1024 MB (1 GB). Make sure that this memory is physical memory and not virtual memory.
<YOUNG_GENERATION_SIZE>
should be onefourth (25%) of the <HEAP_SIZE>
value.
verbose:gc will print all minor and major Java garbage collections. Monitoring these statistics could be useful for memory resource planning. If you find that garbage collections are occurring frequently or are lasting several seconds, you probably need to allocate more physical memory to the Java VM.
Note: The amount of memory the Java VM will need depends mostly on two parameters: the<maxhttpconnections value="..." /> element in the <applicationserver> element in server.xml , and the partition_cache_size_limit parameter in web.xml . 
The following command is an example that starts OC4J. Note that the config flag is an OC4J command line parameter, not a VM option.
c:\jdk1.5.0_06\bin\java server Xms1024m Xmx1024m XX:NewSize=256m XX:MaxNewSize=256m Dsun.rmi.dgc.server.gcInterval=3600000 Dsun.rmi.dgc.client.gcInterval=3600000 verbose:gc jar c:\oc4j\j2ee\home\oc4j.jar config c:\oc4j\j2ee\home\config\server.xml
Verify your deployment by visiting the URL in the following format:
http://<hostname>:<port>
/routeserver
You should see a welcome page. You should also see a message in the console window in which you started OC4J indicating that the Oracle Route Server was successfully initialized.
If you do not see a welcome message, the route server is probably not configured properly to run in your environment. In this case, edit the <ROUTE_SERVER_HOME>/routeserver/web/WEBINF/web.xml
file to reflect your environment and your preferences. (The web.xml
file is inside the routeserver.ear
file, and it will not be visible until OC4J expands it into the route server directory structure under <ROUTE_SERVER_HOME>
.) When you are finished editing, restart the routing engine or OC4J, and verify your deployment.
Consult the supplied examples. The page http://<hostname>:<port>/routeserver/
has links at the bottom in a section named Test Samples. These examples demonstrate various capabilities of the Oracle Route Server. This is the best way to learn the XML API, which is described in Section 13.3.
You will probably need to make some changes to the default web.xml
file that is included with Spatial, especially if you want to use settings from an older web.xml
file or if you want to specify a language or use long ID values. You may want to edit or add some of the following parameters.
The parameters and grouped and listed here in the order in which they appear in the web.xml
file. See also the descriptive comments in the web.xml
file.
Route Server initialization parameters:
routeserver_schema_jdbc_connect_string
: Connect string to the database that contains routing data.
routeserver_schema_username
: Name of the user that was created to access Oracle routing data.
routeserver_schema_password
: Password for the user that was created to access Oracle routing data. You can obfuscate the password by preceding the password string with an exclamation point (!
); if you do this, the password is obfuscated, and the web.xml
file is rewritten the next time the routing engine is started.
routeserver_network_name
: TBS??? Network name for the routing engine.
routeserver_schema_connection_cache_min_limit
: Minimum number of database connections cached by the routing engine.
routeserver_schema_connection_cache_max_limit
: Maximum number of database connections cached by the routing engine.
Geocoder parameters:
geocoder_type
: Type of geocoder being used: httpclient
HTTP client; interacts with the Java servlet), thinclient
(thin client; interacts with the Oracle Database geocoder), or none
(no geocoder is provided).
If geocoder_type
is thinclient
and if the geocoder and the routing engine are in the same OC4J container, the geocoder must be configured to use a data source and to avoid connection pool conflicts.
Depending on the value of this parameter, examine the settings in the HTTP Client or Thin Client section of the web.xml
file, and make any edits as appropriate. For example, if you specified thinclient
, you can obfuscate the Oracle geocoder password in the same way as with the routeserver_schema_password
parameter.
Parameters used if geocoder_type = httpclient
: geocoder_http_url
, geocoder_http_proxy_host
, geocoder_http_proxy_port
Parameters used if geocoder_type = thinclient
: geocoder_schema_host
, geocoder_schema_port
, geocoder_schema_sid
, geocoder_schema_username
, geocoder_schema_password
, geocoder_schema_mode
Logging parameters:
log_filename
: Location (relative or absolute) and name of the log file.
log_level
: Type (and amount) of information to be written to the log file. From least to most information: FATAL, ERROR, WARN, INFO, DEBUG, or FINEST (all messages).
log_thread_name
: Whether to log the name of the thread that makes each entry.
log_time
: Whether to include the time with each entry.
Road description parameters:
max_speed_limit
: Maximum speed limit of any road segment, in meters per second. (34 meters per second is about 122 kilometers per hour or 75 miles per hour.)
local_road_threshold
: A number of miles (default = 25, minimum = 10). If the estimated distance in miles between source and destination nodes is less than or equal to this value, local roads are considered as an option; if the distance is greater than this value, local roads are not considered.
This parameter enables optimizations for short routes. Lower values can speed the routing engine performance by decreasing the size of the solution set to be searched, but can produce nonoptimal short routes by causing the routing engine not to consider viable local road routes. Higher values (above the default of 25) can generate more accurate routes using local roads, but can slow the routing engine performance by increasing the size of the solution set to be searched.
highway_cost_multiplier
: The amount by which to make highways less attractive when computing routes with route_preference
set to local
.
driving_side
: R (the default) if traffic drives on the right side of the road, or L if traffic drives on the left side of the road.
language
: Default language to use to produce driving directions. The supported languages are English (the default), French, German, Italian, and Spanish.
long_ids
: TRUE
(the default) causes ID values to have their length stored as LONG and not INTEGER data; FALSE
causes ID values to have their length stored as INTEGER and not LONG data.
If you have routing data that was partitioned using an Oracle Database release before 11.1, the long_ids
parameter value must be FALSE
until the data is repartitioned using a current release.
distance_function_type
: geodetic
for geodetic coordinate systems (such as SRID 8307 for longitude/latitude) or euclidean
for projected coordinate systems.
Partitioning parameters:
partition_cache_size_limit
: Maximum number of partitions that the network partition cache can hold. If partitions are already in the cache, the routing engine will not have to load them from the database; however, if you set this value too high, you can encounter an "out of memory" error.
partition_table_name
: Name of the partition table that contains the network partitions. (The table is assumed to be in the schema associated with the routeserver_schema_jdbc_connect_string
, routeserver_schema_username
, and routeserver_schema_password
parameters.)
This section explains how to submit route requests in XML format to the routing engine, and it describes the XML document type definitions (DTDs) for the route requests (input) and responses (output). XML is widely used for transmitting structured documents using the HTTP protocol. If an HTTP request (GET or POST method) is used, it is assumed the request has a parameter named xml_request
whose value is a string containing the XML document for the request.
A request to the routing engine servlet has the following format:
http://hostname:port/routeserverservletpath?xml_request=xmlrequest
In this format:
hostname is the network path of the server on which the routing engine is running.
port is the port on which the application server listens.
routeserverservletpath is the routing engine servlet path (for example, routeserver/servlet/RouteServerServlet
).
xmlrequest is the URLencoded XML request submitted using the HTML GET or POST method.
The input XML is required for all requests. The output will be an XML document.
In a simple route (as opposed to batch route) request, you must specify a route ID, and you can specify one or more of the following attributes:
route_preference
: fastest
or shortest
(default)
road_preference
: highway
(default) or local
return_driving_directions
(whether to return driving directions): true
or false
(default)
return_hierarchical_directions
(whether to return hierarchical directions): true
or false
(default)
return_locations
(return the start and end locations of the route and any subroutes): true
(default) or false
return_subroutes
(whether to return subroutes): true
(default if a multiaddress route, ignored for a singleaddress route) or false
return_route_geometry
(whether to return the line string coordinates for the route): true
or false
(default)
return_subroute_geometry
(whether to return the line string coordinates for each subroute): true
or false
(default if a multiaddress route, ignored if a singleaddress route)
return_segment_geometry
(whether to return the line string coordinates for each maneuver in the route): true
or false
(default)
return_detailed_geometry
: true
(default; returns detailed geometries) or false
(returns generalized geometries)
language
: language used to generate driving directions (ENGLISH
, FRENCH
, GERMAN
, ITALIAN
, or SPANISH
)
return_segment_edge_ids
(whether to return the edge ID values of the edges of each maneuver in the route): true
or false
(default)
return_route_edge_ids
(whether to return the edge ID values of the edges in the route): true
or false
(default)
return_subroute_edge_ids
(whether to return the edge ID values of the edges in each subroute): true
or false
(default if a multiaddress route, ignored if a singleaddress route)
distance_unit
: kilometer
, mile
(default), or meter
time_unit
: hour
, minute
(default), or second
pre_geocoded_locations
(whether the start and end locations are input locations (address specifications or points) or previously geocoded locations): true
(previously geocoded locations) or false
(default; input locations)
In a batch route request, you must specify a request ID, a start location, and one or more end locations. Each location must have an ID attribute. You can also specify one or more of the following attributes for the batch route request:
route_preference
: fastest
or shortest
(default)
road_preference
: highway
(default) or local
distance_unit
: kilometer
, mile
(default), or meter
time_unit
: hour
, minute
(default), or second
sort_by_distance
(whether to sort the returned routes in ascending order by distance of the end location from the start location): true
or false
(default)
cutoff_distance
(returning only routes where the end location is less than or equal to a specified number of distance units from the start location): (number; default = no limit)
pre_geocoded_locations
(whether the start and end locations are input locations (address specifications or points) or previously geocoded locations): true
(previously geocoded locations) or false
(default; input locations)
This section contains the following subsections:
This section contains XML examples of route requests and the responses generated by those requests. One request uses specified addresses, another uses points specified by longitude and latitude coordinates, and another uses previously geocoded locations. For reference information about the available elements and attributes, see Section 13.3.2 for requests and Section 13.3.3 for responses.
Example 131 shows a request for the fastest route, preferably using highways, between two offices at specified addresses (in Waltham, Massachusetts and Nashua, New Hampshire), with driving directions for each segment, and using miles for distances and minutes for times.
Example 131 Route Request with Specified Addresses
<?xml version="1.0" standalone="yes"?> <route_request id="8" route_preference="fastest" road_preference="highway" return_driving_directions="true" distance_unit="mile" time_unit="minute"> <start_location> <input_location id="1"> <input_address> <us_form1 street="1000 Winter St" lastline="Waltham, MA" /> </input_address> </input_location></start_location> <end_location> <input_location id="2"> <input_address> <us_form1 street="1 Oracle Dr" lastline="Nashua, NH" /> </input_address> </input_location> </end_location> </route_request>
Example 132 shows the response generated by the request in Example 131. (The output is reformatted for readability.)
Example 132 Route Response with Specified Addresses
<?xml version="1.0" encoding="UTF8" ?> <route_response> <route id="8" step_count="15" distance="29.855655894643636" distance_unit="mile" time="34.41252848307292" time_unit="minute"> <segment sequence="1" instruction="Start out on WINTER ST (Going North)" distance="0.6715170911787637" time="1.1257004737854004"/> <segment sequence="2" instruction="Turn SLIGHT RIGHT onto RAMP (Going Northwest)" distance="0.05893317343308232" time="0.09879287083943684"/> <segment sequence="3" instruction="Turn RIGHT onto OLD COUNTY RD (Going Northeast)" distance="0.6890481152276999" time="1.6801289876302083"/> <segment sequence="4" instruction="Turn RIGHT onto TRAPELO RD (Going Southeast)" distance="1.0062739119153126" time="1.686871592203776"/> <segment sequence="5" instruction="Turn LEFT onto RAMP (Going North)" distance="0.3364944434303735" time="0.5640838623046875"/> <segment sequence="6" instruction="Merge onto I95/RT128 (Going North)" distance="4.775246959324318" time="4.926156107584635"/> <segment sequence="7" instruction="Continue on I95/RT128" distance="0.0" time="0.0"/> <segment sequence="8" instruction="Stay STRAIGHT to go onto 32B/32A (Going East)" distance="0.27138218577176415" time="0.4549326578776042"/> <segment sequence="9" instruction="Take EXIT 32A toward LOWELL" distance="0.043764782242279254" time="0.07336527506510417"/> <segment sequence="10" instruction="Stay STRAIGHT to go onto RAMP (Going East)" distance="0.2770620621155161" time="0.4644541422526042"/> <segment sequence="11" instruction="Turn LEFT onto US3 (Going Northwest)" distance="20.664632308107564" time="21.317686971028646"/> <segment sequence="12" instruction="Stay STRAIGHT to go onto EVERETT TPKE/US3 (Going Northwest)" distance="0.006080380444913938" time="0.006272379557291667"/> <segment sequence="13" instruction="Take EXIT 1 toward SO NASHUA" distance="0.550406717982974" time="0.9226765950520833"/> <segment sequence="14" instruction="Turn LEFT onto SPIT BROOK RD (Going West)" distance="0.5031617978313553" time="1.0825419108072916"/> <segment sequence="15" instruction="Turn RIGHT onto ORACLE DR (Going North)" distance="0.0016526518707758954" time="0.00886537532011668"/> </route> </route_response>
Example 133 shows a request for the fastest route, preferably using highways, between two locations specified as longitude/latitude points, with driving directions for each segment, and using meters for distances and seconds for times. (The points are associated with two locations in San Francisco, California: the World Trade Center and 100 Flower Street.)
Example 133 Route Request with Specified Longitude/Latitude Points
<?xml version="1.0" standalone="yes"?> <route_request id="8" route_preference="shortest" road_preference="highway" return_driving_directions="true" distance_unit="meter" time_unit="second" return_route_geometry="true" > <start_location> <input_location id="1" longitude="122.39382" latitude="37.79518" /> </start_location> <end_location> <input_location id="2" longitude="122.4054826" latitude="37.7423566" /> </end_location> </route_request>
Example 134 shows the response generated by the request in Example 133. (The output is reformatted for readability.)
Example 134 Route Response with Specified Longitude/Latitude Points
?xml version="1.0" encoding="UTF8" ?> <route_response> <route id="8" step_count="11" distance="7196.72509765625" distance_unit="meter" time="521.2236328125" time_unit="second"> <route_geometry> <LineString> <coordinates> 122.39382,37.79518 122.39382,37.79518 122.39454,37.79601 122.39467,37.79604 122.39476,37.79604 122.39484,37.79599 122.39486,37.79591 122.39484,37.79579 122.39462,37.79539 122.39425,37.79491 122.39389,37.79462 122.39338,37.79433 122.39326,37.79424 122.39275,37.79384 122.39263,37.79371 122.39174,37.79293 122.39151,37.79274 122.39142,37.79266 122.3913,37.7925 122.3912,37.79233 122.39102,37.79184 122.39093,37.79161 122.39072,37.79128 122.39049,37.79104 122.39016,37.79076 122.38878,37.78967 122.38861,37.7895 122.38839,37.7892 122.38819,37.78877 122.38813,37.78857 122.38797,37.78783 122.38796,37.78758 122.38801,37.78709 122.38819,37.78478 122.38832,37.78477 122.38841,37.78474 122.38983,37.78361 122.39127,37.78246 122.39206,37.78184 122.39261,37.78139 122.39319,37.78094 122.3943,37.7801 122.39486,37.77968 122.39534,37.7793 122.39654,37.77833 122.39876,37.77657 122.39902,37.77639 122.40033,37.77537 122.40096,37.77483 122.40151,37.7744 122.40205,37.77396 122.40226,37.7738 122.40266,37.77349 122.40321,37.77305 122.40376,37.77262 122.40543,37.77129 122.40578,37.77101 122.40599,37.77083 122.40699,37.77006 122.40767,37.76953 122.40774,37.76947 122.40781,37.7694 122.40786,37.76932 122.40788,37.76922 122.40788,37.76913 122.40786,37.76897 122.40785,37.76883 122.40779,37.76838 122.40767,37.7671 122.40756,37.76577 122.40743,37.76449 122.40734,37.76321 122.40722,37.76193 122.40709,37.76067 122.40695,37.75937 122.40678,37.75776 122.4067,37.75684 122.40663,37.75617 122.40647,37.75458 122.40644,37.75428 122.40632,37.75299 122.4062,37.75174 122.40617,37.75138 122.40614,37.75103 122.40606,37.75066 122.40565,37.74987 122.40529,37.74937 122.40518,37.74924 122.40506,37.74913 122.4045,37.74873 122.4041,37.74845 122.40393,37.74827 122.40384,37.74815 122.40378,37.74801 122.40375,37.74785 122.40381,37.74762 122.40397,37.74719 122.4043,37.74633 122.40434,37.74618 122.40434,37.74603 122.40431,37.74594 122.4042,37.74554 122.40416,37.7453 122.40417,37.74515 122.40431,37.74464 122.40445,37.74427 122.40461,37.74393 122.40479,37.74362 122.40522,37.74304 122.40482,37.74282 122.40517,37.74233 122.40545613036156,37.742431337836386 </coordinates> </LineString> </route_geometry> <segment sequence="1" instruction="Start out on FERRY BLDG/FERRY PLZ/HERB CAEN WAY/THE EMBARCADERO (Going Northwest)" distance="111.84008026123047" time="6.990005016326904"/> <segment sequence="2" instruction="Turn LEFT onto RAMP (Going Southwest)" distance="51.30750274658203" time="4.664318561553955"/> <segment sequence="3" instruction="Turn LEFT onto HERB CAEN WAY/THE EMBARCADERO (Going Southeast)" distance="902.3695068359375" time="56.39809036254883"/> <segment sequence="4" instruction="Turn SLIGHT RIGHT onto THE EMBARCADERO (Going Southeast)" distance="534.7628173828125" time="33.42267608642578"/> <segment sequence="5" instruction="Turn RIGHT onto BRANNAN ST (Going Southwest)" distance="2454.0565185546875" time="219.57013702392578"/> <segment sequence="6" instruction="Turn SLIGHT LEFT onto POTRERO AVE (Going South)" distance="2066.54541015625" time="129.15908813476562"/> <segment sequence="7" instruction="Turn SLIGHT LEFT onto BAY SHORE BLVD (Going Southeast)" distance="747.060546875" time="46.6912841796875"/> <segment sequence="8" instruction="Stay STRAIGHT to go onto BAY SHORE BLVD/BAYSHORE BLVD (Going South)" distance="195.7578125" time="12.23486328125"/> <segment sequence="9" instruction="Turn LEFT onto OAKDALE AVE (Going Southeast)" distance="42.8857421875" time="3.898712158203125"/> <segment sequence="10" instruction="Turn RIGHT onto PATTERSON ST (Going Southwest)" distance="62.525390625" time="5.68414306640625"/> <segment sequence="11" instruction="Turn RIGHT onto FLOWER ST (Going West)" distance="27.61372947692871" time="2.5103390216827393"/> </route> </route_response>
Example 135 shows a request for the route, with driving directions, where the start and end locations are previously geocoded locations that are about onehalf mile apart in Boston, Massachusetts.
Example 135 Route Request with Previously Geocoded Locations
<?xml version="1.0" standalone="yes"?> <route_request id="8" route_preference="shortest" road_preference="highway" return_driving_directions="true" distance_unit="mile" time_unit="minute" pre_geocoded_locations="true"> <start_location> <pre_geocoded_location id="1"> <edge_id>22161661</edge_id> <percent>.5</percent> <side>L</side> </pre_geocoded_location> </start_location> <end_location> <pre_geocoded_location id="2"> <edge_id>22104391</edge_id> <percent>.5</percent> <side>R</side> </pre_geocoded_location> </end_location> </route_request>
Example 136 shows the response to the request in Example 135. (The output is reformatted for readability.)
Example 136 Route Response with Previously Geocoded Locations
<?xml version="1.0" encoding="UTF8" ?> <route_response> <route id="8" step_count="5" distance="0.6193447379707987" distance_unit="mile" time="1.6662169138590495" time_unit="minute"> <segment sequence="1" instruction="Start out on HUNTINGTON AVE (Going Southeast)" distance="0.0059065276259536855" time="0.01440208355585734"/> <segment sequence="2" instruction="Turn LEFT onto AVENUE OF THE ARTS/HUNTINGTON AVE/RT9 (Going Northeast)" distance="0.020751234891437903" time="0.050598426659901934"/> <segment sequence="3" instruction="Turn RIGHT onto PUBLIC ALLEY 405 (Going Southeast)" distance="0.053331456545578096" time="0.286087703704834"/> <segment sequence="4" instruction="Turn RIGHT onto ST BOTOLPH ST (Going Southwest)" distance="0.028921701076542888" time="0.07052075068155925"/> <segment sequence="5" instruction="Turn RIGHT onto MASSACHUSETTS AVE (Going Northwest)" distance="0.5104338249425094" time="1.2446078459421794"/> </route> </route_response>
The following is the complete DTD for a route request. The main elements and attributes of the DTD are explained in sections that follow.
<?xml version="1.0" encoding="UTF8"?> <! geocoder.dtd includes gmlfeature.dtd. These define the ELEMENTS input_address and those in Feature, FeatureMember, and FeatureCollection that are used in geoFeature, geoFeatureCollection, and geoFeatureMember. > <!ENTITY % GEOCODERDTD SYSTEM "geocoder.dtd"> %GEOCODERDTD; <!— input_location: specify an input address to the geocoder input_address: specify a location using a street address Point: specify a location using its longitude/latitude (The input_location, input_address and Point elements are defined in geocoder.dtd. GeometryClasses is defined in gmlgeometry.dtd.) > <!ELEMENT route_request (start_location, location*, end_location)> <!ATTLIST route_request vendor CDATA "Oracle" id CDATA #REQUIRED route_preference (FASTESTSHORTEST) #IMPLIED road_preference (HIGHWAYLOCAL) #IMPLIED return_driving_directions (TRUEFALSE) #IMPLIED return_hierarchival_driving_directions (TRUEFALSE) #IMPLIED return_locations (TRUEFALSE) #IMPLIED return_subroutes (TRUEFALSE) #IMPLIED return_route_geometry (TRUEFALSE) #IMPLIED return_subroute_geometry (TRUEFALSE) #IMPLIED return_segment_geometry (TRUEFALSE) #IMPLIED return_detailed_geometry (TRUEFALSE) #IMPLIED return_route_edge_ids (TRUEFALSE) #IMPLIED return_subroute_edge_ids (TRUEFALSE) #IMPLIED return_route_segment_ids (TRUEFALSE) #IMPLIED language (ENGLISHFRENCHGERMANITALIANSPANISH) #IMPLIED distance_unit (KMMILEMETER) #IMPLIED time_unit (HOURMINUTESECOND) #IMPLIED pre_geocoded_locations (TRUEFALSE) #IMPLIED> driving_directions_detail (LOWMEDIUMHIGH) #IMPLIED <! The following are alternatives for specifying the location. Use input_location when you want to represent a location with a street address (input_address) or longitude/latitude (Point). If you have already geocoded the location, you can use information from the geocoder response to construct a pre_geocoded_location element. The geocoder returns:  An edge_id (integer that is the road segment identifier)  A side ('L' or 'R' – left or right side)  A percent (floatingpoint number 0.0 to 1.0 representing the fraction of the length from the start of the road segment to this location. > <!ELEMENT pre_geocoded_location (edge_id, percent, side)> <!ATTLIST pre_geocoded_location id CDATA #REQUIRED> <!ELEMENT start_location (input_locationpre_geocoded_location)> <!ELEMENT location (input_locationpre_geocoded_location)> <!ELEMENT end_location (input_locationpre_geocoded_location)>
The <route_request>
element has the following definition:
<!ELEMENT route_request (start_location, location*, end_location)>
The root element of a route request is always named route_request
.
The <start_location>
child element specifies the start location for the route, as an address specification, a geocoded address, or longitude/latitude coordinates.
The <location>
child element specifies a location for a segment, as an address specification, a geocoded address, or longitude/latitude coordinates. If there are no <location>
elements, it is a singleaddress route; if there are one or more <location>
elements, it is a multiaddress route.
The <end_location>
child element specifies the end location for the route, as an address specification, a geocoded address, or longitude/latitude coordinates.
In a route request:
If <start_location>
is an address specification or longitude/latitude coordinates, each <end_location>
and <location
> element can be either an address specification or longitude/latitude coordinate; however, it cannot be a geocoded address.
If <start_location>
is a geocoded address, <end_location>
and any <location>
specifications must be geocoded addresses.
The root element <route_request>
has a number of attributes, most of them optional. The attributes are defined as follows:
<!ATTLIST route_request vendor CDATA "Oracle" id CDATA #REQUIRED route_preference (FASTESTSHORTEST) #IMPLIED road_preference (HIGHWAYLOCAL) #IMPLIED return_driving_directions (TRUEFALSE) #IMPLIED return_hierarchival_driving_directions (TRUEFALSE) #IMPLIED return_locations (TRUEFALSE) #IMPLIED return_subroutes (TRUEFALSE) #IMPLIED return_route_geometry (TRUEFALSE) #IMPLIED return_subroute_geometry (TRUEFALSE) #IMPLIED return_segment_geometry (TRUEFALSE) #IMPLIED return_detailed_geometry (TRUEFALSE) #IMPLIED return_route_edge_ids (TRUEFALSE) #IMPLIED return_subroute_edge_ids (TRUEFALSE) #IMPLIED return_route_segment_ids (TRUEFALSE) #IMPLIED language (ENGLISHFRENCHGERMANITALIANSPANISH) #IMPLIED distance_unit (KMMILEMETER) #IMPLIED time_unit (HOURMINUTESECOND) #IMPLIED pre_geocoded_locations (TRUEFALSE) #IMPLIED> driving_directions_detail (LOWMEDIUMHIGH) #IMPLIED
vendor
is an optional attribute whose default value identifies the routing provider as Oracle.
id
is a required attribute that specifies an identification number to be associated with the request.
route_preference
is an optional attribute that specifies whether you want the route with the lowest estimated driving time (FASTEST
) or the route with the shortest driving distance (SHORTEST
, the default).
road_preference
is an optional attribute that specifies whether you want the route to use highways (HIGHWAY
, the default) or local roads (LOCAL
) when a choice is available.
return_driving_directions
is an optional attribute that specifies whether you want driving directions for the route. TRUE
returns driving directions; FALSE
(the default) does not return driving directions.
return_hierarchical_driving_directions
is an optional attribute that specifies whether you want driving directions for the route returned in an expandable and collapsible hierarchy. TRUE
returns driving directions in an expandable and collapsible hierarchy; FALSE
(the default) returns driving directions in a list with no hierarchy.
return_locations
is an optional attribute that specifies whether to return the start and end locations of the route and any subroutes. TRUE
(the default) returns these locations; FALSE
does not return these locations.
return_subroutes
is an optional attribute that specifies whether to return subroutes is a multiaddress route. TRUE
(the default for multiaddress routes) returns subroutes; FALSE
does not return subroutes. (This attributed is ignored for singleaddress routes.)
return_route_geometry
is an optional attribute that specifies whether you want the coordinates of each line string that represents a maneuver in the route. TRUE
returns the coordinates; FALSE
(the default) does not return the coordinates.
return_subroute_geometry
is an optional attribute that specifies whether you want the coordinates of each line string that represents a maneuver in each subroute. TRUE
returns the coordinates; FALSE
(the default for multiaddress routes) does not return the coordinates. (This attributed is ignored for singleaddress routes.)
return_segment_geometry
is an optional attribute that specifies whether you want the coordinates of the line string that represents the route. TRUE
returns the coordinates; FALSE
(the default) does not return the coordinates. If return_segment_geometry
is TRUE
, driving directions for the route are returned regardless of the value of the return_route_geometry
attribute.
return_detailed_geometry
is an optional attribute that indicates the level of detail to be included in returned geometries. TRUE
(the default) returns detailed geometries; FALSE
returns generalized geometries (usually with fewer coordinates).
return_route_edge_ids
is an optional attribute that specifies whether you want the edge ID values of the edges in the route. TRUE
returns the edge ID values; FALSE
(the default) does not return the edge ID values.
return_subroute_edge_ids
is an optional attribute that specifies whether you want the edge ID values of the edges in the subroutes. TRUE
returns the edge ID values; FALSE
(the default for multiaddress routes) does not return the edge ID values. (This attributed is ignored for singleaddress routes.)
return_segment_edge_ids
is an optional attribute that specifies whether you want the edge ID values of the edges of all maneuvers in the route. TRUE
returns the edge ID values; FALSE
(the default) does not return the edge ID values. If return_segment_edge_ids
is TRUE
, edge ID values are returned regardless of the value of the return_route_edge_ids
attribute.
language
is an optional attribute that overrides the default language used to generate the driving directions. The default language for is set in the web.xml
file; you can use this attribute to override the default on a perrequest basis. The following attribute values are supported: ENGLISH
, FRENCH
, GERMAN
, ITALIAN
, and SPANISH
.
distance_unit
is an optional attribute that specifies the unit of measure for distance values that are returned: KM
for kilometer, MILE
(the default) for mile, or METER
for meter.
time_unit
is an optional attribute that specifies the unit for time values that are returned: HOUR
for hour, MINUTE
(the default) for minute, or SECOND
for second.
pre_geocoded_locations
is an optional attribute that indicates how the start and end locations are specified. TRUE
means that both are previously geocoded locations specified using the <pre_geocoded_location>
element; FALSE
(the default) means that both are addresses specified using the <input_location>
element.
driving_directions_detail
is an optional attribute that influences the level of detail and the number of separate steps in driving instructions. The available values are HIGH
(most details and steps), MEDIUM
(the default), and LOW
(fewest details and steps). For example, LOW
might treat a segment as a single step even if it involves slight maneuvers to the right or left. The effect of a value for this attribute on the length of returned driving directions will vary, depending on the exact names of elements and maneuvers. This attribute is ignored if you do not specify TRUE
for return_driving_directions
or return_hierarchical_driving_directions
.
Note: The default level of detail changed in Oracle Database release 11.1, to provide fewer details and steps than before. If you want to have the same level of detail as in a previous release that did not have thedriving_directions_detail attribute, specify HIGH for the driving_directions_detail attribute. 
The <input_location>
element specifies an address in a format that satisfies the Oracle Spatial geocoding request DTD, which is described in Section 11.7.2. You can specify the input location using either the <Point>
element or the <input_address>
element. Example 131 in Section 13.3.1 shows the start and end addresses specified using the <input_location>
element and its child element <input_address>
.
To use the <input_location>
element, you must ensure that the value of the pre_geocoded_locations
attribute is FALSE
(the default) in the <route_request>
element. You can use the <Point>
and <input_address>
elements together in a request.
The <pre_geocoded_location>
element specifies a geocoded location in terms of how far along a street (an edge) the address is and on which side of the street. Example 135 in Section 13.3.1 shows the start and end addresses specified using the <pre_geocoded_location>
element.
To use the <pre_geocoded_location>
element, you must specify pre_geocoded_locations="TRUE"
in the <route_request>
element, and you must use the <pre_geocoded_location>
element to specify both the start and end locations.
The following is the complete DTD for a route response:
<?xml version="1.0" encoding="UTF8"?> <! route_response DTD includes the gmlgeometry DTD as an external entity reference. > <!ENTITY % GMLGEOMETRYDTD SYSTEM "gmlgeometry.dtd"> %GMLGEOMETRYDTD; <!ELEMENT route_response (route  router_error)> <!ELEMENT route (route_geometry?, segment+)> <!ATTLIST route id CDATA #REQUIRED step_count CDATA #IMPLIED time CDATA #IMPLIED distance CDATA #IMPLIED> <!ELEMENT router_error EMPTY> <!ATTLIST router_error id CDATA #REQUIRED error_code CDATA #IMPLIED error_msg CDATA #IMPLIED> <!ELEMENT route_geometry (LineString  MultiLineString)?> <!ELEMENT route_edge_ids (EdgeIDs)?> <!ELEMENT segment segment*, (LineString  MultiLineString)?> <!ATTLIST segment sequence CDATA #REQUIRED instruction CDATA #IMPLIED time CDATA #IMPLIED distance CDATA #IMPLIED> <!ELEMENT segment_geometry (LineString  MultiLineString)?> <!ELEMENT segment_edge_ids (EdgeIDs)?>
This section contains XML examples of batch route requests and the responses generated by those requests. One request uses specified addresses, and the other request uses previously geocoded locations. For reference information about the available elements and attributes, see Section 13.3.5 for requests and Section 13.3.6 for responses.
Example 137 shows a batch route request using specified addresses. The request is for the fastest routes, preferably using highways, between an office in Waltham, Massachusetts and three end locations (an Oracle office in Nashua, New Hampshire; the town offices in Concord, Massachusetts; and Boston City Hall), using miles for distances and minutes for times. The request calls for the returned routes to be sorted by distance between the start and end location, and for no routes over 35 miles to be returned.
Example 137 Batch Route Request with Specified Addresses
<?xml version="1.0" standalone="yes"?> <batch_route_request id="8" route_preference="fastest" road_preference="highway" return_driving_directions="false" sort_by_distance = "true" cutoff_distance="35" distance_unit="mile" time_unit="minute"> <start_location> <input_location id="1"> <input_address> <us_form1 street="1000 Winter St" lastline="Waltham, MA" /> </input_address> </input_location> </start_location> <end_location> <input_location id="10"> <input_address> <us_form1 street="1 Oracle Dr" lastline="Nashua, NH" /> </input_address> </input_location> </end_location> <end_location> <input_location id="11"> <input_address> <us_form1 street="22 Monument Sq" lastline="Concord, MA" /> </input_address> </input_location> </end_location> <end_location> <input_location id="12"> <input_address> <us_form1 street="1 City Hall Plaza" lastline="Boston, MA" /> </input_address> </input_location> </end_location> </batch_route_request>
Example 138 shows the response generated by the request in Example 137. (The output is reformatted for readability.)
Example 138 Batch Route Response with Specified Addresses
<?xml version="1.0" encoding="UTF8" standalone="yes" ?> <batch_route_response id="8"> <route id="11" step_count="0" distance="6.637544152543032" distance_unit="mile" time="10.53597412109375" e/ time_unit="minute" /> <route id="12" step_count="0" distance="17.204805418116575" distance_unit="mile" time="24.47645467122396" time_unit="minute" /> <route id="10" step_count="0" distance="29.855655894643636" distance_unit="mile" time="34.41252848307292" time_unit="minute" /> </batch_route_response>
Example 139 shows a batch route request using previously geocoded locations. The request is for the shortest routes, preferably using highways, between one location and three other locations, using miles for distances and minutes for times. The request calls for the returned routes to be sorted by distance between the start and end location, and for no routes over 50 miles to be returned.
Example 139 Batch Route Request with Previously Geocoded Locations
<?xml version="1.0" standalone="yes"?> <batch_route_request id="8" route_preference="shortest" road_preference="highway" return_driving_directions="false" distance_unit="mile" time_unit="minute" pre_geocoded_locations="true" cutoff_distance="50" sort_by_distance="true"> <start_location> <pre_geocoded_location id="1"> <edge_id>22161661</edge_id> <percent>.5</percent> <side>L</side> </pre_geocoded_location> </start_location> <end_location> <pre_geocoded_location id="2"> <edge_id>22104391</edge_id> <percent>.5</percent> <side>R</side> </pre_geocoded_location> </end_location> <end_location> <pre_geocoded_location id="3"> <edge_id>22160808</edge_id> <percent>.5</percent> <side>L</side> </pre_geocoded_location> </end_location> <end_location> <pre_geocoded_location id="4"> <edge_id>22325991</edge_id> <percent>.5</percent> <side>R</side> </pre_geocoded_location> </end_location> </batch_route_request>
Example 1310 shows the response to the request in Example 139. Only two routes are returned, because the third route is longer than the specified cutoff distance of 50 miles. (The output is reformatted for readability.)
Example 1310 Batch Route Response with Previously Geocoded Locations
<?xml version="1.0" encoding="UTF8" standalone="yes" ?> <batch_route_response id="8"> <route id="2" step_count="0" distance="0.6193447379707987" distance_unit="mile" time="1.6662169138590495" time_unit="minute" /> <route id="4" step_count="0" distance="41.342018851363946" distance_unit="mile" time="47.95714518229167" time_unit="minute" /> </batch_route_response>
The following is the complete DTD for a batch route request. The main elements and attributes of the DTD are explained in sections that follow.
<!ENTITY % GEOCODERDTD SYSTEM "geocoder.dtd"> %GEOCODERDTD; <! input_location element is defined in geocoder.dtd > <!ELEMENT batch_route_request (start_location, end_location+)> <!ATTLIST batch_route_request vendor CDATA "Oracle" id CDATA #REQUIRED route_preference (FASTEST  SHORTEST ) #IMPLIED road_preference (HIGHWAY  LOCAL) #IMPLIED distance_unit (KM  MILE  METER ) #IMPLIED time_unit (HOUR  MINUTE  SECOND) #IMPLIED sort_by_distance (TRUE  FALSE) #IMPLIED cutoff_distance CDATA #IMPLIED> <! The following are alternatives for specifying the location. Use input_location when you want to represent a location with a street address (input_address) or by longitude/latitude (Point). If you have already geocoded the location, you can use information from the geocoder response to construct a pre_geocoded_location element. The geocoder returns:  an edge_id (integer that is the road segment identifier)  a side ('L' or 'R' – left or right side)  a percent (floatingpoint number 0.0 to 1.0 representing the fraction of the length from the start of the road segment to this location. > <!ELEMENT pre_geocoded_location (edge_id, percent, side)> <!ATTLIST pre_geocoded_location id CDATA #REQUIRED> <!ELEMENT start_location (input_locationpre_geocoded_location)> <!ELEMENT end_location (input_locationpre_geocoded_location)> <! IMPORTANT VALIDITY CONSTRAINT: each of the input_location elements that are children of end_location MUST contain the id attribute. Normally, the id attribute is optional. If an id is not present, an exception will result. Also, each id must be unique within a batch_route_request. Otherwise, the request will yield unpredictable results. >
The <batch_route_request>
element has the following definition:
<!ELEMENT batch_route_request (start_location, end_location+)>
The root element of a route request is always named batch_route_request
.
The <start_location>
child element specifies the start location for the route, as an address specification, a geocoded address, or longitude/latitude point.
Each of the one or more <end_location>
child elements specifies the end location for the route, as an address specification, a geocoded address, or longitude/latitude point.
The root element <batch_route_request>
has a number of attributes, most of them optional. The attributes are defined as follows:
<!ATTLIST batch_route_request vendor CDATA "Oracle" id CDATA #REQUIRED route_preference (FASTESTSHORTEST) #IMPLIED road_preference (HIGHWAYLOCAL) #IMPLIED distance_unit (KMMILEMETER) #IMPLIED time_unit (HOURMINUTESECOND) #IMPLIED sort_by_distance (TRUE  FALSE) #IMPLIED cutoff_distance CDATA #IMPLIED> pre_geocoded_locations (TRUEFALSE) #IMPLIED>
Most <batch_route_request>
attributes have the same meaning as their counterpart <route_request>
attributes, which are explained in Section 13.3.5.2. In addition, the sort_by_distance
and cutoff_distance
attributes do not apply to single route requests.
sort_by_distance
is an optional attribute that specifies whether you want the routes returned in ascending order by distance of the end location from the start location. TRUE
sorts the returned routes by distance; FALSE
(the default) does not sort the returned routes by distance.
cutoff_distance
is an optional attribute that causes routes to be returned only where the end location is less than or equal to a specified distance from the start location. By default, all routes are returned.
Note: If a route is within the specifiedcutoff_distance value but would generate a <router_error> element in the response (see Section 13.3.6), the route is removed from the response and not shown. 
The following is the complete DTD for a batch route response:
<?xml version="1.0" encoding="UTF8"?> <!ELEMENT batch_route_response (route  route_error)+ > <!ATTLIST batch_route_response id CDATA #REQUIRED> <!ELEMENT route EMPTY> <!ATTLIST route id CDATA #REQUIRED step_count CDATA #IMPLIED distance CDATA #IMPLIED distance_unit CDATA #IMPLIED time CDATA #IMPLIED time_unit CDATA #IMPLIED> <!ELEMENT router_error EMPTY> <!ATTLIST router_error id CDATA #REQUIRED error_code CDATA #IMPLIED error_msg CDATA #IMPLIED>
Each database user of the routing engine must have the following tables in its schema:
EDGE
NODE
PARTITION
SIGN_POST
The EDGE and NODE tables store edge and node information about the street network used by the routing engine. To understand how edges and nodes are used to represent street segments, intersections, and other entities in a street network, you must be familiar with the Oracle Spatial network data model, which is described in Oracle Spatial Topology and Network Data Models Developer's Guide.
The following sections describe the tables used by the routing engine, in alphabetical order by table name.
The EDGE table contains one row for each directed edge in a street network. Each street segment (a part of a road between two nodes) is an undirected edge that corresponds to one or more directed edges in the EDGE table. The EDGE table contains the columns shown in Table 131.
Table 131 EDGE Table
Column Name  Data Type  Description 

EDGE_ID 
NUMBER 
Edge ID number. 
START_NODE_ID 
NUMBER 
Node ID number of the start node of this edge. 
END_NODE_ID 
NUMBER 
Node ID number of the end node of this edge. 
PARTITION_ID 
NUMBER 
Partition ID number of the network partition that contains this edge. 
FUNC_CLASS 
NUMBER 
Functional road class: a number from 1 through 5, with 1 indicating a large, highspeed, highvolume road, and each successive class generally smaller in size, speed, and volume. Class 2 roads have consistent speeds and are used to get traffic to and from class 1 roads. Class 3 roads have high volume and are used to connect class 2 roads. Class 4 roads move volumes of traffic between neighborhoods (for example, a busy main road in a city). Class 5 roads are all other roads (for example, a small, lowvolume street in a neighborhood). 
LENGTH 
NUMBER 
Length of this edge, in meters. 
SPEED_LIMIT 
NUMBER 
Assigned speed limit for this edge, in meters per second. 
GEOMETRY 
SDO_GEOMETRY 
Line string geometry representing this edge, with the coordinates ordered from the start node to the end node. 
NAME 
VARCHAR2(128) 
Name of this edge. 
DIVIDER 
VARCHAR2(1) 
A value of 
The NODE table contains one row for each node that is the start node or end node of one or more edges in the street network. A node often corresponds to an intersection (the intersection of two edges); however, a node can be independent of any intersection (for example, the end of a "dead end" or "no outlet" street). The NODE table contains the columns shown in Table 132.
The PARTITION table is generated by Oracle based on the contents of the EDGE and NODE tables. The PARTITION table contains the columns shown in Table 133.
Table 133 PARTITION Table
Column Name  Data Type  Description 

PARTITION_ID 
NUMBER 
Partition ID number. 
SUBNETWORK 
BLOB 
Part of the network included in this partition. 
NUM_NODES 
NUMBER 
Number of nodes in this partition. 
NUM_NON_BOUNDARY_EDGES 
NUMBER 
Number of edges in this partition that are edges that are completely contained within the partition. 
NUM_OUTGOING_BOUNDARY_EDGES 
NUMBER 
Number of edges in this partition that start in this partition and terminate in another partition. (An edge cannot be in more that two partitions; for example, an edge cannot start in one partition, go through a second partition, and end in a third partition.) 
NUM_INCOMING_BOUNDARY_EDGES 
NUMBER 
Number of edges in this partition that start in another partition and terminate in this partition. (An edge cannot be in more that two partitions; for example, an edge cannot start in one partition, go through a second partition, and end in a third partition.) 
The SIGN_POST table stores sign information that is used to generate driving directions. For example, a sign might indicate that Exit 33A on US Route 3 South goes toward Winchester. A SIGN_POST row might correspond to a physical sign at an exit ramp on a highway, but it does not need to correspond to a physical sign. The SIGN_POST table contains the columns shown in Table 134.
Table 134 SIGN_POST Table
Column Name  Data Type  Description 

FROM_EDGE_ID 
NUMBER 
Edge ID number of the edge to which this sign applies (for example, the street segment containing the exit ramp). 
TO_EDGE_ID 
NUMBER 
Edge ID number of the edge to which this sign points (for example, the street segment to which the exit ramp leads). 
RAMP 
VARCHAR2(64) 
Ramp text (for example, 
EXIT 
VARCHAR2(8) 
Exit number (for example, 
TOWARD 
VARCHAR2(64) 
Text indicating where the exit is heading (for example, 
The MDSYS.SDO_LRS package contains subprograms that create, modify, query, and convert linear referencing elements. These subprograms do not change the state of the database. Most LRS subprograms are functions.
To use the subprograms in this chapter, you must understand the linear referencing system (LRS) concepts and techniques described in Chapter 7.
Table 251 lists subprograms related to creating and editing geometric segments.
Table 251 Subprograms for Creating and Editing Geometric Segments
Subprogram  Description 


Defines a geometric segment. 

Populates the measures of all shape points of a geometric segment based on the start and end measures, overriding any previously assigned measures between the start point and end point. 

Clips a geometric segment (synonym of SDO_LRS.DYNAMIC_SEGMENT). 

Clips a geometric segment (synonym of SDO_LRS.CLIP_GEOM_SEGMENT). 
SDO_LRS.CONCATENATE_GEOM_SEGMENTS 
Concatenates two geometric segments into one segment. 

Returns an LRS geometry object that is the topological intersection (AND operation) of two geometry objects where one or both are LRS geometries. 

Returns the geometric segment at a specified offset from a geometric segment. 

Splits a geometric segment into two segments. 

Sets all measures of a geometric segment, including the start and end measures, to null values, overriding any previously assigned measures. 

Returns the geometry object resulting from a measure scaling operation on a geometric segment. 

Sets the measure value of a specified point. 

Returns a new geometric segment by reversing the measure values, but not the direction, of the original geometric segment. 

Returns a new geometric segment by translating the original geometric segment (that is, shifting the start and end measures by a specified value). 

Returns a new geometric segment by reversing the measure values and the direction of the original geometric segment. 
Table 252 lists subprograms related to querying geometric segments.
Table 252 Subprograms for Querying and Validating Geometric Segments
Subprogram  Description 


Checks if a geometric segment is valid. 

Checks if an LRS point is valid. 

Checks if a measure falls within the measure range of a geometric segment. 
SDO_LRS.CONNECTED_GEOM_SEGMENTS 
Checks if two geometric segments are spatially connected. 

Returns the length of a geometric segment. 

Returns the start point of a geometric segment. 

Returns the end point of a geometric segment. 
SDO_LRS.GEOM_SEGMENT_START_MEASURE 
Returns the start measure of a geometric segment. 
SDO_LRS.GEOM_SEGMENT_END_MEASURE 
Returns the end measure of a geometric segment. 

Returns the measure of an LRS point. 

Returns the next shape point on a geometric segment after a specified measure value or LRS point. 
SDO_LRS.GET_NEXT_SHAPE_PT_MEASURE 
Returns the measure value of the next shape point on a geometric segment after a specified measure value or LRS point. 

Returns the previous shape point on a geometric segment before a specified measure value or LRS point. 
SDO_LRS.GET_PREV_SHAPE_PT_MEASURE 
Returns the measure value of the previous shape point on a geometric segment before a specified measure value or LRS point. 
SDO_LRS.IS_GEOM_SEGMENT_DEFINED 
Checks if an LRS segment is defined correctly. 

Checks if the measure values along an LRS segment are decreasing (that is, descending in numerical value). 

Checks if the measure values along an LRS segment are increasing (that is, ascending in numerical value). 

Checks if a specified measure value is associated with a shape point on a geometric segment. 

Returns the measure range of a geometric segment, that is, the difference between the start measure and end measure. 

Returns the percentage (0 to 100) that a specified measure is of the measure range of a geometric segment. 

Returns the measure value of a specified percentage (0 to 100) of the measure range of a geometric segment. 

Returns the point located at a specified distance from the start of a geometric segment. 

Returns the projection point of a specified point. The projection point is on the geometric segment. 

Returns the position of the measure dimension within the SDO_DIM_ARRAY structure for a specified SDO_GEOMETRY column. 

Returns the measure of the closest point on a segment to a specified projection point. 

Returns the signed offset (shortest distance) from a point to a geometric segment. 

Checks if an LRS geometry is valid. 
Table 253 lists subprograms related to converting geometric segments.
Table 253 Subprograms for Converting Geometric Segments
Subprogram  Description 

SDO_LRS.CONVERT_TO_LRS_DIM_ARRAY 
Converts a standard dimensional array to an LRS dimensional array by creating a measure dimension. 

Converts a standard SDO_GEOMETRY line string to an LRS geometric segment by adding measure information. 

Converts all geometry objects in a column of type SDO_GEOMETRY from standard line string geometries without measure information to LRS geometric segments with measure information, and updates the metadata. 
SDO_LRS.CONVERT_TO_STD_DIM_ARRAY 
Converts an LRS dimensional array to a standard dimensional array by removing the measure dimension. 

Converts an LRS geometric segment to a standard SDO_GEOMETRY line string by removing measure information. 

Converts all geometry objects in a column of type SDO_GEOMETRY from LRS geometric segments with measure information to standard line string geometries without measure information, and updates the metadata. 
For more information about conversion subprograms, see Section 7.5.10.
The rest of this chapter provides reference information on the subprograms, listed in alphabetical order.
Format
SDO_LRS.CLIP_GEOM_SEGMENT(
geom_segment IN SDO_GEOMETRY,
start_measure IN NUMBER,
end_measure IN NUMBER,
tolerance IN NUMBER DEFAULT 1.0e8
) RETURN SDO_GEOMETRY;
or
SDO_LRS.CLIP_GEOM_SEGMENT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
start_measure IN NUMBER,
end_measure IN NUMBER
) RETURN SDO_GEOMETRY;
Description
Returns the geometry object resulting from a clip operation on a geometric segment.
Note: SDO_LRS.CLIP_GEOM_SEGMENT and SDO_LRS.DYNAMIC_SEGMENT are synonyms: both functions have the same parameters, behavior, and return value. 
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Start measure of the geometric segment.
End measure of the geometric segment.
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Usage Notes
An exception is raised if geom_segment
, start_measure
, or end_measure
is invalid.
start_measure
and end_measure
can be any points on the geometric segment. They do not have to be in any specific order. For example, start_measure
and end_measure
can be 5 and 10, respectively, or 10 and 5, respectively.
The direction and measures of the resulting geometric segment are preserved (that is, they reflect the original segment).
The _3D format of this function (SDO_LRS.CLIP_GEOM_SEGMENT_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
For more information about clipping geometric segments, see Section 7.5.3.
Examples
The following example clips the geometric segment representing Route 1, returning the segment from measures 5 through 10. This segment might represent a construction zone. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.CLIP_GEOM_SEGMENT(route_geometry, 5, 10) FROM lrs_routes WHERE route_id = 1; SDO_LRS.CLIP_GEOM_SEGMENT(ROUTE_GEOMETRY,5,10)(SDO_GTYPE, SDO_SRID, SDO_POINT(X,  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 5, 4, 5, 8, 4, 8, 10, 4, 10))
Format
SDO_LRS.CONCATENATE_GEOM_SEGMENTS(
geom_segment_1 IN SDO_GEOMETRY,
geom_segment_2 IN SDO_GEOMETRY,
tolerance IN NUMBER DEFAULT 1.0e8
) RETURN SDO_GEOMETRY;
or
SDO_LRS.CONCATENATE_GEOM_SEGMENTS(
geom_segment_1 IN SDO_GEOMETRY,
dim_array_1 IN SDO_DIM_ARRAY,
geom_segment_2 IN SDO_GEOMETRY,
dim_array_2 IN SDO_DIM_ARRAY
) RETURN SDO_GEOMETRY;
Parameters
First geometric segment to be concatenated.
Dimensional information array corresponding to geom_segment_1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Second geometric segment to be concatenated.
Dimensional information array corresponding to geom_segment_2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Usage Notes
An exception is raised if geom_segment_1
or geom_segment_2
has an invalid geometry type or dimensionality, or if geom_segment_1
and geom_segment_2
are based on different coordinate systems.
The direction of the first geometric segment is preserved, and all measures of the second segment are shifted so that its start measure is the same as the end measure of the first segment.
The geometry type of geom_segment_1
and geom_segment_2
must be line or multiline. Neither can be a polygon.
The _3D format of this function (SDO_LRS.CONCATENATE_GEOM_SEGMENTS_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
For more information about concatenating geometric segments, see Section 7.5.5.
Examples
The following example defines the geometric segment, splits it into two segments, then concatenates those segments. (This example uses the definitions from the example in Section 7.7. The definitions of result_geom_1
, result_geom_2
, and result_geom_3
are displayed in Example 73.)
DECLARE geom_segment SDO_GEOMETRY; line_string SDO_GEOMETRY; dim_array SDO_DIM_ARRAY; result_geom_1 SDO_GEOMETRY; result_geom_2 SDO_GEOMETRY; result_geom_3 SDO_GEOMETRY; BEGIN SELECT a.route_geometry into geom_segment FROM lrs_routes a WHERE a.route_name = 'Route1'; SELECT m.diminfo into dim_array from user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY';  Define the LRS segment for Route1. SDO_LRS.DEFINE_GEOM_SEGMENT (geom_segment, dim_array, 0,  Zero starting measure: LRS segment starts at start of route. 27);  End of LRS segment is at measure 27. SELECT a.route_geometry INTO line_string FROM lrs_routes a WHERE a.route_name = 'Route1';  Split Route1 into two segments. SDO_LRS.SPLIT_GEOM_SEGMENT(line_string,dim_array,5,result_geom_1,result_geom_2);  Concatenate the segments that were just split. result_geom_3 := SDO_LRS.CONCATENATE_GEOM_SEGMENTS(result_geom_1, dim_array, result_geom_2, dim_array);  Insert geometries into table, to display later. INSERT INTO lrs_routes VALUES( 11, 'result_geom_1', result_geom_1 ); INSERT INTO lrs_routes VALUES( 12, 'result_geom_2', result_geom_2 ); INSERT INTO lrs_routes VALUES( 13, 'result_geom_3', result_geom_3 ); END; /
Format
SDO_LRS.CONNECTED_GEOM_SEGMENTS(
geom_segment_1 IN SDO_GEOMETRY,
geom_segment_2 IN SDO_GEOMETRY,
tolerance IN NUMBER DEFAULT 1.0e8
) RETURN VARCHAR2;
or
SDO_LRS.CONNECTED_GEOM_SEGMENTS(
geom_segment_1 IN SDO_GEOMETRY,
dim_array_1 IN SDO_DIM_ARRAY,
geom_segment_2 IN SDO_GEOMETRY,
dim_array_2 IN SDO_DIM_ARRAY
) RETURN VARCHAR2;
Parameters
First of two geometric segments to be checked.
Dimensional information array corresponding to geom_segment_1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Second of two geometric segments to be checked.
Dimensional information array corresponding to geom_segment_2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Usage Notes
This function returns TRUE if the geometric segments are spatially connected and FALSE if the geometric segments are not spatially connected.
An exception is raised if geom_segment_1
or geom_segment_2
has an invalid geometry type or dimensionality, or if geom_segment_1
and geom_segment_2
are based on different coordinate systems.
The _3D format of this function (SDO_LRS.CONNECTED_GEOM_SEGMENTS_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example checks if two geometric segments (results of a previous split operation) are spatially connected.
 Are result_geom_1 and result_geom2 connected? SELECT SDO_LRS.CONNECTED_GEOM_SEGMENTS(a.route_geometry, b.route_geometry, 0.005) FROM lrs_routes a, lrs_routes b WHERE a.route_id = 11 AND b.route_id = 12; SDO_LRS.CONNECTED_GEOM_SEGMENTS(A.ROUTE_GEOMETRY,B.ROUTE_GEOMETRY,0.005)  TRUE
Format
SDO_LRS.CONVERT_TO_LRS_DIM_ARRAY(
dim_array IN SDO_DIM_ARRAY
[, lower_bound IN NUMBER,
upper_bound IN NUMBER,
tolerance IN NUMBER]
) RETURN SDO_DIM_ARRAY;
or
SDO_LRS.CONVERT_TO_LRS_DIM_ARRAY(
dim_array IN SDO_DIM_ARRAY,
dim_name IN VARCHAR2
[, lower_bound IN NUMBER,
upper_bound IN NUMBER,
tolerance IN NUMBER]
) RETURN SDO_DIM_ARRAY;
or
SDO_LRS.CONVERT_TO_LRS_DIM_ARRAY(
dim_array IN SDO_DIM_ARRAY,
dim_name IN VARCHAR2,
dim_pos IN INTEGER
[, lower_bound IN NUMBER,
upper_bound IN NUMBER,
tolerance IN NUMBER]
) RETURN SDO_DIM_ARRAY;
Description
Converts a standard dimensional array to an LRS dimensional array by creating a measure dimension.
Parameters
Dimensional information array corresponding to the layer (column of geometries) to be converted, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Name of the measure dimension (M
, if not otherwise specified).
Position of the measure dimension (the last SDO_DIM_ELEMENT object position in the SDO_DIM_ARRAY, if not otherwise specified).
Lower bound (SDO_LB value in the SDO_DIM_ELEMENT definition) of the ordinate in the measure dimension.
Upper bound (SDO_UB value in the SDO_DIM_ELEMENT definition) of the ordinate in the measure dimension.
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Usage Notes
This function converts a standard dimensional array to an LRS dimensional array by creating a measure dimension. Specifically, it adds an SDO_DIM_ELEMENT object at the end of the current SDO_DIM_ELEMENT objects in the SDO_DIM_ARRAY for the dimensional array (unless another dim_pos
is specified), and sets the SDO_DIMNAME value in this added SDO_DIM_ELEMENT to M (unless another dim_name
is specified). It sets the other values in the added SDO_DIM_ELEMENT according to the values of the upper_bound
, lower_bound
, and tolerance
parameter values.
If dim_array
already contains dimensional information, the dim_array
is returned.
The _3D format of this function (SDO_LRS.CONVERT_TO_LRS_DIM_ARRAY_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
For more information about conversion functions, see Section 7.5.10.
Examples
The following example converts the dimensional array for the LRS_ROUTES table to LRS format. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.CONVERT_TO_LRS_DIM_ARRAY(m.diminfo) FROM user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY'; SDO_LRS.CONVERT_TO_LRS_DIM_ARRAY(M.DIMINFO)(SDO_DIMNAME, SDO_LB, SDO_UB, SDO_TOL  SDO_DIM_ARRAY(SDO_DIM_ELEMENT('X', 0, 20, .005), SDO_DIM_ELEMENT('Y', 0, 20, .00 5), SDO_DIM_ELEMENT('M', 0, 20, .005))
Format
SDO_LRS.CONVERT_TO_LRS_GEOM(
standard_geom IN SDO_GEOMETRY
[, start_measure IN NUMBER,
end_measure IN NUMBER]
) RETURN SDO_GEOMETRY;
or
SDO_LRS.CONVERT_TO_LRS_GEOM(
standard_geom IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY
[, start_measure IN NUMBER,
end_measure IN NUMBER]
) RETURN SDO_GEOMETRY;
or
SDO_LRS.CONVERT_TO_LRS_GEOM(
standard_geom IN SDO_GEOMETRY,
m_pos IN INTEGER
[, start_measure IN NUMBER,
end_measure IN NUMBER]
) RETURN SDO_GEOMETRY;
Description
Converts a standard SDO_GEOMETRY line string to an LRS geometric segment by adding measure information.
Parameters
Line string geometry that does not contain measure information.
Dimensional information array corresponding to standard_geom
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Position of the measure dimension. If specified, must be 3 or 4. By default, the measure dimension is the last dimension in the SDO_DIM_ARRAY.
Distance measured from the start point of a geometric segment to the start point of the linear feature. The default is 0.
Distance measured from the end point of a geometric segment to the start point of the linear feature. The default is the cartographic length (for example, 75 if the cartographic length is 75 and the unit of measure is miles).
Usage Notes
This function returns an LRS geometric segment with measure information, with measure information provided for all shape points.
An exception is raised if standard_geom
has an invalid geometry type or dimensionality, if m_pos
is less than 3 or greater than 4, or if start_measure
or end_measure
is out of range.
The _3D format of this function (SDO_LRS.CONVERT_TO_LRS_GEOM_3D) is available; however, the m_pos
parameter is not available for SDO_LRS.CONVERT_TO_LRS_GEOM_3D. For information about _3D formats of LRS functions, see Section 7.4.
For more information about conversion functions, see Section 7.5.10.
Examples
The following example converts the geometric segment representing Route 1 to LRS format. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.CONVERT_TO_LRS_GEOM(a.route_geometry, m.diminfo) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.CONVERT_TO_LRS_GEOM(A.ROUTE_GEOMETRY,M.DIMINFO)(SDO_GTYPE, SDO_SRID, SDO  SDO_GEOMETRY(3002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 8, 4, 8, 12, 4, 12, 12, 10, NULL, 8, 10, 22, 5, 14, 27))
Format
SDO_LRS.CONVERT_TO_LRS_LAYER(
table_name IN VARCHAR2,
column_name IN VARCHAR2
[, lower_bound IN NUMBER,
upper_bound IN NUMBER,
tolerance IN NUMBER]
) RETURN VARCHAR2;
or
SDO_LRS.CONVERT_TO_LRS_LAYER(
table_name IN VARCHAR2,
column_name IN VARCHAR2,
dim_name IN VARCHAR2,
dim_pos IN INTEGER
[, lower_bound IN NUMBER,
upper_bound IN NUMBER,
tolerance IN NUMBER]
) RETURN VARCHAR2;
Description
Converts all geometry objects in a column of type SDO_GEOMETRY (that is, converts a layer) from standard line string geometries without measure information to LRS geometric segments with measure information, and updates the metadata in the USER_SDO_GEOM_METADATA view.
Parameters
Table containing the column with the SDO_GEOMETRY objects.
Column in table_name
containing the SDO_GEOMETRY objects.
Name of the measure dimension. If this parameter is null, M
is assumed.
Position of the measure dimension within the SDO_DIM_ARRAY structure for the specified SDO_GEOMETRY column. If this parameter is null, the number corresponding to the last position is assumed.
Lower bound (SDO_LB value in the SDO_DIM_ELEMENT definition) of the ordinate in the measure dimension.
Upper bound (SDO_UB value in the SDO_DIM_ELEMENT definition) of the ordinate in the measure dimension.
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Usage Notes
This function returns TRUE if the conversion was successful or if the layer already contains measure information, and the function returns an exception if the conversion was not successful.
An exception is raised if the existing dimensional information for the table is invalid.
The measure values are assigned based on a start measure of zero and an end measure of the cartographic length.
If a spatial index already exists on column_name
, you must delete (drop) the index before converting the layer and create a new index after converting the layer. For information about deleting and creating indexes, see the DROP INDEX and CREATE INDEX statements in Chapter 18.
The _3D format of this function (SDO_LRS.CONVERT_TO_LRS_LAYER_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
For more information about conversion functions, see Section 7.5.10.
Examples
The following example converts the geometric segments in the ROUTE_GEOMETRY column of the LRS_ROUTES table to LRS format. (This example uses the definitions from the example in Section 7.7.) The SELECT statement shows that dimensional information has been added (that is, SDO_DIM_ELEMENT('M', NULL, NULL, NULL)
is included in the definition).
BEGIN IF (SDO_LRS.CONVERT_TO_LRS_LAYER('LRS_ROUTES', 'ROUTE_GEOMETRY') = 'TRUE') THEN DBMS_OUTPUT.PUT_LINE('Conversion from STD_LAYER to LRS_LAYER succeeded.'); ELSE DBMS_OUTPUT.PUT_LINE('Conversion from STD_LAYER to LRS_LAYER failed.'); END IF; END; . / Conversion from STD_LAYER to LRS_LAYER succeeded. PL/SQL procedure successfully completed. SQL> SELECT diminfo FROM user_sdo_geom_metadata WHERE table_name = 'LRS_ROUTES' AND column_name = 'ROUTE_GEOMETRY'; DIMINFO(SDO_DIMNAME, SDO_LB, SDO_UB, SDO_TOLERANCE)  SDO_DIM_ARRAY(SDO_DIM_ELEMENT('X', 0, 20, .005), SDO_DIM_ELEMENT('Y', 0, 20, .00 5), SDO_DIM_ELEMENT('M', NULL, NULL, NULL))
Format
SDO_LRS.CONVERT_TO_STD_DIM_ARRAY(
dim_array IN SDO_DIM_ARRAY
[, m_pos IN INTEGER]
) RETURN SDO_DIM_ARRAY;
Description
Converts an LRS dimensional array to a standard dimensional array by removing the measure dimension.
Parameters
Dimensional information array corresponding to the layer (column of geometries) to be converted, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Position of the measure dimension. If specified, must be 3 or 4. By default, the measure dimension is the last dimension in the SDO_DIM_ARRAY.
Usage Notes
This function converts an LRS dimensional array to a standard dimensional array by removing the measure dimension. Specifically, it removes the SDO_DIM_ELEMENT object at the end of the current SDO_DIM_ELEMENT objects in the SDO_DIM_ARRAY for the dim_array
.
An exception is raised if m_pos
is invalid (less than 3 or greater than 4).
If dim_array
is already a standard dimensional array (that is, does not contain dimensional information), the dim_array
is returned.
The _3D format of this function (SDO_LRS.CONVERT_TO_STD_DIM_ARRAY_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
For more information about conversion functions, see Section 7.5.10.
Examples
The following example converts the dimensional array for the LRS_ROUTES table to standard format. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.CONVERT_TO_STD_DIM_ARRAY(m.diminfo) FROM user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY'; SDO_LRS.CONVERT_TO_STD_DIM_ARRAY(M.DIMINFO)(SDO_DIMNAME, SDO_LB, SDO_UB, SDO_TOL  SDO_DIM_ARRAY(SDO_DIM_ELEMENT('X', 0, 20, .005), SDO_DIM_ELEMENT('Y', 0, 20, .00 5))
Format
SDO_LRS.CONVERT_TO_STD_GEOM(
lrs _geom IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN SDO_GEOMETRY;
Description
Converts an LRS geometric segment to a standard SDO_GEOMETRY line string by removing measure information.
Parameters
LRS geometry that contains measure information.
Dimensional information array corresponding to lrs_geom
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns an SDO_GEOMETRY object in which all measure information is removed.
The _3D format of this function (SDO_LRS.CONVERT_TO_STD_GEOM_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
For more information about conversion functions, see Section 7.5.10.
Examples
The following example converts the geometric segment representing Route 1 to standard format. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.CONVERT_TO_STD_GEOM(a.route_geometry, m.diminfo) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.CONVERT_TO_STD_GEOM(A.ROUTE_GEOMETRY,M.DIMINFO)(SDO_GTYPE, SDO_SRID, SDO  SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 2, 4, 8, 4, 12, 4, 12, 10, 8, 10, 5, 14))
Format
SDO_LRS.CONVERT_TO_STD_LAYER(
table_name IN VARCHAR2,
column_name IN VARCHAR2
) RETURN VARCHAR2;
Description
Converts all geometry objects in a column of type SDO_GEOMETRY (that is, converts a layer) from LRS geometric segments with measure information to standard line string geometries without measure information, and updates the metadata in the USER_SDO_GEOM_METADATA view.
Parameters
Table containing the column with the SDO_GEOMETRY objects.
Column in table_name
containing the SDO_GEOMETRY objects.
Usage Notes
This function returns TRUE if the conversion was successful or if the layer already is a standard layer (that is, contains geometries without measure information), and the function returns an exception if the conversion was not successful.
If a spatial index already exists on column_name
, you must delete (drop) the index before converting the layer and create a new index after converting the layer. For information about deleting and creating indexes, see the DROP INDEX and CREATE INDEX statements in Chapter 18.
The _3D format of this function (SDO_LRS.CONVERT_TO_STD_LAYER_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
For more information about conversion functions, see Section 7.5.10.
Examples
The following example converts the geometric segments in the ROUTE_GEOMETRY column of the LRS_ROUTES table to standard format. (This example uses the definitions from the example in Section 7.7.) The SELECT statement shows that dimensional information has been removed (that is, no SDO_DIM_ELEMENT('M', NULL, NULL, NULL)
is included in the definition).
BEGIN IF (SDO_LRS.CONVERT_TO_STD_LAYER('LRS_ROUTES', 'ROUTE_GEOMETRY') = 'TRUE') THEN DBMS_OUTPUT.PUT_LINE('Conversion from LRS_LAYER to STD_LAYER succeeded.'); ELSE DBMS_OUTPUT.PUT_LINE('Conversion from LRS_LAYER to STD_LAYER failed.'); END IF; END; . / Conversion from LRS_LAYER to STD_LAYER succeeded. PL/SQL procedure successfully completed. SELECT diminfo FROM user_sdo_geom_metadata WHERE table_name = 'LRS_ROUTES' AND column_name = 'ROUTE_GEOMETRY'; DIMINFO(SDO_DIMNAME, SDO_LB, SDO_UB, SDO_TOLERANCE)  SDO_DIM_ARRAY(SDO_DIM_ELEMENT('X', 0, 20, .005), SDO_DIM_ELEMENT('Y', 0, 20, .00 5))
Format
SDO_LRS.DEFINE_GEOM_SEGMENT(
geom_segment IN OUT SDO_GEOMETRY
[, start_measure IN NUMBER,
end_measure IN NUMBER]);
or
SDO_LRS.DEFINE_GEOM_SEGMENT(
geom_segment IN OUT SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY
[, start_measure IN NUMBER,
end_measure IN NUMBER]);
Description
Defines a geometric segment by assigning start and end measures to a geometric segment, and assigns values to any null measures.
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Distance measured from the start point of a geometric segment to the start point of the linear feature. The default is the existing value (if any) in the measure dimension; otherwise, the default is 0.
Distance measured from the end point of a geometric segment to the start point of the linear feature. The default is the existing value (if any) in the measure dimension; otherwise, the default is the cartographic length of the segment.
Usage Notes
An exception is raised if geom_segment
has an invalid geometry type or dimensionality, or if start_measure
or end_measure
is out of range.
All unassigned measures of the geometric segment will be populated automatically.
To store the resulting geometric segment (geom_segment
) in the database, you must execute an UPDATE or INSERT statement, as appropriate.
The _3D format of this procedure (SDO_LRS.DEFINE_GEOM_SEGMENT_3D) is available. For information about _3D formats of LRS functions and procedures, see Section 7.4.
For more information about defining a geometric segment, see Section 7.5.1.
Examples
The following example defines the geometric segment, splits it into two segments, then concatenates those segments. (This example uses the definitions from the example in Section 7.7. The definitions of result_geom_1
, result_geom_2
, and result_geom_3
are displayed in Example 73.)
DECLARE geom_segment SDO_GEOMETRY; line_string SDO_GEOMETRY; dim_array SDO_DIM_ARRAY; result_geom_1 SDO_GEOMETRY; result_geom_2 SDO_GEOMETRY; result_geom_3 SDO_GEOMETRY; BEGIN SELECT a.route_geometry into geom_segment FROM lrs_routes a WHERE a.route_name = 'Route1'; SELECT m.diminfo into dim_array from user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY';  Define the LRS segment for Route1. This will populate any null measures. SDO_LRS.DEFINE_GEOM_SEGMENT (geom_segment, dim_array, 0,  Zero starting measure: LRS segment starts at start of route. 27);  End of LRS segment is at measure 27. SELECT a.route_geometry INTO line_string FROM lrs_routes a WHERE a.route_name = 'Route1';  Split Route1 into two segments. SDO_LRS.SPLIT_GEOM_SEGMENT(line_string,dim_array,5,result_geom_1,result_geom_2);  Concatenate the segments that were just split. result_geom_3 := SDO_LRS.CONCATENATE_GEOM_SEGMENTS(result_geom_1, dim_array, result_geom_2, dim_array);  Update and insert geometries into table, to display later. UPDATE lrs_routes a SET a.route_geometry = geom_segment WHERE a.route_id = 1; INSERT INTO lrs_routes VALUES( 11, 'result_geom_1', result_geom_1 ); INSERT INTO lrs_routes VALUES( 12, 'result_geom_2', result_geom_2 ); INSERT INTO lrs_routes VALUES( 13, 'result_geom_3', result_geom_3 ); END; /
Format
SDO_LRS.DYNAMIC_SEGMENT(
geom_segment IN SDO_GEOMETRY,
start_measure IN NUMBER,
end_measure IN NUMBER,
tolerance IN NUMBER DEFAULT 1.0e8
) RETURN SDO_GEOMETRY;
or
SDO_LRS.DYNAMIC_SEGMENT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
start_measure IN NUMBER,
end_measure IN NUMBER
) RETURN SDO_GEOMETRY;
Description
Returns the geometry object resulting from a clip operation on a geometric segment.
Note: SDO_LRS.CLIP_GEOM_SEGMENT and SDO_LRS.DYNAMIC_SEGMENT are synonyms: both functions have the same parameters, behavior, and return value. 
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Start measure of the geometric segment.
End measure of the geometric segment.
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Usage Notes
An exception is raised if geom_segment
, start_measure
, or end_measure
is invalid.
The direction and measures of the resulting geometric segment are preserved.
For more information about clipping a geometric segment, see Section 7.5.3.
Examples
The following example clips the geometric segment representing Route 1, returning the segment from measures 5 through 10. This segment might represent a construction zone. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.DYNAMIC_SEGMENT(route_geometry, 5, 10) FROM lrs_routes WHERE route_id = 1; SDO_LRS.DYNAMIC_SEGMENT(ROUTE_GEOMETRY,5,10)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 5, 4, 5, 8, 4, 8, 10, 4, 10))
Description
Returns the position of the measure dimension within the SDO_DIM_ARRAY structure for a specified SDO_GEOMETRY column.
Parameters
Table containing the column with the SDO_GEOMETRY objects.
Column in table_name
containing the SDO_GEOMETRY objects.
Examples
The following example returns the position of the measure dimension within the SDO_DIM_ARRAY structure for geometries in the ROUTE_GEOMETRY column of the LRS_ROUTES table. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.FIND_LRS_DIM_POS('LRS_ROUTES', 'ROUTE_GEOMETRY') FROM DUAL; SDO_LRS.FIND_LRS_DIM_POS('LRS_ROUTES','ROUTE_GEOMETRY')  3
Format
SDO_LRS.FIND_MEASURE(
geom_segment IN SDO_GEOMETRY,
point IN SDO_GEOMETRY
) RETURN NUMBER;
or
SDO_LRS.FIND_MEASURE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
point IN SDO_GEOMETRY
) RETURN NUMBER;
Parameters
Cartographic representation of a linear feature. This function returns the measure of the point on this segment that is closest to the projection point.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Projection point. This function returns the measure of the point on geom_segment
that is closest to the projection point.
Usage Notes
This function returns the measure of the point on geom_segment
that is closest to the projection point. For example, if the projection point represents a shopping mall, the function could be used to find how far from the start of the highway is the point on the highway that is closest to the shopping mall.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality, or if geom_segment
and point
are based on different coordinate systems.
The _3D format of this function (SDO_LRS.FIND_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example finds the measure for the point on the geometric segment representing Route 1 that is closest to the point (10, 7). (This example uses the definitions from the example in Section 7.7.)
 Find measure for point on segment closest to 10,7.  Should return 15 (for point 12,7). SELECT SDO_LRS.FIND_MEASURE(a.route_geometry, m.diminfo, SDO_GEOMETRY(3001, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(10, 7, NULL)) ) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.FIND_MEASURE(A.ROUTE_GEOMETRY,M.DIMINFO,SDO_GEOMETRY(3001,NULL,NUL  15
Format
SDO_LRS.FIND_OFFSET(
geom_segment IN SDO_GEOMETRY,
point IN SDO_GEOMETRY,
tolerance IN NUMBER DEFAULT 1.0e8
) RETURN NUMBER;
or
SDO_LRS.FIND_OFFSET(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
point IN SDO_GEOMETRY
[, point_dim_array IN SDO_GEOMETRY]
) RETURN NUMBER;
Parameters
Geometric segment to be checked for distance from point
.
Point whose shortest distance from geom_segment
is to be returned.
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Dimensional information array corresponding to point
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function calls the SDO_LRS.PROJECT_PT function format that includes the offset
output parameter: it passes in the geometric segment and point information, and it returns the SDO_LRS.PROJECT_PT offset
parameter value. Thus, to find the offset of a point from a geometric segment, you can use either this function or the SDO_LRS.PROJECT_PT function with the offset
parameter.
An exception is raised if geom_segment
or point
has an invalid geometry type or dimensionality, or if geom_segment
and point
are based on different coordinate systems.
For more information about offsets to a geometric segment, see Section 7.1.5.
Examples
The following example returns the offset of point (9,3,NULL) from the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.) As you can see from Figure 720 in Section 7.7, the point at (9,3,NULL) is on the right side along the segment, and therefore the offset has a negative value, as explained in Section 7.1.5. The point at (9,3.NULL) is one distance unit away from the point at (9,4,NULL), which is on the segment.
 Find the offset of point (9,3,NULL) from the road; should return 1. SELECT SDO_LRS.FIND_OFFSET(route_geometry, SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(9, 3, NULL)) ) FROM lrs_routes WHERE route_id = 1; SDO_LRS.FIND_OFFSET(ROUTE_GEOMETRY,SDO_GEOMETRY(3301,NULL,NULL,SDO_ELEM_INFO_ARR  1
Format
SDO_LRS.GEOM_SEGMENT_END_MEASURE(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN NUMBER;
Parameters
Geometric segment whose end measure is to be returned.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns the end measure of geom_segment
.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality.
The _3D format of this function (SDO_LRS.GEOM_SEGMENT_END_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the end measure of the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.GEOM_SEGMENT_END_MEASURE(route_geometry) FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_END_MEASURE(ROUTE_GEOMETRY)  27
Format
SDO_LRS.GEOM_SEGMENT_END_PT(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN SDO_GEOMETRY;
Parameters
Geometric segment whose end point is to be returned.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns the end point of geom_segment
.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality.
The _3D format of this function (SDO_LRS.GEOM_SEGMENT_END_PT_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the end point of the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.GEOM_SEGMENT_END_PT(route_geometry) FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_END_PT(ROUTE_GEOMETRY)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y,  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 5, 14, 27))
Format
SDO_LRS.GEOM_SEGMENT_LENGTH(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN NUMBER;
Parameters
Geometric segment whose length is to be calculated.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns the length of geom_segment
. The length is the geometric length, which is not the same as the total of the measure unit values. To determine how long a segment is in terms of measure units, subtract the result of an SDO_LRS.GEOM_SEGMENT_START_MEASURE operation from the result of an SDO_LRS.GEOM_SEGMENT_END_MEASURE operation.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality.
The _3D format of this function (SDO_LRS.GEOM_SEGMENT_LENGTH_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the length of the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.GEOM_SEGMENT_LENGTH(route_geometry) FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_LENGTH(ROUTE_GEOMETRY)  27
Format
SDO_LRS.GEOM_SEGMENT_START_MEASURE(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN NUMBER;
Parameters
Geometric segment whose start measure is to be returned.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns the start measure of geom_segment
.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality.
The _3D format of this function (SDO_LRS.GEOM_SEGMENT_START_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the start measure of the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.GEOM_SEGMENT_START_MEASURE(route_geometry) FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_START_MEASURE(ROUTE_GEOMETRY)  0
Format
SDO_LRS.GEOM_SEGMENT_START_PT(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN SDO_GEOMETRY;
Parameters
Geometric segment whose start point is to be returned.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns the start point of geom_segment
.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality.
The _3D format of this function (SDO_LRS.GEOM_SEGMENT_START_PT_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the start point of the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.GEOM_SEGMENT_START_PT(route_geometry) FROM lrs_routes WHERE route_id = 1; SDO_LRS.GEOM_SEGMENT_START_PT(ROUTE_GEOMETRY)(SDO_GTYPE, SDO_SRID, SDO_POINT(X,  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 2, 2, 0))
Parameters
Point whose measure is to be returned.
Dimensional information array corresponding to point
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns the measure of an LRS point.
If point
is not valid, an "invalid LRS point" exception is raised.
Contrast this function with SDO_LRS.PROJECT_PT, which accepts as input a point that is not necessarily on the geometric segment, but which returns a point that is on the geometric segment, as opposed to a measure value. As the following example shows, the SDO_LRS.GET_MEASURE function can be used to return the measure of the projected point returned by SDO_LRS.PROJECT_PT.
The _3D format of this function (SDO_LRS.GET_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the measure of a projected point. In this case, the point resulting from the projection is 9 units from the start of the segment.
SELECT SDO_LRS.GET_MEASURE( SDO_LRS.PROJECT_PT(a.route_geometry, m.diminfo, SDO_GEOMETRY(3001, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(9, 3, NULL)) ), m.diminfo ) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.GET_MEASURE(SDO_LRS.PROJECT_PT(A.ROUTE_GEOMETRY,M.DIMINFO,SDO_GEOM  9
Format
SDO_LRS.GET_NEXT_SHAPE_PT(
geom_segment IN SDO_GEOMETRY,
measure IN NUMBER
) RETURN SDO_GEOMETRY;
or
SDO_LRS.GET_NEXT_SHAPE_PT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER
) RETURN SDO_GEOMETRY;
or
SDO_LRS.GET_NEXT_SHAPE_PT(
geom_segment IN SDO_GEOMETRY,
point IN SDO_GEOMETRY
) RETURN SDO_GEOMETRY;
or
SDO_LRS.GET_NEXT_SHAPE_PT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
point IN SDO_GEOMETRY
) RETURN SDO_GEOMETRY;
Description
Returns the next shape point on a geometric segment after a specified measure value or LRS point.
Parameters
Geometric segment.
Measure value on the geometric segment for which to return the next shape point.
Point for which to return the next shape point. If point
is not on geom_segment
, the point on the geometric segment closest to the specified point is computed, and the next shape point after that point is returned.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
If measure
or point
identifies the end point of the geometric segment, a null value is returned.
An exception is raised if measure
is not a valid value for geom_segment
or if point
is not a valid LRS point.
Contrast this function with SDO_LRS.GET_PREV_SHAPE_PT, which returns the previous shape point on a geometric segment before a specified measure value or LRS point.
The _3D format of this function (SDO_LRS.GET_NEXT_SHAPE_PT_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the next shape point after measure 14 on the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.GET_NEXT_SHAPE_PT(a.route_geometry, 14) FROM lrs_routes a WHERE a.route_id = 1; SDO_LRS.GET_NEXT_SHAPE_PT(A.ROUTE_GEOMETRY,14)(SDO_GTYPE, SDO_SRID, SDO_POINT(X,  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 12, 10, 18))
SDO_LRS.GET_NEXT_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
measure IN NUMBER
) RETURN NUMBER;
or
SDO_LRS.GET_NEXT_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER
) RETURN NUMBER;
or
SDO_LRS.GET_NEXT_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
point IN SDO_GEOMETRY
) RETURN NUMBER;
or
SDO_LRS.GET_NEXT_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
point IN SDO_GEOMETRY
) RETURN NUMBER;
Description
Returns the measure value of the next shape point on a geometric segment after a specified measure value or LRS point.
Parameters
Geometric segment.
Measure value on the geometric segment for which to return the measure value of the next shape point.
Point for which to return the measure value of the next shape point. If point
is not on geom_segment
, the point on the geometric segment closest to the specified point is computed, and the measure value of the next shape point after that point is returned.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
If measure
or point
identifies the end point of the geometric segment, a null value is returned.
An exception is raised if measure
is not a valid value for geom_segment
or if point
is not a valid LRS point.
Contrast this function with SDO_LRS.GET_PREV_SHAPE_PT_MEASURE, which returns the measure value of the previous shape point on a geometric segment before a specified measure value or LRS point.
The _3D format of this function (SDO_LRS.GET_NEXT_SHAPE_PT_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the measure value of the next shape point after measure 14 on the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.GET_NEXT_SHAPE_PT_MEASURE(a.route_geometry, 14) FROM lrs_routes a WHERE a.route_id = 1; SDO_LRS.GET_NEXT_SHAPE_PT_MEASURE(A.ROUTE_GEOMETRY,14)  18
Format
SDO_LRS.GET_PREV_SHAPE_PT(
geom_segment IN SDO_GEOMETRY,
measure IN NUMBER
) RETURN SDO_GEOMETRY;
or
SDO_LRS.GET_PREV_SHAPE_PT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER
) RETURN SDO_GEOMETRY;
or
SDO_LRS.GET_PREV_SHAPE_PT(
geom_segment IN SDO_GEOMETRY,
point IN SDO_GEOMETRY
) RETURN SDO_GEOMETRY;
or
SDO_LRS.GET_PREV_SHAPE_PT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
point IN SDO_GEOMETRY
) RETURN SDO_GEOMETRY;
Description
Returns the previous shape point on a geometric segment before a specified measure value or LRS point.
Parameters
Geometric segment.
Measure value on the geometric segment for which to return the previous shape point.
Point for which to return the previous shape point. If point
is not on geom_segment
, the point on the geometric segment closest to the specified point is computed, and the closest shape point before that point is returned.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
If measure
or point
identifies the start point of the geometric segment, a null value is returned.
An exception is raised if measure
is not a valid value for geom_segment
or if point
is not a valid LRS point.
Contrast this function with SDO_LRS.GET_NEXT_SHAPE_PT, which returns the next shape point on a geometric segment after a specified measure value or LRS point.
The _3D format of this function (SDO_LRS.GET_PREV_SHAPE_PT_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the closest shape point to measure 14 and before measure 14 on the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.GET_PREV_SHAPE_PT(a.route_geometry, 14) FROM lrs_routes a WHERE a.route_id = 1; SDO_LRS.GET_PREV_SHAPE_PT(A.ROUTE_GEOMETRY,14)(SDO_GTYPE, SDO_SRID, SDO_POINT(X,  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 12, 4, 12))
Format
SDO_LRS.GET_PREV_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
measure IN NUMBER
) RETURN NUMBER;
or
SDO_LRS.GET_PREV_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER
) RETURN NUMBER;
or
SDO_LRS.GET_PREV_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
point IN SDO_GEOMETRY
) RETURN NUMBER;
or
SDO_LRS.GET_PREV_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
point IN SDO_GEOMETRY
) RETURN NUMBER;
Description
Returns the measure value of the previous shape point on a geometric segment before a specified measure value or LRS point.
Parameters
Geometric segment.
Measure value on the geometric segment for which to return the measure value of the previous shape point.
Point for which to return the measure value of the previous shape point. If point
is not on geom_segment
, the point on the geometric segment closest to the specified point is computed, and the measure value of the closest shape point before that point is returned.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
If measure
or point
identifies the start point of the geometric segment, a null value is returned.
An exception is raised if measure
is not a valid value for geom_segment
or if point
is not a valid LRS point.
Contrast this function with SDO_LRS.GET_NEXT_SHAPE_PT_MEASURE, which returns the measure value of the next shape point on a geometric segment after a specified measure value or LRS point.
The _3D format of this function (SDO_LRS.GET_PREV_SHAPE_PT_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the measure value of the closest shape point to measure 14 and before measure 14 on the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.GET_PREV_SHAPE_PT_MEASURE(a.route_geometry, 14) FROM lrs_routes a WHERE a.route_id = 1; SDO_LRS.GET_PREV_SHAPE_PT_MEASURE(A.ROUTE_GEOMETRY,14)  12
Format
SDO_LRS.IS_GEOM_SEGMENT_DEFINED(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN VARCHAR2;
Parameters
Geometric segment to be checked.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns TRUE if geom_segment
is defined correctly and FALSE if geom_segment
is not defined correctly.
The start and end measures of geom_segment
must be defined (cannot be null), and any measures assigned must be in an ascending or descending order along the segment direction.
The _3D format of this function (SDO_LRS.IS_GEOM_SEGMENT_DEFINED_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
See also the SDO_LRS.VALID_GEOM_SEGMENT function.
Examples
The following example checks if the geometric segment representing Route 1 is defined. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.IS_GEOM_SEGMENT_DEFINED(route_geometry) FROM lrs_routes WHERE route_id = 1; SDO_LRS.IS_GEOM_SEGMENT_DEFINED(ROUTE_GEOMETRY)  TRUE
Format
SDO_LRS.IS_MEASURE_DECREASING(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN VARCHAR2;
Description
Checks if the measure values along an LRS segment are decreasing (that is, descending in numerical value).
Parameters
Geometric segment to be checked.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns TRUE if the measure values along an LRS segment are decreasing and FALSE if the measure values along an LRS segment are not decreasing.
The start and end measures of geom_segment
must be defined (cannot be null).
The _3D format of this function (SDO_LRS.IS_MEASURE_DECREASING_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
See also the SDO_LRS.IS_MEASURE_INCREASING function.
Examples
The following example checks if the measure values along the geometric segment representing Route 1 are decreasing. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.IS_MEASURE_DECREASING(a.route_geometry, m.diminfo) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.IS_MEASURE_DECREASING(A.ROUTE_GEOMETRY,M.DIMINFO)  FALSE
Format
SDO_LRS.IS_MEASURE_INCREASING(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN VARCHAR2;
Description
Checks if the measure values along an LRS segment are increasing (that is, ascending in numerical value).
Parameters
Geometric segment to be checked.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns TRUE if the measure values along an LRS segment are increasing and FALSE if the measure values along an LRS segment are not increasing.
The start and end measures of geom_segment
must be defined (cannot be null).
The _3D format of this function (SDO_LRS.IS_MEASURE_INCREASING_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
See also the SDO_LRS.IS_MEASURE_DECREASING function.
Examples
The following example checks if the measure values along the geometric segment representing Route 1 are increasing. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.IS_MEASURE_INCREASING(a.route_geometry, m.diminfo) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.IS_MEASURE_INCREASING(A.ROUTE_GEOMETRY,M.DIMINFO)  TRUE
Format
SDO_LRS.IS_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
measure IN NUMBER
) RETURN VARCHAR2;
or
SDO_LRS.IS_SHAPE_PT_MEASURE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER
) RETURN VARCHAR2;
Description
Checks if a specified measure value is associated with a shape point on a geometric segment.
Parameters
Geometric segment to be checked.
Measure value on the geometric segment to check if it is a shape point.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns TRUE if the specified measure value is associated with a shape point and FALSE if the measure value is not associated with a shape point.
An exception is raised if measure
is not a valid value for geom_segment
.
The _3D format of this function (SDO_LRS.IS_SHAPE_PT_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example checks if measure 14 on the geometric segment representing Route 1 is a shape point. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.IS_SHAPE_PT_MEASURE(a.route_geometry, 14) FROM lrs_routes a WHERE a.route_id = 1; SDO_LRS.IS_SHAPE_PT_MEASURE(A.ROUTE_GEOMETRY,14)  FALSE
Format
SDO_LRS.LOCATE_PT(
geom_segment IN SDO_GEOMETRY,
measure IN NUMBER
[, offset IN NUMBER
) RETURN SDO_GEOMETRY;
or
SDO_LRS.LOCATE_PT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER
[, offset IN NUMBER]
) RETURN SDO_GEOMETRY;
Description
Returns the point located at a specified distance from the start of a geometric segment.
Parameters
Geometric segment to be checked to see if it falls within the measure range of measure
.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Distance to measure from the start point of geom_segment
.
Distance to measure perpendicularly from the point that is located at measure
units from the start point of geom_segment
. The default is 0 (that is, the point is on geom_segment
).
Usage Notes
This function returns the referenced point. For example, on a highway, the point might represent the location of an accident.
The unit of measurement for offset
is the same as for the coordinate system associated with geom_segment
. For geodetic data, the default unit of measurement is meters.
With geodetic data using the WGS 84 coordinate system, this function can be used to return the longitude and latitude coordinates of any point on or offset from the segment.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality, or if the location is out of range.
The _3D format of this function (SDO_LRS.LOCATE_PT_3D) is available; however, the offset
parameter is not available for SDO_LRS.LOCATE_PT_3D. For information about _3D formats of LRS functions, see Section 7.4.
For more information about locating a point on a geometric segment, see Section 7.5.8.
Examples
The following example creates a table for automobile accident data, inserts a record for an accident at the point at measure 9 and on (that is, offset 0) the geometric segment representing Route 1, and displays the data. (The accident table is deliberately oversimplified. This example also uses the route definition from the example in Section 7.7.)
 Create a table for accidents. CREATE TABLE accidents ( accident_id NUMBER PRIMARY KEY, route_id NUMBER, accident_geometry SDO_GEOMETRY);  Insert an accident record. DECLARE geom_segment SDO_GEOMETRY; BEGIN SELECT SDO_LRS.LOCATE_PT(a.route_geometry, 9, 0) into geom_segment FROM lrs_routes a WHERE a.route_name = 'Route1'; INSERT INTO accidents VALUES(1, 1, geom_segment); END; / SELECT * from accidents; ACCIDENT_ID ROUTE_ID   ACCIDENT_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_OR  1 1 SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 9, 4, 9))
Format
SDO_LRS.LRS_INTERSECTION(
geom_1 IN SDO_GEOMETRY,
dim_array_1 IN SDO_DIM_ARRAY,
geom_2 IN SDO_GEOMETRY,
dim_array_2 IN SDO_DIM_ARRAY
) RETURN SDO_GEOMETRY;
or
SDO_LRS.LRS_INTERSECTION(
geom_1 IN SDO_GEOMETRY,
geom_2 IN SDO_GEOMETRY,
tolerance IN NUMBER
) RETURN SDO_GEOMETRY;
Description
Returns an LRS geometry object that is the topological intersection (AND operation) of two geometry objects where one or both are LRS geometries.
Parameters
Geometry object.
Dimensional information array corresponding to geom_1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Geometry object.
Dimensional information array corresponding to geom_2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5).
Usage Notes
This function performs essentially the same intersection operation as the SDO_GEOM.SDO_INTERSECTION function (described in Chapter 24), except that SDO_LRS.LRS_INTERSECTION is designed to return a valid LRS geometry (point, line string, or multiline string) where one or both of the geometryrelated input parameters are LRS geometries. (If neither input geometry is an LRS geometry, this function operates the same as the SDO_GEOM.SDO_INTERSECTION function.).
The returned geometry is an LRS line string, multiline string, or point geometry that includes measure dimension information. The measure values reflect those in the first LRS geometry specified as an input parameter.
The first LRS geometry specified as an input parameter must not be a polygon; it must be a line string, multiline string, or point.
If an LRS line string (geometric segment) intersects a line string (LRS or standard), the result is an LRS point; if an LRS line string intersects a polygon, the result is an LRS line string.
An exception is raised if geom_1
and geom_2
are based on different coordinate systems.
Examples
The following example shows an LRS geometric segment (illustrated in Figure 720 in Section 7.7) intersected by a vertical line from (8,2) to (8,6). The result is an LRS point geometry, in which the measure value (8) reflects the measure for that point (designated as Exit 3 in Figure 720) in the geom_1
geometry. (This example uses the definitions from the example in Section 7.7.)
 Intersection of LRS segment and standard line segment SELECT SDO_LRS.LRS_INTERSECTION(route_geometry, SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1,2,1), SDO_ORDINATE_ARRAY(8,2, 8,6)), 0.005) FROM lrs_routes WHERE route_id = 1; SDO_LRS.LRS_INTERSECTION(ROUTE_GEOMETRY,SDO_GEOMETRY(2002,NULL,NULL,SDO_ELEM_INF  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 8, 4, 8))
The following example shows an LRS geometric segment (illustrated in Figure 720 in Section 7.7) intersected by a vertical line from (12,2) to (12,6). The result is an LRS line string geometry, in which the measure values (12 and 14) reflect measures for points (the first of which is designated as Exit 4 in Figure 720) in the geom_1
geometry. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.LRS_INTERSECTION(route_geometry, SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1,2,1), SDO_ORDINATE_ARRAY(12,2, 12,6)), 0.005) FROM lrs_routes WHERE route_id = 1; SDO_LRS.LRS_INTERSECTION(ROUTE_GEOMETRY,SDO_GEOMETRY(2002,NULL,NULL,SDO_ELEM_INF  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 12, 4, 12, 12, 6, 14))
Format
SDO_LRS.MEASURE_RANGE(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN NUMBER;
Description
Returns the measure range of a geometric segment, that is, the difference between the start measure and end measure.
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function subtracts the start measure of geom_segment
from the end measure of geom_segment
.
The _3D format of this function (SDO_LRS.MEASURE_RANGE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example returns the measure range of the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.MEASURE_RANGE(route_geometry) FROM lrs_routes WHERE route_id = 1; SDO_LRS.MEASURE_RANGE(ROUTE_GEOMETRY)  27
Format
SDO_LRS.MEASURE_TO_PERCENTAGE(
geom_segment IN SDO_GEOMETRY,
measure IN NUMBER
) RETURN NUMBER;
or
SDO_LRS.MEASURE_TO_PERCENTAGE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER
) RETURN NUMBER;
Description
Returns the percentage (0 to 100) that a specified measure is of the measure range of a geometric segment.
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Measure value. This function returns the percentage that this measure value is of the measure range.
Usage Notes
This function returns a number (0 to 100) that is the percentage of the measure range that the specified measure represents. (The measure range is the end measure minus the start measure.) For example, if the measure range of geom_segment
is 50 and measure
is 20, the function returns 40 (because 20/50 = 40%).
This function performs the reverse of the SDO_LRS.PERCENTAGE_TO_MEASURE function, which returns the measure that corresponds to a percentage value.
An exception is raised if geom_segment
or measure
is invalid.
Examples
The following example returns the percentage that 5 is of the measure range of the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.) The measure range of this segment is 27, and 5 is approximately 18.5 percent of 27.
SELECT SDO_LRS.MEASURE_TO_PERCENTAGE(a.route_geometry, m.diminfo, 5) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.MEASURE_TO_PERCENTAGE(A.ROUTE_GEOMETRY,M.DIMINFO,5)  18.5185185
Format
SDO_LRS.OFFSET_GEOM_SEGMENT(
geom_segment IN SDO_GEOMETRY,
start_measure IN NUMBER,
end_measure IN NUMBER,
offset IN NUMBER,
tolerance IN NUMBER DEFAULT 1.0e8
[, unit IN VARCHAR2]
) RETURN SDO_GEOMETRY;
or
SDO_LRS.OFFSET_GEOM_SEGMENT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
start_measure IN NUMBER,
end_measure IN NUMBER,
offset IN NUMBER
[, unit IN VARCHAR2]
) RETURN SDO_GEOMETRY;
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Start measure of geom_segment
at which to start the offset operation.
End measure of geom_segment
at which to start the offset operation.
Distance to measure perpendicularly from the points along geom_segment
. Positive offset values are to the left of geom_segment
; negative offset values are to the right of geom_segment
.
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Unit of measurement specification: a quoted string with one or both of the following keywords:
unit
and an SDO_UNIT value from the MDSYS.SDO_DIST_UNITS table. 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 Chapter 24 for more information about the arc_tolerance
keyword.
For example: 'unit=km arc_tolerance=0.05'
If the input geometry is geodetic data, this parameter is required, and arc_tolerance
must be specified. 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
start_measure
and end_measure
can be any points on the geometric segment. They do not have to be in any specific order. For example, start_measure
and end_measure
can be 5 and 10, respectively, or 10 and 5, respectively.
The direction and measures of the resulting geometric segment are preserved (that is, they reflect the original segment).
The geometry type of geom_segment
must be line or multiline. For example, it cannot be a polygon.
An exception is raised if geom_segment
, start_measure
, or end_measure
is invalid.
Examples
The following example returns the geometric segment 2 distance units to the left (positive offset 2) of the segment from measures 5 through 10 of Route 1. Note in SDO_ORDINATE_ARRAY of the returned segment that the Y values (6) are 2 greater than the Y values (4) of the relevant part of the original segment. (This example uses the definitions from the example in Section 7.7.)
 Create a segment offset 2 to the left from measures 5 through 10.  First, display the original segment; then, offset. SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 8, 4, 8, 12, 4, 12, 12, 10, 18, 8, 10, 22, 5, 14, 27)) SELECT SDO_LRS.OFFSET_GEOM_SEGMENT(a.route_geometry, m.diminfo, 5, 10, 2) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.OFFSET_GEOM_SEGMENT(A.ROUTE_GEOMETRY,M.DIMINFO,5,10,2)(SDO_GTYPE, SDO_SR  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 5, 6, 5, 10, 6, 10))
Format
SDO_LRS.PERCENTAGE_TO_MEASURE(
geom_segment IN SDO_GEOMETRY,
percentage IN NUMBER
) RETURN NUMBER;
or
SDO_LRS.PERCENTAGE_TO_MEASURE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
percentage IN NUMBER
) RETURN NUMBER;
Description
Returns the measure value of a specified percentage (0 to 100) of the measure range of a geometric segment.
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Percentage value. Must be from 0 to 100. This function returns the measure value corresponding to this percentage of the measure range.
Usage Notes
This function returns the measure value corresponding to the specified percentage of the measure range. (The measure range is the end measure minus the start measure.) For example, if the measure range of geom_segment
is 50 and percentage
is 40, the function returns 20 (because 40% of 50 = 20).
This function performs the reverse of the SDO_LRS.MEASURE_TO_PERCENTAGE function, which returns the percentage value that corresponds to a measure.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality, or if percentage
is less than 0 or greater than 100.
Examples
The following example returns the measure that is 50 percent of the measure range of the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.) The measure range of this segment is 27, and 50 percent of 27 is 13.5.
SELECT SDO_LRS.PERCENTAGE_TO_MEASURE(a.route_geometry, m.diminfo, 50) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.PERCENTAGE_TO_MEASURE(A.ROUTE_GEOMETRY,M.DIMINFO,50)  13.5
Format
SDO_LRS.PROJECT_PT(
geom_segment IN SDO_GEOMETRY,
point IN SDO_GEOMETRY,
tolerance IN NUMBER DEFAULT 1.0e8
[, offset OUT NUMBER]
) RETURN SDO_GEOMETRY;
or
SDO_LRS.PROJECT_PT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
point IN SDO_GEOMETRY
[, point_dim_array IN SDO_DIM_ARRAY]
) RETURN SDO_GEOMETRY;
or
SDO_LRS.PROJECT_PT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
point IN SDO_GEOMETRY,
point_dim_array IN SDO_DIM_ARRAY
[, offset OUT NUMBER]
) RETURN SDO_GEOMETRY;
Description
Returns the projection point of a specified point. The projection point is on the geometric segment.
Parameters
Geometric segment to be checked.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Point to be projected.
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Dimensional information array corresponding to point
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Offset (shortest distance) from the point to the geometric segment.
Usage Notes
This function returns the projection point (including its measure) of a specified point (point
). The projection point is on the geometric segment.
If multiple projection points exist, the first projection point encountered from the start point is returned.
If you specify the output parameter offset
, the function stores the signed offset (shortest distance) from the point to the geometric segment. For more information about the offset to a geometric segment, see Section 7.1.5.
An exception is raised if geom_segment
or point
has an invalid geometry type or dimensionality, or if geom_segment
and point
are based on different coordinate systems.
The _3D format of this function (SDO_LRS.PROJECT_PT_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
For more information about projecting a point onto a geometric segment, see Section 7.5.9.
Examples
The following example returns the point (9,4,9) on the geometric segment representing Route 1 that is closest to the specified point (9,3,NULL). (This example uses the definitions from the example in Section 7.7.)
 Point 9,3,NULL is off the road; should return 9,4,9. SELECT SDO_LRS.PROJECT_PT(route_geometry, SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(9, 3, NULL)) ) FROM lrs_routes WHERE route_id = 1; SDO_LRS.PROJECT_PT(ROUTE_GEOMETRY,SDO_GEOMETRY(3301,NULL,NULL,SDO_EL  SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY( 9, 4, 9))
Format
SDO_LRS.REDEFINE_GEOM_SEGMENT(
geom_segment IN OUT SDO_GEOMETRY
[, start_measure IN NUMBER,
end_measure IN NUMBER]);
or
SDO_LRS.REDEFINE_GEOM_SEGMENT(
geom_segment IN OUT SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY
[, start_measure IN NUMBER,
end_measure IN NUMBER]);
Description
Populates the measures of all shape points based on the start and end measures of a geometric segment, overriding any previously assigned measures between the start point and end point.
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Distance measured from the start point of a geometric segment to the start point of the linear feature. The default is the existing value (if any) in the measure dimension; otherwise, the default is 0.
Distance measured from the end point of a geometric segment to the start point of the linear feature. The default is the existing value (if any) in the measure dimension; otherwise, the default is the cartographic length of the segment.
Usage Notes
An exception is raised if geom_segment
has an invalid geometry type or dimensionality, or if start_measure
or end_measure
is out of range.
The _3D format of this procedure (SDO_LRS.REDEFINE_GEOM_SEGMENT_3D) is available. For information about _3D formats of LRS functions and procedures, see Section 7.4.
For more information about redefining a geometric segment, see Section 7.5.2.
Examples
The following example redefines a geometric segment, effectively converting miles to kilometers in the measure values. (This example uses the definitions from the example in Section 7.7.)
 First, display the original segment; then, redefine. SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 8, 4, 8, 12, 4, 12, 12, 10, 18, 8, 10, 22, 5, 14, 27))  Redefine geometric segment to "convert" miles to kilometers. DECLARE geom_segment SDO_GEOMETRY; dim_array SDO_DIM_ARRAY; BEGIN SELECT a.route_geometry into geom_segment FROM lrs_routes a WHERE a.route_name = 'Route1'; SELECT m.diminfo into dim_array from user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY';  "Convert" mile measures to kilometers (27 * 1.609 = 43.443). SDO_LRS.REDEFINE_GEOM_SEGMENT (geom_segment, dim_array, 0,  Zero starting measure: LRS segment starts at start of route. 43.443);  End of LRS segment. 27 miles = 43.443 kilometers.  Update and insert geometries into table, to display later. UPDATE lrs_routes a SET a.route_geometry = geom_segment WHERE a.route_id = 1; END; / PL/SQL procedure successfully completed.  Display the redefined segment, with all measures "converted." SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 3.218, 8, 4, 12.872, 12, 4, 19.308, 12, 10, 28.962, 8, 10, 35.398 , 5, 14, 43.443))
Description
Sets all measures of a geometric segment, including the start and end measures, to null values, overriding any previously assigned measures.
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Examples
The following example sets all measures of a geometric segment to null values. (This example uses the definitions from the example in Section 7.7.)
 First, display the original segment; then, redefine. SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 8, 4, 8, 12, 4, 12, 12, 10, 18, 8, 10, 22, 5, 14, 27))  Reset geometric segment measures. DECLARE geom_segment SDO_GEOMETRY; BEGIN SELECT a.route_geometry into geom_segment FROM lrs_routes a WHERE a.route_name = 'Route1'; SDO_LRS.RESET_MEASURE (geom_segment);  Update and insert geometries into table, to display later. UPDATE lrs_routes a SET a.route_geometry = geom_segment WHERE a.route_id = 1; END; / PL/SQL procedure successfully completed.  Display the segment, with all measures set to null. SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, NULL, 2, 4, NULL, 8, 4, NULL, 12, 4, NULL, 12, 10, NULL, 8, 10, NULL, 5, 1 4, NULL))
Format
SDO_LRS.REVERSE_GEOMETRY(
geom IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN SDO_GEOMETRY;
Description
Returns a new geometric segment by reversing the measure values and the direction of the original geometric segment.
Parameters
Cartographic representation of a linear feature.
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:
Reverses the measure values of geom
That is, the start measure of geom
is the end measure of the returned geometric segment, the end measure of geom
is the start measure of the returned geometric segment, and all other measures are adjusted accordingly.
Reverses the direction of geom
Compare this function with SDO_LRS.REVERSE_MEASURE, which reverses only the measure values (not the direction) of a geometric segment.
To reverse the vertices of a nonLRS line string geometry, use the SDO_UTIL.REVERSE_LINESTRING function, which is described in Chapter 32.
An exception is raised if geom
has an invalid geometry type or dimensionality. The geometry type must be a line or multiline, and the dimensionality must be 3 (two dimensions plus the measure dimension).
The _3D format of this function (SDO_LRS.REVERSE_GEOMETRY_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example reverses the measure values and the direction of the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
 Reverse direction and measures (for example, to prepare for  concatenating with another road).  First, display the original segment; then, reverse. SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 8, 4, 8, 12, 4, 12, 12, 10, 18, 8, 10, 22, 5, 14, 27)) SELECT SDO_LRS.REVERSE_GEOMETRY(a.route_geometry, m.diminfo) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.REVERSE_GEOMETRY(A.ROUTE_GEOMETRY,M.DIMINFO)(SDO_GTYPE, SDO_SRID, SDO_PO  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 5, 14, 27, 8, 10, 22, 12, 10, 18, 12, 4, 12, 8, 4, 8, 2, 4, 2, 2, 2, 0))
Note in the returned segment that the M values (measures) now go in descending order from 27 to 0, and the segment start and end points have the opposite X and Y values as in the original segment (5,14 and 2,2 here, as opposed to 2,2 and 5,14 in the original).
Format
SDO_LRS.REVERSE_MEASURE(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN SDO_GEOMETRY;
Description
Returns a new geometric segment by reversing the measure values, but not the direction, of the original geometric segment.
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function:
Reverses the measure values of geom_segment
That is, the start measure of geom_segment
is the end measure of the returned geometric segment, the end measure of geom_segment
is the start measure of the returned geometric segment, and all other measures are adjusted accordingly.
Does not affect the direction of geom_segment
Compare this function with SDO_LRS.REVERSE_GEOMETRY, which reverses both the direction and the measure values of a geometric segment.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality.
The _3D format of this function (SDO_LRS.REVERSE_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Note: The behavior of the SDO_LRS.REVERSE_MEASURE function changed after release 8.1.7. In release 8.1.7, REVERSE_MEASURE reversed both the measures and the segment direction. However, if you want to have this same behavior with subsequent releases, you must use the SDO_LRS.REVERSE_GEOMETRY function. 
Examples
The following example reverses the measure values of the geometric segment representing Route 1, but does not affect the direction. (This example uses the definitions from the example in Section 7.7.)
 First, display the original segment; then, reverse. SELECT a.route_geometry FROM lrs_routes a WHERE a.route_id = 1; ROUTE_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_ORDIN  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 0, 2, 4, 2, 8, 4, 8, 12, 4, 12, 12, 10, 18, 8, 10, 22, 5, 14, 27)) SELECT SDO_LRS.REVERSE_MEASURE(a.route_geometry, m.diminfo) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.REVERSE_MEASURE(A.ROUTE_GEOMETRY,M.DIMINFO)(SDO_GTYPE, SDO_SRID, SDO_POI  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 27, 2, 4, 25, 8, 4, 19, 12, 4, 15, 12, 10, 9, 8, 10, 5, 5, 14, 0))
Note in the returned segment that the M values (measures) now go in descending order from 27 to 0, but the segment start and end points have the same X and Y values as in the original segment (2,2 and 5,14).
Format
SDO_LRS.SCALE_GEOM_SEGMENT(
geom_segment IN SDO_GEOMETRY,
start_measure IN NUMBER,
end_measure IN NUMBER,
shift_measure IN NUMBER,
tolerance IN NUMBER DEFAULT 1.0e8
) RETURN SDO_GEOMETRY;
or
SDO_LRS.SCALE_GEOM_SEGMENT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
start_measure IN NUMBER,
end_measure IN NUMBER,
shift_measure IN NUMBER,
) RETURN SDO_GEOMETRY;
Description
Returns the geometry object resulting from a measure scaling operation on a geometric segment.
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Start measure of the geometric segment.
End measure of the geometric segment.
Amount to be added to each measure value after the initial scaling. A value of 0 (zero) means that nothing is added (no shifting of measure values).
Tolerance value (see Section 1.5.5 and Section 7.6). The default value is 0.00000001.
Usage Notes
This function performs the following actions:
It redistributes the measure values of the LRS geometric segment, using between start_measure
for the start point and end_measure
for the end point, and adjusting (scaling) the measure values in between accordingly.
If shift_measure
is not 0 (zero), it translates (shifts) each measure value computed in step 1 by adding the shift_measure
value.
The action of this function is sometimes referred to as "stretching" the measure values. The function affects only the measure values; the other coordinates of the geometry are not changed.
An exception is raised if geom_segment
, start_measure
, or end_measure
is invalid.
The direction of the resulting geometric segment is preserved (that is, it reflects the original segment).
For more information about scaling geometric segments, see Section 7.5.6.
Examples
The following example scales the geometric segment representing Route 1, returning a segment in which the start measure is specified as100, the end measure is specified 200, with a shift measure value of 10. Consequently, after all measure values are scaled according to the start and end measure values, 10 is added to all measure values. Thus, for example, the start point measure is 110 and the end point measure is 210 in the returned geometry. (This example uses the definitions from the example in Section 7.7.)
SQL> SELECT SDO_LRS.SCALE_GEOM_SEGMENT(route_geometry, 100, 200, 10) FROM lrs_routes WHERE route_id = 1; SDO_LRS.SCALE_GEOM_SEGMENT(ROUTE_GEOMETRY,100,200,10)(SDO_GTYPE, SDO_SRID, SDO_P  SDO_GEOMETRY(3302, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 110, 2, 4, 117.407407, 8, 4, 139.62963, 12, 4, 154.444444, 12, 10, 176.666 667, 8, 10, 191.481481, 5, 14, 210))
Format
SDO_LRS.SET_PT_MEASURE(
geom_segment IN OUT SDO_GEOMETRY,
point IN SDO_GEOMETRY,
measure IN NUMBER) RETURN VARCHAR2;
or
SDO_LRS.SET_PT_MEASURE(
geom_segment IN OUT SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
point IN SDO_GEOMETRY,
pt_dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER) RETURN VARCHAR2;
or
SDO_LRS.SET_PT_MEASURE(
point IN OUT SDO_GEOMETRY,
measure IN NUMBER) RETURN VARCHAR2;
or
SDO_LRS.SET_PT_MEASURE(
point IN OUT SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER) RETURN VARCHAR2;
Parameters
Geometric segment containing the point.
Dimensional information array corresponding to geom_segment
(in the second format) or point
(in the fourth format), usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Point for which the measure value is to be set.
Dimensional information array corresponding to point
(in the second format), usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Measure value to be assigned to the specified point.
Usage Notes
The function returns TRUE if the measure value was successfully set, and FALSE if the measure value was not set.
If both geom_segment
and point
are specified, the behavior of the procedure depends on whether or not point
is a shape point on geom_segment
:
If point
is a shape point on geom_segment
, the measure value of point
is set.
If point
is not a shape point on geom_segment
, the shape point on geom_segment
that is nearest to point
is found, and the measure value of that shape point is set.
The _3D format of this function (SDO_LRS.SET_PT_MEASURE_3D) is available; however, only the formats that include the geom_segment
parameter are available for SDO_LRS.SET_PT_MEASURE_3D. For information about _3D formats of LRS functions, see Section 7.4.
An exception is raised if geom_segment
or point
is invalid.
Examples
The following example sets the measure value of point (8,10) to 20. (This example uses the definitions from the example in Section 7.7.)
 Set the measure value of point 8,10 to 20 (originally 22). DECLARE geom_segment SDO_GEOMETRY; dim_array SDO_DIM_ARRAY; result VARCHAR2(32); BEGIN SELECT a.route_geometry into geom_segment FROM lrs_routes a WHERE a.route_name = 'Route1'; SELECT m.diminfo into dim_array from user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY';  Set the measure value of point 8,10 to 20 (originally 22). result := SDO_LRS.SET_PT_MEASURE (geom_segment, SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(8, 10, 22)), 20);  Display the result. DBMS_OUTPUT.PUT_LINE('Returned value = '  result); END; / Returned value = TRUE PL/SQL procedure successfully completed.
Format
SDO_LRS.SPLIT_GEOM_SEGMENT(
geom_segment IN SDO_GEOMETRY,
split_measure IN NUMBER,
segment_1 OUT SDO_GEOMETRY,
segment_2 OUT SDO_GEOMETRY);
or
SDO_LRS.SPLIT_GEOM_SEGMENT(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
split_measure IN NUMBER,
segment_1 OUT SDO_GEOMETRY,
segment_2 OUT SDO_GEOMETRY);
Parameters
Geometric segment to be split.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Distance measured from the start point of a geometric segment to the split point.
First geometric segment: from the start point of geom_segment
to the split point.
Second geometric segment: from the split point to the end point of geom_segment
.
Usage Notes
An exception is raised if geom_segment
or split_measure
is invalid.
The directions and measures of the resulting geometric segments are preserved.
The _3D format of this procedure (SDO_LRS.SPLIT_GEOM_SEGMENT_3D) is available. For information about _3D formats of LRS functions and procedures, see Section 7.4.
For more information about splitting a geometric segment, see Section 7.5.4.
Examples
The following example defines the geometric segment, splits it into two segments, then concatenates those segments. (This example uses the definitions from the example in Section 7.7. The definitions of result_geom_1
, result_geom_2
, and result_geom_3
are displayed in Example 73.)
DECLARE geom_segment SDO_GEOMETRY; line_string SDO_GEOMETRY; dim_array SDO_DIM_ARRAY; result_geom_1 SDO_GEOMETRY; result_geom_2 SDO_GEOMETRY; result_geom_3 SDO_GEOMETRY; BEGIN SELECT a.route_geometry into geom_segment FROM lrs_routes a WHERE a.route_name = 'Route1'; SELECT m.diminfo into dim_array from user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY';  Define the LRS segment for Route1. SDO_LRS.DEFINE_GEOM_SEGMENT (geom_segment, dim_array, 0,  Zero starting measure: LRS segment starts at start of route. 27);  End of LRS segment is at measure 27. SELECT a.route_geometry INTO line_string FROM lrs_routes a WHERE a.route_name = 'Route1';  Split Route1 into two segments. SDO_LRS.SPLIT_GEOM_SEGMENT(line_string,dim_array,5,result_geom_1,result_geom_2);  Concatenate the segments that were just split. result_geom_3 := SDO_LRS.CONCATENATE_GEOM_SEGMENTS(result_geom_1, dim_array, result_geom_2, dim_array);  Insert geometries into table, to display later. INSERT INTO lrs_routes VALUES( 11, 'result_geom_1', result_geom_1 ); INSERT INTO lrs_routes VALUES( 12, 'result_geom_2', result_geom_2 ); INSERT INTO lrs_routes VALUES( 13, 'result_geom_3', result_geom_3 ); END; /
Format
SDO_LRS.TRANSLATE_MEASURE(
geom_segment IN SDO_GEOMETRY,
translate_m IN NUMBER
) RETURN SDO_GEOMETRY;
or
SDO_LRS.TRANSLATE_MEASURE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
translate_m IN NUMBER
) RETURN SDO_GEOMETRY;
Description
Returns a new geometric segment by translating the original geometric segment (that is, shifting the start and end measures by a specified value).
Parameters
Cartographic representation of a linear feature.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Distance measured from the start point of a geometric segment to the start point of the linear feature.
Usage Notes
This function adds translate_m
to the start and end measures of geom_segment
. For example, if geom_segment
has a start measure of 50 and an end measure of 100, and if translate_m
is 10, the returned geometric segment has a start measure of 60 and an end measure of 110, as shown in Figure 251.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality.
The _3D format of this function (SDO_LRS.TRANSLATE_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example translates (shifts) by 10 the geometric segment representing Route 1. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.TRANSLATE_MEASURE(a.route_geometry, m.diminfo, 10) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.TRANSLATE_MEASURE(A.ROUTE_GEOMETRY,M.DIMINFO,10)(SDO_GTYPE, SDO_SRID, SD  SDO_GEOMETRY(3002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1), SDO_ORDINATE_ARRAY( 2, 2, 10, 2, 4, 12, 8, 4, 18, 12, 4, 22, 12, 10, 28, 8, 10, 32, 5, 14, 37))
Format
SDO_LRS.VALID_GEOM_SEGMENT(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN VARCHAR2;
Parameters
Geometric segment to be checked for validity.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns TRUE if geom_segment
is valid and FALSE if geom_segment
is not valid.
Measure information is assumed to be stored in the last element of the SDO_DIM_ARRAY in the Oracle Spatial metadata.
This function only checks for geometry type and number of dimensions of the geometric segment. To further validate measure information, use the SDO_LRS.IS_GEOM_SEGMENT_DEFINED function.
The _3D format of this function (SDO_LRS.VALID_GEOM_SEGMENT_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example checks if the geometric segment representing Route 1 is valid. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.VALID_GEOM_SEGMENT(route_geometry) FROM lrs_routes WHERE route_id = 1; SDO_LRS.VALID_GEOM_SEGMENT(ROUTE_GEOMETRY)  TRUE
Format
SDO_LRS.VALID_LRS_PT(
point IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN VARCHAR2;
Parameters
Point to be checked for validity.
Dimensional information array corresponding to point
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns TRUE if point
is valid and FALSE if point
is not valid.
This function checks if point
is a point with measure information, and it checks for the geometry type and number of dimensions for the point geometry.
All LRS point data must be stored in the SDO_ELEM_INFO_ARRAY and SDO_ORDINATE_ARRAY, and cannot be stored in the SDO_POINT field in the SDO_GEOMETRY definition of the point.
The _3D format of this function (SDO_LRS.VALID_LRS_PT_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example checks if point (9,3,NULL) is a valid LRS point. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.VALID_LRS_PT( SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(9, 3, NULL)), m.diminfo) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.VALID_LRS_PT(SDO_GEOMETRY(3301,NULL,NULL,SDO_ELEM_INFO_ARRAY(1,1,1),SDO_  TRUE
Format
SDO_LRS.VALID_MEASURE(
geom_segment IN SDO_GEOMETRY,
measure IN NUMBER
) RETURN VARCHAR2;
or
SDO_LRS.VALID_MEASURE(
geom_segment IN SDO_GEOMETRY,
dim_array IN SDO_DIM_ARRAY,
measure IN NUMBER
) RETURN VARCHAR2;
Parameters
Geometric segment to be checked to see if measure
falls within its measure range.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Measure value to be checked to see if it falls within the measure range of geom_segment
.
Usage Notes
This function returns TRUE if measure
falls within the measure range of geom_segment
and FALSE if measure
does not fall within the measure range of geom_segment
.
An exception is raised if geom_segment
has an invalid geometry type or dimensionality.
The _3D format of this function (SDO_LRS.VALID_MEASURE_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example checks if 50 is a valid measure on the Route 1 segment. The function returns FALSE because the measure range for that segment is 0 to 27. For example, if the route is 27 miles long with mile markers at 1mile intervals, there is no 50mile marker because the last marker is the 27mile marker. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.VALID_MEASURE(route_geometry, 50) FROM lrs_routes WHERE route_id = 1; SDO_LRS.VALID_MEASURE(ROUTE_GEOMETRY,50) =  FALSE
Format
SDO_LRS.VALIDATE_LRS_GEOMETRY(
geom_segment IN SDO_GEOMETRY
[, dim_array IN SDO_DIM_ARRAY]
) RETURN VARCHAR2;
Parameters
Geometric segment to be checked.
Dimensional information array corresponding to geom_segment
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Usage Notes
This function returns TRUE if geom_segment
is valid and one of the following errors if geom_segment
is not valid:
ORA13331 (invalid LRS segment)
ORA13335 (measure information not defined)
The _3D format of this function (SDO_LRS.VALIDATE_LRS_GEOMETRY_3D) is available. For information about _3D formats of LRS functions, see Section 7.4.
Examples
The following example checks if the Route 1 segment is a valid LRS geometry. (This example uses the definitions from the example in Section 7.7.)
SELECT SDO_LRS.VALIDATE_LRS_GEOMETRY(a.route_geometry, m.diminfo) FROM lrs_routes a, user_sdo_geom_metadata m WHERE m.table_name = 'LRS_ROUTES' AND m.column_name = 'ROUTE_GEOMETRY' AND a.route_id = 1; SDO_LRS.VALIDATE_LRS_GEOMETRY(A.ROUTE_GEOMETRY,M.DIMINFO)  TRUE
This chapter contains descriptions of the geometryrelated PL/SQL subprograms in the SDO_GEOM package, which can be grouped into the following categories:
Relationship (True/False) between two objects: RELATE, WITHIN_DISTANCE
Validation: VALIDATE_GEOMETRY_WITH_CONTEXT, VALIDATE_LAYER_WITH_CONTEXT
Singleobject operations: SDO_ALPHA_SHAPE, SDO_ARC_DENSIFY, SDO_AREA, SDO_BUFFER, SDO_CENTROID, SDO_CONVEXHULL, SDO_CONCAVEHULL, SDO_CONCAVEHULL_BOUNDARY, SDO_LENGTH, SDO_MAX_MBR_ORDINATE, SDO_MIN_MBR_ORDINATE, SDO_MBR, SDO_POINTONSURFACE, SDO_TRIANGULATE, SDO_VOLUME
Twoobject operations: SDO_CLOSEST_POINTS, SDO_DISTANCE, SDO_DIFFERENCE, SDO_INTERSECTION, SDO_UNION, SDO_XOR
The geometry subprograms are listed Table 241, and some usage information follows the table.
Table 241 Geometry Subprograms
Subprogram  Description 


Determines how two objects interact. 

Returns the alpha shape geometry of the input geometry, based on a specified radius value. 

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. 

Computes the area of a twodimensional polygon. 

Generates a buffer polygon around or inside a geometry. 

Returns the centroid of a polygon. 

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

Returns a polygontype object that represents the concave hull of a geometry object. 
SDO_GEOM.SDO_CONCAVEHULL_BOUNDARY 
Returns a polygontype object that represents the concave hull of a geometry object, based on boundary points rather than the alpha shape. 

Returns a polygontype object that represents the convex hull of a geometry object. 

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

Computes the distance between two geometry objects. 

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

Computes the length or perimeter of a geometry. 

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

Returns the minimum bounding rectangle of a geometry. 

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

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

Returns a collection of triangles resulting from Delaunay triangulation of the input geometry. 

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

Computes the volume of a threedimensional solid geometry. 

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. 

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.)
Certain combinations of input parameters and operations can return a null value, that is, an empty geometry. For example, requesting the intersection of two disjoint geometry objects returns a null value.
A null value (empty geometry) as an input parameter to a geometry function (for example, SDO_GEOM.RELATE) produces an error.
Certain operations can return a geometry of a different type than one or both input geometries. For example, the intersection of a line and an overlapping polygon returns a line; the intersection of two lines returns a point; and the intersection of two tangent polygons returns a line.
SDO_GEOM subprograms are supported for twodimensional geometries only, except for the following, which are supported for both twodimensional and threedimensional geometries:
SDO_GEOM.RELATE with (A) the ANYINTERACT mask, or (B) the INSIDE mask (3D support for solid geometries only)
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;
Parameters
Geometry object.
Dimensional information array corresponding to geom1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Specifies a list of relationships to check. See the list of keywords in the Usage Notes.
Geometry object.
Dimensional information array corresponding to geom2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
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:
If you pass a mask
listing one or more relationships, the function returns the specified mask
value if one or more of the relationships are true for the pair of geometries. If all relationships are false, the procedure returns FALSE.
If you pass the DETERMINE keyword in mask
, the function returns the one relationship keyword that best matches the geometries.
If you pass the ANYINTERACT keyword in mask
, the function returns TRUE if the two geometries are not disjoint.
The following mask
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.
ON: Returns ON if the boundary and interior of a line (the first object) is completely on the boundary of a polygon (the second object); 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.
Values for mask
can be combined using the logical Boolean operator OR. For example, 'INSIDE + TOUCH' returns INSIDE+TOUCH
if the relationship between the geometries is INSIDE or TOUCH or both INSIDE and TOUCH; it returns FALSE
if the relationship between the geometries is neither INSIDE nor TOUCH.
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
Format
SDO_GEOM.SDO_ALPHA_SHAPE(
geom IN SDO_GEOMETRY,
tol IN NUMBER,
radius IN NUMBER DEFALT NULL,
flag IN BINARY_INTEGER DEFAULT 0
) RETURN SDO_GEOMETRY;
Description
Returns the alpha shape geometry of the input geometry, based on a specified radius value.
Parameters
Geometry object.
Tolerance value (see Section 1.5.5).
Radius to be used in calculating the alpha shape. If this parameter is null, the alpha shape is the convex hull of the input geometry.
Determines whether isolated points and edges are included: 0
(the default) includes isolated points and edges, so that the alpha shape is returned; 1
does not include isolated points and edges, so that only the polygon portion of the alpha shape is returned.
Usage Notes
The alpha shape is a generalization of the convex hull (see http://biogeometry.duke.edu/software/alphashapes/
). This function takes all coordinates from the input geometry, uses them to compute Delaunay triangulations and the alpha shape.
If you specify a value for the radius
parameter, you may first want to call the SDO_GEOM.SDO_CONCAVEHULL function using the format with the radius
output parameter.
An exception is raised if geom
is of point type, has fewer than three points or vertices, or consists of multiple points all in a straight line, or if radius
is less than 0.
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 alpha shape of cola_c
, which is also the convex hull of cola_c
because the default value for the radius
parameter (null) is used. (This simplified example uses a polygon as the input geometry; this function is normally used with a large set of point data. The example uses the definitions and data from Section 2.1.)
SELECT c.name, SDO_GEOM.SDO_ALPHA_SHAPE(c.shape, 0.005) FROM cola_markets c WHERE c.name = 'cola_c'; SDO_GEOM.SDO_ALPHA_SHAPE(C.SHAPE,0.005)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z),  cola_c SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1), SDO_ORDINATE_ARR AY(4, 5, 3, 3, 6, 3, 6, 5, 4, 5))
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
Geometry object.
Dimensional information array corresponding to geom
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5).
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 straightline 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 241 shows a line whose length is the arc_tolerance
value for the arc between points A and B.
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))
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;
Parameters
Geometry object.
Dimensional information array corresponding to geom
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
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.
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
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;
Parameters
Geometry object.
Dimensional information array corresponding to geom
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
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.
Tolerance value (see Section 1.5.5).
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 17 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.
If the input geometry has more than 50 ordinates, and the buffer width is less than 0.1 percent (0.001) of the rootmeansquare spacing between consecutive coordinates, then the original geometry is returned unchanged.
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 nongeodetic 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.13.
 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))
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
Geometry object.
Dimensional information array corresponding to geom
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
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))
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
Geometry object.
Geometry object.
Tolerance value (see Section 1.5.5).
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.
Output parameter containing the minimum distance between geom1
and geom2
. Specifically, the distance between geoma
and geomb
.
Output parameter containing the point geometry object on the boundary of geom1
that is closest to the closest point on the boundary of geom2
.
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.
If the distance between the two points is 0 (zero), the output geometries (geoma
and geomb
) are null.
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))
Format
SDO_GEOM.SDO_CONCAVEHULL(
geom IN SDO_GEOMETRY,
tol IN NUMBER
) RETURN SDO_GEOMETRY;
or
SDO_GEOM.SDO_CONCAVEHULL(
geom IN SDO_GEOMETRY,
tol IN NUMBER,
radius OUT NUMBER
) RETURN SDO_GEOMETRY;
Parameters
Geometry object.
Tolerance value (see Section 1.5.5).
Output parameter to hold the radius of the circumcircle of the triangles created internally (using Delaunay triangulations) in computing the concave hull.
Usage Notes
The concave hull is a polygon that represents the area of the input geometry, such as a collection of points. With complex input geometries, the concave hull is typically significantly smaller in area that the convex hull.
This function takes all coordinates from the input geometry, uses them to compute Delaunay triangulations, and computes a concave hull. It returns only an exterior ring; any interior rings are discarded.
This function uses the alpha shape in computing the concave hull. By contrast, the SDO_GEOM.SDO_CONCAVEHULL_BOUNDARY function uses exterior boundary points.
The format with the radius
parameter returns a radius value that can be useful if you plan to call the SDO_GEOM.SDO_ALPHA_SHAPE function.
An exception is raised if geom
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 concave hull of cola_c
. (The example uses the definitions and data from Section 2.1.
 Return the concave hull of a polygon. SELECT c.name, SDO_GEOM.SDO_CONCAVEHULL(c.shape, 0.005) FROM cola_markets c WHERE c.name = 'cola_c'; NAME  SDO_GEOM.SDO_CONCAVEHULL(C.SHAPE,0.005)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z),  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))
Format
SDO_GEOM.SDO_CONCAVEHULL_BOUNDARY(
geom IN SDO_GEOMETRY,
tol IN NUMBER,
length IN NUMBER DEFAULT NULL
) RETURN SDO_GEOMETRY;
Description
Returns a polygontype object that represents the concave hull of a geometry object, based on boundary points rather than the alpha shape.
Parameters
Geometry object.
Tolerance value (see Section 1.5.5).
A value to control the size of the concave hull: specifically, computation of the concave hull is stopped when the longest edge in the concave hull is shorter than the length
value. Thus, the larger the length
value, the larger the concave hull will probably be. If you do not specify this parameter, computation continues as described in the Usage Notes.
Usage Notes
The concave hull is a polygon that represents the area of the input geometry, such as a collection of points. With complex input geometries, the concave hull is typically significantly smaller in area than the convex hull.
Like the SDO_GEOM.SDO_CONCAVEHULL function, this function takes all coordinates from the input geometry, and uses them to compute Delaunay triangulations. But after that, it computes a convex hull, puts all boundary edges into a priority queue based on the lengths of these edges, and then removes edges one by one as long as the shape is still a single connected polygon (unless stopped by a specified length
parameter value). If an edge is removed during the computation, the other two edges of its triangle will be on the boundary.
An exception is raised if geom
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 concave hull of cola_c
. (The example uses the definitions and data from Section 2.1.)
 Return the concave hull of a polygon. SELECT c.name, SDO_GEOM.SDO_CONCAVEHULL_BOUNDARY(c.shape, 0.005) FROM cola_markets c WHERE c.name = 'cola_c'; NAME  SDO_GEOM.SDO_CONCAVEHULL_BOUNDARY(C.SHAPE,0.005)(SDO_GTYPE, SDO_SRID, SDO_POINT(  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))
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;
Parameters
Geometry object.
Dimensional information array corresponding to geom1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
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 straightline 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))
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
Geometry object.
Dimensional information array corresponding to geom1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Geometry object.
Dimensional information array corresponding to geom2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5).
Usage Notes
In Figure 242, the shaded area represents the polygon returned when SDO_DIFFERENCE is used with a square (geom1
) and another polygon (geom2
).
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).
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
Geometry object whose distance from geom2
is to be computed.
Dimensional information array corresponding to geom1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Geometry object whose distance from geom1
is to be computed.
Dimensional information array corresponding to geom2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
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.
Tolerance value (see Section 1.5.5).
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
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
Geometry object.
Dimensional information array corresponding to geom1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Geometry object.
Dimensional information array corresponding to geom2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5).
Usage Notes
In Figure 243, the shaded area represents the polygon returned when SDO_INTERSECTION is used with a square (geom1
) and another polygon (geom2
).
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).
Format
SDO_GEOM.SDO_LENGTH(
geom IN SDO_GEOMETRY,
dim IN SDO_DIM_ARRAY
[, unit IN VARCHAR2]
[, count_shared_edges IN NUMBER]
) RETURN NUMBER;
or
SDO_GEOM.SDO_LENGTH(
geom IN SDO_GEOMETRY,
tol IN NUMBER
[, unit IN VARCHAR2]
[, count_shared_edges IN NUMBER]
) RETURN NUMBER;
Parameters
Geometry object.
Dimensional information array corresponding to geom
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5).
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.
For threedimensional geometries only: the number of times to count the length of shared parts of edges if the input geometry contains any edges that are fully or partially shared. If specified, must be 1 (count each once) or 2 (count each twice). The default is 1.
This parameter is ignored for twodimensional input geometries.
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
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
Geometry object.
Dimensional information array corresponding to geom
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
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.
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
Description
Returns the minimum bounding rectangle of a geometry object, that is, a single rectangle that minimally encloses the geometry.
Parameters
Geometry object.
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:
If the input geometry is null, the function returns a null geometry.
If the input geometry is a point, the function returns the point.
If the input geometry consists of points all on a straight line, the function returns a twopoint line.
If the input geometry has three dimensions but all Z dimension values are the same, the function returns a threedimensional line.
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))
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
Geometry object.
Dimensional information array corresponding to geom
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
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.
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
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;
Parameters
Polygon geometry object.
Dimensional information array corresponding to geom1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
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
; however, it is not guaranteed to be an interior point. (That is, it can be on the boundary or edge 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.
In most cases this function is less useful than the SDO_UTIL.INTERIOR_POINT function, which returns a point that is guaranteed to be an interior point.
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))
Description
Returns a geometry with triangular elements that result from Delaunay triangulation of the input geometry.
Usage Notes
This function takes all coordinates from the input geometry, uses them to compute Delaunay triangulations, and returns a geometry object, each element of which is a triangle.
An exception is raised if geom
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 consists of triangular elements (two in this case) comprising the cola_c
polygon geometry. (The example uses the definitions and data from Section 2.1.
 Return triangles comprising a specified polygon. SELECT c.name, SDO_GEOM.SDO_TRIANGULATE(c.shape, 0.005) FROM cola_markets c WHERE c.name = 'cola_c'; NAME  SDO_GEOM.SDO_TRIANGULATE(C.SHAPE,0.005)(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z),  cola_c SDO_GEOMETRY(2007, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 1, 9, 1003, 1), SDO_ ORDINATE_ARRAY(3, 3, 6, 3, 4, 5, 3, 3, 4, 5, 6, 3, 6, 5, 4, 5))
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
Geometry object.
Dimensional information array corresponding to geom1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Geometry object.
Dimensional information array corresponding to geom2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5).
Usage Notes
In Figure 244, the shaded area represents the polygon returned when SDO_UNION is used with a square (geom1
) and another polygon (geom2
).
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).
Format
SDO_GEOM.SDO_VOLUME(
geom IN SDO_GEOMETRY,
tol IN NUMBER
[, unit IN VARCHAR2]
) RETURN NUMBER;
Parameters
Geometry object.
Tolerance value (see Section 1.5.5).
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 threedimensional 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
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
Geometry object.
Dimensional information array corresponding to geom1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Geometry object.
Dimensional information array corresponding to geom2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5).
Usage Notes
In Figure 245, the shaded area represents the polygon returned when SDO_XOR is used with a square (geom1
) and another polygon (geom2
).
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).
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
Geometry object.
Dimensional information array corresponding to theGeometry
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5).
Conditional flag; relevant only for a threedimensional 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.
Oracle Database 10g compatibility flag. A string value of TRUE
causes only validation checks specific to twodimensional geometries to be performed, and no 3Dspecific 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
If the geometry is valid, this function returns TRUE. (For a userdefined 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 selfcrossing.
No two 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.)
An interior polygon ring touches the exterior polygon ring at no more than one point.
If two or more interior polygon rings are in an exterior polygon ring, the interior polygon rings touch at no more than one point.
Line strings have at least two points.
SDO_ETYPE 1digit and 4digit 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 Chapter 7) 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 polygonpolygon overlap checks are not performed for polygon elements of the COLLECTION type geometry.
For multipoint geometries, this function checks for duplicate vertices with threedimensional geometries, but not with twodimensional geometries.
For threedimensional geometries, this function also performs the checks described in Section 1.11.5.
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 threedimensional geometries that contain geometries in preRelease 11.1 format to pass the validation check when they would otherwise fail. For example, a threedimensional 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 twodimensional geometry, a vertex is two numbers (X and Y, or Longitude and Latitude). In a threedimensional geometry, a vertex is defined using three numbers; and in a fourdimensional 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 userspecified 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 multielement 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 selfintersecting polygons. (The Open Geospatial Consortium simple features specification does not allow a polygon to selfintersect.) In such cases, Oracle reports error 13349 (polygon boundary crosses itself), including the Element, Ring, and Edge numbers where selfintersection 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 Section 6.2.4.
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 ORA13349: 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).
Format
SDO_GEOM.VALIDATE_LAYER_WITH_CONTEXT(
geom_table IN VARCHAR2,
geom_column IN VARCHAR2,
result_table IN VARCHAR2
commit_interval IN NUMBER DEFAULT 1,
conditional IN VARCHAR2 DEFAULT 'TRUE' ,
flag10g IN VARCHAR2 DEFAULT 'FALSE');
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
Spatial geometry table.
Geometry object column to be examined.
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.
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.
Conditional flag; relevant only for a threedimensional 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.
Oracle Database 10g compatibility flag. A string value of TRUE
causes only validation checks specific to twodimensional geometries to be performed, and no 3Dspecific validation checks to be performed. A string value of FALSE
(the default) performs all validation checks that are relevant for the geometries. (See the Usage Notes for the SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT function for more information about the flag10g
parameter.)
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:
If commit_interval
is not specified (or if the commit_interval
value is greater than the number of geometries in the layer) and no invalid geometries are found, a single row with a RESULT value of DONE is written.
If commit_interval
is specified and if no invalid geometries are found between an internal commit and the previous internal commit (or start of validation for the first internal commit), a single row with the primary key of the last geometry validated and a RESULT value of DONE is written. (If there have been no invalid geometries since the last internal commit operation, this row replaces the previous row that had a result of DONE.)
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
):
All type consistency and geometry consistency checks that are performed by the SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT function (see the Usage Notes for that function).
The geometry's SRID value (coordinate system) is the same as the one specified in the applicable DIMINFO column value (from the USER_SDO_GEOM_METADATA view, which is described in Section 2.8).
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>]
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;
Parameters
Geometry object.
Dimensional information array corresponding to geom1
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Distance value.
Geometry object.
Dimensional information array corresponding to geom2
, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Section 2.8).
Tolerance value (see Section 1.5.5).
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 sjpecified 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
This chapter describes the Oracle Spatial implementation of the Open GIS Consortium specification for catalog services. According to this specification: "Catalogue services support the ability to publish and search collections of descriptive information (metadata) for data, services, and related information objects. Metadata in catalogues represent resource characteristics that can be queried and presented for evaluation and further processing by both humans and software. Catalogue services are required to support the discovery and binding to registered information resources within an information community."
The Oracle Spatial implementation will be referred to as Catalog Services for the Web, or CSW
This chapter includes the following major sections:
Note: Before you use CSW, be sure that you understand the concepts described in Chapter 10, "Introduction to Spatial Web Services", and that you have performed any necessary configuration work as described in that chapter.If you have data from a previous release that was indexed using one or more SYS.XMLTABLEINDEX indexes, you must drop the associated indexes before the upgrade and recreate the indexes after the upgrade, as described in Section A.3. 
This section describes CSW, including its relationship to clients and to the database server. CSW is implemented as a Web service and can be deployed in a WebLogic Server, Oracle Application Server, or standalone Oracle Application Server Containers for J2EE (OC4J) environment.
CSW has a metadata layer, which stores in the database the metadata needed to reply to catalog requests. The metadata includes spatial columns, which can be queried and processed using Oracle Spatial interfaces. The metadata also stores the association of nonspatial and spatial attributes of records, as well as the services that the catalog service provides to its clients.
Figure 161 shows the CSW architecture.
As shown in Figure 161:
CSW is part of a container in the Oracle Application Server middle tier.
CSW can communicate with a Web service client using CSW requests and responses in SOAP/XML format.
CSW performs spatial data and metadata access through JDBC calls to the database.
The database includes Oracle Spatial with CSW metadata and data.
CSW security is implemented using secure transport. User identities and user labels are managed in LDAP, and the middle tier and CSW security combine to perform authentication. Oracle labelbased security is used for managing user privileges at the record level.
The CSW APIs enable you to perform operations that include:
Specifying information about record type domains and record view transformations
Publishing record types
Dropping (unpublishing) record types
Granting to users and revoking from users privileges on CSW record types
Chapter 22 describes the PL/SQL API (SDO_CSW_PROCESS package), Section 16.3 provides examples of XML requests and responses, and Section 16.4 describes the Java API.
A capabilities document describes an instance of a capability. The document specifies a record type and the type of operations supported (such as insert and delete).
A capabilities document is generated by the CSW server in response to a GetCapabilities request. The CSW server uses a capabilities template, and adds information about the record type and operations to this template to create the capabilities document.
The client can use the HTTP GET method to access this capabilities document using either the SOAP interface or the XML interface:
For the SOAP interface, use oracle.spatial.ws.servlet.CSWServlet,
which can be accessed at an address in the following format:
http:///machinename:port/SpatialWSSpatialWScontextroot/cswservlet?request=GetCapabilities&service=CSW&acceptversion=2.0.0&outputFormat=text/xml
For the XML interface, use oracle.spatial.ws.servlet.CSWXMLServlet
, which can be accessed at an address in the following format:
http:///machinename:port/SpatialWSSpatialWScontextroot/xmlcswservlet?request=GetCapabilities&service=CSW&acceptversion=2.0.0&outputFormat=text/xml
In the preceding formats:
machinename is the name of the system where the application server or OC4J server is running.
port is the port number where the application server or OC4J server is running.
SpatialWSSpatialWScontextroot is the default root where the Spatial Web services application is mounted.
cswservlet is the servletmapping urlpattern
for oracle.spatial.ws.servlet.CSWServlet
, as specified by default in the web.xml
file.
xmlcswservlet is the servletmapping urlpattern
for oracle.spatial.ws.servlet.CSWXMLServlet
, as specified by default in the web.xml
file.
If you need CSW to process any spatial content that is not in GML format, you must create a userdefined function named extractSDO
to extract the spatial path information. This function must be implemented for each record type that has spatial content in nonGML format and on which you want to create a spatial index. (This function is not needed if all spatial content for a record type is in GML format.)
This function must be registered, as explained in Section 16.2.2.1, so that the Oracle Spatial CSW server can find and invoke this function when it needs to extract spatial path content that is not in GML format.
The extractSDO
function has the following format:
extractSDO(
xmlData IN XMLType,
srsNs IN VARCHAR2,
spPathsSRSNSList IN MDSYS.STRINGLISTLIST);
) RETURN MDSYS.SDO_GEOM_PATH_INFO;