libproj: recognise NAD83(HARN) for NC; fix SIRGAS2000 datum; add explanations about datum management (contributed by Paul Kelly, trunk https://trac.osgeo.org/grass/changeset/68308)

git-svn-id: https://svn.osgeo.org/grass/grass/branches/releasebranch_7_0@68314 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/gis/datum.table

@@ -1,14 +1,20 @@
-# this file contains datum shift parameters,
+# Datum Transformation Parameter Lists for GRASS
+# (single 3-parameter datum transformation))
+#
+# This file contains datum shift parameters,
 # it supplies a datum database table for GRASS
 # format:
 # shortname "Full EPSG-style name" ellipsoid dx= dy= dz=
 #
-# where short name is a single word datum specifier,
-# Full EPSG-style name is the exact name used in the European 
-# Petroleum Survey Group (EPSG) database (enclosed in double quotes),
-# ellipsoid is the acronym of the ellipsoid used with this map datum, 
-# dx, dy and dz are the datum shift parameters.
-# no spaces allowed before or after the =.
+# where 
+# * short name is a single word datum specifier,
+# * Full EPSG-style name is the exact name used in the European 
+#   Petroleum Survey Group (EPSG) database (enclosed in double quotes),
+# * ellipsoid is the acronym of the ellipsoid used with this map datum, 
+#   (GRASS ellipsoid code, from ellipse.table)
+# * dx, dy and dz are the datum shift parameters that should cover the
+#   whole area the datum is used in.
+#   Note: no spaces allowed before or after the =.
 #
 # In general the 3-parameter transformation given in this file should
 # be a mean solution for the countries or area the datum is used in.
@@ -25,8 +31,7 @@
 # cited from NIMA document TR8350.2
 #
 # Datum parameters for/from European Terrestrial Reference System ETRS89
-# are here: http://crs.ifag.de/crs_national.php
-#           http://crs.bkg.bund.de/crs-eu
+# are here: http://www.crs-geo.eu 
 
 # World Geodetic System 1984
 wgs84  "WGS_1984"	  wgs84		dx=0.0	    dy=0.0      dz=0.0
@@ -36,6 +41,7 @@ wgs72  "WGS_1972"       wgs72         dx=0.0      dy=0.0      dz=5.0
 nad27  "North_American_Datum_1927"              clark66       dx=-22.0    dy=157.0    dz=176.0
 # North American 1983
 nad83	"North_American_Datum_1983"		  grs80		dx=0.0	    dy=0.0	dz=0.0
+nad83harn "NAD83_High_Accuracy_Reference_Network" grs80		dx=0.0	    dy=0.0	dz=0.0
 # Tokyo datum mean
 tokyo  "Tokyo"                       bessel        dx=-148   dy=507    dz=685
 # Ordnance Survey of Great Britain (1936)
@@ -91,4 +97,4 @@ itrf92   "ITRF92"    grs80 dx=0   dy=0    dz=0
 # https://epsg.io/5514 + https://epsg.io/6156-datum
 S_JTSK	"System_Jednotne_Trigonometricke_Site_Katastralni"	bessel	dx=589	dy=76	dz=480
 # http://spatialreference.org/ref/epsg/4674/
-Sistema_de_Referencia_Geocentrico_para_America_del_Sur_2000 "Sistema_de_Referencia_Geocentrico_para_America_del_Sur_2000"   grs80       dx=0        dy=0       dz=0
+sirgas2000 "Sistema_de_Referencia_Geocentrico_para_las_AmericaS_2000"   grs80       dx=0        dy=0       dz=0

lib/gis/datumtransform.table

@@ -1,15 +1,23 @@
 # Datum Transformation Parameter Lists for GRASS
+# (allows multiple different sets of datum transformation parameters to be
+#  supplied for any datum)
 #
 # Line Format:
-# shortname "PROJ.4-style parameters" "Where Used" "Comment"
+# shortname "parameters" "Where Used" "Comment"
 #
-# 4 fields on each line, shortname should be already listed in datum.table
+# where
+# * parameters can be in any format accepted by PROJ.4, 
+#   so towgs84= 3 parameters or 7 parameters, or nadgrids=
+# * area of validity
+# * comment
+# Hence, 4 fields on each line, and shortname should be already
+# listed in datum.table.
 #
 # All but 1st field must be enclosed in quotes ("") An empty field can
 # contain a single space between the quotes (" ") but try to provide as
 # much detail as possible for the user.
 #
-# datum.table only holds one 3-parameter transformation. Extra sets of 
+# Note: datum.table only holds one 3-parameter transformation. Extra sets of 
 # transformation parameters may be defined in this file for each datum
 # and will be presented to the user to select the most appropriate one for
 # his/her location. The "Where Used" and "Comment" fields should contain

lib/proj/convert.c

@@ -742,14 +742,24 @@ const char *GPJ_set_csv_loc(const char *name)
 /* The list below is only for files that use a non-standard name for a 
  * datum that is already supported in GRASS. The number of entries must be even;
  * they are all in pairs. The first one in the pair is the non-standard name;
- * the second is the GRASS name. If a name appears more than once (as for
+ * the second is the GRASS/GDAL name. If a name appears more than once (as for
  * European_Terrestrial_Reference_System_1989) then it means there was more
  * than one non-standard name for it that needs to be accounted for. 
  *
  * N.B. The order of these pairs is different from that in 
  * ogr/ogrfromepsg.cpp in the GDAL source tree! GRASS uses the EPSG
  * names in its WKT representation except WGS_1984 and WGS_1972 as
- * these shortened versions seem to be standard
+ * these shortened versions seem to be standard.
+ * Below order:
+ * the equivalent name comes first in the pair, and
+ * the EPSG name (as used in the GRASS datum.table file) comes second.
+ *
+ * The datum parameters are stored in
+ *   ../gis/datum.table           # 3 parameters
+ *   ../gis/datumtransform.table  # 7 parameters (requires entry in datum.table)
+ *
+ * Hint: use GDAL's "testepsg" to identify the canonical name, e.g.
+ *       testepsg epsg:4674
  */
 
 static const char *papszDatumEquiv[] = {
@@ -785,8 +795,6 @@ static const char *papszDatumEquiv[] = {
     "Deutsches_Hauptdreiecksnetz",
     "South_American_1969",
     "South_American_Datum_1969",
-    "Sistema_de_Referencia_Geocentrico_para_las_AmericaS_2000",
-    "Sistema_de_Referencia_Geocentrico_para_America_del_Sur_2000",
     "ITRF_1992",
     "ITRF92",
     NULL