[postgis-tickets] r15983 - try to modernize the geography section a bit.
Regina Obe
lr at pcorp.us
Sat Oct 14 01:08:15 PDT 2017
Author: robe
Date: 2017-10-14 01:08:15 -0700 (Sat, 14 Oct 2017)
New Revision: 15983
Modified:
trunk/doc/using_postgis_dataman.xml
Log:
try to modernize the geography section a bit.
References #3902
Modified: trunk/doc/using_postgis_dataman.xml
===================================================================
--- trunk/doc/using_postgis_dataman.xml 2017-10-14 07:26:59 UTC (rev 15982)
+++ trunk/doc/using_postgis_dataman.xml 2017-10-14 08:08:15 UTC (rev 15983)
@@ -275,12 +275,18 @@
<para>The basis for the PostGIS geographic type is a sphere. The shortest path between two points on the sphere is a great circle arc. That means that calculations on geographies (areas, distances, lengths, intersections, etc) must be calculated on the sphere, using more complicated mathematics. For more accurate measurements, the calculations must take the actual spheroidal shape of the world into account, and the mathematics becomes very complicated indeed.</para>
<para>Because the underlying mathematics is much more complicated, there are fewer functions defined for the geography type than for the geometry type. Over time, as new algorithms are added, the capabilities of the geography type will expand.</para>
- <!-- TODO: Fill in more information -->
- <para>One restriction is that it only supports WGS 84 long lat (SRID:4326). It uses a new data type called
+ <para>It uses a new data type called
geography. None of the GEOS functions support this new
type. As a workaround one can convert back and forth between geometry and geography types.</para>
+ <para>Prior to PostGIS 2.2, the geography type only supported WGS 84 long lat (SRID:4326).
+ For PostGIS 2.2 and above, any long/lat based spatial reference system defined in the <varname>spatial_ref_sys</varname> table can be used.
+ You can even add your own custom spheroidal spatial refence system as described in <ulink url="http://www.bostongis.com/blog/index.php?/archives/266-geography-type-is-not-limited-to-earth.html">geography type is not limited to earth</ulink></para>
+
+ <para>Regardless which spatial reference system you use, the units returned by the measurement (<xref linkend="ST_Distance" />, <xref linkend="ST_Length" />, <xref linkend="ST_Perimeter" />, <xref linkend="ST_Area" />) and for input of for input of <xref linkend="ST_DWithin" /> are in meters.</para>
+
+
<para>The new geography type uses the PostgreSQL 8.3+ typmod definition format so that a table with a geography field
can be added in a single step. All the standard OGC formats except for curves are supported.</para>
@@ -291,16 +297,21 @@
<itemizedlist>
<listitem>
- <para>POINT: Creating a table with 2d point geometry:</para>
- <para><programlisting>CREATE TABLE testgeog(gid serial PRIMARY KEY, the_geog geography(POINT,4326) );</programlisting></para>
- <para>Creating a table with z coordinate point</para>
- <para><programlisting>CREATE TABLE testgeog(gid serial PRIMARY KEY, the_geog geography(POINTZ,4326) );</programlisting></para>
+ <para>POINT: Creating a table with 2d point geography when srid is not specified defaults to 4326 WGS 84 long lat:</para>
+ <para><programlisting>CREATE TABLE ptgeogwgs(gid serial PRIMARY KEY, geog geography(POINT) );</programlisting></para>
+ <para>POINT: Creating a table with 2d point geography in NAD83 longlat:</para>
+ <para><programlisting>CREATE TABLE ptgeognad83(gid serial PRIMARY KEY, geog geography(POINT,4269) );</programlisting></para>
+ <para>Creating a table with z coordinate point and explicitly specifying srid</para>
+ <para><programlisting>CREATE TABLE ptzgeogwgs84(gid serial PRIMARY KEY, geog geography(POINTZ,4326) );</programlisting></para>
</listitem>
<listitem>
<para>LINESTRING</para>
+ <para><programlisting>CREATE TABLE lgeog(gid serial PRIMARY KEY, geog geography(LINESTRING) );</programlisting></para>
</listitem>
<listitem>
<para>POLYGON</para>
+ <para><programlisting>--polygon NAD 1927 long lat
+CREATE TABLE lgeognad27(gid serial PRIMARY KEY, geog geography(POLYGON,4267) );</programlisting></para>
</listitem>
<listitem>
<para>MULTIPOINT</para>
@@ -317,13 +328,12 @@
<!-- TODO: Add other examples -->
</itemizedlist>
<para>The new geography fields don't get registered in the <varname>geometry_columns</varname>. They get registered in a new view called
- geography_columns which is a view against the system catalogs so is always automatically kept up to date without need
+ <varname>geography_columns</varname> which is a view against the system catalogs so is always automatically kept up to date without need
for an AddGeom... like function.</para>
<para>Now, check the "geography_columns" view and see that your table is listed.</para>
- <para>You can create a new table with a GEOGRAPHY column using the CREATE TABLE syntax.
- Unlike GEOMETRY, there is no need to run a separate AddGeometryColumns() process to register the column in metadata.</para>
+ <para>You can create a new table with a GEOGRAPHY column using the CREATE TABLE syntax.</para>
<para>
<programlisting>CREATE TABLE global_points (
@@ -346,9 +356,9 @@
<para>You can insert data into the table the same as you would if it was using a GEOMETRY column:</para>
<para><programlisting>-- Add some data into the test table
-INSERT INTO global_points (name, location) VALUES ('Town', ST_GeographyFromText('SRID=4326;POINT(-110 30)') );
-INSERT INTO global_points (name, location) VALUES ('Forest', ST_GeographyFromText('SRID=4326;POINT(-109 29)') );
-INSERT INTO global_points (name, location) VALUES ('London', ST_GeographyFromText('SRID=4326;POINT(0 49)') );</programlisting></para>
+INSERT INTO global_points (name, location) VALUES ('Town', ST_GeogFromText('SRID=4326;POINT(-110 30)') );
+INSERT INTO global_points (name, location) VALUES ('Forest', ST_GeogFromText('SRID=4326;POINT(-109 29)') );
+INSERT INTO global_points (name, location) VALUES ('London', ST_GeogFromText('SRID=4326;POINT(0 49)') );</programlisting></para>
<para>Creating an index works the same as GEOMETRY.
PostGIS will note that the column type is GEOGRAPHY and create an appropriate sphere-based index instead of the usual planar index used for GEOMETRY.</para>
@@ -360,7 +370,7 @@
<para>Query and measurement functions use units of meters. So distance parameters should be expressed in meters, and return values should be expected in meters (or square meters for areas).</para>
<para><programlisting>-- Show a distance query and note, London is outside the 1000km tolerance
- SELECT name FROM global_points WHERE ST_DWithin(location, ST_GeographyFromText('SRID=4326;POINT(-110 29)'), 1000000);</programlisting>
+ SELECT name FROM global_points WHERE ST_DWithin(location, ST_GeogFromText('SRID=4326;POINT(-110 29)'), 1000000);</programlisting>
</para>
<para>You can see the power of GEOGRAPHY in action by calculating the how close a plane flying from Seattle to London (LINESTRING(-122.33 47.606, 0.0 51.5)) comes to Reykjavik (POINT(-21.96 64.15)).</para>
More information about the postgis-tickets
mailing list