|
1 |
| ---------------------------------------------------------------------- |
2 |
| -I corrected a bug in the geo_distance code where two double constants |
3 |
| -were declared as int. I changed the distance function to use the |
4 |
| -haversine formula which is more accurate for small distances. |
5 |
| -I added a regression test to the package. I added a grant statement |
6 |
| -to give execute access for geo_distance to public. |
| 1 | +This contrib package contains two different approaches to calculating |
| 2 | +great circle distances on the surface of the Earth. The one described |
| 3 | +first depends on the contrib/cube package (which MUST be installed before |
| 4 | +earthdistance is installed). The second one is based on the point |
| 5 | +datatype using latitude and longitude for the coordinates. The install |
| 6 | +script makes the defined functions executable by anyone. |
| 7 | + |
| 8 | +Make sure contrib/cube has been installed. |
| 9 | +make |
| 10 | +make install |
| 11 | +make installcheck |
| 12 | + |
| 13 | +To use these functions in a particular database as a postgres superuser do: |
| 14 | +psql databasename < earthdistance.sql |
7 | 15 |
|
| 16 | +------------------------------------------- |
| 17 | +contrib/cube based Earth distance functions |
8 | 18 | Bruno Wolff III
|
9 | 19 | September 2002
|
| 20 | + |
| 21 | +A spherical model of the Earth is used. |
| 22 | + |
| 23 | +Data is stored in cubes that are points (both corners are the same) using 3 |
| 24 | +coordinates representing the distance from the center of the Earth. |
| 25 | + |
| 26 | +The radius of the Earth is obtained from the earth() function. It is |
| 27 | +given in meters. But by changing this one function you can change it |
| 28 | +to use some other units or to use a different value of the radius |
| 29 | +that you feel is more appropiate. |
| 30 | + |
| 31 | +This package also has applications to astronomical databases as well. |
| 32 | +Astronomers will probably want to change earth() to return a radius of |
| 33 | +180/pi() so that distances are in degrees. |
| 34 | + |
| 35 | +Functions are provided to allow for input in latitude and longitude (in |
| 36 | +degrees), to allow for output of latitude and longitude, to calculate |
| 37 | +the great circle distance between two points and to easily specify a |
| 38 | +bounding box usable for index searches. |
| 39 | + |
| 40 | +The functions are all 'sql' functions. If you want to make these functions |
| 41 | +executable by other people you will also have to make the referenced |
| 42 | +cube functions executable. cube(text), cube_distance(cube,cube), |
| 43 | +cube_ll_coord(cube,int) and cube_enlarge(cube,float8,int) are used indirectly |
| 44 | +by the earth distance functions. is_point(cube) and cube_dim(cube) are used |
| 45 | +in suggested constraints for data in domain earth. cube_ur_coord(cube,int) |
| 46 | +is used in the regression tests and might be useful for looking at bounding |
| 47 | +box coordinates in user applications. |
| 48 | + |
| 49 | +A domain of type cube named earth is defined. Since check constraints |
| 50 | +are not supported for domains yet, this isn't as useful as it might be. |
| 51 | +However the checks that should be supplied to all data of type earth are: |
| 52 | + |
| 53 | +constraint not_point check(is_point(earth)) |
| 54 | +constraint not_3d check(cube_dim(earth) <= 3) |
| 55 | +constraint on_surface check(abs(cube_distance(earth, '(0)'::cube) / |
| 56 | + earth() - 1) < '10e-12'::float8); |
| 57 | + |
| 58 | +The following functions are provided: |
| 59 | + |
| 60 | +earth() - Returns the radius of the earth in meters. |
| 61 | + |
| 62 | +sec_to_gc(float8) - Converts the normal straight line (secant) distance between |
| 63 | +between two points on the surface of the Earth to the great circle distance |
| 64 | +between them. |
| 65 | + |
| 66 | +gc_to_sec(float8) - Converts the great circle distance between two points |
| 67 | +on the surface of the Earth to the normal straight line (secant) distance |
| 68 | +between them. |
| 69 | + |
| 70 | +ll_to_cube(float8, float8) - Returns the location of a point on the surface of |
| 71 | +the Earth given its latitude (argument 1) and longitude (argument 2) in degrees. |
| 72 | + |
| 73 | +latitude(earth) - Returns the latitude in degrees of a point on the surface |
| 74 | +of the Earth. |
| 75 | + |
| 76 | +longitude(earth) - Returns the longitude in degrees of a point on the surface |
| 77 | +of the Earth. |
| 78 | + |
| 79 | +earth_distance(earth, earth) - Returns the great circle distance between |
| 80 | +two points on the surface of the Earth. |
| 81 | + |
| 82 | +earth_box(earth, float8) - Returns a box suitable for an indexed search using |
| 83 | +the cube @ operator for points within a given great circle distance of a |
| 84 | +location. Some points in this box are further than the specified great circle |
| 85 | +distance from the location so a second check using earth_distance should be |
| 86 | +made at the same time. |
| 87 | + |
| 88 | +One advantage of using cube representation over a point using latitude and |
| 89 | +longitude for coordinates, is that you don't have to worry about special |
| 90 | +conditions at +/- 180 degrees of longitude or near the poles. |
| 91 | + |
| 92 | +Below is the documentation for the Earth distance operator that works |
| 93 | +with the point data type. |
| 94 | + |
| 95 | +--------------------------------------------------------------------- |
| 96 | + |
| 97 | +I corrected a bug in the geo_distance code where two double constants |
| 98 | +were declared as int. I also changed the distance function to use |
| 99 | +the haversine formula which is more accurate for small distances. |
| 100 | +Bruno Wolff |
| 101 | +September 2002 |
| 102 | + |
10 | 103 | ---------------------------------------------------------------------
|
| 104 | + |
11 | 105 | Date: Wed, 1 Apr 1998 15:19:32 -0600 (CST)
|
12 | 106 | From: Hal Snyder <hal@vailsys.com>
|
13 | 107 | To: vmehr@ctp.com
|
|
0 commit comments