Adding upstream version 15.5.upstream/15.5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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>