summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/earthdistance.sgml
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:17:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:17:33 +0000
commit5e45211a64149b3c659b90ff2de6fa982a5a93ed (patch)
tree739caf8c461053357daa9f162bef34516c7bf452 /doc/src/sgml/earthdistance.sgml
parentInitial commit. (diff)
downloadpostgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.tar.xz
postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.zip
Adding upstream version 15.5.upstream/15.5
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/src/sgml/earthdistance.sgml')
-rw-r--r--doc/src/sgml/earthdistance.sgml265
1 files changed, 265 insertions, 0 deletions
diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml
new file mode 100644
index 0000000..4377249
--- /dev/null
+++ b/doc/src/sgml/earthdistance.sgml
@@ -0,0 +1,265 @@
+<!-- doc/src/sgml/earthdistance.sgml -->
+
+<sect1 id="earthdistance" xreflabel="earthdistance">
+ <title>earthdistance</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>
+ <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>@&gt;</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>
+ <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>&lt;@&gt;</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>