## pgLatLon

### diff README.mkd @ 46:3cbce515387f

Added safety margins for distance calculation on index lookups (fixes bug that caused nearest-neighbor search to fail in certain cases); Improved "fair_distance" function

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

date | Mon Oct 31 13:06:31 2016 +0100 (2016-10-31) |

parents | 10640afbe2ea |

children | b37a0dc6d1ec |

line diff

1.1 --- a/README.mkd Tue Oct 25 22:15:17 2016 +0200 1.2 +++ b/README.mkd Mon Oct 31 13:06:31 2016 +0100 1.3 @@ -1,4 +1,4 @@ 1.4 -pgLatLon v0.9 documentation 1.5 +pgLatLon v0.10 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-v0008.so latlon-v0008.c 1.14 - cp latlon-v0008.so `pg_config --pkglibdir` 1.15 + cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0009.so latlon-v0009.c 1.16 + cp latlon-v0009.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 @@ -484,22 +484,40 @@ 1.21 The penalty by which the returned distance is increased fulfills (at least) the 1.22 following properties: 1.23 1.24 -* For search points far away from the `ecluster` (i.e. distance approaching 1.25 - infinity), the penalty approaches zero (i.e. `fair_distance` behaves the same 1.26 - as `distance`). 1.27 +* The penalty function is continuous (except noise created by numerical 1.28 + integration, see paragraph after this list) as long as no objects are added 1.29 + to or removed from the `ecluster`. That particularly means: small changes in 1.30 + the search point (second argument) cause only small changes in the result. 1.31 +* For search points far away from the `ecluster` (i.e. large distances compared 1.32 + to the dimensions of the `ecluster`), the penalty approaches zero, i.e. the 1.33 + behavior of the `fair_distance` function approaches the behavior of the 1.34 + `distance` function. 1.35 * If the `ecluster` consists of a set of points, the penalty for a search point 1.36 - close to one of that points (closer than half of the minimum distance between 1.37 - each pair of points in the `ecluster`) is chosen in such a way that the 1.38 - adjusted distance is equal to the distance from the search point to the 1.39 + close to one of those points (closer than half of the minimum distance 1.40 + between each pair of points in the `ecluster`) is chosen in such a way that 1.41 + the adjusted distance is equal to the distance from the search point to the 1.42 closest point in the `ecluster` multiplied by the square root of the count of 1.43 points in the `ecluster`. 1.44 +* If the `ecluster` does not cover any area (i.e. only consists of points, 1.45 + paths, and/or outlines), and if the search point (second argument) overlaps 1.46 + with the `ecluster`, then the penalty (and thus the result) is zero. 1.47 +* The integral (or average) of the square of the fair distance value (result of 1.48 + this function) over all possible search points is independent of the 1.49 + `ecluster` as long as the `ecluster` does not cover more than a half of 1.50 + earth's surface. 1.51 1.52 -The function interally uses numerical integration (Monte Carlo like) to compute 1.53 -the result. The third parameter (which defaults to 10000) can be used to adjust 1.54 -the number of samples taken. It is ensured that the penalty is always positive, 1.55 -i.e. results returned by the `fair_distance` function are always equal to or 1.56 -greater than the results returned by the `distance` function regardless of 1.57 -stochastic effects. 1.58 +The function uses numerical integration to compute the result. The third 1.59 +parameter (which defaults to 10000) can be used to adjust the number of samples 1.60 +taken. A higher sample count increases precision as well as execution time of 1.61 +the function. Because this function internally uses a spherical model of earth 1.62 +for certain steps of the calculation, the precision cannot be increased 1.63 +unboundedly. 1.64 + 1.65 +Despite the limitations explained above, it is ensured that the penalty is 1.66 +always positive, i.e. results returned by the `fair_distance` function are 1.67 +always equal to or greater than the results returned by the `distance` 1.68 +function regardless of stochastic effects. Furthermore, all results are 1.69 +deterministic and reproducible with the same version of pgLatLon. 1.70 1.71 #### `GeoJSON_to_epoint(jsonb, text)` 1.72