| 1 |
<!-- doc/src/sgml/earthdistance.sgml --> |
| 2 |
|
| 3 |
<sect1 id="earthdistance" xreflabel="earthdistance"> |
| 4 |
<title>earthdistance — calculate great-circle distances</title> |
| 5 |
|
| 6 |
<indexterm zone="earthdistance"> |
| 7 |
<primary>earthdistance</primary> |
| 8 |
</indexterm> |
| 9 |
|
| 10 |
<para> |
| 11 |
The <filename>earthdistance</filename> module provides two different approaches to |
| 12 |
calculating great circle distances on the surface of the Earth. The one |
| 13 |
described first depends on the <filename>cube</filename> module. |
| 14 |
The second one is based on the built-in <type>point</type> data type, |
| 15 |
using longitude and latitude for the coordinates. |
| 16 |
</para> |
| 17 |
|
| 18 |
<para> |
| 19 |
In this module, the Earth is assumed to be perfectly spherical. |
| 20 |
(If that's too inaccurate for you, you might want to look at the |
| 21 |
<application><ulink url="https://postgis.net/">PostGIS</ulink></application> |
| 22 |
project.) |
| 23 |
</para> |
| 24 |
|
| 25 |
<para> |
| 26 |
The <filename>cube</filename> module must be installed |
| 27 |
before <filename>earthdistance</filename> can be installed |
| 28 |
(although you can use the <literal>CASCADE</literal> option |
| 29 |
of <command>CREATE EXTENSION</command> to install both in one command). |
| 30 |
</para> |
| 31 |
|
| 32 |
<caution> |
| 33 |
<para> |
| 34 |
It is strongly recommended that <filename>earthdistance</filename> |
| 35 |
and <filename>cube</filename> be installed in the same schema, and that |
| 36 |
that schema be one for which CREATE privilege has not been and will not |
| 37 |
be granted to any untrusted users. |
| 38 |
Otherwise there are installation-time security hazards |
| 39 |
if <filename>earthdistance</filename>'s schema contains objects defined |
| 40 |
by a hostile user. |
| 41 |
Furthermore, when using <filename>earthdistance</filename>'s functions |
| 42 |
after installation, the entire search path should contain only trusted |
| 43 |
schemas. |
| 44 |
</para> |
| 45 |
</caution> |
| 46 |
|
| 47 |
<sect2 id="earthdistance-cube-based"> |
| 48 |
<title>Cube-Based Earth Distances</title> |
| 49 |
|
| 50 |
<para> |
| 51 |
Data is stored in cubes that are points (both corners are the same) using 3 |
| 52 |
coordinates representing the x, y, and z distance from the center of the |
| 53 |
Earth. A <glossterm linkend="glossary-domain">domain</glossterm> |
| 54 |
<type>earth</type> over type <type>cube</type> is provided, which |
| 55 |
includes constraint checks that the value meets these restrictions and |
| 56 |
is reasonably close to the actual surface of the Earth. |
| 57 |
</para> |
| 58 |
|
| 59 |
<para> |
| 60 |
The radius of the Earth is obtained from the <function>earth()</function> |
| 61 |
function. It is given in meters. But by changing this one function you can |
| 62 |
change the module to use some other units, or to use a different value of |
| 63 |
the radius that you feel is more appropriate. |
| 64 |
</para> |
| 65 |
|
| 66 |
<para> |
| 67 |
This package has applications to astronomical databases as well. |
| 68 |
Astronomers will probably want to change <function>earth()</function> to return a |
| 69 |
radius of <literal>180/pi()</literal> so that distances are in degrees. |
| 70 |
</para> |
| 71 |
|
| 72 |
<para> |
| 73 |
Functions are provided to support input in latitude and longitude (in |
| 74 |
degrees), to support output of latitude and longitude, to calculate |
| 75 |
the great circle distance between two points and to easily specify a |
| 76 |
bounding box usable for index searches. |
| 77 |
</para> |
| 78 |
|
| 79 |
<para> |
| 80 |
The provided functions are shown |
| 81 |
in <xref linkend="earthdistance-cube-functions"/>. |
| 82 |
</para> |
| 83 |
|
| 84 |
<table id="earthdistance-cube-functions"> |
| 85 |
<title>Cube-Based Earthdistance Functions</title> |
| 86 |
<tgroup cols="1"> |
| 87 |
<thead> |
| 88 |
<row> |
| 89 |
<entry role="func_table_entry"><para role="func_signature"> |
| 90 |
Function |
| 91 |
</para> |
| 92 |
<para> |
| 93 |
Description |
| 94 |
</para></entry> |
| 95 |
</row> |
| 96 |
</thead> |
| 97 |
|
| 98 |
<tbody> |
| 99 |
<row> |
| 100 |
<entry role="func_table_entry"><para role="func_signature"> |
| 101 |
<indexterm><primary>earth</primary></indexterm> |
| 102 |
<function>earth</function> () |
| 103 |
<returnvalue>float8</returnvalue> |
| 104 |
</para> |
| 105 |
<para> |
| 106 |
Returns the assumed radius of the Earth. |
| 107 |
</para></entry> |
| 108 |
</row> |
| 109 |
|
| 110 |
<row> |
| 111 |
<entry role="func_table_entry"><para role="func_signature"> |
| 112 |
<indexterm><primary>sec_to_gc</primary></indexterm> |
| 113 |
<function>sec_to_gc</function> ( <type>float8</type> ) |
| 114 |
<returnvalue>float8</returnvalue> |
| 115 |
</para> |
| 116 |
<para> |
| 117 |
Converts the normal straight line |
| 118 |
(secant) distance between two points on the surface of the Earth |
| 119 |
to the great circle distance between them. |
| 120 |
</para></entry> |
| 121 |
</row> |
| 122 |
|
| 123 |
<row> |
| 124 |
<entry role="func_table_entry"><para role="func_signature"> |
| 125 |
<indexterm><primary>gc_to_sec</primary></indexterm> |
| 126 |
<function>gc_to_sec</function> ( <type>float8</type> ) |
| 127 |
<returnvalue>float8</returnvalue> |
| 128 |
</para> |
| 129 |
<para> |
| 130 |
Converts the great circle distance between two points on the |
| 131 |
surface of the Earth to the normal straight line (secant) distance |
| 132 |
between them. |
| 133 |
</para></entry> |
| 134 |
</row> |
| 135 |
|
| 136 |
<row> |
| 137 |
<entry role="func_table_entry"><para role="func_signature"> |
| 138 |
<indexterm><primary>ll_to_earth</primary></indexterm> |
| 139 |
<function>ll_to_earth</function> ( <type>float8</type>, <type>float8</type> ) |
| 140 |
<returnvalue>earth</returnvalue> |
| 141 |
</para> |
| 142 |
<para> |
| 143 |
Returns the location of a point on the surface of the Earth given |
| 144 |
its latitude (argument 1) and longitude (argument 2) in degrees. |
| 145 |
</para></entry> |
| 146 |
</row> |
| 147 |
|
| 148 |
<row> |
| 149 |
<entry role="func_table_entry"><para role="func_signature"> |
| 150 |
<indexterm><primary>latitude</primary></indexterm> |
| 151 |
<function>latitude</function> ( <type>earth</type> ) |
| 152 |
<returnvalue>float8</returnvalue> |
| 153 |
</para> |
| 154 |
<para> |
| 155 |
Returns the latitude in degrees of a point on the surface of the |
| 156 |
Earth. |
| 157 |
</para></entry> |
| 158 |
</row> |
| 159 |
|
| 160 |
<row> |
| 161 |
<entry role="func_table_entry"><para role="func_signature"> |
| 162 |
<indexterm><primary>longitude</primary></indexterm> |
| 163 |
<function>longitude</function> ( <type>earth</type> ) |
| 164 |
<returnvalue>float8</returnvalue> |
| 165 |
</para> |
| 166 |
<para> |
| 167 |
Returns the longitude in degrees of a point on the surface of the |
| 168 |
Earth. |
| 169 |
</para></entry> |
| 170 |
</row> |
| 171 |
|
| 172 |
<row> |
| 173 |
<entry role="func_table_entry"><para role="func_signature"> |
| 174 |
<indexterm><primary>earth_distance</primary></indexterm> |
| 175 |
<function>earth_distance</function> ( <type>earth</type>, <type>earth</type> ) |
| 176 |
<returnvalue>float8</returnvalue> |
| 177 |
</para> |
| 178 |
<para> |
| 179 |
Returns the great circle distance between two points on the |
| 180 |
surface of the Earth. |
| 181 |
</para></entry> |
| 182 |
</row> |
| 183 |
|
| 184 |
<row> |
| 185 |
<entry role="func_table_entry"><para role="func_signature"> |
| 186 |
<indexterm><primary>earth_box</primary></indexterm> |
| 187 |
<function>earth_box</function> ( <type>earth</type>, <type>float8</type> ) |
| 188 |
<returnvalue>cube</returnvalue> |
| 189 |
</para> |
| 190 |
<para> |
| 191 |
Returns a box suitable for an indexed search using the <type>cube</type> |
| 192 |
<literal>@></literal> |
| 193 |
operator for points within a given great circle distance of a location. |
| 194 |
Some points in this box are further than the specified great circle |
| 195 |
distance from the location, so a second check using |
| 196 |
<function>earth_distance</function> should be included in the query. |
| 197 |
</para></entry> |
| 198 |
</row> |
| 199 |
</tbody> |
| 200 |
</tgroup> |
| 201 |
</table> |
| 202 |
|
| 203 |
</sect2> |
| 204 |
|
| 205 |
<sect2 id="earthdistance-point-based"> |
| 206 |
<title>Point-Based Earth Distances</title> |
| 207 |
|
| 208 |
<para> |
| 209 |
The second part of the module relies on representing Earth locations as |
| 210 |
values of type <type>point</type>, in which the first component is taken to |
| 211 |
represent longitude in degrees, and the second component is taken to |
| 212 |
represent latitude in degrees. Points are taken as (longitude, latitude) |
| 213 |
and not vice versa because longitude is closer to the intuitive idea of |
| 214 |
x-axis and latitude to y-axis. |
| 215 |
</para> |
| 216 |
|
| 217 |
<para> |
| 218 |
A single operator is provided, shown |
| 219 |
in <xref linkend="earthdistance-point-operators"/>. |
| 220 |
</para> |
| 221 |
|
| 222 |
<table id="earthdistance-point-operators"> |
| 223 |
<title>Point-Based Earthdistance Operators</title> |
| 224 |
<tgroup cols="1"> |
| 225 |
<thead> |
| 226 |
<row> |
| 227 |
<entry role="func_table_entry"><para role="func_signature"> |
| 228 |
Operator |
| 229 |
</para> |
| 230 |
<para> |
| 231 |
Description |
| 232 |
</para></entry> |
| 233 |
</row> |
| 234 |
</thead> |
| 235 |
<tbody> |
| 236 |
<row> |
| 237 |
<entry role="func_table_entry"><para role="func_signature"> |
| 238 |
<type>point</type> <literal><@></literal> <type>point</type> |
| 239 |
<returnvalue>float8</returnvalue> |
| 240 |
</para> |
| 241 |
<para> |
| 242 |
Computes the distance in statute miles between |
| 243 |
two points on the Earth's surface. |
| 244 |
</para></entry> |
| 245 |
</row> |
| 246 |
</tbody> |
| 247 |
</tgroup> |
| 248 |
</table> |
| 249 |
|
| 250 |
<para> |
| 251 |
Note that unlike the <type>cube</type>-based part of the module, units |
| 252 |
are hardwired here: changing the <function>earth()</function> function will |
| 253 |
not affect the results of this operator. |
| 254 |
</para> |
| 255 |
|
| 256 |
<para> |
| 257 |
One disadvantage of the longitude/latitude representation is that |
| 258 |
you need to be careful about the edge conditions near the poles |
| 259 |
and near +/- 180 degrees of longitude. The <type>cube</type>-based |
| 260 |
representation avoids these discontinuities. |
| 261 |
</para> |
| 262 |
|
| 263 |
</sect2> |
| 264 |
|
| 265 |
</sect1> |