SDO_UTIL.CIRCLE

Format

SDO_UTIL.CIRCLE_POLYGON(
     point         IN SDO_GEOMETRY, 
     radius        IN NUMBER, 
     arc_tolerance IN NUMBER, 
     start_azimuth IN NUMBER DEFAULT NULL, 
     end_azimuth   IN NUMBER DEFAULT NULL, 
     orientation   IN NUMBER DEFAULT NULL, 
     arc           IN NUMBER DEFAULT NULL 
     ) RETURN SDO_GEOMETRY;

or

SDO_UTIL.CIRCLE_POLYGON(
     center_longitude IN NUMBER, 
     center_latitude  IN NUMBER, 
     radius           IN NUMBER, 
     arc_tolerance    IN NUMBER 
     ) RETURN SDO_GEOMETRY;

or

SDO_UTIL.CIRCLE_POLYGON(
     center_longitude IN NUMBER, 
     center_latitude  IN NUMBER, 
     radius           IN NUMBER, 
     start_azimuth    IN NUMBER, 
     end_azimuth      IN NUMBER, 
     arc_tolerance    IN NUMBER 
     ) RETURN SDO_GEOMETRY;

Description

Creates polygon or polyline approximations of circles and arcs in geodetic coordinate systems.

The first format allows full control of the output.
The second format returns the polygon geometry that approximates and is covered by a specified circle.
The third format returns a line geometry that approximates the boundary of the circle from the start to the end azimuth (an arc).

Parameters

point

The center of the circle. Must be a point geometry in a geodetic coordinate system. The returned geometry will be in the same coordinate system.

center_longitude

Center longitude (in degrees) of the circle to be used to create the returned geometry.

center_latitude

Center latitude (in degrees) of the circle to be used to create the returned geometry.

radius

Length (in meters) of the radius of the circle to be used to create the returned geometry.

arc_tolerance

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 SDO_GEOM Package (Geometry).)

start_azimuth

Start angle (in degrees) of the arc, measured counterclockwise from due south.

If start_azimuth and end_azimuth are null, the behavior is comparable to the second format, which returns the polygon geometry that approximates and is covered by a specified circle.

end_azimuth

End angle (in degrees) of the arc, measured counterclockwise from due south. If orientation is not explicitly specified, then the arc will be the counterclockwise section of the circle from start_azimuth if end_azimuth is greater than start_azimuth, and the arc will be the clockwise section if end_azimuth is less than start_azimuth.

If start_azimuth and end_azimuth are null, the behavior is comparable to the second format, which returns the polygon geometry that approximates and is covered by a specified circle.

orientation

Controls which portion of the circle from start_azimuth to end_azimuth is used. This controls the shape of the returned output, not the orientation of the output: a returned polygon is always oriented counterclockwise, and a returned arc is always from start_azimuth to end_azimuth. The value can be one of the following:

0 or null (default): Automatic (see the end_azimuth parameter description).
1 or +1: Arc is drawn counterclockwise from start_azimuth to end_azimuth.
-1: Arc is drawn clockwise from start_azimuth to end_azimuth.

arc

If set to 1, the result will be a line; if 0 or null (the default), the result is a polygon. If start_azimuth and end_azimuth specify a subset of the circle with a polygon result, the returned polygon will include the center of the circle (that is, will be a sector of the circle).

Usage Notes

The first format of this function is useful for creating a circle-like 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)).

The second and third formats of this function are useful for creating a polyline approximation to a circular arc or a polygon that represents a sector of the circle.

If the start and end azimuth values are specified, they must not be equal to each other, and must cover no more than a 360 degree rotation. Angles must be in the range -720 to +720.

Circles will always be created with at least four distinct vertices (a square).

Examples

The following example returns a circle-like 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))