diff options
Diffstat (limited to 'doc/src/sgml/earthdistance.sgml')
| -rw-r--r-- | doc/src/sgml/earthdistance.sgml | 265 |
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>@></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><@></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> |