begriffs open source - ai-pg/blob - full-docs/txt/earthdistance.txt

   1
   2 F.14. earthdistance — calculate great-circle distances #
   3
   4    F.14.1. Cube-Based Earth Distances
   5    F.14.2. Point-Based Earth Distances
   6
   7    The earthdistance module provides two different approaches to
   8    calculating great circle distances on the surface of the Earth. The one
   9    described first depends on the cube module. The second one is based on
  10    the built-in point data type, using longitude and latitude for the
  11    coordinates.
  12
  13    In this module, the Earth is assumed to be perfectly spherical. (If
  14    that's too inaccurate for you, you might want to look at the PostGIS
  15    project.)
  16
  17    The cube module must be installed before earthdistance can be installed
  18    (although you can use the CASCADE option of CREATE EXTENSION to install
  19    both in one command).
  20
  21 Caution
  22
  23    It is strongly recommended that earthdistance and cube be installed in
  24    the same schema, and that that schema be one for which CREATE privilege
  25    has not been and will not be granted to any untrusted users. Otherwise
  26    there are installation-time security hazards if earthdistance's schema
  27    contains objects defined by a hostile user. Furthermore, when using
  28    earthdistance's functions after installation, the entire search path
  29    should contain only trusted schemas.
  30
  31 F.14.1. Cube-Based Earth Distances #
  32
  33    Data is stored in cubes that are points (both corners are the same)
  34    using 3 coordinates representing the x, y, and z distance from the
  35    center of the Earth. A domain earth over type cube is provided, which
  36    includes constraint checks that the value meets these restrictions and
  37    is reasonably close to the actual surface of the Earth.
  38
  39    The radius of the Earth is obtained from the earth() function. It is
  40    given in meters. But by changing this one function you can change the
  41    module to use some other units, or to use a different value of the
  42    radius that you feel is more appropriate.
  43
  44    This package has applications to astronomical databases as well.
  45    Astronomers will probably want to change earth() to return a radius of
  46    180/pi() so that distances are in degrees.
  47
  48    Functions are provided to support input in latitude and longitude (in
  49    degrees), to support output of latitude and longitude, to calculate the
  50    great circle distance between two points and to easily specify a
  51    bounding box usable for index searches.
  52
  53    The provided functions are shown in Table F.4.
  54
  55    Table F.4. Cube-Based Earthdistance Functions
  56
  57    Function
  58
  59    Description
  60
  61    earth () → float8
  62
  63    Returns the assumed radius of the Earth.
  64
  65    sec_to_gc ( float8 ) → float8
  66
  67    Converts the normal straight line (secant) distance between two points
  68    on the surface of the Earth to the great circle distance between them.
  69
  70    gc_to_sec ( float8 ) → float8
  71
  72    Converts the great circle distance between two points on the surface of
  73    the Earth to the normal straight line (secant) distance between them.
  74
  75    ll_to_earth ( float8, float8 ) → earth
  76
  77    Returns the location of a point on the surface of the Earth given its
  78    latitude (argument 1) and longitude (argument 2) in degrees.
  79
  80    latitude ( earth ) → float8
  81
  82    Returns the latitude in degrees of a point on the surface of the Earth.
  83
  84    longitude ( earth ) → float8
  85
  86    Returns the longitude in degrees of a point on the surface of the
  87    Earth.
  88
  89    earth_distance ( earth, earth ) → float8
  90
  91    Returns the great circle distance between two points on the surface of
  92    the Earth.
  93
  94    earth_box ( earth, float8 ) → cube
  95
  96    Returns a box suitable for an indexed search using the cube @> operator
  97    for points within a given great circle distance of a location. Some
  98    points in this box are further than the specified great circle distance
  99    from the location, so a second check using earth_distance should be
 100    included in the query.
 101
 102 F.14.2. Point-Based Earth Distances #
 103
 104    The second part of the module relies on representing Earth locations as
 105    values of type point, in which the first component is taken to
 106    represent longitude in degrees, and the second component is taken to
 107    represent latitude in degrees. Points are taken as (longitude,
 108    latitude) and not vice versa because longitude is closer to the
 109    intuitive idea of x-axis and latitude to y-axis.
 110
 111    A single operator is provided, shown in Table F.5.
 112
 113    Table F.5. Point-Based Earthdistance Operators
 114
 115    Operator
 116
 117    Description
 118
 119    point <@> point → float8
 120
 121    Computes the distance in statute miles between two points on the
 122    Earth's surface.
 123
 124    Note that unlike the cube-based part of the module, units are hardwired
 125    here: changing the earth() function will not affect the results of this
 126    operator.
 127
 128    One disadvantage of the longitude/latitude representation is that you
 129    need to be careful about the edge conditions near the poles and near
 130    +/- 180 degrees of longitude. The cube-based representation avoids
 131    these discontinuities.