266 lines
9.0 KiB
Plaintext
266 lines
9.0 KiB
Plaintext
<!-- doc/src/sgml/earthdistance.sgml -->
|
|
|
|
<sect1 id="earthdistance" xreflabel="earthdistance">
|
|
<title>earthdistance — calculate great-circle distances</title>
|
|
|
|
<indexterm zone="earthdistance">
|
|
<primary>earthdistance</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
The <filename>earthdistance</filename> module provides two different approaches to
|
|
calculating great circle distances on the surface of the Earth. The one
|
|
described first depends on the <filename>cube</filename> module.
|
|
The second one is based on the built-in <type>point</type> data type,
|
|
using longitude and latitude for the coordinates.
|
|
</para>
|
|
|
|
<para>
|
|
In this module, the Earth is assumed to be perfectly spherical.
|
|
(If that's too inaccurate for you, you might want to look at the
|
|
<application><ulink url="https://postgis.net/">PostGIS</ulink></application>
|
|
project.)
|
|
</para>
|
|
|
|
<para>
|
|
The <filename>cube</filename> module must be installed
|
|
before <filename>earthdistance</filename> can be installed
|
|
(although you can use the <literal>CASCADE</literal> option
|
|
of <command>CREATE EXTENSION</command> to install both in one command).
|
|
</para>
|
|
|
|
<caution>
|
|
<para>
|
|
It is strongly recommended that <filename>earthdistance</filename>
|
|
and <filename>cube</filename> be installed in the same schema, and that
|
|
that schema be one for which CREATE privilege has not been and will not
|
|
be granted to any untrusted users.
|
|
Otherwise there are installation-time security hazards
|
|
if <filename>earthdistance</filename>'s schema contains objects defined
|
|
by a hostile user.
|
|
Furthermore, when using <filename>earthdistance</filename>'s functions
|
|
after installation, the entire search path should contain only trusted
|
|
schemas.
|
|
</para>
|
|
</caution>
|
|
|
|
<sect2 id="earthdistance-cube-based">
|
|
<title>Cube-Based Earth Distances</title>
|
|
|
|
<para>
|
|
Data is stored in cubes that are points (both corners are the same) using 3
|
|
coordinates representing the x, y, and z distance from the center of the
|
|
Earth. A <glossterm linkend="glossary-domain">domain</glossterm>
|
|
<type>earth</type> over type <type>cube</type> is provided, which
|
|
includes constraint checks that the value meets these restrictions and
|
|
is reasonably close to the actual surface of the Earth.
|
|
</para>
|
|
|
|
<para>
|
|
The radius of the Earth is obtained from the <function>earth()</function>
|
|
function. It is given in meters. But by changing this one function you can
|
|
change the module to use some other units, or to use a different value of
|
|
the radius that you feel is more appropriate.
|
|
</para>
|
|
|
|
<para>
|
|
This package has applications to astronomical databases as well.
|
|
Astronomers will probably want to change <function>earth()</function> to return a
|
|
radius of <literal>180/pi()</literal> so that distances are in degrees.
|
|
</para>
|
|
|
|
<para>
|
|
Functions are provided to support input in latitude and longitude (in
|
|
degrees), to support output of latitude and longitude, to calculate
|
|
the great circle distance between two points and to easily specify a
|
|
bounding box usable for index searches.
|
|
</para>
|
|
|
|
<para>
|
|
The provided functions are shown
|
|
in <xref linkend="earthdistance-cube-functions"/>.
|
|
</para>
|
|
|
|
<table id="earthdistance-cube-functions">
|
|
<title>Cube-Based Earthdistance Functions</title>
|
|
<tgroup cols="1">
|
|
<thead>
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
Function
|
|
</para>
|
|
<para>
|
|
Description
|
|
</para></entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>earth</primary></indexterm>
|
|
<function>earth</function> ()
|
|
<returnvalue>float8</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns the assumed radius of the Earth.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>sec_to_gc</primary></indexterm>
|
|
<function>sec_to_gc</function> ( <type>float8</type> )
|
|
<returnvalue>float8</returnvalue>
|
|
</para>
|
|
<para>
|
|
Converts the normal straight line
|
|
(secant) distance between two points on the surface of the Earth
|
|
to the great circle distance between them.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>gc_to_sec</primary></indexterm>
|
|
<function>gc_to_sec</function> ( <type>float8</type> )
|
|
<returnvalue>float8</returnvalue>
|
|
</para>
|
|
<para>
|
|
Converts the great circle distance between two points on the
|
|
surface of the Earth to the normal straight line (secant) distance
|
|
between them.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>ll_to_earth</primary></indexterm>
|
|
<function>ll_to_earth</function> ( <type>float8</type>, <type>float8</type> )
|
|
<returnvalue>earth</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns the location of a point on the surface of the Earth given
|
|
its latitude (argument 1) and longitude (argument 2) in degrees.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>latitude</primary></indexterm>
|
|
<function>latitude</function> ( <type>earth</type> )
|
|
<returnvalue>float8</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns the latitude in degrees of a point on the surface of the
|
|
Earth.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>longitude</primary></indexterm>
|
|
<function>longitude</function> ( <type>earth</type> )
|
|
<returnvalue>float8</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns the longitude in degrees of a point on the surface of the
|
|
Earth.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>earth_distance</primary></indexterm>
|
|
<function>earth_distance</function> ( <type>earth</type>, <type>earth</type> )
|
|
<returnvalue>float8</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns the great circle distance between two points on the
|
|
surface of the Earth.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>earth_box</primary></indexterm>
|
|
<function>earth_box</function> ( <type>earth</type>, <type>float8</type> )
|
|
<returnvalue>cube</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns a box suitable for an indexed search using the <type>cube</type>
|
|
<literal>@></literal>
|
|
operator for points within a given great circle distance of a location.
|
|
Some points in this box are further than the specified great circle
|
|
distance from the location, so a second check using
|
|
<function>earth_distance</function> should be included in the query.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="earthdistance-point-based">
|
|
<title>Point-Based Earth Distances</title>
|
|
|
|
<para>
|
|
The second part of the module relies on representing Earth locations as
|
|
values of type <type>point</type>, in which the first component is taken to
|
|
represent longitude in degrees, and the second component is taken to
|
|
represent latitude in degrees. Points are taken as (longitude, latitude)
|
|
and not vice versa because longitude is closer to the intuitive idea of
|
|
x-axis and latitude to y-axis.
|
|
</para>
|
|
|
|
<para>
|
|
A single operator is provided, shown
|
|
in <xref linkend="earthdistance-point-operators"/>.
|
|
</para>
|
|
|
|
<table id="earthdistance-point-operators">
|
|
<title>Point-Based Earthdistance Operators</title>
|
|
<tgroup cols="1">
|
|
<thead>
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
Operator
|
|
</para>
|
|
<para>
|
|
Description
|
|
</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<type>point</type> <literal><@></literal> <type>point</type>
|
|
<returnvalue>float8</returnvalue>
|
|
</para>
|
|
<para>
|
|
Computes the distance in statute miles between
|
|
two points on the Earth's surface.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>
|
|
Note that unlike the <type>cube</type>-based part of the module, units
|
|
are hardwired here: changing the <function>earth()</function> function will
|
|
not affect the results of this operator.
|
|
</para>
|
|
|
|
<para>
|
|
One disadvantage of the longitude/latitude representation is that
|
|
you need to be careful about the edge conditions near the poles
|
|
and near +/- 180 degrees of longitude. The <type>cube</type>-based
|
|
representation avoids these discontinuities.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|