Documentation Source Text

Check-in [81cf14c724]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Fix typos in the geopoly document.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 81cf14c72443aee1f5ee526a445a8afa51f82f876130bc6ef7e3bab91059d590
User & Date: drh 2018-09-11 22:44:34
Context
2018-09-12
10:49
Fix typos in the windowfunctions.html document. check-in: 221cce4209 user: drh tags: trunk
2018-09-11
22:44
Fix typos in the geopoly document. check-in: 81cf14c724 user: drh tags: trunk
18:17
Updates to the change log. check-in: 5c91ca999e user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/geopoly.in.

     6      6   
     7      7   <p>
     8      8   The Geopoly module is an alternative interface to the [R-Tree extension] that uses
     9      9   the [http://geojson.org | GeoJSON] notation
    10     10   ([https://tools.ietf.org/html/rfc7946 | RFC-7946]) to describe two-dimensional
    11     11   polygons.  Geopoly includes functions for detecting when one polygon is
    12     12   contained within or overlaps with another, for computing the
    13         -area enclosed by a polygon, for doing linear trasformations of polygons,
           13  +area enclosed by a polygon, for doing linear transformations of polygons,
    14     14   for rendering polygons as
    15     15   [https://en.wikipedia.org/wiki/Scalable_Vector_Graphics | SVG], and other
    16     16   similar operations.
    17     17   
    18     18   <p>
    19     19   Geopoly operates on "simple" polygons - that is, polygons for which
    20     20   the boundary does not intersect itself.  Geopoly thus extends the capabilities
................................................................................
    47     47   The polygon follows the right-hand rule:  When tracing a line from
    48     48   one vertex to the next, the area to the right of the line is outside
    49     49   of the polygon and the area to the left is inside the polygon.
    50     50   In other words, the net rotation of the vertexes is counter-clockwise.
    51     51   
    52     52   <p>
    53     53   For example, the following JSON describes an isosceles triangle, sitting
    54         -on the X access and with an area of 0.5:
           54  +on the X axis and with an area of 0.5:
    55     55   
    56     56   <codeblock>
    57     57   &#91;&#91;0,0],&#91;1,0],&#91;0.5,1],&#91;0,0]]
    58     58   </codeblock>
    59     59   
    60     60   <p>
    61     61   A triangle has three vertexes, but the GeoJSON description of the triangle
................................................................................
   115    115   <p>
   116    116   The previous example will return every row for which the _shape
   117    117   overlaps the polygon in the $query_polygon parameter.  The
   118    118   geopoly_within() function works similarly, but only returns rows for
   119    119   which the _shape is completely contained within $query_polygon.
   120    120   
   121    121   <p>
   122         -Querys (and also DELETE and UPDATE statements) in which the WHERE
          122  +Queries (and also DELETE and UPDATE statements) in which the WHERE
   123    123   clause contains a bare geopoly_overlap() or geopoly_within() function
   124    124   make use of the underly R*Tree data structures for a fast lookup that
   125    125   only has to examine a subset of the rows in the table.  The number of
   126    126   rows examines depends, of course, on the size of the $query_polygon.
   127    127   Large $query_polygons will normally need to look at more rows than small
   128    128   ones.
   129    129   
................................................................................
   146    146   <p>
   147    147   If P1 and P2 are both polygons, then the geopoly_overlap(P1,P2) function returns
   148    148   true if there is any overlap between P1 and P2, or it returns false if P1 and P2
   149    149   completely disjoint.
   150    150   If either P1 or P2 is not a polygon, this routine returns NULL.
   151    151   
   152    152   <p>
   153         -The geopoly_overlap(P1,p2) function is special in that the geopoly virtual
          153  +The geopoly_overlap(P1,P2) function is special in that the geopoly virtual
   154    154   table knows how to use R*Tree indexes to optimize queries in which the 
   155    155   WHERE clause uses geopoly_overlap() as a boolean function.  Only the
   156    156   geopoly_overlap(P1,P2) and geopoly_within(P1,P2) functions have this
   157    157   capability.
   158    158   
   159    159   <tcl>hd_fragment gwithin geopoly_within</tcl>
   160    160   <h2>The geopoly_within(P1,P2) Function</h2>
................................................................................
   162    162   <p>
   163    163   If P1 and P2 are both polygons, then the geopoly_within(P1,P2) function returns
   164    164   true if P2 is completely contained within P1, or it returns false if any part of
   165    165   P2 is outside of P1.  If P1 and P2 are the same polygon, this routine returns true.
   166    166   If either P1 or P2 is not a polygon, this routine returns NULL.
   167    167   
   168    168   <p>
   169         -The geopoly_within(P1,p2) function is special in that the geopoly virtual
          169  +The geopoly_within(P1,P2) function is special in that the geopoly virtual
   170    170   table knows how to use R*Tree indexes to optimize queries in which the 
   171    171   WHERE clause uses geopoly_within() as a boolean function.  Only the
   172    172   geopoly_within(P1,P2) and geopoly_overlap(P1,P2) functions have this
   173    173   capability.
   174    174   
   175    175   <tcl>hd_fragment garea geopoly_area</tcl>
   176    176   <h2>The geopoly_area(P) Function</h2>
................................................................................
   188    188   If P is not a polygon, geopoly_blob(P) returns NULL.
   189    189   
   190    190   <tcl>hd_fragment gjson geopoly_json</tcl>
   191    191   <h2>The geopoly_json(P) Function</h2>
   192    192   
   193    193   <p>
   194    194   If P is a polygon, then geopoly_json(P) returns the GeoJSON representation
   195         -of that polygon as a TEPT string.
          195  +of that polygon as a TEXT string.
   196    196   If P is not a polygon, geopoly_json(P) returns NULL.
   197    197   
   198    198   <tcl>hd_fragment gsvg geopoly_svg</tcl>
   199    199   <h2>The geopoly_svg(P,...) Function</h2>
   200    200   
   201    201   <p>
   202    202   If P is a polygon, then geopoly_svg(P,...) returns a text string which is a
................................................................................
   220    220   can be used to transform the output from cartesian to SVG coordinates prior to
   221    221   passing the polygons into geopoly_svg().
   222    222   
   223    223   <tcl>hd_fragment gbbox geopoly_bbox</tcl>
   224    224   <h2>The geopoly_bbox(P) Function</h2>
   225    225   
   226    226   <p>
   227         -If P is a polygon, then geopoly_bbox(P) returns the a new polygon that is
   228         -the smallest rectangle completely enclosing P.
          227  +If P is a polygon, then geopoly_bbox(P) returns a new polygon that is
          228  +the smallest (axis-aligned) rectangle completely enclosing P.
   229    229   If P is not a polygon, geopoly_bbox(P) returns NULL.
   230    230   
   231    231   <tcl>hd_fragment gpoint geopoly_constains_point</tcl>
   232    232   <h2>The geopoly_contains_point(P,X,Y) Function</h2>
   233    233   
   234    234   <p>
   235    235   If P is a polygon, then geopoly_contains_point(P,X,Y) returns true if and only
................................................................................
   237    237   If P is not a polygon, geopoly_contains_point(P,X,Y) returns NULL.
   238    238   
   239    239   <tcl>hd_fragment xform geopoly_xform</tcl>
   240    240   <h2>The geopoly_xform(P,A,B,C,D,E,F) Function</h2>
   241    241   
   242    242   <p>
   243    243   The geopoly_xform(P,A,B,C,D,E,F) returns a new polygon that is a
   244         -linear transformation of the polygon P and where the transformation
          244  +affine transformation of the polygon P and where the transformation
   245    245   is defined by values A,B,C,D,E,F. If P is not a valid polygon, this
   246    246   routine returns NULL.
   247    247   
   248    248   <p>
   249    249   The transformation converts each vertex of the polygon according to the
   250    250   following formula:
   251    251   
................................................................................
   276    276   Geopoly merely presents a different interface, and provides some extra logic
   277    277   to compute polygon decoding, overlap, and containment.
   278    278   
   279    279   <h2>Binary Encoding of Polygons</h2>
   280    280   
   281    281   <p>
   282    282   Geopoly stores all polygons internally using a binary format.  A binary
   283         -polygon consists of a 4-byte header following by an array coordinate
   284         -pairs which each dimension of each coordinate is of 32-byte floating point
          283  +polygon consists of a 4-byte header following by an array of coordinate
          284  +pairs in which each dimension of each coordinate is of 32-byte floating point
   285    285   number.
   286    286   
   287    287   <p>
   288    288   The first byte of the header is a flag byte.  The least significant bit
   289         -of the flag byte determines whether the coordinate pairs the follow the
          289  +of the flag byte determines whether the coordinate pairs that follow the
   290    290   header are stored big-endian or little-endian.  A value of 0 for the least
   291    291   significant bit means big-endian and a value of 1 means little endian.
   292    292   Other bits of the first byte in the header are reserved for future expansion.
   293    293   
   294    294   <p>
   295    295   The next three bytes in the header record the number of vertexes in the polygon
   296    296   as a big-endian integer.  Thus there is an upper bound of about 16 million