MarkLogic Server 11.0 Product Documentation

geo:circle-polygon

geo:circle-polygon(
   $circle as cts:circle,
   $arc-tolerance as xs:double,
   [$options as xs:string*]
) as cts:region

Summary

Construct a polygon approximating a circle.

Usage Notes

When approximating the polygon, if the distance between two points is less than tolerance, then they are considered to be the same point. The arc-tolerance parameter specifies the allowable error in the polygon approximation. That is, the resulting polygon will differ from the provided circle by at most arc-tolerance.

The arc-tolerance parameter value must be greater than the tolerance, and both arc-tolerance and tolerance should be expressed in the same units. For example, if the units option is set to "km" and you're using a geodetic coordinate system, then arc-tolerance and tolerance (if specified) should also be in kilometers. The default tolerance is 0.05km (or the equivalent in other units). Use the tolerance option to override the default.

The value of the precision option takes precedence over that implied by the governing coordinate system name, including the value of the coordinate-system option. For example, if the governing coordinate system is "wgs84/double" and the precision option is "float", then the operation uses single precision.

It is recommended to use this function for queries, as circle geometry matching cannot be optimized. Convert circles to polygons before passing them in as arguments to your queries to get better performance. A common question to ask is 'what points do I have in my database that are within 10 kilometers of point A?' This function provides an optimized path for this query.

See Also

• Geospatial Search Applications in the Search Developer's Guide

Example

geo:circle-polygon(cts:circle(7,cts:point(10,20)),4, ("tolerance=1"));

=> A cts:region with the following coordinates:
   10.10185,20 10.050913,20.088997 9.9490623,20.08897 9.8981495,20
   9.9490623,19.91103 10.050913,19.911001 10.10185,20

Example

xquery version "1.0-ml";
import module namespace op = 'http://marklogic.com/optic' 
           at 'MarkLogic/optic.xqy';
import module namespace ogeo = 'http://marklogic.com/optic/expression/geo' 
           at 'MarkLogic/optic/optic-geo.xqy';

(: Optic example using the Value Processing Function ogeo:intersects() and geo:circle-polygon() :)
(: $circlePolygonLit is a polygon representing a 10 kilometer radius around Tucson, Arizona, US :)
let $circlePolygonLit := geo:circle-polygon(cts:circle(10,cts:point('POINT(-110.97345746274591 32.213051181896034)')),0.01,('tolerance=0.001','units=km'))
let $plan:= op:from-view('buildings', 'builds')
             =>op:where(ogeo:intersects(op:col('poly'),$circlePolygonLit))
             =>op:select(('name', op:col('geoid')))
             =>op:order-by('geoid')

return $plan=>op:result()

(:
==>
rows representing names and geoids where values in the 'poly' column INTERSECT circlePolygonLit
:)