pgLatLon

annotate README.mkd @ 79:16787a19a325

find changesets by author, revision, files, or words in the commit message
Do not return CSTRING to static memory

Avoids wrong pfree under certain circumstances
(e.g. array_agg on empty EBOX or ECLUSTER).
author jbe
date Thu Oct 23 10:16:01 2025 +0200 (3 days ago)
parents 76b3fd3293fc
children
rev   line source
jbe@74 1 pgLatLon v0.15 documentation
jbe@65 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@32 8 While many other spatial databases still use imprecise bounding boxes for
jbe@32 9 many operations, pgLatLon aims to support more precise calculations for all
jbe@32 10 implemented geographic operators. Efficient indexing of geographic objects
jbe@32 11 is provided using space-filling fractal curves. Optimizations on bit level
jbe@32 12 (including logarithmic compression) allow for a highly memory-efficient
jbe@32 13 non-overlapping 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@74 42 cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0010.so latlon-v0010.c
jbe@74 43 cp latlon-v0010.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@33 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@33 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@33 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@49 221 `GeoJSON_to_ecluster(jsonb, 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@58 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@20 277 The `&&` operator is commutative, i.e. "`a && b`" is the same as "`b && a`".
jbe@20 278 Each 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@20 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@20 304 * `ebox @> ebox`
jbe@16 305 * `ebox @> ecluster`
jbe@16 306 * `ecluster @> epoint` (alias for `&&`)
jbe@16 307 * `ecluster @> ebox`
jbe@16 308 * `ecluster @> ecluster`
jbe@16 309
jbe@20 310 The commutator of `@>` ("contains") is `<@` ("is contained in"), i.e.
jbe@20 311 "`a @> b`" is the same as "`b <@ a`".
jbe@20 312
jbe@20 313 Whether the perimeter of an object is taken into account is undefined and may
jbe@20 314 differ between the left and the right hand side of the operator. The current
jbe@65 315 implementation (where not an alias for `&&`) returns true only if an object is
jbe@65 316 contained completely within the other object, not touching its perimeter,
jbe@65 317 paths, outlines, or any singular points.
jbe@16 318
jbe@0 319 #### Distance operator `<->`
jbe@0 320
jbe@0 321 Calculates the shortest distance between two geographic objects in meters (zero
jbe@0 322 if the objects are overlapping). Currently implemented for:
jbe@0 323
jbe@0 324 * `epoint <-> epoint`
jbe@16 325 * `epoint <-> ebox`
jbe@0 326 * `epoint <-> ecircle`
jbe@0 327 * `epoint <-> ecluster`
jbe@16 328 * `ebox <-> ebox`
jbe@16 329 * `ebox <-> ecircle`
jbe@16 330 * `ebox <-> ecluster`
jbe@0 331 * `ecircle <-> ecircle`
jbe@0 332 * `ecircle <-> ecluster`
jbe@16 333 * `ecluster <-> ecluster`
jbe@0 334
jbe@20 335 The `<->` operator is commutative, i.e. "`a <-> b`" is the same as "`b <-> a`".
jbe@0 336 Each commutation is supported as well.
jbe@0 337
jbe@0 338 For short distances, the result is very accurate (i.e. respects the dimensions
jbe@0 339 of the WGS-84 spheroid). For longer distances in the order of magnitude of
jbe@33 340 Earth's radius or greater, the value is only approximate (but the error is
jbe@0 341 still less than 0.2% as long as no polygons with very long edges are involved).
jbe@0 342
jbe@0 343 The functions `distance(epoint, epoint)` and `distance(ecluster, epoint)` can
jbe@0 344 be used as an alias for this operator.
jbe@0 345
jbe@0 346 Note: In case of radial searches with a fixed radius, this operator should
jbe@0 347 not be used. Instead, an `ecircle` should be created and used in combination
jbe@0 348 with the overlap operator (`&&`). Alternatively, the functions
jbe@0 349 `distance_within(epoint, epoint, float8)` or `distance_within(ecluster, epoint,
jbe@0 350 float8)` can be used for fixed-radius searches.
jbe@0 351
jbe@0 352 ### 4. Functions
jbe@0 353
jbe@0 354 #### `center(circle)`
jbe@0 355
jbe@0 356 Returns the center of an `ecircle` as an `epoint`.
jbe@0 357
jbe@0 358 #### `distance(epoint, epoint)`
jbe@0 359
jbe@0 360 Calculates the distance between two `epoint` datums in meters. This function is
jbe@0 361 an alias for the distance operator `<->`.
jbe@0 362
jbe@0 363 Note: In case of radial searches with a fixed radius, this function should not be
jbe@0 364 used. Use `distance_within(epoint, epoint, float8)` instead.
jbe@0 365
jbe@0 366 #### `distance(ecluster, epoint)`
jbe@0 367
jbe@0 368 Calculates the distance from an `ecluster` to an `epoint` in meters. This
jbe@0 369 function is an alias for the distance operator `<->`.
jbe@0 370
jbe@0 371 Note: In case of radial searches with a fixed radius, this function should not be
jbe@0 372 used. Use `distance_within(epoint, epoint, float8)` instead.
jbe@0 373
jbe@0 374 #### `distance_within(`variable `epoint,` fixed `epoint,` radius `float8)`
jbe@0 375
jbe@0 376 Checks if the distance between two `epoint` datums is not greater than a given
jbe@0 377 value (search radius).
jbe@0 378
jbe@0 379 Note: In case of radial searches with a fixed radius, the first argument must
jbe@0 380 be used for the table column, while the second argument must be used for the
jbe@0 381 search center. Otherwise an existing index cannot be used.
jbe@0 382
jbe@0 383 #### `distance_within(`variable `ecluster,` fixed `epoint,` radius `float8)`
jbe@0 384
jbe@0 385 Checks if the distance from an `ecluster` to an `epoint` is not greater than a
jbe@0 386 given value (search radius).
jbe@0 387
jbe@0 388 #### `ebox(`latmin `float8,` latmax `float8,` lonmin `float8,` lonmax `float8)`
jbe@0 389
jbe@0 390 Creates a new `ebox` with the given boundaries.
jbe@0 391 See "1. Types", subsection `ebox` for details.
jbe@0 392
jbe@0 393 #### `ebox(epoint, epoint)`
jbe@0 394
jbe@0 395 Creates a new `ebox`. This function may only be used if the longitude
jbe@0 396 difference is less than or equal to 120 degrees.
jbe@0 397 See "1. Types", subsection `ebox` for details.
jbe@0 398
jbe@0 399 #### `ecircle(epoint, float8)`
jbe@0 400
jbe@0 401 Creates an `ecircle` with the given center point and radius.
jbe@0 402
jbe@0 403 #### `ecircle(`latitude `float8,` longitude `float8,` radius `float8)`
jbe@0 404
jbe@0 405 Creates an `ecircle` with the given center point and radius.
jbe@0 406
jbe@0 407 #### `ecluster_concat(ecluster, ecluster)`
jbe@0 408
jbe@0 409 Combines two clusters to form a new `ecluster` by uniting all entries of both
jbe@0 410 clusters. Note that two overlapping areas of polygons annihilate each other
jbe@0 411 (which may be used to create polygons with holes).
jbe@0 412
jbe@0 413 #### `ecluster_concat(ecluster[])`
jbe@0 414
jbe@0 415 Creates a new `ecluster` that unites all entries of all clusters in the passed
jbe@0 416 array. Note that two overlapping areas of polygons annihilate each other (which
jbe@0 417 may be used to create polygons with holes).
jbe@0 418
jbe@0 419 #### `ecluster_create_multipoint(epoint[])`
jbe@0 420
jbe@0 421 Creates a new `ecluster` which contains multiple points.
jbe@0 422
jbe@0 423 #### `ecluster_create_outline(epoint[])`
jbe@0 424
jbe@0 425 Creates a new `ecluster` that is an outline given by the passed points.
jbe@0 426
jbe@0 427 #### `ecluster_create_path(epoint[])`
jbe@0 428
jbe@0 429 Creates a new `ecluster` that is a path given by the passed points.
jbe@0 430
jbe@0 431 #### `ecluster_create_polygon(epoint[])`
jbe@0 432
jbe@0 433 Creates a new `ecluster` that is a polygon given by the passed points.
jbe@0 434
jbe@0 435 #### `ecluster_extract_outlines(ecluster)`
jbe@0 436
jbe@0 437 Set-returning function that returns the outlines of an `ecluster` as `epoint[]`
jbe@0 438 rows.
jbe@0 439
jbe@0 440 #### `ecluster_extract_paths(ecluster)`
jbe@0 441
jbe@0 442 Set-returning function that returns the paths of an `ecluster` as `epoint[]`
jbe@0 443 rows.
jbe@0 444
jbe@0 445 #### `ecluster_extract_points(ecluster)`
jbe@0 446
jbe@0 447 Set-returning function that returns the points of an `ecluster` as `epoint`
jbe@0 448 rows.
jbe@0 449
jbe@0 450 #### `ecluster_extract_polygons(ecluster)`
jbe@0 451
jbe@0 452 Set-returning function that returns the polygons of an `ecluster` as `epoint[]`
jbe@0 453 rows.
jbe@0 454
jbe@0 455 #### `empty_ebox`()
jbe@0 456
jbe@0 457 Returns the empty `ebox`.
jbe@0 458 See "1. Types", subsection `ebox` for details.
jbe@0 459
jbe@0 460 #### `epoint(`latitude `float8,` longitude `float8)`
jbe@0 461
jbe@0 462 Returns an `epoint` with the given latitude and longitude.
jbe@0 463
jbe@0 464 #### `epoint_latlon(`latitude `float8,` longitude `float8)`
jbe@0 465
jbe@0 466 Alias for `epoint(float8, float8)`.
jbe@0 467
jbe@0 468 #### `epoint_lonlat(`longitude `float8,` latitude `float8)`
jbe@0 469
jbe@0 470 Same as `epoint(float8, float8)` but with arguments reversed.
jbe@0 471
jbe@42 472 #### `fair_distance(ecluster, epoint,` samples `int4 = 10000)`
jbe@42 473
jbe@42 474 When working with user-generated content, users may be tempted to create
jbe@42 475 intentionally oversized objects in order to optimize search results in an
jbe@42 476 unfair manner. The `fair_distance` function aims to handle this by returning an
jbe@42 477 adjusted distance (i.e. distance increased by a penalty) if a geographic object
jbe@42 478 (the `ecluster`) consists of more than one point.
jbe@42 479
jbe@42 480 The first argument to this function is an `ecluster`, the second argument is a
jbe@42 481 search point (`epoint`), and the third argument is an interger related to the
jbe@42 482 precision (higher precision will require more computation time).
jbe@42 483
jbe@42 484 The penalty by which the returned distance is increased fulfills (at least) the
jbe@42 485 following properties:
jbe@42 486
jbe@46 487 * The penalty function is continuous (except noise created by numerical
jbe@46 488 integration, see paragraph after this list) as long as no objects are added
jbe@46 489 to or removed from the `ecluster`. That particularly means: small changes in
jbe@46 490 the search point (second argument) cause only small changes in the result.
jbe@46 491 * For search points far away from the `ecluster` (i.e. large distances compared
jbe@46 492 to the dimensions of the `ecluster`), the penalty approaches zero, i.e. the
jbe@46 493 behavior of the `fair_distance` function approaches the behavior of the
jbe@46 494 `distance` function.
jbe@42 495 * If the `ecluster` consists of a set of points, the penalty for a search point
jbe@46 496 close to one of those points (closer than half of the minimum distance
jbe@46 497 between each pair of points in the `ecluster`) is chosen in such a way that
jbe@46 498 the adjusted distance is equal to the distance from the search point to the
jbe@42 499 closest point in the `ecluster` multiplied by the square root of the count of
jbe@42 500 points in the `ecluster`.
jbe@46 501 * If the `ecluster` does not cover any area (i.e. only consists of points,
jbe@46 502 paths, and/or outlines), and if the search point (second argument) overlaps
jbe@46 503 with the `ecluster`, then the penalty (and thus the result) is zero.
jbe@46 504 * The integral (or average) of the square of the fair distance value (result of
jbe@46 505 this function) over all possible search points is independent of the
jbe@46 506 `ecluster` as long as the `ecluster` does not cover more than a half of
jbe@46 507 earth's surface.
jbe@42 508
jbe@46 509 The function uses numerical integration to compute the result. The third
jbe@46 510 parameter (which defaults to 10000) can be used to adjust the number of samples
jbe@46 511 taken. A higher sample count increases precision as well as execution time of
jbe@46 512 the function. Because this function internally uses a spherical model of earth
jbe@46 513 for certain steps of the calculation, the precision cannot be increased
jbe@46 514 unboundedly.
jbe@46 515
jbe@46 516 Despite the limitations explained above, it is ensured that the penalty is
jbe@46 517 always positive, i.e. results returned by the `fair_distance` function are
jbe@46 518 always equal to or greater than the results returned by the `distance`
jbe@46 519 function regardless of stochastic effects. Furthermore, all results are
jbe@46 520 deterministic and reproducible with the same version of pgLatLon.
jbe@42 521
jbe@0 522 #### `GeoJSON_to_epoint(jsonb, text)`
jbe@0 523
jbe@0 524 Maps a GeoJSON object of type "Point" or "Feature" (which contains a
jbe@0 525 "Point") to an `epoint` datum. For any other JSON objects, NULL is returned.
jbe@0 526
jbe@0 527 The second parameter (which defaults to `epoint_lonlat`) may be set to a name
jbe@0 528 of a conversion function that transforms two coordinates (two `float8`
jbe@0 529 parameters) to an `epoint`.
jbe@0 530
jbe@0 531 #### `GeoJSON_to_ecluster(jsonb, text)`
jbe@0 532
jbe@0 533 Maps a (valid) GeoJSON object to an `ecluster`. Note that this function
jbe@0 534 does not check whether the JSONB object is a valid GeoJSON object.
jbe@0 535
jbe@0 536 The second parameter (which defaults to `epoint_lonlat`) may be set to a name
jbe@0 537 of a conversion function that transforms two coordinates (two `float8`
jbe@0 538 parameters) to an `epoint`.
jbe@0 539
jbe@0 540 #### `max_latitude(ebox)`
jbe@0 541
jbe@0 542 Returns the northern boundary of a given `ebox` in degrees between -90 and +90.
jbe@0 543
jbe@0 544 #### `max_longitude(ebox)`
jbe@0 545
jbe@0 546 Returns the eastern boundary of a given `ebox` in degrees between -180 and +180
jbe@0 547 (both inclusive).
jbe@0 548
jbe@0 549 #### `min_latitude(ebox)`
jbe@0 550
jbe@0 551 Returns the southern boundary of a given `ebox` in degrees between -90 and +90.
jbe@0 552
jbe@0 553 #### `min_longitude(ebox)`
jbe@0 554
jbe@0 555 Returns the western boundary of a given `ebox` in degrees between -180 and +180
jbe@0 556 (both inclusive).
jbe@0 557
jbe@0 558 #### `latitude(epoint)`
jbe@0 559
jbe@0 560 Returns the latitude value of an `epoint` in degrees between -90 and +90.
jbe@0 561
jbe@0 562 #### `longitude(epoint)`
jbe@0 563
jbe@0 564 Returns the longitude value of an `epoint` in degrees between -180 and +180
jbe@0 565 (both inclusive).
jbe@0 566
jbe@0 567 #### `radius(ecircle)`
jbe@0 568
jbe@0 569 Returns the radius of an `ecircle` in meters.
jbe@0 570

Impressum / About Us