Documentation Source Text

Hex Artifact Content
Login

Artifact 9aefa20090445b54227a2411065cc1b8932827a5fbc2318fb2918a20ab9410a1:


0000: 3c 74 69 74 6c 65 3e 54 68 65 20 47 65 6f 70 6f  <title>The Geopo
0010: 6c 79 20 49 6e 74 65 72 66 61 63 65 20 54 6f 20  ly Interface To 
0020: 54 68 65 20 53 51 4c 69 74 65 20 52 2a 54 72 65  The SQLite R*Tre
0030: 65 20 4d 6f 64 75 6c 65 3c 2f 74 69 74 6c 65 3e  e Module</title>
0040: 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f 72 64  .<tcl>hd_keyword
0050: 73 20 7b 67 65 6f 70 6f 6c 79 7d 20 7b 47 65 6f  s {geopoly} {Geo
0060: 70 6f 6c 79 20 6d 6f 64 75 6c 65 7d 20 7b 47 65  poly module} {Ge
0070: 6f 70 6f 6c 79 20 65 78 74 65 6e 73 69 6f 6e 7d  opoly extension}
0080: 3c 2f 74 63 6c 3e 0a 3c 74 61 62 6c 65 5f 6f 66  </tcl>.<table_of
0090: 5f 63 6f 6e 74 65 6e 74 73 3e 0a 0a 3c 68 31 3e  _contents>..<h1>
00a0: 4f 76 65 72 76 69 65 77 3c 2f 68 31 3e 0a 0a 3c  Overview</h1>..<
00b0: 70 3e 0a 54 68 65 20 47 65 6f 70 6f 6c 79 20 6d  p>.The Geopoly m
00c0: 6f 64 75 6c 65 20 69 73 20 61 6e 20 61 6c 74 65  odule is an alte
00d0: 72 6e 61 74 69 76 65 20 69 6e 74 65 72 66 61 63  rnative interfac
00e0: 65 20 74 6f 20 74 68 65 20 5b 52 2d 54 72 65 65  e to the [R-Tree
00f0: 20 65 78 74 65 6e 73 69 6f 6e 5d 20 74 68 61 74   extension] that
0100: 20 75 73 65 73 0a 74 68 65 20 5b 68 74 74 70 3a   uses.the [http:
0110: 2f 2f 67 65 6f 6a 73 6f 6e 2e 6f 72 67 20 7c 20  //geojson.org | 
0120: 47 65 6f 4a 53 4f 4e 5d 20 6e 6f 74 61 74 69 6f  GeoJSON] notatio
0130: 6e 0a 28 5b 68 74 74 70 73 3a 2f 2f 74 6f 6f 6c  n.([https://tool
0140: 73 2e 69 65 74 66 2e 6f 72 67 2f 68 74 6d 6c 2f  s.ietf.org/html/
0150: 72 66 63 37 39 34 36 20 7c 20 52 46 43 2d 37 39  rfc7946 | RFC-79
0160: 34 36 5d 29 20 74 6f 20 64 65 73 63 72 69 62 65  46]) to describe
0170: 20 74 77 6f 2d 64 69 6d 65 6e 73 69 6f 6e 61 6c   two-dimensional
0180: 0a 70 6f 6c 79 67 6f 6e 73 2e 20 20 47 65 6f 70  .polygons.  Geop
0190: 6f 6c 79 20 69 6e 63 6c 75 64 65 73 20 66 75 6e  oly includes fun
01a0: 63 74 69 6f 6e 73 20 66 6f 72 20 64 65 74 65 63  ctions for detec
01b0: 74 69 6e 67 20 77 68 65 6e 20 6f 6e 65 20 70 6f  ting when one po
01c0: 6c 79 67 6f 6e 20 69 73 0a 63 6f 6e 74 61 69 6e  lygon is.contain
01d0: 65 64 20 77 69 74 68 69 6e 20 6f 72 20 6f 76 65  ed within or ove
01e0: 72 6c 61 70 73 20 77 69 74 68 20 61 6e 6f 74 68  rlaps with anoth
01f0: 65 72 2c 20 66 6f 72 20 63 6f 6d 70 75 74 69 6e  er, for computin
0200: 67 20 74 68 65 0a 61 72 65 61 20 65 6e 63 6c 6f  g the.area enclo
0210: 73 65 64 20 62 79 20 61 20 70 6f 6c 79 67 6f 6e  sed by a polygon
0220: 2c 20 66 6f 72 20 64 6f 69 6e 67 20 6c 69 6e 65  , for doing line
0230: 61 72 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ar transformatio
0240: 6e 73 20 6f 66 20 70 6f 6c 79 67 6f 6e 73 2c 0a  ns of polygons,.
0250: 66 6f 72 20 72 65 6e 64 65 72 69 6e 67 20 70 6f  for rendering po
0260: 6c 79 67 6f 6e 73 20 61 73 0a 5b 68 74 74 70 73  lygons as.[https
0270: 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e  ://en.wikipedia.
0280: 6f 72 67 2f 77 69 6b 69 2f 53 63 61 6c 61 62 6c  org/wiki/Scalabl
0290: 65 5f 56 65 63 74 6f 72 5f 47 72 61 70 68 69 63  e_Vector_Graphic
02a0: 73 20 7c 20 53 56 47 5d 2c 20 61 6e 64 20 6f 74  s | SVG], and ot
02b0: 68 65 72 0a 73 69 6d 69 6c 61 72 20 6f 70 65 72  her.similar oper
02c0: 61 74 69 6f 6e 73 2e 0a 0a 3c 70 3e 0a 54 68 65  ations...<p>.The
02d0: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 66 6f 72   source code for
02e0: 20 47 65 6f 70 6f 6c 79 20 69 73 20 69 6e 63 6c   Geopoly is incl
02f0: 75 64 65 64 20 69 6e 20 74 68 65 20 5b 61 6d 61  uded in the [ama
0300: 6c 67 61 6d 61 74 69 6f 6e 5d 20 62 75 74 20 69  lgamation] but i
0310: 73 20 6e 6f 74 0a 69 6e 63 6c 75 64 65 64 20 69  s not.included i
0320: 6e 20 74 68 65 20 6c 69 62 72 61 72 79 20 75 6e  n the library un
0330: 6c 65 73 73 20 74 68 65 20 5b 2d 44 53 51 4c 49  less the [-DSQLI
0340: 54 45 5f 45 4e 41 42 4c 45 5f 47 45 4f 50 4f 4c  TE_ENABLE_GEOPOL
0350: 59 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Y] compile-time 
0360: 6f 70 74 69 6f 6e 0a 69 73 20 75 73 65 64 2e 0a  option.is used..
0370: 0a 3c 70 3e 0a 47 65 6f 70 6f 6c 79 20 6f 70 65  .<p>.Geopoly ope
0380: 72 61 74 65 73 20 6f 6e 20 22 73 69 6d 70 6c 65  rates on "simple
0390: 22 20 70 6f 6c 79 67 6f 6e 73 20 2d 20 74 68 61  " polygons - tha
03a0: 74 20 69 73 2c 20 70 6f 6c 79 67 6f 6e 73 20 66  t is, polygons f
03b0: 6f 72 20 77 68 69 63 68 0a 74 68 65 20 62 6f 75  or which.the bou
03c0: 6e 64 61 72 79 20 64 6f 65 73 20 6e 6f 74 20 69  ndary does not i
03d0: 6e 74 65 72 73 65 63 74 20 69 74 73 65 6c 66 2e  ntersect itself.
03e0: 20 20 47 65 6f 70 6f 6c 79 20 74 68 75 73 20 65    Geopoly thus e
03f0: 78 74 65 6e 64 73 20 74 68 65 20 63 61 70 61 62  xtends the capab
0400: 69 6c 69 74 69 65 73 0a 6f 66 20 74 68 65 20 5b  ilities.of the [
0410: 52 2d 54 72 65 65 20 65 78 74 65 6e 73 69 6f 6e  R-Tree extension
0420: 5d 20 77 68 69 63 68 20 63 61 6e 20 6f 6e 6c 79  ] which can only
0430: 20 64 65 61 6c 20 77 69 74 68 20 72 65 63 74 61   deal with recta
0440: 6e 67 75 6c 61 72 20 61 72 65 61 73 2e 0a 4f 6e  ngular areas..On
0450: 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
0460: 20 74 68 65 20 5b 52 2d 54 72 65 65 20 65 78 74   the [R-Tree ext
0470: 65 6e 73 69 6f 6e 5d 20 69 73 0a 61 62 6c 65 20  ension] is.able 
0480: 74 6f 20 68 61 6e 64 6c 65 20 62 65 74 77 65 65  to handle betwee
0490: 6e 20 31 20 61 6e 64 20 35 20 63 6f 6f 72 64 69  n 1 and 5 coordi
04a0: 6e 61 74 65 20 64 69 6d 65 6e 73 69 6f 6e 73 2c  nate dimensions,
04b0: 20 77 68 65 72 65 61 73 20 47 65 6f 70 6f 6c 79   whereas Geopoly
04c0: 20 69 73 20 72 65 73 74 72 69 63 74 65 64 0a 74   is restricted.t
04d0: 6f 20 32 2d 64 69 6d 65 6e 73 69 6f 6e 61 6c 20  o 2-dimensional 
04e0: 73 68 61 70 65 73 20 6f 6e 6c 79 2e 0a 0a 3c 70  shapes only...<p
04f0: 3e 0a 45 61 63 68 20 70 6f 6c 79 67 6f 6e 20 69  >.Each polygon i
0500: 6e 20 74 68 65 20 47 65 6f 70 6f 6c 79 20 6d 6f  n the Geopoly mo
0510: 64 75 6c 65 20 63 61 6e 20 62 65 20 61 73 73 6f  dule can be asso
0520: 63 69 61 74 65 64 20 77 69 74 68 20 61 6e 20 61  ciated with an a
0530: 72 62 69 74 72 61 72 79 0a 6e 75 6d 62 65 72 20  rbitrary.number 
0540: 6f 66 20 61 75 78 69 6c 69 61 72 79 20 64 61 74  of auxiliary dat
0550: 61 20 66 69 65 6c 64 73 2e 0a 0a 3c 68 32 3e 47  a fields...<h2>G
0560: 65 6f 4a 53 4f 4e 3c 2f 68 32 3e 0a 0a 3c 70 3e  eoJSON</h2>..<p>
0570: 54 68 65 20 5b 68 74 74 70 73 3a 2f 2f 74 6f 6f  The [https://too
0580: 6c 73 2e 69 65 74 66 2e 6f 72 67 2f 68 74 6d 6c  ls.ietf.org/html
0590: 2f 72 66 63 37 39 34 36 7c 20 47 65 6f 4a 53 4f  /rfc7946| GeoJSO
05a0: 4e 20 73 74 61 6e 64 61 72 64 5d 20 69 73 20 73  N standard] is s
05b0: 79 6e 74 61 78 20 66 6f 72 0a 65 78 63 68 61 6e  yntax for.exchan
05c0: 67 69 6e 67 20 67 65 6f 73 70 61 74 69 61 6c 20  ging geospatial 
05d0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 75 73 69 6e  information usin
05e0: 67 20 4a 53 4f 4e 2e 20 20 47 65 6f 4a 53 4f 4e  g JSON.  GeoJSON
05f0: 20 69 73 20 61 20 72 69 63 68 20 73 74 61 6e 64   is a rich stand
0600: 61 72 64 0a 74 68 61 74 20 63 61 6e 20 64 65 73  ard.that can des
0610: 63 72 69 62 65 20 6e 65 61 72 6c 79 20 61 6e 79  cribe nearly any
0620: 20 6b 69 6e 64 20 6f 66 20 67 65 6f 73 70 61 74   kind of geospat
0630: 69 61 6c 20 63 6f 6e 74 65 6e 74 2e 0a 0a 3c 70  ial content...<p
0640: 3e 54 68 65 20 47 65 6f 70 6f 6c 79 20 6d 6f 64  >The Geopoly mod
0650: 75 6c 65 20 6f 6e 6c 79 20 75 6e 64 65 72 73 74  ule only underst
0660: 61 6e 64 73 0a 61 20 73 6d 61 6c 6c 20 73 75 62  ands.a small sub
0670: 73 65 74 20 6f 66 20 47 65 6f 4a 53 4f 4e 2c 20  set of GeoJSON, 
0680: 62 75 74 20 61 20 63 72 69 74 69 63 61 6c 20 73  but a critical s
0690: 75 62 73 65 74 2e 20 20 0a 49 6e 20 70 61 72 74  ubset.  .In part
06a0: 69 63 75 6c 61 72 2c 20 47 65 6f 4a 53 4f 4e 20  icular, GeoJSON 
06b0: 75 6e 64 65 72 73 74 61 6e 64 73 0a 74 68 65 20  understands.the 
06c0: 4a 53 4f 4e 20 61 72 72 61 79 20 6f 66 20 76 65  JSON array of ve
06d0: 72 74 65 78 65 73 20 74 68 61 74 20 64 65 73 63  rtexes that desc
06e0: 72 69 62 65 73 20 61 20 73 69 6d 70 6c 65 20 70  ribes a simple p
06f0: 6f 6c 79 67 6f 6e 2e 0a 0a 3c 70 3e 41 20 70 6f  olygon...<p>A po
0700: 6c 79 67 6f 6e 20 69 73 20 64 65 66 69 6e 65 64  lygon is defined
0710: 20 62 79 20 69 74 73 20 76 65 72 74 65 78 65 73   by its vertexes
0720: 2e 0a 45 61 63 68 20 76 65 72 74 65 78 20 69 73  ..Each vertex is
0730: 20 61 20 4a 53 4f 4e 20 61 72 72 61 79 20 6f 66   a JSON array of
0740: 20 74 77 6f 20 6e 75 6d 65 72 69 63 20 76 61 6c   two numeric val
0750: 75 65 73 20 77 68 69 63 68 20 61 72 65 20 74 68  ues which are th
0760: 65 0a 58 20 61 6e 64 20 59 20 63 6f 6f 72 64 69  e.X and Y coordi
0770: 6e 61 74 65 73 20 6f 66 20 74 68 65 20 76 65 72  nates of the ver
0780: 74 65 78 2e 0a 41 20 70 6f 6c 79 67 6f 6e 20 69  tex..A polygon i
0790: 73 20 61 20 4a 53 4f 4e 20 61 72 72 61 79 20 6f  s a JSON array o
07a0: 66 20 61 74 20 6c 65 61 73 74 20 66 6f 75 72 20  f at least four 
07b0: 6f 66 20 74 68 65 73 65 20 76 65 72 74 65 78 65  of these vertexe
07c0: 73 2c 20 0a 61 6e 64 20 68 65 6e 63 65 20 69 73  s, .and hence is
07d0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 61 72 72   an array of arr
07e0: 61 79 73 2e 0a 54 68 65 20 66 69 72 73 74 20 61  ays..The first a
07f0: 6e 64 20 6c 61 73 74 20 76 65 72 74 65 78 20 69  nd last vertex i
0800: 6e 20 74 68 65 20 61 72 72 61 79 20 6d 75 73 74  n the array must
0810: 20 62 65 20 74 68 65 20 73 61 6d 65 2e 0a 54 68   be the same..Th
0820: 65 20 70 6f 6c 79 67 6f 6e 20 66 6f 6c 6c 6f 77  e polygon follow
0830: 73 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  s the right-hand
0840: 20 72 75 6c 65 3a 20 20 57 68 65 6e 20 74 72 61   rule:  When tra
0850: 63 69 6e 67 20 61 20 6c 69 6e 65 20 66 72 6f 6d  cing a line from
0860: 0a 6f 6e 65 20 76 65 72 74 65 78 20 74 6f 20 74  .one vertex to t
0870: 68 65 20 6e 65 78 74 2c 20 74 68 65 20 61 72 65  he next, the are
0880: 61 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f  a to the right o
0890: 66 20 74 68 65 20 6c 69 6e 65 20 69 73 20 6f 75  f the line is ou
08a0: 74 73 69 64 65 0a 6f 66 20 74 68 65 20 70 6f 6c  tside.of the pol
08b0: 79 67 6f 6e 20 61 6e 64 20 74 68 65 20 61 72 65  ygon and the are
08c0: 61 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 73  a to the left is
08d0: 20 69 6e 73 69 64 65 20 74 68 65 20 70 6f 6c 79   inside the poly
08e0: 67 6f 6e 2e 0a 49 6e 20 6f 74 68 65 72 20 77 6f  gon..In other wo
08f0: 72 64 73 2c 20 74 68 65 20 6e 65 74 20 72 6f 74  rds, the net rot
0900: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 76 65 72  ation of the ver
0910: 74 65 78 65 73 20 69 73 20 63 6f 75 6e 74 65 72  texes is counter
0920: 2d 63 6c 6f 63 6b 77 69 73 65 2e 0a 0a 3c 70 3e  -clockwise...<p>
0930: 0a 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68  .For example, th
0940: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 4a 53 4f 4e  e following JSON
0950: 20 64 65 73 63 72 69 62 65 73 20 61 6e 20 69 73   describes an is
0960: 6f 73 63 65 6c 65 73 20 74 72 69 61 6e 67 6c 65  osceles triangle
0970: 2c 20 73 69 74 74 69 6e 67 0a 6f 6e 20 74 68 65  , sitting.on the
0980: 20 58 20 61 78 69 73 20 61 6e 64 20 77 69 74 68   X axis and with
0990: 20 61 6e 20 61 72 65 61 20 6f 66 20 30 2e 35 3a   an area of 0.5:
09a0: 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 26 23  ..<codeblock>.&#
09b0: 39 31 3b 26 23 39 31 3b 30 2c 30 5d 2c 26 23 39  91;&#91;0,0],&#9
09c0: 31 3b 31 2c 30 5d 2c 26 23 39 31 3b 30 2e 35 2c  1;1,0],&#91;0.5,
09d0: 31 5d 2c 26 23 39 31 3b 30 2c 30 5d 5d 0a 3c 2f  1],&#91;0,0]].</
09e0: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a  codeblock>..<p>.
09f0: 41 20 74 72 69 61 6e 67 6c 65 20 68 61 73 20 74  A triangle has t
0a00: 68 72 65 65 20 76 65 72 74 65 78 65 73 2c 20 62  hree vertexes, b
0a10: 75 74 20 74 68 65 20 47 65 6f 4a 53 4f 4e 20 64  ut the GeoJSON d
0a20: 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
0a30: 65 20 74 72 69 61 6e 67 6c 65 0a 68 61 73 20 34  e triangle.has 4
0a40: 20 76 65 72 74 65 78 65 73 20 62 65 63 61 75 73   vertexes becaus
0a50: 65 20 74 68 65 20 66 69 72 73 74 20 61 6e 64 20  e the first and 
0a60: 6c 61 73 74 20 76 65 72 74 65 78 20 61 72 65 20  last vertex are 
0a70: 64 75 70 6c 69 63 61 74 65 73 2e 0a 0a 3c 68 32  duplicates...<h2
0a80: 3e 42 69 6e 61 72 79 20 73 74 6f 72 61 67 65 20  >Binary storage 
0a90: 66 6f 72 6d 61 74 3c 2f 68 32 3e 0a 0a 3c 70 3e  format</h2>..<p>
0aa0: 0a 49 6e 74 65 72 6e 61 6c 6c 79 2c 20 47 65 6f  .Internally, Geo
0ab0: 70 6f 6c 79 20 73 74 6f 72 65 73 20 70 6f 6c 79  poly stores poly
0ac0: 67 6f 6e 73 20 69 6e 20 61 20 62 69 6e 61 72 79  gons in a binary
0ad0: 20 66 6f 72 6d 61 74 20 2d 20 61 6e 20 53 51 4c   format - an SQL
0ae0: 20 42 4c 4f 42 2e 0a 44 65 74 61 69 6c 73 20 6f   BLOB..Details o
0af0: 66 20 74 68 65 20 62 69 6e 61 72 79 20 66 6f 72  f the binary for
0b00: 6d 61 74 20 61 72 65 20 67 69 76 65 6e 20 62 65  mat are given be
0b10: 6c 6f 77 2e 0a 41 6c 6c 20 6f 66 20 74 68 65 20  low..All of the 
0b20: 47 65 6f 70 6f 6c 79 20 69 6e 74 65 72 66 61 63  Geopoly interfac
0b30: 65 73 20 61 72 65 20 61 62 6c 65 20 74 6f 20 61  es are able to a
0b40: 63 63 65 70 74 20 70 6f 6c 79 67 6f 6e 73 20 69  ccept polygons i
0b50: 6e 20 65 69 74 68 65 72 20 74 68 65 0a 47 65 6f  n either the.Geo
0b60: 4a 53 4f 4e 20 66 6f 72 6d 61 74 20 6f 72 20 69  JSON format or i
0b70: 6e 20 74 68 65 20 62 69 6e 61 72 79 20 66 6f 72  n the binary for
0b80: 6d 61 74 2e 0a 0a 3c 68 31 3e 55 73 69 6e 67 20  mat...<h1>Using 
0b90: 54 68 65 20 47 65 6f 70 6f 6c 79 20 45 78 74 65  The Geopoly Exte
0ba0: 6e 73 69 6f 6e 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a  nsion</h1>..<p>.
0bb0: 41 20 67 65 6f 70 6f 6c 79 20 74 61 62 6c 65 20  A geopoly table 
0bc0: 69 73 20 63 72 65 61 74 65 64 20 61 73 20 66 6f  is created as fo
0bd0: 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  llows:..<codeblo
0be0: 63 6b 3e 0a 43 52 45 41 54 45 20 56 49 52 54 55  ck>.CREATE VIRTU
0bf0: 41 4c 20 54 41 42 4c 45 20 6e 65 77 74 61 62 20  AL TABLE newtab 
0c00: 55 53 49 4e 47 20 67 65 6f 70 6f 6c 79 28 61 2c  USING geopoly(a,
0c10: 62 2c 63 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  b,c);.</codebloc
0c20: 6b 3e 0a 0a 3c 70 3e 0a 54 68 65 20 73 74 61 74  k>..<p>.The stat
0c30: 65 6d 65 6e 74 20 61 62 6f 76 65 20 63 72 65 61  ement above crea
0c40: 74 65 73 20 61 20 6e 65 77 20 67 65 6f 70 6f 6c  tes a new geopol
0c50: 79 20 74 61 62 6c 65 20 6e 61 6d 65 64 20 22 6e  y table named "n
0c60: 65 77 74 61 62 22 2e 0a 45 76 65 72 79 20 67 65  ewtab"..Every ge
0c70: 6f 70 6f 6c 79 20 74 61 62 6c 65 20 63 6f 6e 74  opoly table cont
0c80: 61 69 6e 73 20 61 20 62 75 69 6c 74 2d 69 6e 20  ains a built-in 
0c90: 69 6e 74 65 67 65 72 20 22 72 6f 77 69 64 22 20  integer "rowid" 
0ca0: 63 6f 6c 75 6d 6e 0a 61 6e 64 20 61 20 22 5f 73  column.and a "_s
0cb0: 68 61 70 65 22 20 63 6f 6c 75 6d 6e 20 74 68 61  hape" column tha
0cc0: 74 20 63 6f 6e 74 61 69 6e 73 0a 74 68 65 20 70  t contains.the p
0cd0: 6f 6c 79 67 6f 6e 20 61 73 73 6f 63 69 61 74 65  olygon associate
0ce0: 64 20 77 69 74 68 20 74 68 61 74 20 72 6f 77 20  d with that row 
0cf0: 6f 66 20 74 68 65 20 74 61 62 6c 65 2e 0a 54 68  of the table..Th
0d00: 65 20 65 78 61 6d 70 6c 65 20 61 62 6f 76 65 20  e example above 
0d10: 61 6c 73 6f 20 64 65 66 69 6e 65 73 20 74 68 72  also defines thr
0d20: 65 65 20 61 75 78 69 6c 69 61 72 79 20 64 61 74  ee auxiliary dat
0d30: 61 20 63 6f 6c 75 6d 6e 73 20 0a 6e 61 6d 65 64  a columns .named
0d40: 20 22 61 22 2c 20 22 62 22 2c 20 61 6e 64 20 22   "a", "b", and "
0d50: 63 22 20 74 68 61 74 20 63 61 6e 20 73 74 6f 72  c" that can stor
0d60: 65 20 77 68 61 74 65 76 65 72 20 61 64 64 69 74  e whatever addit
0d70: 69 6f 6e 61 6c 0a 69 6e 66 6f 72 6d 61 74 69 6f  ional.informatio
0d80: 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
0d90: 6e 20 6e 65 65 64 73 20 74 6f 20 61 73 73 6f 63  n needs to assoc
0da0: 69 61 74 65 0a 77 69 74 68 20 65 61 63 68 20 70  iate.with each p
0db0: 6f 6c 79 67 6f 6e 2e 20 20 49 66 20 74 68 65 72  olygon.  If ther
0dc0: 65 20 69 73 20 6e 6f 20 6e 65 65 64 20 74 6f 20  e is no need to 
0dd0: 73 74 6f 72 65 20 61 75 78 69 6c 69 61 72 79 0a  store auxiliary.
0de0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 74 68 65  information, the
0df0: 20 6c 69 73 74 20 6f 66 20 61 75 78 69 6c 69 61   list of auxilia
0e00: 72 79 20 63 6f 6c 75 6d 6e 73 20 63 61 6e 20 62  ry columns can b
0e10: 65 20 6f 6d 69 74 74 65 64 2e 0a 0a 3c 70 3e 0a  e omitted...<p>.
0e20: 53 74 6f 72 65 20 6e 65 77 20 70 6f 6c 79 67 6f  Store new polygo
0e30: 6e 73 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ns in the table 
0e40: 75 73 69 6e 67 20 6f 72 64 69 6e 61 72 79 20 49  using ordinary I
0e50: 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 73  NSERT statements
0e60: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 49  :..<codeblock>.I
0e70: 4e 53 45 52 54 20 49 4e 54 4f 20 6e 65 77 74 61  NSERT INTO newta
0e80: 62 28 5f 73 68 61 70 65 29 20 56 41 4c 55 45 53  b(_shape) VALUES
0e90: 28 27 26 23 39 31 3b 26 23 39 31 3b 30 2c 30 5d  ('&#91;&#91;0,0]
0ea0: 2c 26 23 39 31 3b 31 2c 30 5d 2c 26 23 39 31 3b  ,&#91;1,0],&#91;
0eb0: 30 2e 35 2c 31 5d 2c 26 23 39 31 3b 30 2c 30 5d  0.5,1],&#91;0,0]
0ec0: 5d 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  ]');.</codeblock
0ed0: 3e 0a 0a 3c 70 3e 0a 55 50 44 41 54 45 20 61 6e  >..<p>.UPDATE an
0ee0: 64 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  d DELETE stateme
0ef0: 6e 74 73 20 77 6f 72 6b 20 73 69 6d 69 6c 61 72  nts work similar
0f00: 6c 79 2e 0a 0a 3c 68 32 3e 51 75 65 72 69 65 73  ly...<h2>Queries
0f10: 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 54 6f 20 71 75  </h2>..<p>.To qu
0f20: 65 72 79 20 74 68 65 20 67 65 6f 70 6f 6c 79 20  ery the geopoly 
0f30: 74 61 62 6c 65 20 75 73 69 6e 67 20 61 6e 20 69  table using an i
0f40: 6e 64 65 78 65 64 20 67 65 6f 73 70 61 74 69 61  ndexed geospatia
0f50: 6c 20 73 65 61 72 63 68 2c 20 0a 75 73 65 20 6f  l search, .use o
0f60: 6e 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ne of the functi
0f70: 6f 6e 73 20 67 65 6f 70 6f 6c 79 5f 6f 76 65 72  ons geopoly_over
0f80: 6c 61 70 28 29 0a 6f 72 20 67 65 6f 70 6f 6c 79  lap().or geopoly
0f90: 5f 77 69 74 68 69 6e 28 29 20 61 73 20 61 20 62  _within() as a b
0fa0: 6f 6f 6c 65 61 6e 20 66 75 6e 63 74 69 6f 6e 20  oolean function 
0fb0: 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  in the WHERE cla
0fc0: 75 73 65 2c 0a 77 69 74 68 20 74 68 65 20 22 5f  use,.with the "_
0fd0: 73 68 61 70 65 22 20 63 6f 6c 75 6d 6e 20 61 73  shape" column as
0fe0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
0ff0: 65 6e 74 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ent to the funct
1000: 69 6f 6e 2e 0a 46 6f 72 20 65 78 61 6d 70 6c 65  ion..For example
1010: 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 53  :..<codeblock>.S
1020: 45 4c 45 43 54 20 2a 20 46 52 4f 4d 20 6e 65 77  ELECT * FROM new
1030: 74 61 62 20 57 48 45 52 45 20 67 65 6f 70 6f 6c  tab WHERE geopol
1040: 79 5f 6f 76 65 72 6c 61 70 28 5f 73 68 61 70 65  y_overlap(_shape
1050: 2c 20 24 71 75 65 72 79 5f 70 6f 6c 79 67 6f 6e  , $query_polygon
1060: 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  );.</codeblock>.
1070: 0a 3c 70 3e 0a 54 68 65 20 70 72 65 76 69 6f 75  .<p>.The previou
1080: 73 20 65 78 61 6d 70 6c 65 20 77 69 6c 6c 20 72  s example will r
1090: 65 74 75 72 6e 20 65 76 65 72 79 20 72 6f 77 20  eturn every row 
10a0: 66 6f 72 20 77 68 69 63 68 20 74 68 65 20 5f 73  for which the _s
10b0: 68 61 70 65 0a 6f 76 65 72 6c 61 70 73 20 74 68  hape.overlaps th
10c0: 65 20 70 6f 6c 79 67 6f 6e 20 69 6e 20 74 68 65  e polygon in the
10d0: 20 24 71 75 65 72 79 5f 70 6f 6c 79 67 6f 6e 20   $query_polygon 
10e0: 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a  parameter.  The.
10f0: 67 65 6f 70 6f 6c 79 5f 77 69 74 68 69 6e 28 29  geopoly_within()
1100: 20 66 75 6e 63 74 69 6f 6e 20 77 6f 72 6b 73 20   function works 
1110: 73 69 6d 69 6c 61 72 6c 79 2c 20 62 75 74 20 6f  similarly, but o
1120: 6e 6c 79 20 72 65 74 75 72 6e 73 20 72 6f 77 73  nly returns rows
1130: 20 66 6f 72 0a 77 68 69 63 68 20 74 68 65 20 5f   for.which the _
1140: 73 68 61 70 65 20 69 73 20 63 6f 6d 70 6c 65 74  shape is complet
1150: 65 6c 79 20 63 6f 6e 74 61 69 6e 65 64 20 77 69  ely contained wi
1160: 74 68 69 6e 20 24 71 75 65 72 79 5f 70 6f 6c 79  thin $query_poly
1170: 67 6f 6e 2e 0a 0a 3c 70 3e 0a 51 75 65 72 69 65  gon...<p>.Querie
1180: 73 20 28 61 6e 64 20 61 6c 73 6f 20 44 45 4c 45  s (and also DELE
1190: 54 45 20 61 6e 64 20 55 50 44 41 54 45 20 73 74  TE and UPDATE st
11a0: 61 74 65 6d 65 6e 74 73 29 20 69 6e 20 77 68 69  atements) in whi
11b0: 63 68 20 74 68 65 20 57 48 45 52 45 0a 63 6c 61  ch the WHERE.cla
11c0: 75 73 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 62  use contains a b
11d0: 61 72 65 20 67 65 6f 70 6f 6c 79 5f 6f 76 65 72  are geopoly_over
11e0: 6c 61 70 28 29 20 6f 72 20 67 65 6f 70 6f 6c 79  lap() or geopoly
11f0: 5f 77 69 74 68 69 6e 28 29 20 66 75 6e 63 74 69  _within() functi
1200: 6f 6e 0a 6d 61 6b 65 20 75 73 65 20 6f 66 20 74  on.make use of t
1210: 68 65 20 75 6e 64 65 72 6c 79 20 52 2a 54 72 65  he underly R*Tre
1220: 65 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  e data structure
1230: 73 20 66 6f 72 20 61 20 66 61 73 74 20 6c 6f 6f  s for a fast loo
1240: 6b 75 70 20 74 68 61 74 0a 6f 6e 6c 79 20 68 61  kup that.only ha
1250: 73 20 74 6f 20 65 78 61 6d 69 6e 65 20 61 20 73  s to examine a s
1260: 75 62 73 65 74 20 6f 66 20 74 68 65 20 72 6f 77  ubset of the row
1270: 73 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20  s in the table. 
1280: 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 72   The number of.r
1290: 6f 77 73 20 65 78 61 6d 69 6e 65 73 20 64 65 70  ows examines dep
12a0: 65 6e 64 73 2c 20 6f 66 20 63 6f 75 72 73 65 2c  ends, of course,
12b0: 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
12c0: 74 68 65 20 24 71 75 65 72 79 5f 70 6f 6c 79 67  the $query_polyg
12d0: 6f 6e 2e 0a 4c 61 72 67 65 20 24 71 75 65 72 79  on..Large $query
12e0: 5f 70 6f 6c 79 67 6f 6e 73 20 77 69 6c 6c 20 6e  _polygons will n
12f0: 6f 72 6d 61 6c 6c 79 20 6e 65 65 64 20 74 6f 20  ormally need to 
1300: 6c 6f 6f 6b 20 61 74 20 6d 6f 72 65 20 72 6f 77  look at more row
1310: 73 20 74 68 61 6e 20 73 6d 61 6c 6c 0a 6f 6e 65  s than small.one
1320: 73 2e 0a 0a 3c 70 3e 0a 51 75 65 72 69 65 73 20  s...<p>.Queries 
1330: 61 67 61 69 6e 73 74 20 74 68 65 20 72 6f 77 69  against the rowi
1340: 64 20 6f 66 20 61 20 67 65 6f 70 6f 6c 79 20 74  d of a geopoly t
1350: 61 62 6c 65 20 61 72 65 20 61 6c 73 6f 20 76 65  able are also ve
1360: 72 79 20 71 75 69 63 6b 2c 20 65 76 65 6e 0a 66  ry quick, even.f
1370: 6f 72 20 74 61 62 6c 65 73 20 77 69 74 68 20 61  or tables with a
1380: 20 76 61 73 74 20 6e 75 6d 62 65 72 20 6f 66 20   vast number of 
1390: 72 6f 77 73 2e 0a 48 6f 77 65 76 65 72 2c 20 6e  rows..However, n
13a0: 6f 6e 65 20 6f 66 20 74 68 65 20 61 75 78 69 6c  one of the auxil
13b0: 69 61 72 79 20 64 61 74 61 20 63 6f 6c 75 6d 6e  iary data column
13c0: 73 20 61 72 65 20 69 6e 64 65 78 65 73 2c 20 61  s are indexes, a
13d0: 6e 64 20 73 6f 20 71 75 65 72 69 65 73 0a 61 67  nd so queries.ag
13e0: 61 69 6e 73 74 20 74 68 65 20 61 75 78 69 6c 69  ainst the auxili
13f0: 61 72 79 20 64 61 74 61 20 63 6f 6c 75 6d 6e 73  ary data columns
1400: 20 77 69 6c 6c 20 69 6e 76 6f 6c 76 65 20 61 20   will involve a 
1410: 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 2e  full table scan.
1420: 0a 0a 3c 68 31 3e 53 70 65 63 69 61 6c 20 46 75  ..<h1>Special Fu
1430: 6e 63 74 69 6f 6e 73 3c 2f 68 31 3e 0a 0a 3c 70  nctions</h1>..<p
1440: 3e 0a 54 68 65 20 67 65 6f 70 6f 6c 79 20 6d 6f  >.The geopoly mo
1450: 64 75 6c 65 20 64 65 66 69 6e 65 73 20 73 65 76  dule defines sev
1460: 65 72 61 6c 20 6e 65 77 20 53 51 4c 20 66 75 6e  eral new SQL fun
1470: 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ctions that are 
1480: 75 73 65 66 75 6c 20 66 6f 72 0a 64 65 61 6c 69  useful for.deali
1490: 6e 67 20 77 69 74 68 20 70 6f 6c 79 67 6f 6e 73  ng with polygons
14a0: 2e 20 20 41 6c 6c 20 70 6f 6c 79 67 6f 6e 20 61  .  All polygon a
14b0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 73  rguments to thes
14c0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  e functions can 
14d0: 62 65 0a 65 69 74 68 65 72 20 74 68 65 20 47 65  be.either the Ge
14e0: 6f 4a 53 4f 4e 20 66 6f 72 6d 61 74 20 6f 72 20  oJSON format or 
14f0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 62 69 6e  the internal bin
1500: 61 72 79 20 66 6f 72 6d 61 74 2e 0a 0a 3c 74 63  ary format...<tc
1510: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 67 6f  l>hd_fragment go
1520: 76 65 72 6c 61 70 20 67 65 6f 70 6f 6c 79 5f 6f  verlap geopoly_o
1530: 76 65 72 6c 61 70 3c 2f 74 63 6c 3e 0a 3c 68 32  verlap</tcl>.<h2
1540: 3e 54 68 65 20 67 65 6f 70 6f 6c 79 5f 6f 76 65  >The geopoly_ove
1550: 72 6c 61 70 28 50 31 2c 50 32 29 20 46 75 6e 63  rlap(P1,P2) Func
1560: 74 69 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 49  tion</h2>..<p>.I
1570: 66 20 50 31 20 61 6e 64 20 50 32 20 61 72 65 20  f P1 and P2 are 
1580: 62 6f 74 68 20 70 6f 6c 79 67 6f 6e 73 2c 20 74  both polygons, t
1590: 68 65 6e 20 74 68 65 20 67 65 6f 70 6f 6c 79 5f  hen the geopoly_
15a0: 6f 76 65 72 6c 61 70 28 50 31 2c 50 32 29 20 66  overlap(P1,P2) f
15b0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a  unction returns.
15c0: 74 72 75 65 20 69 66 20 74 68 65 72 65 20 69 73  true if there is
15d0: 20 61 6e 79 20 6f 76 65 72 6c 61 70 20 62 65 74   any overlap bet
15e0: 77 65 65 6e 20 50 31 20 61 6e 64 20 50 32 2c 20  ween P1 and P2, 
15f0: 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 66 61  or it returns fa
1600: 6c 73 65 20 69 66 20 50 31 20 61 6e 64 20 50 32  lse if P1 and P2
1610: 0a 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 73 6a  .completely disj
1620: 6f 69 6e 74 2e 0a 49 66 20 65 69 74 68 65 72 20  oint..If either 
1630: 50 31 20 6f 72 20 50 32 20 69 73 20 6e 6f 74 20  P1 or P2 is not 
1640: 61 20 70 6f 6c 79 67 6f 6e 2c 20 74 68 69 73 20  a polygon, this 
1650: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1660: 4e 55 4c 4c 2e 0a 0a 3c 70 3e 0a 54 68 65 20 67  NULL...<p>.The g
1670: 65 6f 70 6f 6c 79 5f 6f 76 65 72 6c 61 70 28 50  eopoly_overlap(P
1680: 31 2c 50 32 29 20 66 75 6e 63 74 69 6f 6e 20 69  1,P2) function i
1690: 73 20 73 70 65 63 69 61 6c 20 69 6e 20 74 68 61  s special in tha
16a0: 74 20 74 68 65 20 67 65 6f 70 6f 6c 79 20 76 69  t the geopoly vi
16b0: 72 74 75 61 6c 0a 74 61 62 6c 65 20 6b 6e 6f 77  rtual.table know
16c0: 73 20 68 6f 77 20 74 6f 20 75 73 65 20 52 2a 54  s how to use R*T
16d0: 72 65 65 20 69 6e 64 65 78 65 73 20 74 6f 20 6f  ree indexes to o
16e0: 70 74 69 6d 69 7a 65 20 71 75 65 72 69 65 73 20  ptimize queries 
16f0: 69 6e 20 77 68 69 63 68 20 74 68 65 20 0a 57 48  in which the .WH
1700: 45 52 45 20 63 6c 61 75 73 65 20 75 73 65 73 20  ERE clause uses 
1710: 67 65 6f 70 6f 6c 79 5f 6f 76 65 72 6c 61 70 28  geopoly_overlap(
1720: 29 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 66  ) as a boolean f
1730: 75 6e 63 74 69 6f 6e 2e 20 20 4f 6e 6c 79 20 74  unction.  Only t
1740: 68 65 0a 67 65 6f 70 6f 6c 79 5f 6f 76 65 72 6c  he.geopoly_overl
1750: 61 70 28 50 31 2c 50 32 29 20 61 6e 64 20 67 65  ap(P1,P2) and ge
1760: 6f 70 6f 6c 79 5f 77 69 74 68 69 6e 28 50 31 2c  opoly_within(P1,
1770: 50 32 29 20 66 75 6e 63 74 69 6f 6e 73 20 68 61  P2) functions ha
1780: 76 65 20 74 68 69 73 0a 63 61 70 61 62 69 6c 69  ve this.capabili
1790: 74 79 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  ty...<tcl>hd_fra
17a0: 67 6d 65 6e 74 20 67 77 69 74 68 69 6e 20 67 65  gment gwithin ge
17b0: 6f 70 6f 6c 79 5f 77 69 74 68 69 6e 3c 2f 74 63  opoly_within</tc
17c0: 6c 3e 0a 3c 68 32 3e 54 68 65 20 67 65 6f 70 6f  l>.<h2>The geopo
17d0: 6c 79 5f 77 69 74 68 69 6e 28 50 31 2c 50 32 29  ly_within(P1,P2)
17e0: 20 46 75 6e 63 74 69 6f 6e 3c 2f 68 32 3e 0a 0a   Function</h2>..
17f0: 3c 70 3e 0a 49 66 20 50 31 20 61 6e 64 20 50 32  <p>.If P1 and P2
1800: 20 61 72 65 20 62 6f 74 68 20 70 6f 6c 79 67 6f   are both polygo
1810: 6e 73 2c 20 74 68 65 6e 20 74 68 65 20 67 65 6f  ns, then the geo
1820: 70 6f 6c 79 5f 77 69 74 68 69 6e 28 50 31 2c 50  poly_within(P1,P
1830: 32 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  2) function retu
1840: 72 6e 73 0a 74 72 75 65 20 69 66 20 50 32 20 69  rns.true if P2 i
1850: 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 63 6f 6e  s completely con
1860: 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 50 31  tained within P1
1870: 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20  , or it returns 
1880: 66 61 6c 73 65 20 69 66 20 61 6e 79 20 70 61 72  false if any par
1890: 74 20 6f 66 0a 50 32 20 69 73 20 6f 75 74 73 69  t of.P2 is outsi
18a0: 64 65 20 6f 66 20 50 31 2e 20 20 49 66 20 50 31  de of P1.  If P1
18b0: 20 61 6e 64 20 50 32 20 61 72 65 20 74 68 65 20   and P2 are the 
18c0: 73 61 6d 65 20 70 6f 6c 79 67 6f 6e 2c 20 74 68  same polygon, th
18d0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
18e0: 6e 73 20 74 72 75 65 2e 0a 49 66 20 65 69 74 68  ns true..If eith
18f0: 65 72 20 50 31 20 6f 72 20 50 32 20 69 73 20 6e  er P1 or P2 is n
1900: 6f 74 20 61 20 70 6f 6c 79 67 6f 6e 2c 20 74 68  ot a polygon, th
1910: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1920: 6e 73 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 0a 54 68  ns NULL...<p>.Th
1930: 65 20 67 65 6f 70 6f 6c 79 5f 77 69 74 68 69 6e  e geopoly_within
1940: 28 50 31 2c 50 32 29 20 66 75 6e 63 74 69 6f 6e  (P1,P2) function
1950: 20 69 73 20 73 70 65 63 69 61 6c 20 69 6e 20 74   is special in t
1960: 68 61 74 20 74 68 65 20 67 65 6f 70 6f 6c 79 20  hat the geopoly 
1970: 76 69 72 74 75 61 6c 0a 74 61 62 6c 65 20 6b 6e  virtual.table kn
1980: 6f 77 73 20 68 6f 77 20 74 6f 20 75 73 65 20 52  ows how to use R
1990: 2a 54 72 65 65 20 69 6e 64 65 78 65 73 20 74 6f  *Tree indexes to
19a0: 20 6f 70 74 69 6d 69 7a 65 20 71 75 65 72 69 65   optimize querie
19b0: 73 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 0a  s in which the .
19c0: 57 48 45 52 45 20 63 6c 61 75 73 65 20 75 73 65  WHERE clause use
19d0: 73 20 67 65 6f 70 6f 6c 79 5f 77 69 74 68 69 6e  s geopoly_within
19e0: 28 29 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  () as a boolean 
19f0: 66 75 6e 63 74 69 6f 6e 2e 20 20 4f 6e 6c 79 20  function.  Only 
1a00: 74 68 65 0a 67 65 6f 70 6f 6c 79 5f 77 69 74 68  the.geopoly_with
1a10: 69 6e 28 50 31 2c 50 32 29 20 61 6e 64 20 67 65  in(P1,P2) and ge
1a20: 6f 70 6f 6c 79 5f 6f 76 65 72 6c 61 70 28 50 31  opoly_overlap(P1
1a30: 2c 50 32 29 20 66 75 6e 63 74 69 6f 6e 73 20 68  ,P2) functions h
1a40: 61 76 65 20 74 68 69 73 0a 63 61 70 61 62 69 6c  ave this.capabil
1a50: 69 74 79 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  ity...<tcl>hd_fr
1a60: 61 67 6d 65 6e 74 20 67 61 72 65 61 20 67 65 6f  agment garea geo
1a70: 70 6f 6c 79 5f 61 72 65 61 3c 2f 74 63 6c 3e 0a  poly_area</tcl>.
1a80: 3c 68 32 3e 54 68 65 20 67 65 6f 70 6f 6c 79 5f  <h2>The geopoly_
1a90: 61 72 65 61 28 50 29 20 46 75 6e 63 74 69 6f 6e  area(P) Function
1aa0: 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 49 66 20 50 20  </h2>..<p>.If P 
1ab0: 69 73 20 61 20 70 6f 6c 79 67 6f 6e 2c 20 74 68  is a polygon, th
1ac0: 65 6e 20 67 65 6f 70 6f 6c 79 5f 61 72 65 61 28  en geopoly_area(
1ad0: 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  P) returns the a
1ae0: 72 65 61 20 65 6e 63 6c 6f 73 65 64 20 62 79 0a  rea enclosed by.
1af0: 74 68 61 74 20 70 6f 6c 79 67 6f 6e 2e 20 20 49  that polygon.  I
1b00: 66 20 50 20 69 73 20 6e 6f 74 20 61 20 70 6f 6c  f P is not a pol
1b10: 79 67 6f 6e 2c 20 67 65 6f 70 6f 6c 79 5f 61 72  ygon, geopoly_ar
1b20: 65 61 28 50 29 20 72 65 74 75 72 6e 73 20 4e 55  ea(P) returns NU
1b30: 4c 4c 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  LL...<tcl>hd_fra
1b40: 67 6d 65 6e 74 20 67 62 6c 6f 62 20 67 65 6f 70  gment gblob geop
1b50: 6f 6c 79 5f 62 6c 6f 62 3c 2f 74 63 6c 3e 0a 3c  oly_blob</tcl>.<
1b60: 68 32 3e 54 68 65 20 67 65 6f 70 6f 6c 79 5f 62  h2>The geopoly_b
1b70: 6c 6f 62 28 50 29 20 46 75 6e 63 74 69 6f 6e 3c  lob(P) Function<
1b80: 2f 68 32 3e 0a 0a 3c 70 3e 0a 49 66 20 50 20 69  /h2>..<p>.If P i
1b90: 73 20 61 20 70 6f 6c 79 67 6f 6e 2c 20 74 68 65  s a polygon, the
1ba0: 6e 20 67 65 6f 70 6f 6c 79 5f 62 6c 6f 62 28 50  n geopoly_blob(P
1bb0: 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 62 69  ) returns the bi
1bc0: 6e 61 72 79 20 65 6e 63 6f 64 69 6e 67 0a 6f 66  nary encoding.of
1bd0: 20 74 68 61 74 20 70 6f 6c 79 67 6f 6e 20 61 73   that polygon as
1be0: 20 61 20 42 4c 4f 42 2e 0a 49 66 20 50 20 69 73   a BLOB..If P is
1bf0: 20 6e 6f 74 20 61 20 70 6f 6c 79 67 6f 6e 2c 20   not a polygon, 
1c00: 67 65 6f 70 6f 6c 79 5f 62 6c 6f 62 28 50 29 20  geopoly_blob(P) 
1c10: 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 0a 3c  returns NULL...<
1c20: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
1c30: 67 6a 73 6f 6e 20 67 65 6f 70 6f 6c 79 5f 6a 73  gjson geopoly_js
1c40: 6f 6e 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 54 68 65  on</tcl>.<h2>The
1c50: 20 67 65 6f 70 6f 6c 79 5f 6a 73 6f 6e 28 50 29   geopoly_json(P)
1c60: 20 46 75 6e 63 74 69 6f 6e 3c 2f 68 32 3e 0a 0a   Function</h2>..
1c70: 3c 70 3e 0a 49 66 20 50 20 69 73 20 61 20 70 6f  <p>.If P is a po
1c80: 6c 79 67 6f 6e 2c 20 74 68 65 6e 20 67 65 6f 70  lygon, then geop
1c90: 6f 6c 79 5f 6a 73 6f 6e 28 50 29 20 72 65 74 75  oly_json(P) retu
1ca0: 72 6e 73 20 74 68 65 20 47 65 6f 4a 53 4f 4e 20  rns the GeoJSON 
1cb0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 0a 6f  representation.o
1cc0: 66 20 74 68 61 74 20 70 6f 6c 79 67 6f 6e 20 61  f that polygon a
1cd0: 73 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 2e  s a TEXT string.
1ce0: 0a 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 70  .If P is not a p
1cf0: 6f 6c 79 67 6f 6e 2c 20 67 65 6f 70 6f 6c 79 5f  olygon, geopoly_
1d00: 6a 73 6f 6e 28 50 29 20 72 65 74 75 72 6e 73 20  json(P) returns 
1d10: 4e 55 4c 4c 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  NULL...<tcl>hd_f
1d20: 72 61 67 6d 65 6e 74 20 67 73 76 67 20 67 65 6f  ragment gsvg geo
1d30: 70 6f 6c 79 5f 73 76 67 3c 2f 74 63 6c 3e 0a 3c  poly_svg</tcl>.<
1d40: 68 32 3e 54 68 65 20 67 65 6f 70 6f 6c 79 5f 73  h2>The geopoly_s
1d50: 76 67 28 50 2c 2e 2e 2e 29 20 46 75 6e 63 74 69  vg(P,...) Functi
1d60: 6f 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 49 66 20  on</h2>..<p>.If 
1d70: 50 20 69 73 20 61 20 70 6f 6c 79 67 6f 6e 2c 20  P is a polygon, 
1d80: 74 68 65 6e 20 67 65 6f 70 6f 6c 79 5f 73 76 67  then geopoly_svg
1d90: 28 50 2c 2e 2e 2e 29 20 72 65 74 75 72 6e 73 20  (P,...) returns 
1da0: 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
1db0: 69 63 68 20 69 73 20 61 0a 5b 68 74 74 70 73 3a  ich is a.[https:
1dc0: 2f 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f  //en.wikipedia.o
1dd0: 72 67 2f 77 69 6b 69 2f 53 63 61 6c 61 62 6c 65  rg/wiki/Scalable
1de0: 5f 56 65 63 74 6f 72 5f 47 72 61 70 68 69 63 73  _Vector_Graphics
1df0: 7c 53 63 61 6c 61 62 6c 65 20 56 65 63 74 6f 72  |Scalable Vector
1e00: 20 47 72 61 70 68 69 63 73 20 28 53 56 47 29 5d   Graphics (SVG)]
1e10: 0a 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20  .representation 
1e20: 6f 66 20 74 68 61 74 20 70 6f 6c 79 67 6f 6e 2e  of that polygon.
1e30: 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6d 6f    If there is mo
1e40: 72 65 20 6f 6e 65 20 61 72 67 75 6d 65 6e 74 2c  re one argument,
1e50: 20 74 68 65 6e 20 73 65 63 6f 6e 64 0a 61 6e 64   then second.and
1e60: 20 73 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   subsequent argu
1e70: 6d 65 6e 74 73 20 61 72 65 20 61 64 64 65 64 20  ments are added 
1e80: 61 73 20 61 74 74 72 69 62 75 74 65 73 20 74 6f  as attributes to
1e90: 20 65 61 63 68 20 53 56 47 20 67 6c 79 70 68 2e   each SVG glyph.
1ea0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 0a    For example:..
1eb0: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 53 45 4c 45  <codeblock>.SELE
1ec0: 43 54 20 67 65 6f 70 6f 6c 79 5f 73 76 67 28 24  CT geopoly_svg($
1ed0: 70 6f 6c 79 67 6f 6e 2c 27 63 6c 61 73 73 3d 22  polygon,'class="
1ee0: 70 6f 6c 79 22 27 2c 27 73 74 79 6c 65 3d 22 66  poly"','style="f
1ef0: 69 6c 6c 3a 62 6c 75 65 3b 22 27 29 3b 0a 3c 2f  ill:blue;"');.</
1f00: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a  codeblock>..<p>.
1f10: 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 70 6f  If P is not a po
1f20: 6c 79 67 6f 6e 2c 20 67 65 6f 70 6f 6c 79 5f 73  lygon, geopoly_s
1f30: 76 67 28 50 2c 2e 2e 2e 29 20 72 65 74 75 72 6e  vg(P,...) return
1f40: 73 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 0a 4e 6f 74  s NULL...<p>.Not
1f50: 65 20 74 68 61 74 20 67 65 6f 70 6f 6c 79 20 75  e that geopoly u
1f60: 73 65 73 20 61 20 74 72 61 64 69 74 69 6f 6e 61  ses a traditiona
1f70: 6c 20 72 69 67 68 74 2d 68 61 6e 64 65 64 20 63  l right-handed c
1f80: 61 72 74 65 73 69 61 6e 20 63 6f 6f 72 64 69 6e  artesian coordin
1f90: 61 74 65 20 73 79 73 74 65 6d 0a 77 69 74 68 20  ate system.with 
1fa0: 74 68 65 20 6f 72 69 67 69 6e 20 61 74 20 74 68  the origin at th
1fb0: 65 20 6c 6f 77 65 72 20 6c 65 66 74 2c 20 77 68  e lower left, wh
1fc0: 65 72 65 61 73 20 53 56 47 20 75 73 65 73 20 61  ereas SVG uses a
1fd0: 20 6c 65 66 74 2d 68 61 6e 64 65 64 20 63 6f 6f   left-handed coo
1fe0: 72 64 69 6e 61 74 65 0a 73 79 73 74 65 6d 20 77  rdinate.system w
1ff0: 69 74 68 20 74 68 65 20 6f 72 69 67 69 6e 20 61  ith the origin a
2000: 74 20 74 68 65 20 75 70 70 65 72 20 6c 65 66 74  t the upper left
2010: 2e 20 20 54 68 65 20 67 65 6f 70 6f 6c 79 5f 73  .  The geopoly_s
2020: 76 67 28 29 20 72 6f 75 74 69 6e 65 20 6d 61 6b  vg() routine mak
2030: 65 73 20 6e 6f 0a 61 74 74 65 6d 70 74 20 74 6f  es no.attempt to
2040: 20 74 72 61 6e 73 66 6f 72 6d 20 74 68 65 20 63   transform the c
2050: 6f 6f 72 64 69 6e 61 74 65 20 73 79 73 74 65 6d  oordinate system
2060: 2c 20 73 6f 20 74 68 65 20 64 69 73 70 6c 61 79  , so the display
2070: 65 64 20 69 6d 61 67 65 73 20 61 72 65 20 73 68  ed images are sh
2080: 6f 77 6e 0a 69 6e 20 6d 69 72 72 6f 72 20 69 6d  own.in mirror im
2090: 61 67 65 20 61 6e 64 20 72 6f 74 61 74 65 64 2e  age and rotated.
20a0: 20 20 49 66 20 74 68 61 74 20 69 73 20 75 6e 64    If that is und
20b0: 65 73 69 72 61 62 6c 65 2c 20 74 68 65 20 67 65  esirable, the ge
20c0: 6f 70 6f 6c 79 5f 78 66 6f 72 6d 28 29 20 72 6f  opoly_xform() ro
20d0: 75 74 69 6e 65 0a 63 61 6e 20 62 65 20 75 73 65  utine.can be use
20e0: 64 20 74 6f 20 74 72 61 6e 73 66 6f 72 6d 20 74  d to transform t
20f0: 68 65 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 63  he output from c
2100: 61 72 74 65 73 69 61 6e 20 74 6f 20 53 56 47 20  artesian to SVG 
2110: 63 6f 6f 72 64 69 6e 61 74 65 73 20 70 72 69 6f  coordinates prio
2120: 72 20 74 6f 0a 70 61 73 73 69 6e 67 20 74 68 65  r to.passing the
2130: 20 70 6f 6c 79 67 6f 6e 73 20 69 6e 74 6f 20 67   polygons into g
2140: 65 6f 70 6f 6c 79 5f 73 76 67 28 29 2e 0a 0a 3c  eopoly_svg()...<
2150: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
2160: 67 62 62 6f 78 20 67 65 6f 70 6f 6c 79 5f 62 62  gbbox geopoly_bb
2170: 6f 78 20 67 65 6f 70 6f 6c 79 5f 67 72 6f 75 70  ox geopoly_group
2180: 5f 62 62 6f 78 3c 2f 74 63 6c 3e 0a 3c 68 32 3e  _bbox</tcl>.<h2>
2190: 54 68 65 20 67 65 6f 70 6f 6c 79 5f 62 62 6f 78  The geopoly_bbox
21a0: 28 50 29 20 61 6e 64 20 67 65 6f 70 6f 6c 79 5f  (P) and geopoly_
21b0: 67 72 6f 75 70 5f 62 62 6f 78 28 50 29 20 46 75  group_bbox(P) Fu
21c0: 6e 63 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a 3c 70  nctions</h2>..<p
21d0: 3e 0a 49 66 20 50 20 69 73 20 61 20 70 6f 6c 79  >.If P is a poly
21e0: 67 6f 6e 2c 20 74 68 65 6e 20 67 65 6f 70 6f 6c  gon, then geopol
21f0: 79 5f 62 62 6f 78 28 50 29 20 72 65 74 75 72 6e  y_bbox(P) return
2200: 73 20 61 20 6e 65 77 20 70 6f 6c 79 67 6f 6e 20  s a new polygon 
2210: 74 68 61 74 20 69 73 0a 74 68 65 20 73 6d 61 6c  that is.the smal
2220: 6c 65 73 74 20 28 61 78 69 73 2d 61 6c 69 67 6e  lest (axis-align
2230: 65 64 29 20 72 65 63 74 61 6e 67 6c 65 20 63 6f  ed) rectangle co
2240: 6d 70 6c 65 74 65 6c 79 20 65 6e 63 6c 6f 73 69  mpletely enclosi
2250: 6e 67 20 50 2e 0a 49 66 20 50 20 69 73 20 6e 6f  ng P..If P is no
2260: 74 20 61 20 70 6f 6c 79 67 6f 6e 2c 20 67 65 6f  t a polygon, geo
2270: 70 6f 6c 79 5f 62 62 6f 78 28 50 29 20 72 65 74  poly_bbox(P) ret
2280: 75 72 6e 73 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 0a  urns NULL...<p>.
2290: 54 68 65 20 67 65 6f 70 6f 6c 79 5f 67 72 6f 75  The geopoly_grou
22a0: 70 5f 62 62 6f 78 28 50 29 20 66 75 6e 63 74 69  p_bbox(P) functi
22b0: 6f 6e 20 69 73 20 61 6e 20 61 67 67 72 65 67 61  on is an aggrega
22c0: 74 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 67 65  te version of ge
22d0: 6f 70 6f 6c 79 5f 62 62 6f 78 28 50 29 2e 0a 54  opoly_bbox(P)..T
22e0: 68 65 20 67 65 6f 70 6f 6c 79 5f 67 72 6f 75 70  he geopoly_group
22f0: 5f 62 62 6f 78 28 50 29 20 66 75 6e 63 74 69 6f  _bbox(P) functio
2300: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 6d  n returns the sm
2310: 61 6c 6c 65 73 74 20 72 65 63 74 61 6e 67 6c 65  allest rectangle
2320: 20 74 68 61 74 20 77 69 6c 6c 0a 65 6e 63 6c 6f   that will.enclo
2330: 73 65 20 61 6c 6c 20 50 20 76 61 6c 75 65 73 20  se all P values 
2340: 73 65 65 6e 20 64 75 72 69 6e 67 20 61 67 67 72  seen during aggr
2350: 65 67 61 74 69 6f 6e 2e 0a 0a 3c 74 63 6c 3e 68  egation...<tcl>h
2360: 64 5f 66 72 61 67 6d 65 6e 74 20 67 70 6f 69 6e  d_fragment gpoin
2370: 74 20 67 65 6f 70 6f 6c 79 5f 63 6f 6e 73 74 61  t geopoly_consta
2380: 69 6e 73 5f 70 6f 69 6e 74 3c 2f 74 63 6c 3e 0a  ins_point</tcl>.
2390: 3c 68 32 3e 54 68 65 20 67 65 6f 70 6f 6c 79 5f  <h2>The geopoly_
23a0: 63 6f 6e 74 61 69 6e 73 5f 70 6f 69 6e 74 28 50  contains_point(P
23b0: 2c 58 2c 59 29 20 46 75 6e 63 74 69 6f 6e 3c 2f  ,X,Y) Function</
23c0: 68 32 3e 0a 0a 3c 70 3e 0a 49 66 20 50 20 69 73  h2>..<p>.If P is
23d0: 20 61 20 70 6f 6c 79 67 6f 6e 2c 20 74 68 65 6e   a polygon, then
23e0: 20 67 65 6f 70 6f 6c 79 5f 63 6f 6e 74 61 69 6e   geopoly_contain
23f0: 73 5f 70 6f 69 6e 74 28 50 2c 58 2c 59 29 20 72  s_point(P,X,Y) r
2400: 65 74 75 72 6e 73 20 74 72 75 65 20 69 66 20 61  eturns true if a
2410: 6e 64 20 6f 6e 6c 79 0a 69 66 20 74 68 65 20 63  nd only.if the c
2420: 6f 6f 72 64 69 6e 61 74 65 20 58 2c 59 20 69 73  oordinate X,Y is
2430: 20 69 6e 73 69 64 65 20 6f 72 20 6f 6e 20 74 68   inside or on th
2440: 65 20 62 6f 75 6e 64 61 72 79 20 6f 66 20 74 68  e boundary of th
2450: 65 20 70 6f 6c 79 67 6f 6e 20 50 2e 0a 49 66 20  e polygon P..If 
2460: 50 20 69 73 20 6e 6f 74 20 61 20 70 6f 6c 79 67  P is not a polyg
2470: 6f 6e 2c 20 67 65 6f 70 6f 6c 79 5f 63 6f 6e 74  on, geopoly_cont
2480: 61 69 6e 73 5f 70 6f 69 6e 74 28 50 2c 58 2c 59  ains_point(P,X,Y
2490: 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  ) returns NULL..
24a0: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
24b0: 74 20 78 66 6f 72 6d 20 67 65 6f 70 6f 6c 79 5f  t xform geopoly_
24c0: 78 66 6f 72 6d 3c 2f 74 63 6c 3e 0a 3c 68 32 3e  xform</tcl>.<h2>
24d0: 54 68 65 20 67 65 6f 70 6f 6c 79 5f 78 66 6f 72  The geopoly_xfor
24e0: 6d 28 50 2c 41 2c 42 2c 43 2c 44 2c 45 2c 46 29  m(P,A,B,C,D,E,F)
24f0: 20 46 75 6e 63 74 69 6f 6e 3c 2f 68 32 3e 0a 0a   Function</h2>..
2500: 3c 70 3e 0a 54 68 65 20 67 65 6f 70 6f 6c 79 5f  <p>.The geopoly_
2510: 78 66 6f 72 6d 28 50 2c 41 2c 42 2c 43 2c 44 2c  xform(P,A,B,C,D,
2520: 45 2c 46 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  E,F) function re
2530: 74 75 72 6e 73 20 61 20 6e 65 77 20 70 6f 6c 79  turns a new poly
2540: 67 6f 6e 20 74 68 61 74 20 69 73 20 61 6e 0a 61  gon that is an.a
2550: 66 66 69 6e 65 20 74 72 61 6e 73 66 6f 72 6d 61  ffine transforma
2560: 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 6f 6c 79  tion of the poly
2570: 67 6f 6e 20 50 20 61 6e 64 20 77 68 65 72 65 20  gon P and where 
2580: 74 68 65 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  the transformati
2590: 6f 6e 0a 69 73 20 64 65 66 69 6e 65 64 20 62 79  on.is defined by
25a0: 20 76 61 6c 75 65 73 20 41 2c 42 2c 43 2c 44 2c   values A,B,C,D,
25b0: 45 2c 46 2e 20 49 66 20 50 20 69 73 20 6e 6f 74  E,F. If P is not
25c0: 20 61 20 76 61 6c 69 64 20 70 6f 6c 79 67 6f 6e   a valid polygon
25d0: 2c 20 74 68 69 73 0a 72 6f 75 74 69 6e 65 20 72  , this.routine r
25e0: 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 0a 3c 70  eturns NULL...<p
25f0: 3e 0a 54 68 65 20 74 72 61 6e 73 66 6f 72 6d 61  >.The transforma
2600: 74 69 6f 6e 20 63 6f 6e 76 65 72 74 73 20 65 61  tion converts ea
2610: 63 68 20 76 65 72 74 65 78 20 6f 66 20 74 68 65  ch vertex of the
2620: 20 70 6f 6c 79 67 6f 6e 20 61 63 63 6f 72 64 69   polygon accordi
2630: 6e 67 20 74 6f 20 74 68 65 0a 66 6f 6c 6c 6f 77  ng to the.follow
2640: 69 6e 67 20 66 6f 72 6d 75 6c 61 3a 0a 0a 3c 63  ing formula:..<c
2650: 6f 64 65 62 6c 6f 63 6b 3e 0a 78 31 20 3d 20 41  odeblock>.x1 = A
2660: 2a 78 30 20 2b 20 42 2a 79 30 20 2b 20 45 0a 79  *x0 + B*y0 + E.y
2670: 31 20 3d 20 43 2a 78 30 20 2b 20 44 2a 79 30 20  1 = C*x0 + D*y0 
2680: 2b 20 46 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e  + F.</codeblock>
2690: 0a 0a 3c 70 3e 0a 53 6f 2c 20 66 6f 72 20 65 78  ..<p>.So, for ex
26a0: 61 6d 70 6c 65 2c 20 74 6f 20 6d 6f 76 65 20 61  ample, to move a
26b0: 20 70 6f 6c 79 67 6f 6e 20 62 79 20 73 6f 6d 65   polygon by some
26c0: 20 61 6d 6f 75 6e 74 20 44 58 2c 20 44 59 20 77   amount DX, DY w
26d0: 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 0a  ithout changing.
26e0: 69 74 73 20 73 68 61 70 65 2c 20 75 73 65 3a 0a  its shape, use:.
26f0: 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 67 65 6f  .<codeblock>.geo
2700: 70 6f 6c 79 5f 78 66 6f 72 6d 28 24 70 6f 6c 79  poly_xform($poly
2710: 67 6f 6e 2c 20 31 2c 20 30 2c 20 30 2c 20 31 2c  gon, 1, 0, 0, 1,
2720: 20 24 44 58 2c 20 24 44 59 29 0a 3c 2f 63 6f 64   $DX, $DY).</cod
2730: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 54 6f 20  eblock>..<p>.To 
2740: 72 6f 74 61 74 65 20 61 20 70 6f 6c 79 67 6f 6e  rotate a polygon
2750: 20 62 79 20 52 20 72 61 64 69 61 6e 73 20 61 72   by R radians ar
2760: 6f 75 6e 64 20 74 68 65 20 70 6f 69 6e 74 20 30  ound the point 0
2770: 2c 20 30 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  , 0:..<codeblock
2780: 3e 0a 67 65 6f 70 6f 6c 79 5f 78 66 6f 72 6d 28  >.geopoly_xform(
2790: 24 70 6f 6c 79 67 6f 6e 2c 20 63 6f 73 28 24 52  $polygon, cos($R
27a0: 29 2c 20 73 69 6e 28 24 52 29 2c 20 2d 73 69 6e  ), sin($R), -sin
27b0: 28 24 52 29 2c 20 63 6f 73 28 24 52 29 2c 20 30  ($R), cos($R), 0
27c0: 2c 20 30 29 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  , 0).</codeblock
27d0: 3e 0a 0a 3c 68 31 3e 49 6d 70 6c 65 6d 65 6e 74  >..<h1>Implement
27e0: 61 74 69 6f 6e 20 44 65 74 61 69 6c 73 3c 2f 68  ation Details</h
27f0: 31 3e 0a 0a 3c 70 3e 54 68 65 20 67 65 6f 70 6f  1>..<p>The geopo
2800: 6c 79 20 6d 6f 64 75 6c 65 20 69 73 20 61 6e 20  ly module is an 
2810: 65 78 74 65 6e 73 69 6f 6e 20 74 6f 20 74 68 65  extension to the
2820: 20 5b 52 2d 54 72 65 65 20 65 78 74 65 6e 73 69   [R-Tree extensi
2830: 6f 6e 5d 2e 20 20 47 65 6f 70 6f 6c 79 0a 75 73  on].  Geopoly.us
2840: 65 73 20 74 68 65 20 73 61 6d 65 20 75 6e 64 65  es the same unde
2850: 72 6c 79 69 6e 67 20 6c 6f 67 69 63 20 61 6e 64  rlying logic and
2860: 20 73 68 61 64 6f 77 20 74 61 62 6c 65 73 20 61   shadow tables a
2870: 73 20 74 68 65 20 5b 52 2d 54 72 65 65 20 65 78  s the [R-Tree ex
2880: 74 65 6e 73 69 6f 6e 5d 2e 0a 47 65 6f 70 6f 6c  tension]..Geopol
2890: 79 20 6d 65 72 65 6c 79 20 70 72 65 73 65 6e 74  y merely present
28a0: 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 69 6e  s a different in
28b0: 74 65 72 66 61 63 65 2c 20 61 6e 64 20 70 72 6f  terface, and pro
28c0: 76 69 64 65 73 20 73 6f 6d 65 20 65 78 74 72 61  vides some extra
28d0: 20 6c 6f 67 69 63 0a 74 6f 20 63 6f 6d 70 75 74   logic.to comput
28e0: 65 20 70 6f 6c 79 67 6f 6e 20 64 65 63 6f 64 69  e polygon decodi
28f0: 6e 67 2c 20 6f 76 65 72 6c 61 70 2c 20 61 6e 64  ng, overlap, and
2900: 20 63 6f 6e 74 61 69 6e 6d 65 6e 74 2e 0a 0a 3c   containment...<
2910: 68 32 3e 42 69 6e 61 72 79 20 45 6e 63 6f 64 69  h2>Binary Encodi
2920: 6e 67 20 6f 66 20 50 6f 6c 79 67 6f 6e 73 3c 2f  ng of Polygons</
2930: 68 32 3e 0a 0a 3c 70 3e 0a 47 65 6f 70 6f 6c 79  h2>..<p>.Geopoly
2940: 20 73 74 6f 72 65 73 20 61 6c 6c 20 70 6f 6c 79   stores all poly
2950: 67 6f 6e 73 20 69 6e 74 65 72 6e 61 6c 6c 79 20  gons internally 
2960: 75 73 69 6e 67 20 61 20 62 69 6e 61 72 79 20 66  using a binary f
2970: 6f 72 6d 61 74 2e 20 20 41 20 62 69 6e 61 72 79  ormat.  A binary
2980: 0a 70 6f 6c 79 67 6f 6e 20 63 6f 6e 73 69 73 74  .polygon consist
2990: 73 20 6f 66 20 61 20 34 2d 62 79 74 65 20 68 65  s of a 4-byte he
29a0: 61 64 65 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 62  ader following b
29b0: 79 20 61 6e 20 61 72 72 61 79 20 6f 66 20 63 6f  y an array of co
29c0: 6f 72 64 69 6e 61 74 65 0a 70 61 69 72 73 20 69  ordinate.pairs i
29d0: 6e 20 77 68 69 63 68 20 65 61 63 68 20 64 69 6d  n which each dim
29e0: 65 6e 73 69 6f 6e 20 6f 66 20 65 61 63 68 20 63  ension of each c
29f0: 6f 6f 72 64 69 6e 61 74 65 20 69 73 20 61 20 33  oordinate is a 3
2a00: 32 2d 62 69 74 20 66 6c 6f 61 74 69 6e 67 20 70  2-bit floating p
2a10: 6f 69 6e 74 0a 6e 75 6d 62 65 72 2e 0a 0a 3c 70  oint.number...<p
2a20: 3e 0a 54 68 65 20 66 69 72 73 74 20 62 79 74 65  >.The first byte
2a30: 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 69   of the header i
2a40: 73 20 61 20 66 6c 61 67 20 62 79 74 65 2e 20 20  s a flag byte.  
2a50: 54 68 65 20 6c 65 61 73 74 20 73 69 67 6e 69 66  The least signif
2a60: 69 63 61 6e 74 20 62 69 74 0a 6f 66 20 74 68 65  icant bit.of the
2a70: 20 66 6c 61 67 20 62 79 74 65 20 64 65 74 65 72   flag byte deter
2a80: 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 74 68  mines whether th
2a90: 65 20 63 6f 6f 72 64 69 6e 61 74 65 20 70 61 69  e coordinate pai
2aa0: 72 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  rs that follow t
2ab0: 68 65 0a 68 65 61 64 65 72 20 61 72 65 20 73 74  he.header are st
2ac0: 6f 72 65 64 20 62 69 67 2d 65 6e 64 69 61 6e 20  ored big-endian 
2ad0: 6f 72 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  or little-endian
2ae0: 2e 20 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20  .  A value of 0 
2af0: 66 6f 72 20 74 68 65 20 6c 65 61 73 74 0a 73 69  for the least.si
2b00: 67 6e 69 66 69 63 61 6e 74 20 62 69 74 20 6d 65  gnificant bit me
2b10: 61 6e 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61  ans big-endian a
2b20: 6e 64 20 61 20 76 61 6c 75 65 20 6f 66 20 31 20  nd a value of 1 
2b30: 6d 65 61 6e 73 20 6c 69 74 74 6c 65 20 65 6e 64  means little end
2b40: 69 61 6e 2e 0a 4f 74 68 65 72 20 62 69 74 73 20  ian..Other bits 
2b50: 6f 66 20 74 68 65 20 66 69 72 73 74 20 62 79 74  of the first byt
2b60: 65 20 69 6e 20 74 68 65 20 68 65 61 64 65 72 20  e in the header 
2b70: 61 72 65 20 72 65 73 65 72 76 65 64 20 66 6f 72  are reserved for
2b80: 20 66 75 74 75 72 65 20 65 78 70 61 6e 73 69 6f   future expansio
2b90: 6e 2e 0a 0a 3c 70 3e 0a 54 68 65 20 6e 65 78 74  n...<p>.The next
2ba0: 20 74 68 72 65 65 20 62 79 74 65 73 20 69 6e 20   three bytes in 
2bb0: 74 68 65 20 68 65 61 64 65 72 20 72 65 63 6f 72  the header recor
2bc0: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
2bd0: 76 65 72 74 65 78 65 73 20 69 6e 20 74 68 65 20  vertexes in the 
2be0: 70 6f 6c 79 67 6f 6e 0a 61 73 20 61 20 62 69 67  polygon.as a big
2bf0: 2d 65 6e 64 69 61 6e 20 69 6e 74 65 67 65 72 2e  -endian integer.
2c00: 20 20 54 68 75 73 20 74 68 65 72 65 20 69 73 20    Thus there is 
2c10: 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
2c20: 66 20 61 62 6f 75 74 20 31 36 20 6d 69 6c 6c 69  f about 16 milli
2c30: 6f 6e 0a 76 65 72 74 65 78 65 73 20 70 65 72 20  on.vertexes per 
2c40: 70 6f 6c 79 67 6f 6e 2e 0a 0a 3c 70 3e 0a 46 6f  polygon...<p>.Fo
2c50: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 68 65 61 64  llowing the head
2c60: 65 72 20 69 73 20 74 68 65 20 61 72 72 61 79 20  er is the array 
2c70: 6f 66 20 63 6f 6f 72 64 69 6e 61 74 65 20 70 61  of coordinate pa
2c80: 69 72 73 2e 20 20 45 61 63 68 20 63 6f 6f 72 64  irs.  Each coord
2c90: 69 6e 61 74 65 20 69 73 0a 61 20 33 32 2d 62 69  inate is.a 32-bi
2ca0: 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  t floating point
2cb0: 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 75 73   number.  The us
2cc0: 65 20 6f 66 20 33 32 2d 62 69 74 20 66 6c 6f 61  e of 32-bit floa
2cd0: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2ce0: 73 20 66 6f 72 0a 63 6f 6f 72 64 69 6e 61 74 65  s for.coordinate
2cf0: 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 79  s means that any
2d00: 20 70 6f 69 6e 74 20 6f 6e 20 74 68 65 20 65 61   point on the ea
2d10: 72 74 68 27 73 20 73 75 72 66 61 63 65 20 63 61  rth's surface ca
2d20: 6e 20 62 65 20 6d 61 70 70 65 64 20 77 69 74 68  n be mapped with
2d30: 0a 61 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 66  .a resolution of
2d40: 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 32   approximately 2
2d50: 2e 35 20 6d 65 74 65 72 73 2e 20 20 48 69 67 68  .5 meters.  High
2d60: 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 73 20 61  er resolutions a
2d70: 72 65 20 6f 66 20 63 6f 75 72 73 65 0a 70 6f 73  re of course.pos
2d80: 73 69 62 6c 65 20 69 66 20 74 68 65 20 6d 61 70  sible if the map
2d90: 20 69 73 20 72 65 73 74 72 69 63 74 65 64 20 74   is restricted t
2da0: 6f 20 61 20 73 69 6e 67 6c 65 20 63 6f 6e 74 69  o a single conti
2db0: 6e 65 6e 74 20 6f 72 20 63 6f 75 6e 74 72 79 2e  nent or country.
2dc0: 0a 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 72  .Note that the r
2dd0: 65 73 6f 6c 75 74 69 6f 6e 20 6f 66 20 63 6f 6f  esolution of coo
2de0: 72 64 69 6e 61 74 65 73 20 69 6e 20 74 68 65 20  rdinates in the 
2df0: 67 65 6f 70 6f 6c 79 20 6d 6f 64 75 6c 65 20 69  geopoly module i
2e00: 73 20 73 69 6d 69 6c 61 72 0a 69 6e 20 6d 61 67  s similar.in mag
2e10: 6e 69 74 75 64 65 20 74 6f 20 64 61 69 6c 79 20  nitude to daily 
2e20: 6d 6f 76 65 6d 65 6e 74 20 6f 66 20 70 6f 69 6e  movement of poin
2e30: 74 73 20 6f 6e 20 74 68 65 20 65 61 72 74 68 27  ts on the earth'
2e40: 73 20 73 75 72 66 61 63 65 20 64 75 65 20 74 6f  s surface due to
2e50: 0a 74 69 64 61 6c 20 66 6f 72 63 65 73 2e 0a 0a  .tidal forces...
2e60: 3c 70 3e 0a 54 68 65 20 6c 69 73 74 20 6f 66 20  <p>.The list of 
2e70: 63 6f 6f 72 64 69 6e 61 74 65 73 20 69 6e 20 74  coordinates in t
2e80: 68 65 20 62 69 6e 61 72 79 20 66 6f 72 6d 61 74  he binary format
2e90: 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 72 65 64   contains no red
2ea0: 75 6e 64 61 6e 63 79 2e 20 20 0a 54 68 65 20 6c  undancy.  .The l
2eb0: 61 73 74 20 63 6f 6f 72 64 69 6e 61 74 65 20 69  ast coordinate i
2ec0: 73 20 6e 6f 74 20 61 20 72 65 70 65 61 74 20 6f  s not a repeat o
2ed0: 66 20 74 68 65 20 66 69 72 73 74 20 61 73 20 69  f the first as i
2ee0: 74 20 69 73 20 77 69 74 68 20 47 65 6f 4a 53 4f  t is with GeoJSO
2ef0: 4e 2e 20 20 0a 48 65 6e 63 65 2c 20 74 68 65 72  N.  .Hence, ther
2f00: 65 20 69 73 20 61 6c 77 61 79 73 20 6f 6e 65 20  e is always one 
2f10: 66 65 77 65 72 20 63 6f 6f 72 64 69 6e 61 74 65  fewer coordinate
2f20: 20 70 61 69 72 20 69 6e 20 74 68 65 20 62 69 6e   pair in the bin
2f30: 61 72 79 20 72 65 70 72 65 73 65 6e 74 61 74 69  ary representati
2f40: 6f 6e 20 6f 66 0a 61 20 70 6f 6c 79 67 6f 6e 20  on of.a polygon 
2f50: 63 6f 6d 70 61 72 65 64 20 74 6f 20 74 68 65 20  compared to the 
2f60: 47 65 6f 4a 53 4f 4e 20 72 65 70 72 65 73 65 6e  GeoJSON represen
2f70: 74 61 74 69 6f 6e 2e 0a 0a 3c 68 32 3e 53 68 61  tation...<h2>Sha
2f80: 64 6f 77 20 54 61 62 6c 65 73 3c 2f 68 32 3e 0a  dow Tables</h2>.
2f90: 0a 3c 70 3e 0a 54 68 65 20 67 65 6f 70 6f 6c 79  .<p>.The geopoly
2fa0: 20 6d 6f 64 75 6c 65 20 69 73 20 62 75 69 6c 74   module is built
2fb0: 20 6f 6e 20 74 6f 70 20 6f 66 20 74 68 65 20 5b   on top of the [
2fc0: 52 2d 54 72 65 65 20 65 78 74 65 6e 73 69 6f 6e  R-Tree extension
2fd0: 5d 20 61 6e 64 20 75 73 65 73 20 74 68 65 0a 73  ] and uses the.s
2fe0: 61 6d 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  ame underlying s
2ff0: 68 61 64 6f 77 20 74 61 62 6c 65 73 20 61 6e 64  hadow tables and
3000: 20 61 6c 67 6f 72 69 74 68 6d 73 2e 20 20 46 6f   algorithms.  Fo
3010: 72 20 69 6e 64 65 78 69 6e 67 20 70 75 72 70 6f  r indexing purpo
3020: 73 65 73 2c 20 65 61 63 68 0a 70 6f 6c 79 67 6f  ses, each.polygo
3030: 6e 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  n is represented
3040: 20 69 6e 20 74 68 65 20 73 68 61 64 6f 77 20 74   in the shadow t
3050: 61 62 6c 65 73 20 61 73 20 61 20 72 65 63 74 61  ables as a recta
3060: 6e 67 75 6c 61 72 20 62 6f 75 6e 64 69 6e 67 20  ngular bounding 
3070: 62 6f 78 2e 0a 54 68 65 20 75 6e 64 65 72 6c 79  box..The underly
3080: 69 6e 67 20 52 2d 54 72 65 65 20 69 6d 70 6c 65  ing R-Tree imple
3090: 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 62  mentation uses b
30a0: 6f 75 6e 64 69 6e 67 20 62 6f 78 65 73 20 74 6f  ounding boxes to
30b0: 20 6c 69 6d 69 74 20 74 68 65 20 73 65 61 72 63   limit the searc
30c0: 68 0a 73 70 61 63 65 2e 20 20 54 68 65 6e 20 74  h.space.  Then t
30d0: 68 65 20 67 65 6f 70 6c 6f 79 5f 6f 76 65 72 6c  he geoploy_overl
30e0: 61 70 28 29 20 61 6e 64 2f 6f 72 20 67 65 6f 70  ap() and/or geop
30f0: 6f 6c 79 5f 77 69 74 68 69 6e 28 29 20 72 6f 75  oly_within() rou
3100: 74 69 6e 65 73 20 66 75 72 74 68 65 72 0a 72 65  tines further.re
3110: 66 69 6e 65 20 74 68 65 20 73 65 61 72 63 68 20  fine the search 
3120: 74 6f 20 74 68 65 20 65 78 61 63 74 20 61 6e 73  to the exact ans
3130: 77 65 72 2e 0a                                   wer..