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