SDO_GEOM.WITHIN

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]      
  [, ellipsoidal 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]      
  [, ellipsoidal IN VARCHAR2]
) RETURN VARCHAR2;

Description

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

Parameters

geom1

Geometry object.

dim1

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

dist

Distance value.

geom2

Geometry object.

dim2

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

tol

Tolerance value (see Tolerance).

units

Unit of measurement: a quoted string with unit= and an SDO_UNIT value from the MDSYS.SDO_AREA_UNITS table (for example, 'unit=KM'). See Unit of Measurement Support 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.

ellipsoidal

Specifies if ellipsoidal distance is always used with geodetic data (true), or if spherical distance is used in some cases (false, the default). See Distance: Spherical versus Ellipsoidal with Geodetic Data.

Usage Notes

For better performance, use the SDO_WITHIN_DISTANCE operator (described in Spatial Operators ) instead of the SDO_GEOM.WITHIN_DISTANCE function. For more information about performance considerations with operators and functions, see Spatial Operators_ Procedures_ and Functions.

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

The distance between two extended objects (for example, nonpoint objects such as lines and polygons) is defined as the minimum distance between these two objects. Thus the distance between two adjacent polygons is zero.

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

Examples

The following example checks if cola_b and cola_d are within 1 unit apart at the shortest distance between them. (The example uses the definitions and data from Simple Example: Inserting_ Indexing_ and Querying Spatial Data.)

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