| rev |
line source |
|
jbe@83
|
1 <html><head><title>pgLatLon v0.16 documentation</title></head><body>
|
|
jbe@83
|
2 <h1>pgLatLon v0.16 documentation</h1>
|
|
jbe@0
|
3 <p>pgLatLon is a spatial database extension for the PostgreSQL object-relational
|
|
jbe@0
|
4 database management system providing geographic data types and spatial indexing
|
|
jbe@0
|
5 for the WGS-84 spheroid.</p>
|
|
jbe@32
|
6 <p>While many other spatial databases still use imprecise bounding boxes for
|
|
jbe@32
|
7 many operations, pgLatLon aims to support more precise calculations for all
|
|
jbe@32
|
8 implemented geographic operators. Efficient indexing of geographic objects
|
|
jbe@32
|
9 is provided using space-filling fractal curves. Optimizations on bit level
|
|
jbe@32
|
10 (including logarithmic compression) allow for a highly memory-efficient
|
|
jbe@32
|
11 non-overlapping index suitable for huge datasets.</p>
|
|
jbe@11
|
12 <p>pgLatLon is a lightweight solution as it only depends on PostgreSQL itself (and
|
|
jbe@11
|
13 a C compiler for building).</p>
|
|
jbe@0
|
14 <p>Unlike competing spatial extensions for PostgreSQL, pgLatLon is available under
|
|
jbe@0
|
15 the permissive MIT/X11 license to avoid problems with viral licenses like the
|
|
jbe@0
|
16 GPLv2/v3.</p>
|
|
jbe@0
|
17 <h2>Installation</h2>
|
|
jbe@0
|
18 <h3>Automatic installation</h3>
|
|
jbe@0
|
19 <p>Prerequisites:</p>
|
|
jbe@0
|
20 <ul>
|
|
jbe@0
|
21 <li>Ensure that the <code>pg_config</code> binary is in your path (shipped with PostgreSQL).</li>
|
|
jbe@0
|
22 <li>Ensure that GNU Make is available (either as <code>make</code> or <code>gmake</code>).</li>
|
|
jbe@0
|
23 </ul>
|
|
jbe@0
|
24 <p>Then simply type:</p>
|
|
jbe@0
|
25 <pre><code>make install
|
|
jbe@0
|
26 </code></pre>
|
|
jbe@0
|
27 <h3>Manual installation</h3>
|
|
jbe@0
|
28 <p>It is also possible to compile and install the extension without GNU Make as
|
|
jbe@0
|
29 follows:</p>
|
|
jbe@74
|
30 <pre><code>cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0010.so latlon-v0010.c
|
|
jbe@74
|
31 cp latlon-v0010.so `pg_config --pkglibdir`
|
|
jbe@0
|
32 cp latlon.control `pg_config --sharedir`/extension/
|
|
jbe@13
|
33 cp latlon--*.sql `pg_config --sharedir`/extension/
|
|
jbe@0
|
34 </code></pre>
|
|
jbe@0
|
35 <h3>Loading the extension</h3>
|
|
jbe@0
|
36 <p>After installation, you can create a database and load the extension as
|
|
jbe@0
|
37 follows:</p>
|
|
jbe@0
|
38 <pre><code>% createdb test_database
|
|
jbe@0
|
39 % psql test_database
|
|
jbe@0
|
40 psql (9.5.4)
|
|
jbe@82
|
41 Type "help" for help.
|
|
jbe@0
|
42
|
|
jbe@0
|
43 test_database=# CREATE EXTENSION latlon;
|
|
jbe@0
|
44 </code></pre>
|
|
jbe@16
|
45 <h3>Updating</h3>
|
|
jbe@16
|
46 <p>Before updating your database cluster to a new version of pgLatLon, you may
|
|
jbe@82
|
47 want to uninstall the old by calling "<code>make uninstall</code>" in the unpacked source
|
|
jbe@16
|
48 code directory of your old pgLatLon version. You may also manually delete the
|
|
jbe@16
|
49 <code>latlon-v????.so</code> files from your PostgreSQL library directory and the
|
|
jbe@16
|
50 <code>latlon.control</code> and <code>latlon--*.sql</code> files from your PostgreSQL extension
|
|
jbe@16
|
51 directory.</p>
|
|
jbe@16
|
52 <p>The new version can be installed as described above. For altering an existing
|
|
jbe@16
|
53 database to use the installed new version (mandatory if you removed the old
|
|
jbe@16
|
54 version), execute the following SQL command in the respective databases:</p>
|
|
jbe@16
|
55 <pre><code>ALTER EXTENSION latlon UPDATE;
|
|
jbe@16
|
56 </code></pre>
|
|
jbe@16
|
57 <p>If the update contains modifications to operator classes, it may be necessary
|
|
jbe@16
|
58 to drop all indices on geographic data types first (you will get an error
|
|
jbe@16
|
59 message in this case). These indices can be re-created after the update.</p>
|
|
jbe@16
|
60 <p>Note that taking several update steps at once (e.g. updating from version 0.2
|
|
jbe@16
|
61 directly to version 0.4) requires the intermediate versions to be installed
|
|
jbe@16
|
62 (i.e. in this example version 0.3 would need to be installed). Whenever you
|
|
jbe@16
|
63 install or uninstall an intermediate or old version, make sure to afterwards
|
|
jbe@16
|
64 re-install the latest pgLatLon version to ensure that the <code>latlon.control</code> file
|
|
jbe@16
|
65 is available and points to the latest version.</p>
|
|
jbe@16
|
66 <p>If the update contains modifications to the internal data representation
|
|
jbe@16
|
67 format, an update path might not be available. In this case, create a dump of
|
|
jbe@16
|
68 your database, delete your database, and restore it from your dump.</p>
|
|
jbe@16
|
69 <p>Be sure to always keep backups of all your data before attempting to update.</p>
|
|
jbe@0
|
70 <h2>Reference</h2>
|
|
jbe@0
|
71 <h3>1. Types</h3>
|
|
jbe@0
|
72 <p>pgLatLon provides four geographic types: <code>epoint</code>, <code>ebox</code>, <code>ecircle</code>, and
|
|
jbe@0
|
73 <code>ecluster</code>.</p>
|
|
jbe@0
|
74 <h4><code>epoint</code></h4>
|
|
jbe@33
|
75 <p>A point on the Earth spheroid (WGS-84).</p>
|
|
jbe@0
|
76 <p>The text input format is <code>'[N|S]<float> [E|W]<float>'</code>, where each float is in
|
|
jbe@0
|
77 degrees. Note the required white space between the latitude and longitude
|
|
jbe@0
|
78 components. Each floating point number may have a sign, in which case <code>N</code>/<code>S</code>
|
|
jbe@0
|
79 or <code>E</code>/<code>W</code> are switched respectively (e.g. <code>E-5</code> is the same as <code>W5</code>).</p>
|
|
jbe@0
|
80 <p>An <code>epoint</code> may also be created from two floating point numbers by calling
|
|
jbe@0
|
81 <code>epoint(latitude, longitude)</code>, where positive latitudes are used for the
|
|
jbe@0
|
82 northern hemisphere, negative latitudes are used for the southern hemisphere,
|
|
jbe@0
|
83 positive longitudes indicate positions east of the prime meridian, and negative
|
|
jbe@0
|
84 longitudes indicate positions west of the prime meridian.</p>
|
|
jbe@0
|
85 <p>Latitudes exceeding -90 or +90 degrees are truncated to -90 or +90
|
|
jbe@0
|
86 respectively, in which case a warning will be issued. Longitudes exceeding -180
|
|
jbe@0
|
87 or +180 degrees will be converted to values between -180 and +180 (both
|
|
jbe@0
|
88 inclusive) by adding or substracting a multiple of 360 degrees, in which case a
|
|
jbe@0
|
89 notice will be issued.</p>
|
|
jbe@0
|
90 <p>If the latitude is -90 or +90 (south pole or north pole), a longitude value is
|
|
jbe@0
|
91 still stored in the datum, and if a point is on the prime meridian or the
|
|
jbe@0
|
92 180th meridian, the east/west bit is also stored in the datum. In case of the
|
|
jbe@0
|
93 prime meridian, this is done by storing a floating point value of -0 for
|
|
jbe@0
|
94 0 degrees west and a value of +0 for 0 degrees east. In case of the
|
|
jbe@0
|
95 180th meridian, this is done by storing -180 or +180 respectively. The equality
|
|
jbe@33
|
96 operator, however, returns true when the same points on Earth are described,
|
|
jbe@0
|
97 i.e. the longitude is ignored for the poles, and 180 degrees west is considered
|
|
jbe@0
|
98 to be equal to 180 degrees east.</p>
|
|
jbe@0
|
99 <h4><code>ebox</code></h4>
|
|
jbe@33
|
100 <p>An area on Earth demarcated by a southern and northern latitude, and a western
|
|
jbe@0
|
101 and eastern longitude (all given in WGS-84).</p>
|
|
jbe@0
|
102 <p>The text input format is
|
|
jbe@0
|
103 <code>'{N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float>'</code>, where each float is in
|
|
jbe@0
|
104 degrees. The ordering of the four white-space separated blocks is not
|
|
jbe@0
|
105 significant. To include the 180th meridian, one longitude boundary must be
|
|
jbe@0
|
106 equal to or exceed <code>W180</code> or <code>E180</code>, e.g. <code>'N10 N20 E170 E190'</code>.</p>
|
|
jbe@0
|
107 <p>A special value is the empty area, denoted by the text represenation <code>'empty'</code>.
|
|
jbe@0
|
108 Such an <code>ebox</code> does not contain any point.</p>
|
|
jbe@0
|
109 <p>An <code>ebox</code> may also be created from four floating point numbers by calling
|
|
jbe@0
|
110 <code>ebox(min_latitude, max_latitude, min_longitude, max_longitude)</code>, where
|
|
jbe@0
|
111 positive values are used for north and east, and negative values are used for
|
|
jbe@0
|
112 south and west. If <code>min_latitude</code> is strictly greater than <code>max_latitude</code>, an
|
|
jbe@0
|
113 empty <code>ebox</code> is created. If <code>min_longitude</code> is greater than <code>max_longitude</code> and
|
|
jbe@0
|
114 if both longitudes are between -180 and +180 degrees, then the area oriented in
|
|
jbe@0
|
115 such way that the 180th meridian is included.</p>
|
|
jbe@0
|
116 <p>If the longitude span is less than 120 degrees, an <code>ebox</code> may be alternatively
|
|
jbe@82
|
117 created from two <code>epoints</code> in the following way: <code>ebox(epoint(lat1, lon1), epoint(lat2, lon2))</code>. In this case <code>lat1</code> and <code>lat2</code> as well as <code>lon1</code> and
|
|
jbe@0
|
118 <code>lon2</code> can be swapped without any impact.</p>
|
|
jbe@0
|
119 <h4><code>ecircle</code></h4>
|
|
jbe@0
|
120 <p>An area containing all points not farther away from a given center point
|
|
jbe@0
|
121 (WGS-84) than a given radius.</p>
|
|
jbe@0
|
122 <p>The text input format is <code>'{N|S}<float> {E|W}<float> <float>'</code>, where the first
|
|
jbe@0
|
123 two floats denote the center point in degrees and the third float denotes the
|
|
jbe@0
|
124 radius in meters. A radius equal to minus infinity denotes an empty circle
|
|
jbe@0
|
125 which contains no point at all (despite having a center), while a radius equal
|
|
jbe@0
|
126 to zero denotes a circle that includes a single point.</p>
|
|
jbe@0
|
127 <p>An <code>ecircle</code> may also be created by calling <code>ecircle(epoint(...), radius)</code> or
|
|
jbe@82
|
128 from three floating point numbers by calling <code>ecircle(latitude, longitude, radius)</code>.</p>
|
|
jbe@0
|
129 <h4><code>ecluster</code></h4>
|
|
jbe@0
|
130 <p>A collection of points, paths, polygons, and outlines on the WGS-84 spheroid.
|
|
jbe@0
|
131 Each path, polygon, or outline must cover a longitude range of less than
|
|
jbe@0
|
132 180 degrees to avoid ambiguities.</p>
|
|
jbe@0
|
133 <p>The text input format is a white-space separated list of the following items:</p>
|
|
jbe@0
|
134 <ul>
|
|
jbe@0
|
135 <li><code>point ({N|S}<float> {E|W}<float>)</code></li>
|
|
jbe@0
|
136 <li><code>path ({N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> ...)</code></li>
|
|
jbe@0
|
137 <li><code>outline ({N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> ...)</code></li>
|
|
jbe@0
|
138 <li><code>polygon ({N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> {N|S}<float> {E|W}<float> ...)</code></li>
|
|
jbe@0
|
139 </ul>
|
|
jbe@0
|
140 <p>Paths are open by default (i.e. there is no connection from the last point in
|
|
jbe@0
|
141 the list to the first point in the list). Outlines and polygons, in contrast,
|
|
jbe@0
|
142 are automatically closed (i.e. there is a line segment from the last point in
|
|
jbe@0
|
143 the list to the first point in the list) which means the first point should not
|
|
jbe@0
|
144 be repeated as last point in the list. Polygons are filled, outlines are not.</p>
|
|
jbe@0
|
145 <h3>2. Indices</h3>
|
|
jbe@0
|
146 <p>Two kinds of indices are supported: B-tree and GiST indices.</p>
|
|
jbe@0
|
147 <h4>B-tree indices</h4>
|
|
jbe@0
|
148 <p>A B-tree index can be used for simple equality searches and is supported by the
|
|
jbe@0
|
149 <code>epoint</code>, <code>ebox</code>, and <code>ecircle</code> data types. B-tree indices can not be used for
|
|
jbe@0
|
150 geographic searches.</p>
|
|
jbe@0
|
151 <h4>GiST indices</h4>
|
|
jbe@0
|
152 <p>For geographic searches, GiST indices must be used. The <code>epoint</code>, <code>ecircle</code>,
|
|
jbe@0
|
153 and <code>ecluster</code> data types support GiST indexing. A GiST index for geographic
|
|
jbe@0
|
154 searches can be created as follows:</p>
|
|
jbe@0
|
155 <pre><code>CREATE TABLE tbl (
|
|
jbe@0
|
156 id serial4 PRIMARY KEY,
|
|
jbe@0
|
157 loc epoint NOT NULL );
|
|
jbe@0
|
158
|
|
jbe@0
|
159 CREATE INDEX name_of_index ON tbl USING gist (loc);
|
|
jbe@0
|
160 </code></pre>
|
|
jbe@0
|
161 <p>GiST indices also support nearest neighbor searches when using the distance
|
|
jbe@0
|
162 operator (<code><-></code>) in the ORDER BY clause.</p>
|
|
jbe@0
|
163 <h4>Indices on other data types (e.g. GeoJSON)</h4>
|
|
jbe@0
|
164 <p>Note that further types can be indexed by using an index on an expression with
|
|
jbe@0
|
165 a conversion function. One conversion function provided by pgLatLon is the
|
|
jbe@49
|
166 <code>GeoJSON_to_ecluster(jsonb, text)</code> function:</p>
|
|
jbe@0
|
167 <pre><code>CREATE TABLE tbl (
|
|
jbe@0
|
168 id serial4 PRIMARY KEY,
|
|
jbe@0
|
169 loc jsonb NOT NULL );
|
|
jbe@0
|
170
|
|
jbe@82
|
171 CREATE INDEX name_of_index ON tbl USING gist ((GeoJSON_to_ecluster("loc")));
|
|
jbe@0
|
172 </code></pre>
|
|
jbe@0
|
173 <p>When using the conversion function in an expression, the index will be used
|
|
jbe@0
|
174 automatically:</p>
|
|
jbe@82
|
175 <pre><code>SELECT * FROM tbl WHERE GeoJSON_to_ecluster("loc") && 'N50 E10 10000'::ecircle;
|
|
jbe@0
|
176 </code></pre>
|
|
jbe@0
|
177 <h3>3. Operators</h3>
|
|
jbe@0
|
178 <h4>Equality operator <code>=</code></h4>
|
|
jbe@0
|
179 <p>Tests if two geographic objects are equal.</p>
|
|
jbe@0
|
180 <p>The longitude is ignored for the poles, and 180 degrees west is considered to
|
|
jbe@0
|
181 be equal to 180 degrees east.</p>
|
|
jbe@0
|
182 <p>For boxes and circles, two empty objects are considered equal. (Note that a
|
|
jbe@0
|
183 circle is not empty if the radius is zero but only if it is negative infinity,
|
|
jbe@0
|
184 i.e. smaller than zero.) Two circles with a positive infinite radius are also
|
|
jbe@0
|
185 considered equal.</p>
|
|
jbe@0
|
186 <p>Implemented for:</p>
|
|
jbe@0
|
187 <ul>
|
|
jbe@0
|
188 <li><code>epoint = epoint</code></li>
|
|
jbe@0
|
189 <li><code>ebox = ebox</code></li>
|
|
jbe@0
|
190 <li><code>ecircle = ecircle</code></li>
|
|
jbe@0
|
191 </ul>
|
|
jbe@0
|
192 <p>The negation is the inequality operator (<code><></code> or <code>!=</code>).</p>
|
|
jbe@0
|
193 <h4>Linear ordering operators <code><<<</code>, <code><<<=</code>, <code>>>>=</code>, <code>>>></code></h4>
|
|
jbe@0
|
194 <p>These operators create an arbitrary (but well-defined) linear ordering of
|
|
jbe@0
|
195 geographic objects, which is used internally for B-tree indexing and merge
|
|
jbe@0
|
196 joins. These operators will usually not be used by an application programmer.</p>
|
|
jbe@0
|
197 <h4>Overlap operator <code>&&</code></h4>
|
|
jbe@0
|
198 <p>Tests if two geographic objects have at least one point in common. Currently
|
|
jbe@0
|
199 implemented for:</p>
|
|
jbe@0
|
200 <ul>
|
|
jbe@0
|
201 <li><code>epoint && ebox</code></li>
|
|
jbe@0
|
202 <li><code>epoint && ecircle</code></li>
|
|
jbe@0
|
203 <li><code>epoint && ecluster</code></li>
|
|
jbe@0
|
204 <li><code>ebox && ebox</code></li>
|
|
jbe@16
|
205 <li><code>ebox && ecircle</code></li>
|
|
jbe@16
|
206 <li><code>ebox && ecluster</code></li>
|
|
jbe@0
|
207 <li><code>ecircle && ecircle</code></li>
|
|
jbe@0
|
208 <li><code>ecircle && ecluster</code></li>
|
|
jbe@16
|
209 <li><code>ecluster && ecluster</code></li>
|
|
jbe@0
|
210 </ul>
|
|
jbe@82
|
211 <p>The <code>&&</code> operator is commutative, i.e. "<code>a && b</code>" is the same as "<code>b && a</code>".
|
|
jbe@20
|
212 Each commutation is supported as well.</p>
|
|
jbe@11
|
213 <h4>Lossy overlap operator <code>&&+</code></h4>
|
|
jbe@11
|
214 <p>Tests if two geographic objects may have at least one point in common. Opposed
|
|
jbe@11
|
215 to the <code>&&</code> operator, the <code>&&+</code> operator may return false positives and is
|
|
jbe@11
|
216 currently implemented for:</p>
|
|
jbe@11
|
217 <ul>
|
|
jbe@11
|
218 <li><code>epoint &&+ ecluster</code></li>
|
|
jbe@11
|
219 <li><code>ebox &&+ ecircle</code></li>
|
|
jbe@11
|
220 <li><code>ebox &&+ ecluster</code></li>
|
|
jbe@11
|
221 <li><code>ecircle &&+ ecluster</code></li>
|
|
jbe@11
|
222 <li><code>ecluster &&+ ecluster</code></li>
|
|
jbe@11
|
223 </ul>
|
|
jbe@82
|
224 <p>The <code>&&+</code> operator is commutative, i.e. "<code>a &&+ b</code>" is the same as "<code>b &&+ a</code>".
|
|
jbe@16
|
225 Each commutation is supported as well.</p>
|
|
jbe@11
|
226 <p>Where two data types support both the <code>&&</code> and the <code>&&+</code> operator, the <code>&&+</code>
|
|
jbe@11
|
227 operator computes faster.</p>
|
|
jbe@16
|
228 <h4>Contains operator <code>@></code></h4>
|
|
jbe@16
|
229 <p>Tests if the object right of the operator is contained in the object left of
|
|
jbe@16
|
230 the operator. Currently implemented for:</p>
|
|
jbe@16
|
231 <ul>
|
|
jbe@16
|
232 <li><code>ebox @> epoint</code> (alias for <code>&&</code>)</li>
|
|
jbe@20
|
233 <li><code>ebox @> ebox</code></li>
|
|
jbe@16
|
234 <li><code>ebox @> ecluster</code></li>
|
|
jbe@16
|
235 <li><code>ecluster @> epoint</code> (alias for <code>&&</code>)</li>
|
|
jbe@16
|
236 <li><code>ecluster @> ebox</code></li>
|
|
jbe@16
|
237 <li><code>ecluster @> ecluster</code></li>
|
|
jbe@16
|
238 </ul>
|
|
jbe@82
|
239 <p>The commutator of <code>@></code> ("contains") is <code><@</code> ("is contained in"), i.e.
|
|
jbe@82
|
240 "<code>a @> b</code>" is the same as "<code>b <@ a</code>".</p>
|
|
jbe@20
|
241 <p>Whether the perimeter of an object is taken into account is undefined and may
|
|
jbe@20
|
242 differ between the left and the right hand side of the operator. The current
|
|
jbe@65
|
243 implementation (where not an alias for <code>&&</code>) returns true only if an object is
|
|
jbe@65
|
244 contained completely within the other object, not touching its perimeter,
|
|
jbe@65
|
245 paths, outlines, or any singular points.</p>
|
|
jbe@0
|
246 <h4>Distance operator <code><-></code></h4>
|
|
jbe@0
|
247 <p>Calculates the shortest distance between two geographic objects in meters (zero
|
|
jbe@0
|
248 if the objects are overlapping). Currently implemented for:</p>
|
|
jbe@0
|
249 <ul>
|
|
jbe@0
|
250 <li><code>epoint <-> epoint</code></li>
|
|
jbe@16
|
251 <li><code>epoint <-> ebox</code></li>
|
|
jbe@0
|
252 <li><code>epoint <-> ecircle</code></li>
|
|
jbe@0
|
253 <li><code>epoint <-> ecluster</code></li>
|
|
jbe@16
|
254 <li><code>ebox <-> ebox</code></li>
|
|
jbe@16
|
255 <li><code>ebox <-> ecircle</code></li>
|
|
jbe@16
|
256 <li><code>ebox <-> ecluster</code></li>
|
|
jbe@0
|
257 <li><code>ecircle <-> ecircle</code></li>
|
|
jbe@0
|
258 <li><code>ecircle <-> ecluster</code></li>
|
|
jbe@16
|
259 <li><code>ecluster <-> ecluster</code></li>
|
|
jbe@0
|
260 </ul>
|
|
jbe@82
|
261 <p>The <code><-></code> operator is commutative, i.e. "<code>a <-> b</code>" is the same as "<code>b <-> a</code>".
|
|
jbe@0
|
262 Each commutation is supported as well.</p>
|
|
jbe@0
|
263 <p>For short distances, the result is very accurate (i.e. respects the dimensions
|
|
jbe@0
|
264 of the WGS-84 spheroid). For longer distances in the order of magnitude of
|
|
jbe@33
|
265 Earth's radius or greater, the value is only approximate (but the error is
|
|
jbe@0
|
266 still less than 0.2% as long as no polygons with very long edges are involved).</p>
|
|
jbe@0
|
267 <p>The functions <code>distance(epoint, epoint)</code> and <code>distance(ecluster, epoint)</code> can
|
|
jbe@0
|
268 be used as an alias for this operator.</p>
|
|
jbe@0
|
269 <p>Note: In case of radial searches with a fixed radius, this operator should
|
|
jbe@0
|
270 not be used. Instead, an <code>ecircle</code> should be created and used in combination
|
|
jbe@0
|
271 with the overlap operator (<code>&&</code>). Alternatively, the functions
|
|
jbe@82
|
272 <code>distance_within(epoint, epoint, float8)</code> or <code>distance_within(ecluster, epoint, float8)</code> can be used for fixed-radius searches.</p>
|
|
jbe@0
|
273 <h3>4. Functions</h3>
|
|
jbe@0
|
274 <h4><code>center(circle)</code></h4>
|
|
jbe@0
|
275 <p>Returns the center of an <code>ecircle</code> as an <code>epoint</code>.</p>
|
|
jbe@0
|
276 <h4><code>distance(epoint, epoint)</code></h4>
|
|
jbe@0
|
277 <p>Calculates the distance between two <code>epoint</code> datums in meters. This function is
|
|
jbe@0
|
278 an alias for the distance operator <code><-></code>.</p>
|
|
jbe@0
|
279 <p>Note: In case of radial searches with a fixed radius, this function should not be
|
|
jbe@0
|
280 used. Use <code>distance_within(epoint, epoint, float8)</code> instead.</p>
|
|
jbe@0
|
281 <h4><code>distance(ecluster, epoint)</code></h4>
|
|
jbe@0
|
282 <p>Calculates the distance from an <code>ecluster</code> to an <code>epoint</code> in meters. This
|
|
jbe@0
|
283 function is an alias for the distance operator <code><-></code>.</p>
|
|
jbe@0
|
284 <p>Note: In case of radial searches with a fixed radius, this function should not be
|
|
jbe@0
|
285 used. Use <code>distance_within(epoint, epoint, float8)</code> instead.</p>
|
|
jbe@0
|
286 <h4><code>distance_within(</code>variable <code>epoint,</code> fixed <code>epoint,</code> radius <code>float8)</code></h4>
|
|
jbe@0
|
287 <p>Checks if the distance between two <code>epoint</code> datums is not greater than a given
|
|
jbe@0
|
288 value (search radius).</p>
|
|
jbe@0
|
289 <p>Note: In case of radial searches with a fixed radius, the first argument must
|
|
jbe@0
|
290 be used for the table column, while the second argument must be used for the
|
|
jbe@0
|
291 search center. Otherwise an existing index cannot be used.</p>
|
|
jbe@0
|
292 <h4><code>distance_within(</code>variable <code>ecluster,</code> fixed <code>epoint,</code> radius <code>float8)</code></h4>
|
|
jbe@0
|
293 <p>Checks if the distance from an <code>ecluster</code> to an <code>epoint</code> is not greater than a
|
|
jbe@0
|
294 given value (search radius).</p>
|
|
jbe@0
|
295 <h4><code>ebox(</code>latmin <code>float8,</code> latmax <code>float8,</code> lonmin <code>float8,</code> lonmax <code>float8)</code></h4>
|
|
jbe@0
|
296 <p>Creates a new <code>ebox</code> with the given boundaries.
|
|
jbe@82
|
297 See "1. Types", subsection <code>ebox</code> for details.</p>
|
|
jbe@0
|
298 <h4><code>ebox(epoint, epoint)</code></h4>
|
|
jbe@0
|
299 <p>Creates a new <code>ebox</code>. This function may only be used if the longitude
|
|
jbe@0
|
300 difference is less than or equal to 120 degrees.
|
|
jbe@82
|
301 See "1. Types", subsection <code>ebox</code> for details.</p>
|
|
jbe@0
|
302 <h4><code>ecircle(epoint, float8)</code></h4>
|
|
jbe@0
|
303 <p>Creates an <code>ecircle</code> with the given center point and radius.</p>
|
|
jbe@0
|
304 <h4><code>ecircle(</code>latitude <code>float8,</code> longitude <code>float8,</code> radius <code>float8)</code></h4>
|
|
jbe@0
|
305 <p>Creates an <code>ecircle</code> with the given center point and radius.</p>
|
|
jbe@0
|
306 <h4><code>ecluster_concat(ecluster, ecluster)</code></h4>
|
|
jbe@0
|
307 <p>Combines two clusters to form a new <code>ecluster</code> by uniting all entries of both
|
|
jbe@0
|
308 clusters. Note that two overlapping areas of polygons annihilate each other
|
|
jbe@0
|
309 (which may be used to create polygons with holes).</p>
|
|
jbe@0
|
310 <h4><code>ecluster_concat(ecluster[])</code></h4>
|
|
jbe@0
|
311 <p>Creates a new <code>ecluster</code> that unites all entries of all clusters in the passed
|
|
jbe@0
|
312 array. Note that two overlapping areas of polygons annihilate each other (which
|
|
jbe@0
|
313 may be used to create polygons with holes).</p>
|
|
jbe@0
|
314 <h4><code>ecluster_create_multipoint(epoint[])</code></h4>
|
|
jbe@0
|
315 <p>Creates a new <code>ecluster</code> which contains multiple points.</p>
|
|
jbe@0
|
316 <h4><code>ecluster_create_outline(epoint[])</code></h4>
|
|
jbe@0
|
317 <p>Creates a new <code>ecluster</code> that is an outline given by the passed points.</p>
|
|
jbe@0
|
318 <h4><code>ecluster_create_path(epoint[])</code></h4>
|
|
jbe@0
|
319 <p>Creates a new <code>ecluster</code> that is a path given by the passed points.</p>
|
|
jbe@0
|
320 <h4><code>ecluster_create_polygon(epoint[])</code></h4>
|
|
jbe@0
|
321 <p>Creates a new <code>ecluster</code> that is a polygon given by the passed points.</p>
|
|
jbe@0
|
322 <h4><code>ecluster_extract_outlines(ecluster)</code></h4>
|
|
jbe@0
|
323 <p>Set-returning function that returns the outlines of an <code>ecluster</code> as <code>epoint[]</code>
|
|
jbe@0
|
324 rows.</p>
|
|
jbe@0
|
325 <h4><code>ecluster_extract_paths(ecluster)</code></h4>
|
|
jbe@0
|
326 <p>Set-returning function that returns the paths of an <code>ecluster</code> as <code>epoint[]</code>
|
|
jbe@0
|
327 rows.</p>
|
|
jbe@0
|
328 <h4><code>ecluster_extract_points(ecluster)</code></h4>
|
|
jbe@0
|
329 <p>Set-returning function that returns the points of an <code>ecluster</code> as <code>epoint</code>
|
|
jbe@0
|
330 rows.</p>
|
|
jbe@0
|
331 <h4><code>ecluster_extract_polygons(ecluster)</code></h4>
|
|
jbe@0
|
332 <p>Set-returning function that returns the polygons of an <code>ecluster</code> as <code>epoint[]</code>
|
|
jbe@0
|
333 rows.</p>
|
|
jbe@0
|
334 <h4><code>empty_ebox</code>()</h4>
|
|
jbe@0
|
335 <p>Returns the empty <code>ebox</code>.
|
|
jbe@82
|
336 See "1. Types", subsection <code>ebox</code> for details.</p>
|
|
jbe@0
|
337 <h4><code>epoint(</code>latitude <code>float8,</code> longitude <code>float8)</code></h4>
|
|
jbe@0
|
338 <p>Returns an <code>epoint</code> with the given latitude and longitude.</p>
|
|
jbe@0
|
339 <h4><code>epoint_latlon(</code>latitude <code>float8,</code> longitude <code>float8)</code></h4>
|
|
jbe@0
|
340 <p>Alias for <code>epoint(float8, float8)</code>.</p>
|
|
jbe@0
|
341 <h4><code>epoint_lonlat(</code>longitude <code>float8,</code> latitude <code>float8)</code></h4>
|
|
jbe@0
|
342 <p>Same as <code>epoint(float8, float8)</code> but with arguments reversed.</p>
|
|
jbe@42
|
343 <h4><code>fair_distance(ecluster, epoint,</code> samples <code>int4 = 10000)</code></h4>
|
|
jbe@42
|
344 <p>When working with user-generated content, users may be tempted to create
|
|
jbe@42
|
345 intentionally oversized objects in order to optimize search results in an
|
|
jbe@42
|
346 unfair manner. The <code>fair_distance</code> function aims to handle this by returning an
|
|
jbe@42
|
347 adjusted distance (i.e. distance increased by a penalty) if a geographic object
|
|
jbe@42
|
348 (the <code>ecluster</code>) consists of more than one point.</p>
|
|
jbe@42
|
349 <p>The first argument to this function is an <code>ecluster</code>, the second argument is a
|
|
jbe@42
|
350 search point (<code>epoint</code>), and the third argument is an interger related to the
|
|
jbe@42
|
351 precision (higher precision will require more computation time).</p>
|
|
jbe@42
|
352 <p>The penalty by which the returned distance is increased fulfills (at least) the
|
|
jbe@42
|
353 following properties:</p>
|
|
jbe@42
|
354 <ul>
|
|
jbe@46
|
355 <li>The penalty function is continuous (except noise created by numerical
|
|
jbe@46
|
356 integration, see paragraph after this list) as long as no objects are added
|
|
jbe@46
|
357 to or removed from the <code>ecluster</code>. That particularly means: small changes in
|
|
jbe@46
|
358 the search point (second argument) cause only small changes in the result.</li>
|
|
jbe@46
|
359 <li>For search points far away from the <code>ecluster</code> (i.e. large distances compared
|
|
jbe@46
|
360 to the dimensions of the <code>ecluster</code>), the penalty approaches zero, i.e. the
|
|
jbe@46
|
361 behavior of the <code>fair_distance</code> function approaches the behavior of the
|
|
jbe@46
|
362 <code>distance</code> function.</li>
|
|
jbe@42
|
363 <li>If the <code>ecluster</code> consists of a set of points, the penalty for a search point
|
|
jbe@46
|
364 close to one of those points (closer than half of the minimum distance
|
|
jbe@46
|
365 between each pair of points in the <code>ecluster</code>) is chosen in such a way that
|
|
jbe@46
|
366 the adjusted distance is equal to the distance from the search point to the
|
|
jbe@42
|
367 closest point in the <code>ecluster</code> multiplied by the square root of the count of
|
|
jbe@42
|
368 points in the <code>ecluster</code>.</li>
|
|
jbe@46
|
369 <li>If the <code>ecluster</code> does not cover any area (i.e. only consists of points,
|
|
jbe@46
|
370 paths, and/or outlines), and if the search point (second argument) overlaps
|
|
jbe@46
|
371 with the <code>ecluster</code>, then the penalty (and thus the result) is zero.</li>
|
|
jbe@46
|
372 <li>The integral (or average) of the square of the fair distance value (result of
|
|
jbe@46
|
373 this function) over all possible search points is independent of the
|
|
jbe@46
|
374 <code>ecluster</code> as long as the <code>ecluster</code> does not cover more than a half of
|
|
jbe@46
|
375 earth's surface.</li>
|
|
jbe@42
|
376 </ul>
|
|
jbe@46
|
377 <p>The function uses numerical integration to compute the result. The third
|
|
jbe@46
|
378 parameter (which defaults to 10000) can be used to adjust the number of samples
|
|
jbe@46
|
379 taken. A higher sample count increases precision as well as execution time of
|
|
jbe@46
|
380 the function. Because this function internally uses a spherical model of earth
|
|
jbe@46
|
381 for certain steps of the calculation, the precision cannot be increased
|
|
jbe@46
|
382 unboundedly.</p>
|
|
jbe@46
|
383 <p>Despite the limitations explained above, it is ensured that the penalty is
|
|
jbe@46
|
384 always positive, i.e. results returned by the <code>fair_distance</code> function are
|
|
jbe@46
|
385 always equal to or greater than the results returned by the <code>distance</code>
|
|
jbe@46
|
386 function regardless of stochastic effects. Furthermore, all results are
|
|
jbe@46
|
387 deterministic and reproducible with the same version of pgLatLon.</p>
|
|
jbe@0
|
388 <h4><code>GeoJSON_to_epoint(jsonb, text)</code></h4>
|
|
jbe@82
|
389 <p>Maps a GeoJSON object of type "Point" or "Feature" (which contains a
|
|
jbe@82
|
390 "Point") to an <code>epoint</code> datum. For any other JSON objects, NULL is returned.</p>
|
|
jbe@0
|
391 <p>The second parameter (which defaults to <code>epoint_lonlat</code>) may be set to a name
|
|
jbe@0
|
392 of a conversion function that transforms two coordinates (two <code>float8</code>
|
|
jbe@0
|
393 parameters) to an <code>epoint</code>.</p>
|
|
jbe@0
|
394 <h4><code>GeoJSON_to_ecluster(jsonb, text)</code></h4>
|
|
jbe@0
|
395 <p>Maps a (valid) GeoJSON object to an <code>ecluster</code>. Note that this function
|
|
jbe@0
|
396 does not check whether the JSONB object is a valid GeoJSON object.</p>
|
|
jbe@0
|
397 <p>The second parameter (which defaults to <code>epoint_lonlat</code>) may be set to a name
|
|
jbe@0
|
398 of a conversion function that transforms two coordinates (two <code>float8</code>
|
|
jbe@0
|
399 parameters) to an <code>epoint</code>.</p>
|
|
jbe@0
|
400 <h4><code>max_latitude(ebox)</code></h4>
|
|
jbe@0
|
401 <p>Returns the northern boundary of a given <code>ebox</code> in degrees between -90 and +90.</p>
|
|
jbe@0
|
402 <h4><code>max_longitude(ebox)</code></h4>
|
|
jbe@0
|
403 <p>Returns the eastern boundary of a given <code>ebox</code> in degrees between -180 and +180
|
|
jbe@0
|
404 (both inclusive).</p>
|
|
jbe@0
|
405 <h4><code>min_latitude(ebox)</code></h4>
|
|
jbe@0
|
406 <p>Returns the southern boundary of a given <code>ebox</code> in degrees between -90 and +90.</p>
|
|
jbe@0
|
407 <h4><code>min_longitude(ebox)</code></h4>
|
|
jbe@0
|
408 <p>Returns the western boundary of a given <code>ebox</code> in degrees between -180 and +180
|
|
jbe@0
|
409 (both inclusive).</p>
|
|
jbe@0
|
410 <h4><code>latitude(epoint)</code></h4>
|
|
jbe@0
|
411 <p>Returns the latitude value of an <code>epoint</code> in degrees between -90 and +90.</p>
|
|
jbe@0
|
412 <h4><code>longitude(epoint)</code></h4>
|
|
jbe@0
|
413 <p>Returns the longitude value of an <code>epoint</code> in degrees between -180 and +180
|
|
jbe@0
|
414 (both inclusive).</p>
|
|
jbe@0
|
415 <h4><code>radius(ecircle)</code></h4>
|
|
jbe@0
|
416 <p>Returns the radius of an <code>ecircle</code> in meters.</p>
|
|
jbe@0
|
417 </body></html>
|