[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0rc1-11-g8d88f6a
git at osgeo.org
git at osgeo.org
Wed Dec 16 22:40:22 PST 2020
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".
The branch, master has been updated
via 8d88f6a4ed077d5e80d2cf89aff60e964de9dcd9 (commit)
from 5e759ede6dd94e5000e69c12a93e6da29959fa55 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 8d88f6a4ed077d5e80d2cf89aff60e964de9dcd9
Author: Martin Davis <mtnclimb at gmail.com>
Date: Wed Dec 16 22:40:12 2020 -0800
Improve doc SRS section
diff --git a/doc/reference_srs.xml b/doc/reference_srs.xml
index 91b0dec..51f2035 100644
--- a/doc/reference_srs.xml
+++ b/doc/reference_srs.xml
@@ -2,7 +2,8 @@
<sect1 id="SRS_Functions">
<sect1info>
<abstract>
- <para>These functions work with the Spatial Reference System of geometries.</para>
+ <para>These functions work with the Spatial Reference System of geometries
+ as defined in the <varname>spatial_ref_sys</varname> table.</para>
</abstract>
</sect1info>
@@ -12,8 +13,7 @@
<refnamediv>
<refname>ST_SetSRID</refname>
- <refpurpose>Set the SRID on a geometry to a particular integer
- value.</refpurpose>
+ <refpurpose>Set the SRID on a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -63,7 +63,7 @@ SRID=3785;POINT(-13732990.8753491 6178458.96425423)
<refsection>
<title>See Also</title>
- <para><xref linkend="spatial_ref_sys" />, <xref linkend="ST_AsEWKT"/>, <xref linkend="ST_SRID"/>, <xref linkend="ST_Transform"/>, <xref linkend="UpdateGeometrySRID"/></para>
+ <para><xref linkend="spatial_ref_sys" />, <xref linkend="ST_SRID"/>, <xref linkend="ST_Transform"/>, <xref linkend="UpdateGeometrySRID"/></para>
</refsection>
</refentry>
@@ -71,7 +71,7 @@ SRID=3785;POINT(-13732990.8753491 6178458.96425423)
<refentry id="ST_SRID">
<refnamediv>
<refname>ST_SRID</refname>
- <refpurpose>Returns the spatial reference identifier for the ST_Geometry as defined in spatial_ref_sys table.</refpurpose>
+ <refpurpose>Returns the spatial reference identifier for a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -107,7 +107,7 @@ SRID=3785;POINT(-13732990.8753491 6178458.96425423)
<refsection>
<title>See Also</title>
- <para><xref linkend="spatial_ref_sys" />, <xref linkend="ST_GeomFromText" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_Transform" /></para>
+ <para><xref linkend="spatial_ref_sys" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_Transform" /></para>
</refsection>
</refentry>
@@ -115,7 +115,7 @@ SRID=3785;POINT(-13732990.8753491 6178458.96425423)
<refnamediv>
<refname>ST_Transform</refname>
- <refpurpose>Return a new geometry with its coordinates transformed to
+ <refpurpose>Return a new geometry with coordinates transformed to
a different spatial reference system.</refpurpose>
</refnamediv>
@@ -270,7 +270,7 @@ CREATE INDEX idx_the_geom_26986_parcels
<refsection>
<title>See Also</title>
- <para><xref linkend="PostGIS_Full_Version" />, <xref linkend="ST_AsText" />, <xref linkend="ST_SetSRID" />, <xref linkend="UpdateGeometrySRID"/></para>
+ <para><xref linkend="spatial_ref_sys" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_SRID" />, <xref linkend="UpdateGeometrySRID"/></para>
</refsection>
</refentry>
diff --git a/doc/using_postgis_dataman.xml b/doc/using_postgis_dataman.xml
index 9965756..b06a188 100644
--- a/doc/using_postgis_dataman.xml
+++ b/doc/using_postgis_dataman.xml
@@ -534,47 +534,18 @@ The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik
<para>There are two OpenGIS meta-data tables:
<varname>SPATIAL_REF_SYS</varname> and
- <varname>GEOMETRY_COLUMNS</varname>. The
- <varname>SPATIAL_REF_SYS</varname> table holds the numeric IDs and textual
- descriptions of coordinate systems used in the spatial database.</para>
+ <varname>GEOMETRY_COLUMNS</varname>.
+ </para>
<sect3 id="spatial_ref_sys">
<title>The SPATIAL_REF_SYS Table and Spatial Reference Systems</title>
<para>The <varname>SPATIAL_REF_SYS</varname> table used by PostGIS
- is an OGC-compliant database table that lists over 3000
- known <ulink url="https://en.wikipedia.org/wiki/Spatial_reference_system">spatial reference systems</ulink>
- and details needed to transform (reproject) between them.</para>
-
- <para>The PostGIS <varname>SPATIAL_REF_SYS</varname> table contains over 3000 of
- the most common spatial reference system definitions that are handled by the
- <ulink url="https://proj.org">PROJ</ulink> projection library.
- But there are many coordinate systems that it does not contain.
- You can define your own custom spatial reference system if you are familiar with PROJ constructs.
- Keep in mind that most spatial reference systems are regional
- and have no meaning when used outside of the bounds they were intended for.</para>
-
- <para>A resource for finding spatial reference systems not defined in the core set is <ulink url="http://spatialreference.org/">http://spatialreference.org/</ulink></para>
-
- <para>Some commonly used spatial reference systems are:
- <ulink url="http://spatialreference.org/ref/epsg/4326/">4326 - WGS 84 Long Lat</ulink>,
- <ulink url="http://spatialreference.org/ref/epsg/4269/">4269 - NAD 83 Long Lat</ulink>,
- <ulink url="http://spatialreference.org/ref/epsg/3395/">3395 - WGS 84 World Mercator</ulink>,
- <ulink url="http://spatialreference.org/ref/epsg/2163/">2163 - US National Atlas Equal Area</ulink>,
- and the 60 WGS84 UTM zones.
- UTM zones are one of the most ideal for measurement, but only cover 6-degree regions.
- (To determine which UTM zone to use for your area of interest, see the <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiplpgsqlfunctionsDistance">utmzone PostGIS plpgsql helper function</ulink>.)
- </para>
- <para>
- US states use State Plane spatial reference systems (meter or feet based) - usually one or 2 exists per state.
- Most of the meter-based ones are in the core set, but many of the
- feet-based ones or ESRI created ones will need to be copied from <ulink url="http://spatialreference.org">spatialreference.org</ulink>.
- </para>
-
- <para>You can even define non-Earth-based coordinate systems,
- such as <ulink url="http://spatialreference.org/ref/iau2000/mars-2000/">Mars 2000</ulink>
- This Mars coordinate system is non-planar (it's in degrees spheroidal),
- but you can use it with the <varname>geography</varname> type to obtain length and proximity measurements in meters instead of degrees.</para>
+ is an OGC-compliant database table that defines the available
+ <ulink url="https://en.wikipedia.org/wiki/Spatial_reference_system">spatial reference systems</ulink>.
+ It holds the numeric IDs and textual descriptions of the coordinate systems,
+ to support transformation (reprojection) between them using <xref linkend="ST_Transform" />.
+ </para>
<para>The <varname>SPATIAL_REF_SYS</varname> table definition is:</para>
@@ -660,19 +631,74 @@ The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik
<listitem>
<para>PostGIS uses the PROJ library to provide coordinate
transformation capabilities. The <varname>PROJ4TEXT</varname>
- column contains the Proj4 coordinate definition string for a
+ column contains the PROJ coordinate definition string for a
particular SRID. For example:</para>
<programlisting>+proj=utm +zone=10 +ellps=clrk66 +datum=NAD27 +units=m</programlisting>
<para>For more information see the
- <ulink url="https://proj.org/">Proj4 web site</ulink>.
+ <ulink url="https://proj.org/">PROJ web site</ulink>.
The <filename>spatial_ref_sys.sql</filename> file contains both
<varname>SRTEXT</varname> and <varname>PROJ4TEXT</varname>
definitions for all EPSG projections.</para>
</listitem>
</varlistentry>
</variablelist>
+
+ <para>When retrieving spatial reference system definitions for use in transformations,
+ PostGIS uses fhe following strategy:
+ </para>
+ <itemizedlist>
+ <listitem>If <varname>AUTH_NAME</varname> and <varname>AUTH_SRID</varname>
+ are present (non-NULL)
+ use the PROJ SRS based on those entries (if one exists).</listitem>
+ <listitem>If <varname>SRTEXT</varname> is present
+ create a SRS using it, if possible.</listitem>
+ <listitem>If <varname>PROJ4TEXT</varname> is present
+ create a SRS using it, if possible.</listitem>
+ </itemizedlist>
+
+ <para>The PostGIS <varname>SPATIAL_REF_SYS</varname> table contains over 3000 of
+ the most common spatial reference system definitions that are handled by the
+ <ulink url="https://proj.org">PROJ</ulink> projection library.
+ But there are many coordinate systems that it does not contain.
+ You can define your own custom spatial reference system if you are familiar with PROJ constructs.
+ Keep in mind that most spatial reference systems are regional
+ and have no meaning when used outside of the bounds they were intended for.</para>
+
+ <para>A resource for finding spatial reference systems not defined in the core set is <ulink url="http://spatialreference.org/">http://spatialreference.org/</ulink></para>
+
+ <para>Some commonly used spatial reference systems are:
+ <ulink url="http://spatialreference.org/ref/epsg/4326/">4326 - WGS 84 Long Lat</ulink>,
+ <ulink url="http://spatialreference.org/ref/epsg/4269/">4269 - NAD 83 Long Lat</ulink>,
+ <ulink url="http://spatialreference.org/ref/epsg/3395/">3395 - WGS 84 World Mercator</ulink>,
+ <ulink url="http://spatialreference.org/ref/epsg/2163/">2163 - US National Atlas Equal Area</ulink>,
+ and the 60 WGS84 UTM zones.
+ UTM zones are one of the most ideal for measurement, but only cover 6-degree regions.
+ (To determine which UTM zone to use for your area of interest, see the <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiplpgsqlfunctionsDistance">utmzone PostGIS plpgsql helper function</ulink>.)
+ </para>
+ <para>
+ US states use State Plane spatial reference systems (meter or feet based) - usually one or 2 exists per state.
+ Most of the meter-based ones are in the core set, but many of the
+ feet-based ones or ESRI created ones will need to be copied from <ulink url="http://spatialreference.org">spatialreference.org</ulink>.
+ </para>
+
+ <para>You can even define non-Earth-based coordinate systems,
+ such as <ulink url="http://spatialreference.org/ref/iau2000/mars-2000/">Mars 2000</ulink>
+ This Mars coordinate system is non-planar (it's in degrees spheroidal),
+ but you can use it with the <varname>geography</varname> type
+ to obtain length and proximity measurements in meters instead of degrees.</para>
+
+ <para>Here is an example of loading a custom coordinate system using
+ an unassigned SRID and the PROJ definition for a US-centric Lambert Conformal projection:</para>
+
+<programlisting>
+INSERT INTO spatial_ref_sys (srid, proj4text)
+VALUES ( 990000,
+ '+proj=lcc +lon_0=-95 +lat_0=25 +lat_1=25 +lat_2=25 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs'
+);
+</programlisting>
+
</sect3>
<sect3 id="geometry_columns">
@@ -702,8 +728,8 @@ The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik
<listitem>
<para>The fully qualified name of the feature table containing the
geometry column. Note that the terms "catalog" and "schema" are
- Oracle-ish. There is not PostgreSQL analogue of "catalog" so that
- column is left blank -- for "schema" the PostgreSQL schema name is
+ Oracle-ish. There is no PostgreSQL analogue of "catalog" so that
+ column is left blank . For "schema" the PostgreSQL schema name is
used (<varname>public</varname> is the default).</para>
</listitem>
</varlistentry>
-----------------------------------------------------------------------
Summary of changes:
doc/reference_srs.xml | 16 +++----
doc/using_postgis_dataman.xml | 106 ++++++++++++++++++++++++++----------------
2 files changed, 74 insertions(+), 48 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list