23.25 SDO_GEOM.SDO_POINTONSURFACE

Format

SDO_GEOM.SDO_POINTONSURFACE(     
  geom1  IN SDO_GEOMETRY,      
  dim1   IN SDO_DIM_ARRAY       
) RETURN SDO_GEOMETRY;

SDO_GEOM.SDO_POINTONSURFACE(     
  geom1  IN SDO_GEOMETRY,      
  tol    IN NUMBER       
) RETURN SDO_GEOMETRY;

Description

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

Parameters

geom1: Polygon geometry object.
dim1: Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Geometry Metadata Views).
tol: Tolerance value (see Tolerance).

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 Simple Example: Inserting_ Indexing_ and Querying Spatial Data.)

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