## pgLatLon

### diff README.mkd @ 42:1b9cd45e9e48

Bugfix for type casts to ecluster; New "fair_distance" function

author | jbe |
---|---|

date | Tue Oct 25 18:44:43 2016 +0200 (2016-10-25) |

parents | f1a9a5de9a12 |

children | 10640afbe2ea |

line diff

1.1 --- a/README.mkd Fri Oct 21 12:57:46 2016 +0200 1.2 +++ b/README.mkd Tue Oct 25 18:44:43 2016 +0200 1.3 @@ -1,4 +1,4 @@ 1.4 -pgLatLon v0.8 documentation 1.5 +pgLatLon v0.9 documentation 1.6 =========================== 1.7 1.8 pgLatLon is a spatial database extension for the PostgreSQL object-relational 1.9 @@ -39,8 +39,8 @@ 1.10 It is also possible to compile and install the extension without GNU Make as 1.11 follows: 1.12 1.13 - cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0007.so latlon-v0007.c 1.14 - cp latlon-v0007.so `pg_config --pkglibdir` 1.15 + cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0008.so latlon-v0008.c 1.16 + cp latlon-v0008.so `pg_config --pkglibdir` 1.17 cp latlon.control `pg_config --sharedir`/extension/ 1.18 cp latlon--*.sql `pg_config --sharedir`/extension/ 1.19 1.20 @@ -469,6 +469,38 @@ 1.21 1.22 Same as `epoint(float8, float8)` but with arguments reversed. 1.23 1.24 +#### `fair_distance(ecluster, epoint,` samples `int4 = 10000)` 1.25 + 1.26 +When working with user-generated content, users may be tempted to create 1.27 +intentionally oversized objects in order to optimize search results in an 1.28 +unfair manner. The `fair_distance` function aims to handle this by returning an 1.29 +adjusted distance (i.e. distance increased by a penalty) if a geographic object 1.30 +(the `ecluster`) consists of more than one point. 1.31 + 1.32 +The first argument to this function is an `ecluster`, the second argument is a 1.33 +search point (`epoint`), and the third argument is an interger related to the 1.34 +precision (higher precision will require more computation time). 1.35 + 1.36 +The penalty by which the returned distance is increased fulfills (at least) the 1.37 +following properties: 1.38 + 1.39 +* For search points far away from the `ecluster` (i.e. distance approaching 1.40 + infinity), the penalty approaches zero (i.e. `fair_distance` behaves the same 1.41 + as `distance`). 1.42 +* If the `ecluster` consists of a set of points, the penalty for a search point 1.43 + close to one of that points (closer than half of the minimum distance between 1.44 + each pair of points in the `ecluster`) is chosen in such a way that the 1.45 + adjusted distance is equal to the distance from the search point to the 1.46 + closest point in the `ecluster` multiplied by the square root of the count of 1.47 + points in the `ecluster`. 1.48 + 1.49 +The function interally uses a Monte Carlo simulation to compute the result. The 1.50 +third parameter (which defaults to 10000) can be used to adjust the number of 1.51 +samples taken. It is ensured that the penalty is always positive, i.e. results 1.52 +returned by the `fair_distance` function are always equal to or greater than 1.53 +the results returned by the `distance` function regardless of stochastic 1.54 +effects. 1.55 + 1.56 #### `GeoJSON_to_epoint(jsonb, text)` 1.57 1.58 Maps a GeoJSON object of type "Point" or "Feature" (which contains a