# 9.11. Geometric Functions and Operators

The geometric types point, box, lseg, line, path, polygon, and circle have a large set of native support functions and operators, shown in Table 9-31, Table 9-32, and Table 9-33.

 Caution Note that the "same as" operator, ~=, represents the usual notion of equality for the point, box, polygon, and circle types. Some of these types also have an = operator, but = compares for equal areas only. The other scalar comparison operators (<= and so on) likewise compare areas for these types.

Table 9-31. Geometric Operators

OperatorDescriptionExample
+ Translationbox '((0,0),(1,1))' + point '(2.0,0)'
- Translationbox '((0,0),(1,1))' - point '(2.0,0)'
* Scaling/rotationbox '((0,0),(1,1))' * point '(2.0,0)'
/ Scaling/rotationbox '((0,0),(2,2))' / point '(2.0,0)'
# Point or box of intersectionbox '((1,-1),(-1,1))' # box '((1,1),(-2,-2))'
# Number of points in path or polygon# path '((1,0),(0,1),(-1,0))'
@-@ Length or circumference@-@ path '((0,0),(1,0))'
@@ Center@@ circle '((0,0),10)'
## Closest point to first operand on second operandpoint '(0,0)' ## lseg '((2,0),(0,2))'
<-> Distance betweencircle '((0,0),1)' <-> circle '((5,0),1)'
&& Overlaps? (One point in common makes this true.)box '((0,0),(1,1))' && box '((0,0),(2,2))'
<< Is strictly left of?circle '((0,0),1)' << circle '((5,0),1)'
>> Is strictly right of?circle '((5,0),1)' >> circle '((0,0),1)'
&< Does not extend to the right of?box '((0,0),(1,1))' &< box '((0,0),(2,2))'
&> Does not extend to the left of?box '((0,0),(3,3))' &> box '((0,0),(2,2))'
<<| Is strictly below?box '((0,0),(3,3))' <<| box '((3,4),(5,5))'
|>> Is strictly above?box '((3,4),(5,5))' |>> box '((0,0),(3,3))'
&<| Does not extend above?box '((0,0),(1,1))' &<| box '((0,0),(2,2))'
|&> Does not extend below?box '((0,0),(3,3))' |&> box '((0,0),(2,2))'
<^ Is below (allows touching)?circle '((0,0),1)' <^ circle '((0,5),1)'
>^ Is above (allows touching)?circle '((0,5),1)' >^ circle '((0,0),1)'
?# Intersects?lseg '((-1,0),(1,0))' ?# box '((-2,-2),(2,2))'
?- Is horizontal??- lseg '((-1,0),(1,0))'
?- Are horizontally aligned?point '(1,0)' ?- point '(0,0)'
?| Is vertical??| lseg '((-1,0),(1,0))'
?| Are vertically aligned?point '(0,1)' ?| point '(0,0)'
?-| Is perpendicular?lseg '((0,0),(0,1))' ?-| lseg '((0,0),(1,0))'
?|| Are parallel?lseg '((-1,0),(1,0))' ?|| lseg '((-1,2),(1,2))'
@> Contains?circle '((0,0),2)' @> point '(1,1)'
<@ Contained in or on?point '(1,1)' <@ circle '((0,0),2)'
~= Same as?polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))'

Note: Before PostgreSQL 8.2, the containment operators @> and <@ were respectively called ~ and @. These names are still available, but are deprecated and will eventually be removed.

Table 9-32. Geometric Functions

FunctionReturn TypeDescriptionExample
`area(object)`double precisionareaarea(box '((0,0),(1,1))')
`center(object)`pointcentercenter(box '((0,0),(1,2))')
`diameter(circle)`double precisiondiameter of circlediameter(circle '((0,0),2.0)')
`height(box)`double precisionvertical size of boxheight(box '((0,0),(1,1))')
`isclosed(path)`booleana closed path?isclosed(path '((0,0),(1,1),(2,0))')
`isopen(path)`booleanan open path?isopen(path '[(0,0),(1,1),(2,0)]')
`length(object)`double precisionlengthlength(path '((-1,0),(1,0))')
`npoints(path)`intnumber of pointsnpoints(path '[(0,0),(1,1),(2,0)]')
`npoints(polygon)`intnumber of pointsnpoints(polygon '((1,1),(0,0))')
`pclose(path)`pathconvert path to closedpclose(path '[(0,0),(1,1),(2,0)]')
`popen(path)`pathconvert path to openpopen(path '((0,0),(1,1),(2,0))')
`radius(circle)`double precisionradius of circleradius(circle '((0,0),2.0)')
`width(box)`double precisionhorizontal size of boxwidth(box '((0,0),(1,1))')

Table 9-33. Geometric Type Conversion Functions

FunctionReturn TypeDescriptionExample
`box(circle)` boxcircle to boxbox(circle '((0,0),2.0)')
`box(point, point)`boxpoints to boxbox(point '(0,0)', point '(1,1)')
`box(polygon)`boxpolygon to boxbox(polygon '((0,0),(1,1),(2,0))')
`circle(box)` circlebox to circlecircle(box '((0,0),(1,1))')
`circle(point, double precision)`circlecenter and radius to circlecircle(point '(0,0)', 2.0)
`circle(polygon)`circlepolygon to circlecircle(polygon '((0,0),(1,1),(2,0))')
`line(point, point)`linepoints to lineline(point '(-1,0)', point '(1,0)')
`lseg(box)` lsegbox diagonal to line segmentlseg(box '((-1,0),(1,0))')
`lseg(point, point)`lsegpoints to line segmentlseg(point '(-1,0)', point '(1,0)')
`path(polygon)` pathpolygon to pathpath(polygon '((0,0),(1,1),(2,0))')
`point`(double precision, double precision) pointconstruct pointpoint(23.4, -44.5)
`point(box)`pointcenter of boxpoint(box '((-1,0),(1,0))')
`point(circle)`pointcenter of circlepoint(circle '((0,0),2.0)')
`point(lseg)`pointcenter of line segmentpoint(lseg '((-1,0),(1,0))')
`point(polygon)`pointcenter of polygonpoint(polygon '((0,0),(1,1),(2,0))')
`polygon(box)` polygonbox to 4-point polygonpolygon(box '((0,0),(1,1))')
`polygon(circle)`polygoncircle to 12-point polygonpolygon(circle '((0,0),2.0)')
`polygon(npts, circle)`polygoncircle to npts-point polygonpolygon(12, circle '((0,0),2.0)')
`polygon(path)`polygonpath to polygonpolygon(path '((0,0),(1,1),(2,0))')

It is possible to access the two component numbers of a point as though the point were an array with indexes 0 and 1. For example, if t.p is a point column then SELECT p[0] FROM t retrieves the X coordinate and UPDATE t SET p[1] = ... changes the Y coordinate. In the same way, a value of type box or lseg can be treated as an array of two point values.

The `area` function works for the types box, circle, and path. The `area` function only works on the path data type if the points in the path are non-intersecting. For example, the path '((0,0),(0,1),(2,1),(2,2),(1,2),(1,0),(0,0))'::PATH will not work; however, the following visually identical path '((0,0),(0,1),(1,1),(1,2),(2,2),(2,1),(1,1),(1,0),(0,0))'::PATH will work. If the concept of an intersecting versus non-intersecting path is confusing, draw both of the above paths side by side on a piece of graph paper.