begriffs open source - ai-pg/blob - full-docs/txt/functions-geometry.txt

   1
   2 9.11. Geometric Functions and Operators #
   3
   4    The geometric types point, box, lseg, line, path, polygon, and circle
   5    have a large set of native support functions and operators, shown in
   6    Table 9.36, Table 9.37, and Table 9.38.
   7
   8    Table 9.36. Geometric Operators
   9
  10    Operator
  11
  12    Description
  13
  14    Example(s)
  15
  16    geometric_type + point → geometric_type
  17
  18    Adds the coordinates of the second point to those of each point of the
  19    first argument, thus performing translation. Available for point, box,
  20    path, circle.
  21
  22    box '(1,1),(0,0)' + point '(2,0)' → (3,1),(2,0)
  23
  24    path + path → path
  25
  26    Concatenates two open paths (returns NULL if either path is closed).
  27
  28    path '[(0,0),(1,1)]' + path '[(2,2),(3,3),(4,4)]' →
  29    [(0,0),(1,1),(2,2),(3,3),(4,4)]
  30
  31    geometric_type - point → geometric_type
  32
  33    Subtracts the coordinates of the second point from those of each point
  34    of the first argument, thus performing translation. Available for
  35    point, box, path, circle.
  36
  37    box '(1,1),(0,0)' - point '(2,0)' → (-1,1),(-2,0)
  38
  39    geometric_type * point → geometric_type
  40
  41    Multiplies each point of the first argument by the second point
  42    (treating a point as being a complex number represented by real and
  43    imaginary parts, and performing standard complex multiplication). If
  44    one interprets the second point as a vector, this is equivalent to
  45    scaling the object's size and distance from the origin by the length of
  46    the vector, and rotating it counterclockwise around the origin by the
  47    vector's angle from the x axis. Available for point, box,^[a] path,
  48    circle.
  49
  50    path '((0,0),(1,0),(1,1))' * point '(3.0,0)' → ((0,0),(3,0),(3,3))
  51
  52    path '((0,0),(1,0),(1,1))' * point(cosd(45), sind(45)) →
  53    ((0,0),(0.7071067811865475,0.7071067811865475),(0,1.414213562373095))
  54
  55    geometric_type / point → geometric_type
  56
  57    Divides each point of the first argument by the second point (treating
  58    a point as being a complex number represented by real and imaginary
  59    parts, and performing standard complex division). If one interprets the
  60    second point as a vector, this is equivalent to scaling the object's
  61    size and distance from the origin down by the length of the vector, and
  62    rotating it clockwise around the origin by the vector's angle from the
  63    x axis. Available for point, box,^[a] path, circle.
  64
  65    path '((0,0),(1,0),(1,1))' / point '(2.0,0)' →
  66    ((0,0),(0.5,0),(0.5,0.5))
  67
  68    path '((0,0),(1,0),(1,1))' / point(cosd(45), sind(45)) →
  69    ((0,0),(0.7071067811865476,-0.7071067811865476),(1.4142135623730951,0
  70    ))
  71
  72    @-@ geometric_type → double precision
  73
  74    Computes the total length. Available for lseg, path.
  75
  76    @-@ path '[(0,0),(1,0),(1,1)]' → 2
  77
  78    @@ geometric_type → point
  79
  80    Computes the center point. Available for box, lseg, polygon, circle.
  81
  82    @@ box '(2,2),(0,0)' → (1,1)
  83
  84    # geometric_type → integer
  85
  86    Returns the number of points. Available for path, polygon.
  87
  88    # path '((1,0),(0,1),(-1,0))' → 3
  89
  90    geometric_type # geometric_type → point
  91
  92    Computes the point of intersection, or NULL if there is none. Available
  93    for lseg, line.
  94
  95    lseg '[(0,0),(1,1)]' # lseg '[(1,0),(0,1)]' → (0.5,0.5)
  96
  97    box # box → box
  98
  99    Computes the intersection of two boxes, or NULL if there is none.
 100
 101    box '(2,2),(-1,-1)' # box '(1,1),(-2,-2)' → (1,1),(-1,-1)
 102
 103    geometric_type ## geometric_type → point
 104
 105    Computes the closest point to the first object on the second object.
 106    Available for these pairs of types: (point, box), (point, lseg),
 107    (point, line), (lseg, box), (lseg, lseg), (line, lseg).
 108
 109    point '(0,0)' ## lseg '[(2,0),(0,2)]' → (1,1)
 110
 111    geometric_type <-> geometric_type → double precision
 112
 113    Computes the distance between the objects. Available for all seven
 114    geometric types, for all combinations of point with another geometric
 115    type, and for these additional pairs of types: (box, lseg), (lseg,
 116    line), (polygon, circle) (and the commutator cases).
 117
 118    circle '<(0,0),1>' <-> circle '<(5,0),1>' → 3
 119
 120    geometric_type @> geometric_type → boolean
 121
 122    Does first object contain second? Available for these pairs of types:
 123    (box, point), (box, box), (path, point), (polygon, point), (polygon,
 124    polygon), (circle, point), (circle, circle).
 125
 126    circle '<(0,0),2>' @> point '(1,1)' → t
 127
 128    geometric_type <@ geometric_type → boolean
 129
 130    Is first object contained in or on second? Available for these pairs of
 131    types: (point, box), (point, lseg), (point, line), (point, path),
 132    (point, polygon), (point, circle), (box, box), (lseg, box), (lseg,
 133    line), (polygon, polygon), (circle, circle).
 134
 135    point '(1,1)' <@ circle '<(0,0),2>' → t
 136
 137    geometric_type && geometric_type → boolean
 138
 139    Do these objects overlap? (One point in common makes this true.)
 140    Available for box, polygon, circle.
 141
 142    box '(1,1),(0,0)' && box '(2,2),(0,0)' → t
 143
 144    geometric_type << geometric_type → boolean
 145
 146    Is first object strictly left of second? Available for point, box,
 147    polygon, circle.
 148
 149    circle '<(0,0),1>' << circle '<(5,0),1>' → t
 150
 151    geometric_type >> geometric_type → boolean
 152
 153    Is first object strictly right of second? Available for point, box,
 154    polygon, circle.
 155
 156    circle '<(5,0),1>' >> circle '<(0,0),1>' → t
 157
 158    geometric_type &< geometric_type → boolean
 159
 160    Does first object not extend to the right of second? Available for box,
 161    polygon, circle.
 162
 163    box '(1,1),(0,0)' &< box '(2,2),(0,0)' → t
 164
 165    geometric_type &> geometric_type → boolean
 166
 167    Does first object not extend to the left of second? Available for box,
 168    polygon, circle.
 169
 170    box '(3,3),(0,0)' &> box '(2,2),(0,0)' → t
 171
 172    geometric_type <<| geometric_type → boolean
 173
 174    Is first object strictly below second? Available for point, box,
 175    polygon, circle.
 176
 177    box '(3,3),(0,0)' <<| box '(5,5),(3,4)' → t
 178
 179    geometric_type |>> geometric_type → boolean
 180
 181    Is first object strictly above second? Available for point, box,
 182    polygon, circle.
 183
 184    box '(5,5),(3,4)' |>> box '(3,3),(0,0)' → t
 185
 186    geometric_type &<| geometric_type → boolean
 187
 188    Does first object not extend above second? Available for box, polygon,
 189    circle.
 190
 191    box '(1,1),(0,0)' &<| box '(2,2),(0,0)' → t
 192
 193    geometric_type |&> geometric_type → boolean
 194
 195    Does first object not extend below second? Available for box, polygon,
 196    circle.
 197
 198    box '(3,3),(0,0)' |&> box '(2,2),(0,0)' → t
 199
 200    box <^ box → boolean
 201
 202    Is first object below second (allows edges to touch)?
 203
 204    box '((1,1),(0,0))' <^ box '((2,2),(1,1))' → t
 205
 206    box >^ box → boolean
 207
 208    Is first object above second (allows edges to touch)?
 209
 210    box '((2,2),(1,1))' >^ box '((1,1),(0,0))' → t
 211
 212    geometric_type ?# geometric_type → boolean
 213
 214    Do these objects intersect? Available for these pairs of types: (box,
 215    box), (lseg, box), (lseg, lseg), (lseg, line), (line, box), (line,
 216    line), (path, path).
 217
 218    lseg '[(-1,0),(1,0)]' ?# box '(2,2),(-2,-2)' → t
 219
 220    ?- line → boolean
 221
 222    ?- lseg → boolean
 223
 224    Is line horizontal?
 225
 226    ?- lseg '[(-1,0),(1,0)]' → t
 227
 228    point ?- point → boolean
 229
 230    Are points horizontally aligned (that is, have same y coordinate)?
 231
 232    point '(1,0)' ?- point '(0,0)' → t
 233
 234    ?| line → boolean
 235
 236    ?| lseg → boolean
 237
 238    Is line vertical?
 239
 240    ?| lseg '[(-1,0),(1,0)]' → f
 241
 242    point ?| point → boolean
 243
 244    Are points vertically aligned (that is, have same x coordinate)?
 245
 246    point '(0,1)' ?| point '(0,0)' → t
 247
 248    line ?-| line → boolean
 249
 250    lseg ?-| lseg → boolean
 251
 252    Are lines perpendicular?
 253
 254    lseg '[(0,0),(0,1)]' ?-| lseg '[(0,0),(1,0)]' → t
 255
 256    line ?|| line → boolean
 257
 258    lseg ?|| lseg → boolean
 259
 260    Are lines parallel?
 261
 262    lseg '[(-1,0),(1,0)]' ?|| lseg '[(-1,2),(1,2)]' → t
 263
 264    geometric_type ~= geometric_type → boolean
 265
 266    Are these objects the same? Available for point, box, polygon, circle.
 267
 268    polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))' → t
 269
 270    ^[a] “Rotating” a box with these operators only moves its corner
 271    points: the box is still considered to have sides parallel to the axes.
 272    Hence the box's size is not preserved, as a true rotation would do.
 273
 274 Caution
 275
 276    Note that the “same as” operator, ~=, represents the usual notion of
 277    equality for the point, box, polygon, and circle types. Some of the
 278    geometric types also have an = operator, but = compares for equal areas
 279    only. The other scalar comparison operators (<= and so on), where
 280    available for these types, likewise compare areas.
 281
 282 Note
 283
 284    Before PostgreSQL 14, the point is strictly below/above comparison
 285    operators point <<| point and point |>> point were respectively called
 286    <^ and >^. These names are still available, but are deprecated and will
 287    eventually be removed.
 288
 289    Table 9.37. Geometric Functions
 290
 291    Function
 292
 293    Description
 294
 295    Example(s)
 296
 297    area ( geometric_type ) → double precision
 298
 299    Computes area. Available for box, path, circle. A path input must be
 300    closed, else NULL is returned. Also, if the path is self-intersecting,
 301    the result may be meaningless.
 302
 303    area(box '(2,2),(0,0)') → 4
 304
 305    center ( geometric_type ) → point
 306
 307    Computes center point. Available for box, circle.
 308
 309    center(box '(1,2),(0,0)') → (0.5,1)
 310
 311    diagonal ( box ) → lseg
 312
 313    Extracts box's diagonal as a line segment (same as lseg(box)).
 314
 315    diagonal(box '(1,2),(0,0)') → [(1,2),(0,0)]
 316
 317    diameter ( circle ) → double precision
 318
 319    Computes diameter of circle.
 320
 321    diameter(circle '<(0,0),2>') → 4
 322
 323    height ( box ) → double precision
 324
 325    Computes vertical size of box.
 326
 327    height(box '(1,2),(0,0)') → 2
 328
 329    isclosed ( path ) → boolean
 330
 331    Is path closed?
 332
 333    isclosed(path '((0,0),(1,1),(2,0))') → t
 334
 335    isopen ( path ) → boolean
 336
 337    Is path open?
 338
 339    isopen(path '[(0,0),(1,1),(2,0)]') → t
 340
 341    length ( geometric_type ) → double precision
 342
 343    Computes the total length. Available for lseg, path.
 344
 345    length(path '((-1,0),(1,0))') → 4
 346
 347    npoints ( geometric_type ) → integer
 348
 349    Returns the number of points. Available for path, polygon.
 350
 351    npoints(path '[(0,0),(1,1),(2,0)]') → 3
 352
 353    pclose ( path ) → path
 354
 355    Converts path to closed form.
 356
 357    pclose(path '[(0,0),(1,1),(2,0)]') → ((0,0),(1,1),(2,0))
 358
 359    popen ( path ) → path
 360
 361    Converts path to open form.
 362
 363    popen(path '((0,0),(1,1),(2,0))') → [(0,0),(1,1),(2,0)]
 364
 365    radius ( circle ) → double precision
 366
 367    Computes radius of circle.
 368
 369    radius(circle '<(0,0),2>') → 2
 370
 371    slope ( point, point ) → double precision
 372
 373    Computes slope of a line drawn through the two points.
 374
 375    slope(point '(0,0)', point '(2,1)') → 0.5
 376
 377    width ( box ) → double precision
 378
 379    Computes horizontal size of box.
 380
 381    width(box '(1,2),(0,0)') → 1
 382
 383    Table 9.38. Geometric Type Conversion Functions
 384
 385    Function
 386
 387    Description
 388
 389    Example(s)
 390
 391    box ( circle ) → box
 392
 393    Computes box inscribed within the circle.
 394
 395    box(circle '<(0,0),2>') →
 396    (1.414213562373095,1.414213562373095),(-1.414213562373095,-1.414213562
 397    373095)
 398
 399    box ( point ) → box
 400
 401    Converts point to empty box.
 402
 403    box(point '(1,0)') → (1,0),(1,0)
 404
 405    box ( point, point ) → box
 406
 407    Converts any two corner points to box.
 408
 409    box(point '(0,1)', point '(1,0)') → (1,1),(0,0)
 410
 411    box ( polygon ) → box
 412
 413    Computes bounding box of polygon.
 414
 415    box(polygon '((0,0),(1,1),(2,0))') → (2,1),(0,0)
 416
 417    bound_box ( box, box ) → box
 418
 419    Computes bounding box of two boxes.
 420
 421    bound_box(box '(1,1),(0,0)', box '(4,4),(3,3)') → (4,4),(0,0)
 422
 423    circle ( box ) → circle
 424
 425    Computes smallest circle enclosing box.
 426
 427    circle(box '(1,1),(0,0)') → <(0.5,0.5),0.7071067811865476>
 428
 429    circle ( point, double precision ) → circle
 430
 431    Constructs circle from center and radius.
 432
 433    circle(point '(0,0)', 2.0) → <(0,0),2>
 434
 435    circle ( polygon ) → circle
 436
 437    Converts polygon to circle. The circle's center is the mean of the
 438    positions of the polygon's points, and the radius is the average
 439    distance of the polygon's points from that center.
 440
 441    circle(polygon '((0,0),(1,3),(2,0))') → <(1,1),1.6094757082487299>
 442
 443    line ( point, point ) → line
 444
 445    Converts two points to the line through them.
 446
 447    line(point '(-1,0)', point '(1,0)') → {0,-1,0}
 448
 449    lseg ( box ) → lseg
 450
 451    Extracts box's diagonal as a line segment.
 452
 453    lseg(box '(1,0),(-1,0)') → [(1,0),(-1,0)]
 454
 455    lseg ( point, point ) → lseg
 456
 457    Constructs line segment from two endpoints.
 458
 459    lseg(point '(-1,0)', point '(1,0)') → [(-1,0),(1,0)]
 460
 461    path ( polygon ) → path
 462
 463    Converts polygon to a closed path with the same list of points.
 464
 465    path(polygon '((0,0),(1,1),(2,0))') → ((0,0),(1,1),(2,0))
 466
 467    point ( double precision, double precision ) → point
 468
 469    Constructs point from its coordinates.
 470
 471    point(23.4, -44.5) → (23.4,-44.5)
 472
 473    point ( box ) → point
 474
 475    Computes center of box.
 476
 477    point(box '(1,0),(-1,0)') → (0,0)
 478
 479    point ( circle ) → point
 480
 481    Computes center of circle.
 482
 483    point(circle '<(0,0),2>') → (0,0)
 484
 485    point ( lseg ) → point
 486
 487    Computes center of line segment.
 488
 489    point(lseg '[(-1,0),(1,0)]') → (0,0)
 490
 491    point ( polygon ) → point
 492
 493    Computes center of polygon (the mean of the positions of the polygon's
 494    points).
 495
 496    point(polygon '((0,0),(1,1),(2,0))') → (1,0.3333333333333333)
 497
 498    polygon ( box ) → polygon
 499
 500    Converts box to a 4-point polygon.
 501
 502    polygon(box '(1,1),(0,0)') → ((0,0),(0,1),(1,1),(1,0))
 503
 504    polygon ( circle ) → polygon
 505
 506    Converts circle to a 12-point polygon.
 507
 508    polygon(circle '<(0,0),2>') →
 509    ((-2,0),(-1.7320508075688774,0.9999999999999999),(-1.0000000000000002
 510    ,1.7320508075688772),(-1.2246063538223773e-16,2),(0.9999999999999996,
 511    1.7320508075688774),(1.732050807568877,1.0000000000000007),(2,2.44921
 512    27076447545e-16),(1.7320508075688776,-0.9999999999999994),(1.00000000
 513    00000009,-1.7320508075688767),(3.673819061467132e-16,-2),(-0.99999999
 514    99999987,-1.732050807568878),(-1.7320508075688767,-1.0000000000000009)
 515    )
 516
 517    polygon ( integer, circle ) → polygon
 518
 519    Converts circle to an n-point polygon.
 520
 521    polygon(4, circle '<(3,0),1>') →
 522    ((2,0),(3,1),(4,1.2246063538223773e-16),(3,-1))
 523
 524    polygon ( path ) → polygon
 525
 526    Converts closed path to a polygon with the same list of points.
 527
 528    polygon(path '((0,0),(1,1),(2,0))') → ((0,0),(1,1),(2,0))
 529
 530    It is possible to access the two component numbers of a point as though
 531    the point were an array with indexes 0 and 1. For example, if t.p is a
 532    point column then SELECT p[0] FROM t retrieves the X coordinate and
 533    UPDATE t SET p[1] = ... changes the Y coordinate. In the same way, a
 534    value of type box or lseg can be treated as an array of two point
 535    values.