D 2019-05-01T18:15:28.614
L PROJ.6
P c50946fe9f69be5e02cffac433e735fc8ea49f4a
U sandro
W 40770
<a href="https://www.gaia-gis.it/fossil/libspatialite/wiki?name=4.3.0-doc">back</a><hr><br>
<h1>Introduction</h1>
<b>PROJ</b> is a well-known library for performing conversions between cartographic projections.<br>
It's universally supported by almost all open source GIS-oriented applications and packages, so there is no need to waste time in futher presentations.<br>
We just need a bit of history to fully understand the current state of the art of this library:<br>
<h3>Past History</h3>
<b><u>Timeline</u></b>:
<ul>
<li>Very few users and developers do really realize how ancient is PROJ, and how far in time it started moving its first steps.</li>
<li>in <b>1980</b> (about 40 years ago) Gerald Evenden started working on the very first PROJ version, and at the time it was a Ratfor program.</li>
<li>in <b>1985</b> the code was completely rewritten in C to run on UNIX systems, and it was named <b>PROJ.2</b>.</li>
<li>in <b>1990</b> was released an updated version named <b>PROJ.3</li>
<li>in <b>1994</b> a more advanced version was released, and it was obviously named <b>PROJ.4</b></li>
<li>in <b>1995</b> Evenden stopped any further development activity and the project become inactive for several years.</li>
<li>in <b>2000</b> Frank Warmerdam bacame the new maintainer and released version <b>4.4</b></li>
<li>After this reborn the revitalized project continued to be regularly maintained, but no further relevant improvements were introduced.<br>
PROJ.4 just continued its very placid evolution in a substantially conservative way.</li>
</ul><br>
<b><u>Short conclusion</u></b>: the fourth version of PROJ (aka <b>PROJ.4</b>) lasted for about two decades, a very uncommon situation.<br>
And consequently a full generation of developers and users became sincerely convinced that PROJ.4 was the real name of the library.
<h3>The revolution comes</h3>
<b><u>Timeline</u></b>:
<ul>
<li>in <b>2018</b> Even Rouault, Kristian Evers and others start developing a revolutionized PROJ supporting many relevant innovations.<br>
<b>PROJ.5</b> is intended to be the first preliminary step of a more complex evolution schema.</li>
<li>on <b>March 2019</b> a more mature version is released, and it's <b>PROJ.6</b></li>
<li>Next year (2020) <b>PROJ.7</b> is expected to be released, and it will fully complete the transition between the old and new architectures.</li>
</ul>
<br>
<b><u>Note</u></b>: the whole transition implies many relevant changes, so that a deeply revised API will be required.
In other words, the old <b>PROJ.4</b> and the new <b>PROJ.7</b> will support two different APIs, thus abruptly breaking cross-version compatibility.<br>
This is an umpleasant new, because it practically means that all software modules depending on PROJ (this including SpatiaLite) will require a not at all trivial rewrite in order to fulfill the new API requirements.<br>
But when you consider that's the first time in its very long life that PROJ requires an extra effort in order to introduce so many useful innovations, this unexpected API breakage looks fully justified and absolutely reasonable.<br><br>
<b><u>More details about the API breakage</u></b>:
<ul>
<li><b>PROJ.5</b> started introducing the new API, but was still able to support the old traditional API without any complaint.</li>
<li><b>PROJ.6</b> have depreceted the old traditional API.<br>
It still continues to be reluctanctly supported, but the library requires to be compiled by explicitly defining a <b>-DACCEPT_USE_OF_DEPRECATED_PROJ_API_H=1</b> directive in order to effectively enable this option.</li>
<li>and finally the next-to-come <b>PROJ.7</b> will completely get rid of the old API.</li>
</ul>
<br>
<hr>
<h1>What's new in PROJ.6</h1>
<h3>Fully supporting ISO-19111:2019 WKT</h3>
Old versions of PROJ (including <b>PROJ.4</b>) required to define each <b>CRS</b> (<i>Coordinate Reference System</i>) by a corresponding <b>proj-string</b>.
The following table exemplifies the case of few CRSes:<br><br>
<table cellspacing="8" cellpadding="8" bgcolor="#e8ffe8" border="1">
<tr><th bgcolor="#ffb03e">SRID</th><th bgcolor="#ffb03e">CRS Name</th><th bgcolor="#ffb03e">proj-string</th></tr>
<tr><td align="right">3003</td><td>Monte Mario / Italy zone 1</td>
<td>+proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl +towgs84=-104.1,-49.1,-9.9,0.971,-2.917,0.714,-11.68 +units=m +no_defs</td></tr>
<tr><td align="right">4326</td><td>WGS 84</td>
<td>+proj=longlat +datum=WGS84 +no_defs</td></tr>
<tr><td align="right">32632</td><td>WGS 84 / UTM zone 32N</td>
<td>+proj=utm +zone=32 +datum=WGS84 +units=m +no_defs</td>
</table>
<br>
New versions of PROJ (starting since <b>PROJ.6</b>) still continue to support the old <b>proj-strings</b>, but the preferred notation for defining any CRS is now conformant to the <b>ISO-19111:2019</b> international standard<br>
(<i>OGC Abstract Specification Topic 2: “Referencing By Coordinates”</i>).<br>
The following table exemplifies the same CRSes as above in the ISO WKT notation:
<br><br>
<table cellspacing="8" cellpadding="8" bgcolor="#e8ffe8" border="1">
<tr><th bgcolor="#ffb03e">SRID</th><td>3003</td><td>4326</td><td>32632</td></tr>
<tr><th bgcolor="#ffb03e">CRS Name</th><td>Monte Mario / Italy zone 1</td></td><td>WGS 84</td><td>WGS 84 / UTM zone 32N</td></tr>
<tr><th bgcolor="#ffb03e">ISO-2018 WKT</th>
<td valign="top"><verbatim>
PROJCRS["Monte Mario / Italy zone 1",
BASEGEODCRS["Monte Mario",
DATUM["Monte Mario",<br>
ELLIPSOID["International 1924",6378388,297,
LENGTHUNIT["metre",1]]],
PRIMEM["Greenwich",0,
ANGLEUNIT["degree",0.0174532925199433]]],
CONVERSION["Italy zone 1",
METHOD["Transverse Mercator",
ID["EPSG",9807]],
PARAMETER["Latitude of natural origin",0,
ANGLEUNIT["degree",0.0174532925199433],
ID["EPSG",8801]],
PARAMETER["Longitude of natural origin",9,
ANGLEUNIT["degree",0.0174532925199433],
ID["EPSG",8802]],
PARAMETER["Scale factor at natural origin",0.9996,
SCALEUNIT["unity",1],
ID["EPSG",8805]],
PARAMETER["False easting",1500000,
LENGTHUNIT["metre",1],
ID["EPSG",8806]],
PARAMETER["False northing",0,
LENGTHUNIT["metre",1],
ID["EPSG",8807]]],
CS[Cartesian,2],
AXIS["easting (X)",east,
ORDER[1],
LENGTHUNIT["metre",1]],
AXIS["northing (Y)",north,
ORDER[2],<br>
LENGTHUNIT["metre",1]],
AREA["Italy - west of 12°E"],
BBOX[36.53,5.94,47.04,12],
ID["EPSG",3003]]
</verbatim></td>
<td valign="top"><verbatim>
GEODCRS["WGS 84",
DATUM["World Geodetic System 1984",
ELLIPSOID["WGS 84",6378137,298.257223563,
LENGTHUNIT["metre",1]]],
PRIMEM["Greenwich",0,
ANGLEUNIT["degree",0.0174532925199433]],
CS[ellipsoidal,2],
AXIS["geodetic latitude (Lat)",north,
ORDER[1],
ANGLEUNIT["degree",0.0174532925199433]],
AXIS["geodetic longitude (Lon)",east,
ORDER[2],
ANGLEUNIT["degree",0.0174532925199433]],
AREA["World"],
BBOX[-90,-180,90,180],
ID["EPSG",4326]]
</verbatim></td>
<td valign="top"><verbatim>
PROJCRS["WGS 84 / UTM zone 32N",
BASEGEODCRS["WGS 84",
DATUM["World Geodetic System 1984",
ELLIPSOID["WGS 84",6378137,298.257223563,
LENGTHUNIT["metre",1]]],
PRIMEM["Greenwich",0,
ANGLEUNIT["degree",0.0174532925199433]]],
CONVERSION["UTM zone 32N",
METHOD["Transverse Mercator",
ID["EPSG",9807]],
PARAMETER["Latitude of natural origin",0,
ANGLEUNIT["degree",0.0174532925199433],
ID["EPSG",8801]],
PARAMETER["Longitude of natural origin",9,
ANGLEUNIT["degree",0.0174532925199433],
ID["EPSG",8802]],
PARAMETER["Scale factor at natural origin",0.9996,
SCALEUNIT["unity",1],
ID["EPSG",8805]],
PARAMETER["False easting",500000,
LENGTHUNIT["metre",1],
ID["EPSG",8806]],
PARAMETER["False northing",0,
LENGTHUNIT["metre",1],
ID["EPSG",8807]]],
CS[Cartesian,2],
AXIS["(E)",east,
ORDER[1],
LENGTHUNIT["metre",1]],
AXIS["(N)",north,
ORDER[2],
LENGTHUNIT["metre",1]],
AREA["World - N hemisphere - 6°E to 12°E - by country"],
BBOX[0,6,84,12],
ID["EPSG",32632]]
</verbatim></td>
</tr>
</table>
<br>
As you can easily notice, the two notations are profoundly different.
The old <b>proj-string</b> notation is extremely concise and rough, whilst the new <b>ISO-WKT</b> is verbose but exhaustive, detailed and precise.<br>
There is no possible match: ISO-WKT is clearly superior and more sophisticated under any possible aspect.<br>
Not at all surprisingly, coordinate transformations based on ISO-WKT definitions (instead of proj-strings) are usually expected to be more accurate.<br><br>
And that's not all; the old <b>proj-strings</b> weren't formally defined by any standard, and only PROJ, GDAL and few other FLOSS / GFOSS implementations can understand them.<br>
At the opposite, the new <b>ISO-WKT</b> is formally defined by an international standard, and many free and proprietary implementations can understand it.<br><br>
<table cellspacing="8" cellpadding="16" bgcolor="#ffffe9">
<tr><td>
<b><u>Important notice</u></b>: there are several dialects in the WKT notation describing CRSes.<br>
All them share the same common core and mainly differ in few minor details.<br>
PROJ.6 can understand the following dialects:
<ol>
<li><b>ESRI WKT</b>: a dialect widely adopted by ESRI proprietary software.</li>
<li><b>GDAL WKT1</b>: a dialect historically supported by the open source GDAL library.</li>
<li><b>WKT2:2015</b>: as defined by <b>ISO 19162:2015</b> standard specifications.</li>
<li><b>WKT2:2018</b>: as defined by <b>ISO 19162:2018</b> standard specifications.</li>
</ol>
</td></tr>
</table><br>
<h3>Transformation pipelines</h3>
There is a second astonishing improvement supported by PROJ.6, that are <b><i>transformation pipelines</i></b>.<br>
When using a <b><i>pipeline</i></b> you can freely define any complex geodetic transformation by chaining together many elementary steps such as conversion, transformation, projection, axis swap and so on.<br>
A pipeline is conceptually similar to a UNIX shell script, with a dataflow regularly proceding forward from step to step until producing the final result.<br>
The following is a practial example of a pipeline corresponding to a transformation from <b>EPSG:4326</b> <i>WGS 84</i> to <b>EPSG:32632</b> <i>WGS 84 / UTM zone 32N</i>:
<verbatim>
+proj=pipeline
+step +proj=axisswap +order=2,1
+step +proj=unitconvert +xy_in=deg +xy_out=rad
+step +proj=utm +zone=32 +ellps=WGS84
</verbatim>
<table cellspacing="8" cellpadding="16" bgcolor="#ffffd0">
<tr><td>
<b><u>Useful hint</u></b>: PROJ.6 supports a new CLI tool (<b>projinfo</b>) for inspecting in full detail the internal definitions of CRSes, Transformations etc.<br>
The above pipeline is simply the output of the following command:
<verbatim>
projinfo -s EPSG:4326 -t EPSG:32632 -o proj
</verbatim>
<b>projinfo</b> is a very precious resource; don't esitate to frequently use it in order to discover what's really happening behind the scenes.<br>
It's the best and easiest way for fully understanting how PROJ.6 do really works.
</td></tr>
</table><br>
<h3>The private SQLite database supporting PROJ.6</h3>
Starting since <b>PROJ.6</b> the PROJ library requires an external SQLite database containing all definitions about supported CRSes, Ellipsoids, Prime Meridians, Units of Measure, Transformations and alike.<br>
Many of the new advanced PROJ's API will fail if such database is not available at run time.
<br><br>
<table cellspacing="8" cellpadding="8" bgcolor="#ffffe9">
<tr><th>
In order to learn more about the many interesting cool new features supported by PROJ.6 please consult the <a href="https://proj4.org/">original documentation</a>
</th></tr>
</table><br>
<hr>
<h1>SpatiaLite-5.0.0 supporting PROJ.6</h1>
<h3>Existing SQL functions affected by PROJ.6</h3>
<table cellspacing="8" cellpadding="8" bgcolor="#e8ffe8" border="1">
<tr><th bgcolor="#ffb03e">SQL Function</th><th bgcolor="#ffb03e">Extended signature</th><th bgcolor="#ffb03e">Behavior under PROJ.6</th></tr>
<tr><td><b>ST_Transform()</b></td>
<td>
<b>ST_Transform</b> ( geom <i>Geometry</i> , newSrid <i>Integer</i> , area <i>Geometry</i> ) : <i>Geometry</i><hr>
<b>ST_Transform</b> ( geom <i>Geometry</i> , newSrid <i>Integer</i> , area <i>Geometry</i> , method <i>Text</i> ) : <i>Geometry</i><hr>
<b>ST_Transform</b> ( geom <i>Geometry</i> , newSrid <i>Integer</i> , area <i>Geometry</i> , method <i>Text</i> , proj_string <i>Text</i> ) : <i>Geometry</i>
</td>
<td>
<table cellspacing="4" cellpadding="4" bgcolor="#ffffd0">
<tr><td>
<b><u><i>Note</i></u></b>: all these <b><i>extended signatures</i></b> are supported only when <b>libspatialite-5.0</b> has been built on the top of <b>PROJ.6</b><br>
If the library has been built instead on earlier versions of PROJ any attempt to call these extended signatures will just return a <b><i>wrong number of arguments to function ST_Transform()</i></b> error.
</td><tr>
</table><br>
<table cellspacing="4" cellpadding="4" bgcolor="#ffdfd0">
<tr><td>
Any invalid argument passed to <b>ST_Transform()</b> (<b><i>extended signatures</i></b>) will raise an <b>SQL Exception</b>.
</td><tr>
</table><br>
<ul>
<li>the optional argument <b>area</b> may be <b>NULL</b> (<i>default setting</i>).<br>
Otherwise it's expected to contain a valid Geometry in <b>SRID=4326 (long/lat)</b>.
When an <b><i>area of use</i></b> is explicitly supplied, then <b>PROJ.6</b> may eventually use the corresponding <b>BBOX</b> for finely tuning the more accurate transformation.</li>
<li>the optional argument <b>method</b> is expected to contain one the following values (<b>auth_name:auth_strid</b> will be always assumed as the <i>default setting</i>):</li>
<ul>
<li><b>proj4text</b>: both CRSes (origin and destination) will be defined by passing to PROJ.6 the traditionals <b>proj-string</b> definitions for the corresponding SRIDs retrieved from column <b>proj4text</b> in Table <b>spatial_ref_sys</b><br>
This exactly corresponds to the well extablished traditional behavior of all previous versions of <b>libspatialite</b> and still continues to be supported mainly for historical compatibility, but <b><u><i>isn't any longer the best way for taking full profit of the more advanced capabilities of PROJ.6</i></u></b></li>
<li><b>srtext</b>: both CRSes (origin and destination) will be defined by passing to PROJ.6 the <b>WKT</b> definitions for the corresponding SRIDs retrieved from column <b>srtext</b> in Table <b>spatial_ref_sys</b><br>
<b><u><i>Note</i></u></b>: this method could effectively take full profit of the more advanced capabilities of PROJ.6, but only if the underlaying SpatiaLite database has been created with PROJ.6 support.
But it could easily be inadequate when the underlaying SpatiaLite database was created by some earlier version lacking PROJ.6 support.</li>
<li><b>auth_name:auth_srid</b>: both CRSes (origin and destination) will be defined by ignoring the definitions stored in <b>spatial_ref_sys</b> and leaving PROJ.6 free to retrieve their corresponding definitions from its own private SQLite database.<br>
<b><u><i>Note</i></u></b>: this method will always take full profit of the more advanced capabilities of PROJ.6, even when using some SpatiaLite database created by earlier versions not yet supporting PROJ.6</li>
<li><b>proj_string</b>: an <b><i>user-defined proj-string</i></b> (may be one definining a <b><i>transformation pipeline</i></b>) will be passed to PROJ.6; this is an advanced option reserved to skilled power users.</li>
</ul></li>
<li>the optional argument <b>proj_string</b> may be <b>NULL</b> (<i>default setting</i>).<br>
Otherwise it's expected to contain a valid <b>PROJ.6 <i>transformation string</i></b>, may well be corresponding to an <b><i>user-defined transformation pipeline</i></b>.
Meaningful only in the case of <b>method=proj_string</b></li>
</ul>
</td></tr>
<tr><td><b>InitSpatialMetaData()</b><hr>
<b>InitSpatialMetaDataFull()</b><hr>
<b>InsertEpsgSRID()</td><td align="center"><b>unchanged</b></td>
<td>
All these SQL Functions doesn't change their signatures, but behave in a significantly different way when <b>PROJ.6</b> support is available.
<ul>
<li>traditional behavior on old <b>PROJ.4</b>: the <b>spatial_ref_sys</b> metadata Table will be populated by using the CRSes definitions internally inlined within the code of <b>libspatialite</b>.</li>
<li>new behavior on <b>PROJ.6</b>: the <b>spatial_ref_sys</b> metadata Table will be populated by inserting the CRSes definitions extracted from the SQLite private database currently connected to PROJ.6; more precisely, column <b>proj4text</b> will be populated by inserting the new <b>proj-strings</b> as supported by PROJ.6, whilst column <b>srtext</b> will be populated by inserting the <b>ISO-2018 WKT</b> definitions as supported by PROJ.6<br>
<u><b><i>Important consequence</i></b></u>: if there is no database currently connected to PROJ.6 the initialization of <b>spatial_ref_sys</b> will fail.</li>
</ul>
</td></tr>
</table><br>
Few practical SQL examples:
<verbatim>
-- to EPSG:3003 - default settings; ignoring spatialite_ref_sys and using the PROJ.6 own private database
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056 , 4326 ) , 3003 ));
-------------------------------------
SRID=3003;POINT(1732852.942716769 4816277.617690674)
-- to EPSG:3003 - NULL area of use, using ISO-2018 WKT definitions from spatial_ref_sys.srtext
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056, 4326 ) , 3003 , NULL , 'srtext' ));
-------------------------------------
SRID=3003;POINT(1732852.942716769 4816277.617690674)
-- to EPSG:3003 - NULL area of use, using proj-string definitions from spatial_ref_sys.proj4text
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056, 4326 ) , 3003 , NULL , 'proj4text' ));
-------------------------------------
SRID=3003;POINT(1732832.44489238 4816350.146246414)
-- to EPSG:32632 - default settings; ignoring spatialite_ref_sys and using the PROJ.6 own private database
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056 , 4326 ), 32632 ));
-------------------------------------
SRID=32632;POINT(732821.7184751123 4816262.631245253)
-- to EPSG:32632 - NULL area of use, using ISO-2018 WKT definitions from spatial_ref_sys.srtext
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056 , 4326 ) , 32632 , NULL , 'srtext' ));
-------------------------------------
SRID=32632;POINT(732821.7184751123 4816262.631245253)
-- to EPSG:32632 - NULL area of use, using proj-string definitions from spatial_ref_sys.proj4text
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056, 4326 ) , 32632 , NULL , 'proj4text' ));
-------------------------------------
SRID=32632;POINT(732821.7184751123 4816262.631245253)
</verbatim>
This first test is based on a new SpatiaLite database created with full PROJ.6 support. As you can easily notice:
<ul>
<li>the last transformation from SRID=4326 to SRID=3003 based on traditional <b>proj-strings</b> retrieved from <b>spatial_ref_sys.proj4text</b> rather surprisingly significantly differs from the first two results.<br>
there is an impressive distance of about <b>75m</b> between the two reprojected points.</li>
<li>but all transformations from SRID=4326 to SRID=32632 return identical results.</li>
<li>this is a direct confirmation that still continuing to use the traditional approach of transformations driven by proj-strings <b><u><i>definitely isn't the optimal method for using PROJ.6</i></u></b></li>
</ul><br>
<verbatim>
-- to EPSG:3003 - default settings; ignoring spatialite_ref_sys and using the PROJ.6 own private database
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056 , 4326 ) , 3003 ));
-------------------------------------
SRID=3003;POINT(1732852.942716769 4816277.617690674)
-- to EPSG:3003 - NULL area of use, using ISO-2018 WKT definitions from spatial_ref_sys.srtext
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056 , 4326 ) , 3003 , NULL , 'srtext' ));
-------------------------------------
SRID=3003;POINT(1732852.942716769 4816277.617690674)
-- to EPSG:3003 - NULL area of use, using proj-string definitions from spatial_ref_sys.proj4text
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056, 4326 ) , 3003 , NULL , 'proj4text' ));
-------------------------------------
SRID=3003;POINT(1732852.942716769 4816277.617690674)
-- to EPSG:32632 - default settings; ignoring spatialite_ref_sys and using the PROJ.6 own private database
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056, 4326 ) , 32632 ));
-------------------------------------
SRID=32632;POINT(732821.7184751123 4816262.631245253)
-- to EPSG:32632 - NULL area of use, using ISO-2018 WKT definitions from spatial_ref_sys.srtext
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056, 4326 ) , 32632 , NULL , 'srtext' ));
-------------------------------------
SRID=32632;POINT(732821.7184751123 4816262.631245253)
-- to EPSG:32632 - NULL area of use, using proj-string definitions from spatial_ref_sys.proj4text
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056, 4326 ) , 32632 , NULL , 'proj4text' ));
-------------------------------------
SRID=32632;POINT(732821.7184751123 4816262.631245253)
</verbatim>
This second test is based instead on a legacy SpatiaLite database created by some earlier version lacking PROJ.6 support.<br>
In this specific case there is no difference in the results returned by different methods.<br><br>
<b><u>Mistery unveiled</u></b>: just a quick glance to the old and new <b>proj-strings</b>:
<ul>
<li>SRID=3003 proj-string as defined by old PROJ.4:
<ul>
<li><b>+proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl +towgs84=-104.1,-49.1,-9.9,0.971,-2.917,0.714,-11.68 +units=m +no_defs</b></li>
</ul></li>
<li>SRID=3003 proj-string as defined by new PROJ.6:
<ul>
<li><b>+proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl +units=m +no_defs +type=crs</b></li>
</ul></li>
As you can easily notice, there is no <b>+towgs84</b> term defined in new PROJ.6, and this fully explains all.
</ul><br>
<verbatim>
-- to EPSG:3003 - using a transformation pipeline
SELECT AsEWKT ( ST_Transform( SwapCoords ( MakePoint( 11.878056 , 43.463056, 4326 ) ) , 3003 , NULL , 'proj_string' ,
'+proj=pipeline
+step +proj=axisswap +order=2,1
+step +proj=unitconvert +xy_in=deg +xy_out=rad
+step +proj=push +v_3
+step +proj=cart +ellps=WGS84
+step +inv +proj=helmert +x=-104.1 +y=-49.1 +z=-9.9 +rx=0.971 +ry=-2.917 +rz=0.714 +s=-11.68 +convention=position_vector
+step +inv +proj=cart +ellps=intl
+step +proj=pop +v_3
+step +proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl' ));
-------------------------------------
SRID=3003;POINT(1732852.942716769 4816277.617690674)
-- to EPSG:3003 - using a customized transformation pipeline
SELECT AsEWKT ( ST_Transform( MakePoint( 11.878056 , 43.463056, 4326 ) , 3003 , NULL , 'proj_string' ,
'+proj=pipeline
+step +proj=unitconvert +xy_in=deg +xy_out=rad
+step +proj=push +v_3
+step +proj=cart +ellps=WGS84
+step +inv +proj=helmert +x=-104.1 +y=-49.1 +z=-9.9 +rx=0.971 +ry=-2.917 +rz=0.714 +s=-11.68 +convention=position_vector
+step +inv +proj=cart +ellps=intl
+step +proj=pop +v_3
+step +proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl' ));
-------------------------------------
SRID=3003;POINT(1732852.942716769 4816277.617690674)
</verbatim>
This third test is based on using <b><i>transformation pipelines</i></b>:
<ul>
<li>the first query directly uses a proj-string representing the pipeline as defined by executing<br>
<b>projinfo -s EPSG:4326 -t EPSG:3003 --area "Italy - mainland" -o proj</b><br>
(we'll see this topic in more depth on the next paragraph)</li>
<li>the second query is just a small adaptation of the first one:
<ul>
<li>As you can notice the first query requires calling <b>SwapCoodinates()</b> because the first step of the pipeline has an <b>axisswap</b> directive.</li>
<li>The second query just avoids to call <b>SwapCoords()</b> and consequently the trasformation pipeline step removes this first step so to get the same identical overall effect.</li>
</ul></li>
<li><b><u>Note</u></b>: SpatiaLite will always do a best effort in order to guess if swapping the coordinates before passing them to PROJ.6 is required or not.<br>
But in the specific case of a transformation pipeline this test may easily fail, thus requiring to explicitly call <b>SwapCoords()</b></li>
</ul><br>
<table cellspacing="8" cellpadding="16" bgcolor="#c9fff0">
<tr><td>
<h3>using projinfo for detecting transformation pipelines and supported areas of use</h3>
<verbatim>
projinfo -s EPSG:4326 -t EPSG:3003 -o proj --spatial-test intersect
Candidate operations found: 3
-------------------------------------
Operation n°1:
unknown id, Inverse of Monte Mario to WGS 84 (4) + Italy zone 1, 4 m, Italy - mainland
PROJ string:
+proj=pipeline
+step +proj=axisswap +order=2,1
+step +proj=unitconvert +xy_in=deg +xy_out=rad
+step +proj=push +v_3
+step +proj=cart +ellps=WGS84
+step +inv +proj=helmert +x=-104.1 +y=-49.1 +z=-9.9 +rx=0.971 +ry=-2.917 +rz=0.714 +s=-11.68 +convention=position_vector
+step +inv +proj=cart +ellps=intl
+step +proj=pop +v_3
+step +proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl
-------------------------------------
Operation n°2:
unknown id, Inverse of Monte Mario to WGS 84 (2) + Italy zone 1, 4 m, Italy - Sardinia onshore
PROJ string:
+proj=pipeline
+step +proj=axisswap +order=2,1
+step +proj=unitconvert +xy_in=deg +xy_out=rad
+step +proj=push +v_3
+step +proj=cart +ellps=WGS84
+step +inv +proj=helmert +x=-168.6 +y=-34 +z=38.6 +rx=-0.374 +ry=-0.679 +rz=-1.379 +s=-9.48 +convention=position_vector
+step +inv +proj=cart +ellps=intl
+step +proj=pop +v_3
+step +proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl
-------------------------------------
Operation n°3:
unknown id, Inverse of Monte Mario to WGS 84 (11) + Italy zone 1, 10 m, Italy - Sicily Strait west of 13°E
PROJ string:
+proj=pipeline
+step +proj=axisswap +order=2,1
+step +proj=unitconvert +xy_in=deg +xy_out=rad
+step +proj=push +v_3
+step +proj=cart +ellps=WGS84
+step +proj=helmert +x=230.47 +y=56.08 +z=-22.43
+step +inv +proj=cart +ellps=intl
+step +proj=pop +v_3
+step +proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl
</verbatim>
</td></tr>
</table><br>
<verbatim>
-- to EPSG:3003 - default settings; ignoring spatialite_ref_sys and using the PROJ.6 own private database
SELECT AsEWKT ( ST_Transform( MakePoint( 9.169464, 39.478275, 4326 ), 3003 ));
-------------------------------------
SRID=3003;POINT(1514600.134321862 4369874.489269957)
-- to EPSG:3003 - same as above, but explicitly defining a specific area of use
SELECT AsEWKT ( ST_Transform( MakePoint( 9.169464, 39.478275, 4326 ), 3003 , BuildMBR(9.1 , 39.4 , 9.2 , 39.5 , 4326 )));
-------------------------------------
SRID=3003;POINT(1514605.982762248 4369873.004226943)
</verbatim>
Fourth and last example. In some cases explicitly defining a specific <b><i>area of use</i></b> may enable PROJ.6 to select an optimized transformation leading to more precise results.<br>
In this example we've used a Point located in Sardinia, and PROJ.6 supports several flavors of <b>EPSG:3003</b> depending on the specific area of use.<br>
<b>Italy - Sardinia onshore</b> is one between them, so after specifying an explicit <b>area of use</b> a more precise transformation pipeline was selected.<br><br>
<table cellspacing="8" cellpadding="16" bgcolor="#ffffd0">
<tr><td>
<b><u>Lesson learned</u></b>:
<ul>
<li>The best mode for taking full profit from PROJ.6 is by using <i>method</i>=<b>auth_name:auth_srid</b> (that is the <b><i>default setting</i></b>).<br>
This way you'll be absolutely sure that the most recent and fully detailed definitions will be always retrieved from the PROJ.6 own database completely ignoring any definition (may be incomplete or obsolete) eventually stored into the <b>spatial_ref_sys</b> table.
This is a particulary useful option when processing older databases being created by earlier versions of SpatiaLite not yet supporting PROJ.6</li>
<li>SpatiaLite does not constraints you in any way and fully respects users freedom carefully avoiding <i>auto-magical</i> assumptions.<br>
If you have any good reason suggesting to do such a thing you are anyway free to use the proj-strings (<i>method</i>=<b>proj4text</b>) or the WKT definitions (<i>method</i>=<b>srtext</b>) stored into the <b>spatial_ref_sys</b> table.<br>
But this is under your full responsibility, and you must be well sure of what are you doing.</li>
<li>SpatiaLite encourages and promotes the most creative uses of PROJ.6, this including <b><i>transformation pipelines</i></b>.<br>
Correctly using <i>method</i>=<b>proj_string</b> for computing custom transformations isn't necessarily simple and easy, but it's a big opportunity for all skilled and talented power users.</li>
</ul>
</td></tr>
</table><br>
<h3>New auxiliary SQL functions specifically supporting PROJ.6</h3>
<table cellspacing="8" cellpadding="8" bgcolor="#e8ffe8" border="1">
<tr><th bgcolor="#ffb03e">SQL Function</th><th bgcolor="#ffb03e">Supported arguments</th><th bgcolor="#ffb03e">Description</th></tr>
<tr><td><b>HasProj6</b>( <i>void</i> ) : <i>Boolean</i></td>
<td>None</td>
<td>Will return <b>1</b> (<b>TRUE</b>) if the library has been built on <b>PROJ.6</b> (or any later version), otherwise <b>0</b> (<b>FALSE</b>).</td></tr>
<tr><td><b>PROJ_GetLastErrorMsg</b>( <i>void</i> ) : <i>String</i></td>
<td>None</td>
<td>Will return the most recent error message returned by PROJ (if any).<br>
<b>NULL</b> will be returned if there is no curently pending PROJ error.</td></tr>
<tr><td><b>PROJ_GetDatabasePath</b>( <i>void</i> : <i>String</i>)</td>
<td>None</td>
<td>Will return the currently set pathname leading to the private PROJ's SQLite database.<br>
<b>NULL</b> will be returned if there is no private PROJ's SQLite database currently connected.</td></tr>
<tr><td><b>PROJ_SetDatabasePath</b> ( new_path <i>String</i> ) : <i>String</i></td>
<td>
<ul>
<li><b>new_path</b>: a relative or absolute pathname leading to a valid PROJ's SQLite database.</li>
</ul></td>
<td>Will change the currently set pathname leading to the private PROJ's SQLite database.<br>
<b>NULL</b> will be returned if the passed path is invalid, otherwise the path of the currently set private PROJ's SQLite database will be returned.</td></tr>
<tr><td><b>PROJ_AsWKT</b> ( auth_name <i>String</i> , auth_srid <i>Integer</i> ) : <i>String</i><hr>
<b>PROJ_AsWKT</b> ( auth_name <i>String</i> , auth_srid <i>Integer</i> , wkt_style <i>String</i> ) : <i>String</i><hr>
<b>PROJ_AsWKT</b> ( auth_name <i>String</i> , auth_srid <i>Integer</i> , wkt_style <i>String</i> , indented <i>Boolean</i> ) : <i>String</i><hr>
<b>PROJ_AsWKT</b> ( auth_name <i>String</i> , auth_srid <i>Integer</i> , wkt_style <i>String</i> , indented <i>Boolean</i> , indentation <i>Integer</i> ) : <i>String</i></td>
<td><ul>
<li><b>auth_name</b> and <b>auth_srid</b> identify the intended CRS.<br>
<b>auth_name</b> can be <b>NULL</b>, and in this case <b>EPSG</b> will be assumed.</li>
<li>the optional argument <b>style</b> determines which specific WKT format should be adopted, and must be one between <b>GDAL</b>, <b>ESRI</b>, <b>ISO-2015</b> or <b>ISO-2018</b> (this latter being the default setting).</li>
<li>the optional argument <b>indented</b> if set to <b>TRUE</b> will nicely format a multiline WKT expression, otherwise a single monolithic line lacking any white-space or new-line will be printed (the default is <b>TRUE</b>).</li>
<li>the optional argument <b>indentation</b> determines how many white-spaces are to be used for indenting (only meaningful if <b><i>indented=TRUE</i></b>; the default values is <b>4</b>).</li>
</ul></td>
<td>Will return the WKT expression corresponding to a given CRS; the definitions will be taken directly from the private PROJ's own database.<br>
<b>NULL</b> will be returned on failure or on invalid arguments.</td></tr>
<tr><td><b>PROJ_GuessSridFromWKT</b> ( wkt_expr <i>String</i> ) : <i>Integer</i></td>
<td><ul>
<li><b>wkt_expr</b>: the WKT expression to be evaluated.</li>
</ul></td>
<td>
Will possibly return the <b>SRID value</b> corresponding to a given WKT expression defining a CRS.<br>
<b>-1</b> will be returned if no CRS supported by PROJ.6 matches the WKT expression.<br>
<b>NULL</b> will be returned on invalid argument.
</td></tr>
<tr><td><b>PROJ_GuessSridFromSHP</b> ( filename <i>String</i> ) : <i>Integer</i></td>
<td><ul>
<li><b>filename</b>: the absolute or relative path leading to some Shapefile.<br>
Note: exactley as required by <b><i>ImportSHP</i></b>() <b><i>filename</i></b> must omit any <b>.shp</b>, <b>.shx</b>, <b>.dbf</b> or <b>.prj</b> suffix.</li>
</ul></td>
<td>
Will possibly return the <b>SRID value</b> corresponding to the CRS defined by the .PRJ member of the Shapefile.<br>
<b>-1</b> will be returned if no CRS supported by PROJ.6 matches PRJ member of the Shapefile.<br>
<b>NULL</b> will be returned on invalid argument.<hr>
<u>Please note well</u>: this SQL function opend the door to many potential security issues, and thus is always <i>disabled by default</i>.<br>
Explicitly setting the environment variable <b>SPATIALITE_SECURITY=relaxed</b> is absolutely required in order to enable this function.
</td></tr>
</table><br>
<table cellspacing="8" cellpadding="16" bgcolor="#ffffe9">
<tr><td>
<b><u>Note</u></b>: all the above SQL Functions will be available only when Spatialite-5.0.0 has been built against <b>PROJ.6</b> (or any subsequent version).<br>
If SpatiaLite-5.0.0 has been built instead against any previosus version (as e.g. <b>PROJ.4</b>) any attempt to call one of these SQL Functions will simply return a <b><i><u>no such function</u></i></b> SQL error.
</td></tr>
</table><br>
<b>Practical examples:</b>
<verbatim>
SELECT PROJ_GetDatabasePath(); -- retrieving the currently set PROJ's own database
------------------------------
/usr/local/share/proj/proj.db
SELECT PROJ_SetDatabasePath('/home/sandro/not_existing_proj.db'); -- non existing database
------------------------------
NULL
SELECT PROJ_GetLastErrorMsg(); -- retrieving the failure cause
------------------------------
proj_context_set_database_path: Open of /home/sandro/not_existing_proj.db failed
SELECT PROJ_SetDatabasePath('/home/sandro/valid_proj.db'); -- valid database
------------------------------
/home/sandro/valid_proj.db
SELECT PROJ_AsWKT('EPSG', 4326); -- default settings: ISO-2018 style, indented with indentation 4
------------------------------
GEODCRS["WGS 84",
DATUM["World Geodetic System 1984",
ELLIPSOID["WGS 84",6378137,298.257223563,
LENGTHUNIT["metre",1]]],
PRIMEM["Greenwich",0,
ANGLEUNIT["degree",0.0174532925199433]],
CS[ellipsoidal,2],
AXIS["geodetic latitude (Lat)",north,
ORDER[1],
ANGLEUNIT["degree",0.0174532925199433]],
AXIS["geodetic longitude (Lon)",east,
ORDER[2],
ANGLEUNIT["degree",0.0174532925199433]],
AREA["World"],
BBOX[-90,-180,90,180],
ID["EPSG",4326]]
SELECT PROJ_AsWKT('EPSG', 4326, 'ESRI', 0, 0); -- ESRI style, monolithic line
------------------------------
GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]]
SELECT PROJ_GuessSridFromWKT('GEOGCS["GCS_Monte_Mario_Rome",DATUM["D_Monte_Mario",SPHEROID["International_1924",6378388.0,297.0]],PRIMEM["Rome",12.4523333333333],UNIT["Degree",0.0174532925199433]]');
------------------------------
4806
SELECT PROJ_GuessSridFromSHP('/home/sandro/tuscany_shp/prov2011'); -- remember: requires to explicitly set SPATIALITE_SECURITY=relaxed
------------------------------
3003
</verbatim>
<br>
<hr><br>
<table cellspacing="8" cellpadding="8" bgcolor="#ffe0e9" width="100%">
<tr><th>
<h1>Important notice for Windows users</h1>
</th></tr>
<tr><td>
<b>PROJ.6</b> critically depends on its own private SQLite database (<b>proj.db</b>) containing all relevant definitions about Ellipsoids, Prime Meridians, CRSes, Transformations and alike.<br>
If PROJ.6 is unable to correctly establish a connection to this database it will be severely limited and will not be able to correctly behave as expected.<br><br>
<ul>
<li><b><u><i>Short conclusion</i></u></b>: installing the software alone is not enough.<br>
The PROJ.6 private database <b>proj.db</b> must be properly installed as well, in order to ensure that anything runs smoothly.</li>
</ul><br>
This isn't usually a big issue on Linux and Unix-like platforms, where a rational and very clear filesystem layout exists.<br>
On these operating systems the package manager (or <b>make install</b>) will automatically take care to install <b>proj.db</b> on the most appropriate directory (usually as <b>/usr/share/proj/proj.db</b> or as <b>/usr/local/share/proj/proj.db</b>) and that's all.<br><br>
Things are unhappily a little bit more difficults on Windows platforms.
The user itself is responsible for properly installing <b>proj.db</b>
So it becomes critical understanding the basic rules adopted by <b>libspatialite</b> in order to properly locate <b>proj.db</b> on Windows.
</td></tr>
<tr><th>
<h2>Where proj.db is expected to be found on Windows</h2>
</td></tr>
<tr><td>
<ol>
<li>the first place where <b>proj.db</b> will be searched is the same folder form where the <b>EXE</b> binary was initially loaded.<br>
<i><u>Example</i></u>: assuming that you are currently executing <b>C:\myprogs\spatialite\bin\spatialite.exe</b>
<ul>
<li>then an attempt will be made to connect <b>C:\myprogs\spatialite\bin\proj.db</b></li>
</ul></li>
<li>a second attempt will be made on behalf of the <b>Public</b> folder.<br>
<i><u>Example</u></i>: an attempt will be made to connect <b>C:\Users\Public\spatialite\proj\proj.db</b></li>
<li>a third (and last) attempt will be made on behalf of the <b>User</b> folder.<br>
<i><u>Example</i></u>: an attempt will be made to connect <b>C:\Users\sandro\spatialite\proj\proj.db</b></li>
</ol>
<h3>An useful diagnostic check</h3>
<verbatim>
SELECT PROJ_GetDatabasePath();
</verbatim>
<ul>
<li>if <b>NULL</b> is returned, then PROJ.6 is definitely unable to connect to its own private SQLite database <b>proj.db</b><br>
You have to carefully verifiy that it's really installed on one of the expected standard locations.</li>
<li>otherwise the path leading to the currently connected <b>proj.db</b> will be returned.</li>
</ul><br>
</td></tr>
</table><br><br>
<table cellspacing="8" cellpadding="8" bgcolor="#c9fff0" width="100%">
<tr><th>
<h2>Using the environment variable SPATIALITE_PROJ_DB_PATH</h2>
</th></tr>
<tr><td>
If the environment variable <b>SPATIALITE_PROJ_DB_PATH</b> is set, then <b>libspatialite</b> will simply attempt to connect the database pointed by this variable.<br>
Such a capability is supported not only on Windows but also on Linux (and on any other platform).<br><br>
<i><u>Linux example</u></i>:
<ul>
<li><b>export "SPATIALITE_PROJ_DB_PATH=/home/sandro/aux/proj.db"<br>
echo $SPATIALITE_PROJ_DB_PATH<br>
spatialite<b></li>
</ul><br><br>
<i><u>Windows example</u></i>:
<ul>
<li><b>SET SPATIALITE_PROJ_DB_PATH=C:\Users\sandro\aux\proj.db<br>
echo %SPATIALITE_PROJ_DB_PATH%<br>
spatialite_gui<b></li>
</ul><br><br>
</th></tr>
</table><br>
<hr><br>
<a href="https://www.gaia-gis.it/fossil/libspatialite/wiki?name=4.3.0-doc">back</a>
Z db2503575ea1000d098afca3a61ae256