diff options
Diffstat (limited to '_sources')
243 files changed, 26763 insertions, 0 deletions
diff --git a/_sources/about.rst.txt b/_sources/about.rst.txt new file mode 100644 index 00000000..f30d517b --- /dev/null +++ b/_sources/about.rst.txt @@ -0,0 +1,29 @@ +############################################################################### +About +############################################################################### + +.. include:: about_core.rst + +.. image:: ../images/OSGeo_project.png + :scale: 30 % + :alt: OSGeo Project + +Citation +------------------------------------------------------------------------------- + + +.. include:: ../../CITATION + + +.. _license: + +License +------------------------------------------------------------------------------- + +PROJ uses the MIT license. The software was initially released by the USGS in +the public domain. When Frank Warmerdam took over the development of PROJ it +was moved under the MIT license. The full text of the license follows, and can +also be found in the file ``COPYING``, at the top level of the source +distribution package. + +.. literalinclude:: ../../COPYING diff --git a/_sources/about_core.rst.txt b/_sources/about_core.rst.txt new file mode 100644 index 00000000..5f4238bc --- /dev/null +++ b/_sources/about_core.rst.txt @@ -0,0 +1,18 @@ +PROJ is a generic coordinate transformation software that transforms geospatial +coordinates from one coordinate reference system (CRS) to another. This +includes cartographic projections as well as geodetic transformations. PROJ +is released under the :ref:`X/MIT open source license <license>` + +PROJ includes :ref:`command line applications<apps>` for easy conversion of +coordinates from text files or directly from user input. In addition to the +command line utilities PROJ also exposes an +:ref:`application programming interface<reference>`, or API in short. The API +lets developers use the functionality of PROJ in their own software without having +to implement similar functionality themselves. + +PROJ started purely as a cartography application letting users convert geodetic +coordinates into projected coordinates using a number of different cartographic +projections. Over the years, as the need has become apparent, support for datum +shifts has slowly worked its way into PROJ as well. Today PROJ supports more +than a hundred different map projections and can transform coordinates between +datums using all but the most obscure geodetic techniques.
\ No newline at end of file diff --git a/_sources/apps/cct.rst.txt b/_sources/apps/cct.rst.txt new file mode 100644 index 00000000..08bdd004 --- /dev/null +++ b/_sources/apps/cct.rst.txt @@ -0,0 +1,245 @@ +.. _cct: + +================================================================================ +cct +================================================================================ + +.. Index:: cct + +.. only:: html + + Coordinate Conversion and Transformation. + +Synopsis +******** + + **cct** [**-cIostvz** [args]] *+opt[=arg]* ... file ... + +or + + **cct** [**-cIostvz** [args]] {object_definition} file ... + +Where {object_definition} is one of the possibilities accepted +by :c:func:`proj_create`, provided it expresses a coordinate operation + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:1671" "urn:ogc:def:coordinateOperation:EPSG::1671"), + - an object name. e.g. "ITRF2014 to ETRF2014 (1)". In that case as + uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match. + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") + - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.4/projjson.schema.json + + .. versionadded:: 8.0.0 + + .. note:: + + Before version 8.0.0 only proj-strings could be used to instantiate + operations in :program:`cct`. + + +or + + **cct** [**-cIostvz** [args]] {object_reference} file ... + +where {object_reference} is a filename preceded by the '@' character. The +file referenced by the {object_reference} must contain a valid +{object_definition}. + + .. versionadded:: 8.0.0 + + + +Description +*********** + +:program:`cct` is a 4D equivalent to the :program:`proj` projection program, +performs transformation coordinate systems on a set of input points. The +coordinate system transformation can include translation between projected +and geographic coordinates as well as the application of datum shifts. + + +The following control parameters can appear in any order: + +.. program:: cct + +.. option:: -c <x,y,z,t> + + Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4. + +.. option:: -d <n> + + .. versionadded:: 5.2.0 + + Specify the number of decimals in the output. + +.. option:: -I + + Do the inverse transformation. + +.. option:: -o <output file name>, --output=<output file name> + + Specify the name of the output file. + +.. option:: -t <time>, --time=<time> + + Specify a fixed observation *time* to be used for all input data. + +.. option:: -z <height>, --height=<height> + + Specify a fixed observation *height* to be used for all input data. + +.. option:: -s <n>, --skip-lines=<n> + + .. versionadded:: 5.1.0 + + Skip the first *n* lines of input. This applies to any kind of input, whether + it comes from ``STDIN``, a file or interactive user input. + +.. option:: -v, --verbose + + Write non-essential, but potentially useful, information to stderr. + Repeat for additional information (``-vv``, ``-vvv``, etc.) + +.. option:: --version + + Print version number. + +The *+opt* arguments are associated with coordinate operation parameters. +Usage varies with operation. + +.. only:: html + + For a complete description consult the :ref:`projection pages <projections>`. + + +:program:`cct` is an acronym meaning *Coordinate Conversion and Transformation*. + +The acronym refers to definitions given in the OGC 08-015r2/ISO-19111 +standard "Geographical Information -- Spatial Referencing by Coordinates", +which defines two different classes of *coordinate operations*: + +*Coordinate Conversions*, which are coordinate operations where input +and output datum are identical (e.g. conversion from geographical to +cartesian coordinates) and + +*Coordinate Transformations*, which are coordinate operations where +input and output datums differ (e.g. change of reference frame). + +Use of remote grids +******************* + +.. versionadded:: 7.0.0 + +If the :envvar:`PROJ_NETWORK` environment variable is set to ``ON``, +:program:`cct` will attempt to use remote grids stored on CDN (Content +Delivery Network) storage, when they are not available locally. + +More details are available in the :ref:`network` section. + +Examples +******** + +1. The operator specs describe the action to be performed by :program:`cct`. So + the following script + +.. code-block:: console + + echo 12 55 0 0 | cct +proj=utm +zone=32 +ellps=GRS80 + +will transform the input geographic coordinates into UTM zone 32 coordinates. +Hence, the command + +.. code-block:: console + + echo 12 55 | cct -z0 -t0 +proj=utm +zone=32 +ellps=GRS80 + +Should give results comparable to the classic :program:`proj` command + +.. code-block:: console + + echo 12 55 | proj +proj=utm +zone=32 +ellps=GRS80 + +2. Convert geographical input to UTM zone 32 on the GRS80 ellipsoid: + +.. code-block:: console + + cct +proj=utm +ellps=GRS80 +zone=32 + +3. Roundtrip accuracy check for the case above: + +.. code-block:: console + + cct +proj=pipeline +proj=utm +ellps=GRS80 +zone=32 +step +step +inv + +4. As (2) but specify input columns for longitude, latitude, height and time: + +.. code-block:: console + + cct -c 5,2,1,4 +proj=utm +ellps=GRS80 +zone=32 + +5. As (2) but specify fixed height and time, hence needing only 2 cols in + input: + +.. code-block:: console + + cct -t 0 -z 0 +proj=utm +ellps=GRS80 +zone=32 + +6. Auxiliary data following the coordinate input is forward to the output + stream: + +.. code-block:: console + + $ echo 12 56 100 2018.0 auxiliary data | cct +proj=merc + 1335833.8895 7522963.2411 100.0000 2018.0000 auxiliary data + +7. Coordinate operation referenced through its code + +.. code-block:: console + + $ echo 3541657.3778 948984.2343 5201383.5231 2020.5 | cct EPSG:8366 + 3541657.9112 948983.7503 5201383.2482 2020.5000 + +8. Coordinate operation referenced through its name + +.. code-block:: console + + $ echo 3541657.3778 948984.2343 5201383.5231 2020.5 | cct "ITRF2014 to ETRF2014 (1)" + 3541657.9112 948983.7503 5201383.2482 2020.5000 + +Background +********** + +:program:`cct` also refers to Carl Christian Tscherning (1942--2014), +professor of Geodesy at the University of Copenhagen, mentor and advisor +for a generation of Danish geodesists, colleague and collaborator for +two generations of global geodesists, Secretary General for the +International Association of Geodesy, IAG (1995--2007), fellow of the +American Geophysical Union (1991), recipient of the IAG Levallois Medal +(2007), the European Geosciences Union Vening Meinesz Medal (2008), and +of numerous other honours. + +*cct*, or Christian, as he was known to most of us, was recognized for his +good mood, his sharp wit, his tireless work, and his great commitment to +the development of geodesy -- both through his scientific contributions, +comprising more than 250 publications, and by his mentoring and teaching +of the next generations of geodesists. + +As Christian was an avid Fortran programmer, and a keen Unix connoisseur, +he would have enjoyed to know that his initials would be used to name a +modest Unix style transformation filter, hinting at the tireless aspect +of his personality, which was certainly one of the reasons he accomplished +so much, and meant so much to so many people. + +Hence, in honour of *cct* (the geodesist) this is :program:`cct` (the program). + + +.. only:: man + + See also + ******** + + **proj(1)**, **cs2cs(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/common_man.rst.txt b/_sources/apps/common_man.rst.txt new file mode 100644 index 00000000..28a39ba9 --- /dev/null +++ b/_sources/apps/common_man.rst.txt @@ -0,0 +1,12 @@ +.. only:: man + + Bugs + **** + + A list of known bugs can be found at https://github.com/OSGeo/PROJ/issues + where new bug reports can be submitted to. + + Home page + ********* + + https://proj.org/ diff --git a/_sources/apps/cs2cs.rst.txt b/_sources/apps/cs2cs.rst.txt new file mode 100644 index 00000000..841ce092 --- /dev/null +++ b/_sources/apps/cs2cs.rst.txt @@ -0,0 +1,320 @@ +.. _cs2cs: + +================================================================================ +cs2cs +================================================================================ + +.. only:: html + + Filter for transformations between two coordinate reference systems. + +Synopsis +******** + + | **cs2cs** [**-eEfIlrstvwW** [args]] + | [[--area <name_or_code>] | [--bbox <west_long,south_lat,east_long,north_lat>]] + | [--authority <name>] [--no-ballpark] [--accuracy <accuracy>] + | ([*+opt[=arg]* ...] [+to *+opt[=arg]* ...] | {source_crs} {target_crs}) + | file ... + + where {source_crs} or {target_crs} is one of the possibilities accepted + by :c:func:`proj_create`, provided it expresses a CRS + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671"), + - an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as + uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match. + - a OGC URN combining references for compound coordinate reference systems + (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated + syntax "EPSG:2393+5717"), + - a OGC URN combining references for references for projected or derived CRSs + e.g. for Projected 3D CRS "UTM zone 31N / WGS 84 (3D)": + "urn:ogc:def:crs,crs:EPSG::4979,cs:PROJ::ENh,coordinateOperation:EPSG::16031" + (*added in 6.2*) + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") + - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.4/projjson.schema.json (*added in 6.2*) + - a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (*added in 7.1*) + + .. versionadded:: 6.0.0 + + .. note:: before 7.0.1, it was needed to add +to between {source_crs} and {target_crs} + when adding a filename + +Description +*********** + +:program:`cs2cs` performs transformation between the source and destination +cartographic coordinate reference system on a set of input points. The coordinate +reference system transformation can include translation between projected and +geographic coordinates as well as the application of datum shifts. + +The following control parameters can appear in any order: + +.. program:: cs2cs + +.. option:: -I + + Method to specify inverse translation, convert from *+to* coordinate system to + the primary coordinate system defined. + +.. option:: -t<a> + + Where *a* specifies a character employed as the first character to denote a control + line to be passed through without processing. This option applicable to + ASCII input only. (# is the default value). + +.. option:: -d <n> + + .. versionadded:: 5.2.0 + + Specify the number of decimals in the output. + +.. option:: -e <string> + + Where *string* is an arbitrary string to be output if an error is detected during + data transformations. The default value is a three character string: ``*\t*``. + +.. option:: -E + + Causes the input coordinates to be copied to the output line prior to + printing the converted values. + +.. option:: -l<[=id]> + + List projection identifiers that can be selected with *+proj*. ``cs2cs -l=id`` + gives expanded description of projection *id*, e.g. ``cs2cs -l=merc``. + +.. option:: -lp + + List of all projection id that can be used with the *+proj* parameter. + Equivalent to ``cs2cs -l``. + +.. option:: -lP + + Expanded description of all projections that can be used with the *+proj* + parameter. + +.. option:: -le + + List of all ellipsoids that can be selected with the *+ellps* parameters. + +.. option:: -lu + + List of all distance units that can be selected with the *+units* parameter. + +.. option:: -r + + This options reverses the order of the first two expected + inputs from that specified by the CRS to the opposite + order. The third coordinate, typically height, remains + third. + +.. option:: -s + + This options reverses the order of the first two expected + outputs from that specified by the CRS to the opposite + order. The third coordinate, typically height, remains + third. + + +.. option:: -f <format> + + Where *format* is a printf format string to control the form of the output values. + For inverse projections, the output will be in degrees when this option is + employed. If a format is specified for inverse projection the output data + will be in decimal degrees. The default format is ``"%.2f"`` for forward + projection and DMS for inverse. + +.. option:: -w<n> + + Where *n* is the number of significant fractional digits to employ for seconds + output (when the option is not specified, ``-w3`` is assumed). + +.. option:: -W<n> + + Where *n* is the number of significant fractional digits to employ for seconds + output. When ``-W`` is employed the fields will be constant width + with leading zeroes. + +.. option:: -v + + Causes a listing of cartographic control parameters tested for and used by + the program to be printed prior to input data. + +.. option:: --area <name_or_code> + + .. versionadded:: 8.0.0 + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest can be specified either + as a name (e.g "Denmark - onshore") or a AUTHORITY:CODE (EPSG:3237) + + This option is mutually exclusive with :option:`--bbox`. + +.. option:: --bbox <west_long,south_lat,east_long,north_lat> + + .. versionadded:: 8.0.0 + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest is specified as a + bounding box with geographic coordinates, expressed in degrees in a + unspecified geographic CRS. + `west_long` and `east_long` should be in the [-180,180] range, and + `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than + `east_long`, except in the case where the area of interest crosses the antimeridian. + +.. option:: --no-ballpark + + .. versionadded:: 8.0.0 + + Disallow any coordinate operation that is, or contains, a + :term:`Ballpark transformation` + +.. option:: --accuracy <accuracy> + + .. versionadded:: 8.0.0 + + Sets the minimum desired accuracy for candidate coordinate operations. + +.. option:: --authority <name> + + .. versionadded:: 8.0.0 + + This option can be used to restrict the authority of coordinate operations + looked up in the database. When not specified, coordinate + operations from any authority will be searched, with the restrictions set + in the ``authority_to_authority_preference`` database table related to the authority + of the source/target CRS themselves. + If authority is set to ``any``, then coordinate operations from any authority will be searched + If authority is a non-empty string different of ``any``, then coordinate operations + will be searched only in that authority namespace (e.g ``EPSG``). + + This option is mutually exclusive with :option:`--bbox`. + +.. only:: man + + The *+opt* run-line arguments are associated with cartographic + parameters. + +.. only:: html + + The *+opt* run-line arguments are associated with cartographic + parameters. Usage varies with projection and for a complete description + consult the :ref:`projection pages <projections>`. + +The :program:`cs2cs` program requires two coordinate reference system (CRS) definitions. The first (or +primary is defined based on all projection parameters not appearing after the +*+to* argument. All projection parameters appearing after the *+to* argument +are considered the definition of the second CRS. If there is no +second CRS defined, a geographic CRS based on the +datum and ellipsoid of the source CRS is assumed. Note that the +source and destination CRS can both of same or different nature (geographic, +projected, compound CRS), or one of each and may have the same or different datums. + +When using a WKT definition or a AUTHORITY:CODE, the axis order of the CRS will +be enforced. So for example if using EPSG:4326, the first value expected (or +returned) will be a latitude. + +Internally, :program:`cs2cs` uses the :c:func:`proj_create_crs_to_crs` function +to compute the appropriate coordinate operation, so implementation details of +this function directly impact the results returned by the program. + +The environment parameter :envvar:`PROJ_LIB` establishes the +directory for resource files (database, datum shift grids, etc.) + +One or more files (processed in left to right order) specify the source of +data to be transformed. A ``-`` will specify the location of processing standard +input. If no files are specified, the input is assumed to be from stdin. +For input data the two data values must be in the first two white space +separated fields and when both input and output are ASCII all trailing portions +of the input line are appended to the output line. + +Input geographic data (longitude and latitude) must be in DMS or decimal +degrees format and input cartesian data must be in units consistent with the +ellipsoid major axis or sphere radius units. Output geographic coordinates will +normally be in DMS format (use ``-f %.12f`` for decimal degrees with 12 decimal +places), while projected (cartesian) coordinates will be in linear +(meter, feet) units. + +Use of remote grids +------------------- + +.. versionadded:: 7.0.0 + +If the :envvar:`PROJ_NETWORK` environment variable is set to ``ON``, +:program:`cs2cs` will attempt to use remote grids stored on CDN (Content +Delivery Network) storage, when they are not available locally. + +More details are available in the :ref:`network` section. + +Examples +******** + +Using PROJ strings +------------------ + +The following script + +:: + + cs2cs +proj=latlong +datum=NAD83 +to +proj=utm +zone=10 +datum=NAD27 -r <<EOF + 45°15'33.1" 111.5W + 45d15.551666667N -111d30 + +45.25919444444 111d30'000w + EOF + +will transform the input NAD83 geographic coordinates into NAD27 coordinates in +the UTM projection with zone 10 selected. The geographic values of this +example are equivalent and meant as examples of various forms of DMS input. +The x-y output data will appear as three lines of: + +:: + + 1402293.44 5076292.68 0.00 + + +Using EPSG CRS codes +-------------------- + +Transforming from WGS 84 latitude/longitude (in that order) to UTM Zone 31N/WGS 84 + +:: + + cs2cs EPSG:4326 EPSG:32631 <<EOF + 45N 2E + EOF + +outputs + +:: + + 421184.70 4983436.77 0.00 + +Using EPSG CRS names +-------------------- + +Transforming from WGS 84 latitude/longitude (in that order) with EGM96 height to +UTM Zone 31N/WGS 84 with WGS84 ellipsoidal height + +:: + + echo 45 2 0 | cs2cs "WGS 84 + EGM96 height" "WGS 84 / UTM zone 31N" + +outputs + +:: + + 421184.70 4983436.77 50.69 + + +.. only:: man + + See also + ******** + + **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/geod.rst.txt b/_sources/apps/geod.rst.txt new file mode 100644 index 00000000..7b8f921f --- /dev/null +++ b/_sources/apps/geod.rst.txt @@ -0,0 +1,203 @@ +.. _geod: + +================================================================================ +geod +================================================================================ + +Synopsis +******** + + **geod** *+ellps=<ellipse>* [**-afFIlptwW** [args]] [*+opt[=arg]* ...] file ... + + **invgeod** *+ellps=<ellipse>* [**-afFIlptwW** [args]] [*+opt[=arg]* ...] file ... + +Description +*********** + +:program:`geod` (direct) and :program:`invgeod` (inverse) perform geodesic +(Great Circle) computations for determining latitude, longitude and back +azimuth of a terminus point given a initial point latitude, longitude, +azimuth and distance (direct) or the forward and back azimuths and distance +between an initial and terminus point latitudes and longitudes (inverse). +The results are accurate to round off for :math:`|f| < 1/50`, where +:math:`f` is flattening. + + +:program:`invgeod` may not be available on all platforms; in this case +use :option:`geod -I` instead. + +The following command-line options can appear in any order: + + +.. program:: geod + + +.. option:: -I + + Specifies that the inverse geodesic computation is to be performed. May be + used with execution of :program:`geod` as an alternative to :program:`invgeod` execution. + +.. option:: -a + + Latitude and longitudes of the initial and terminal points, forward and + back azimuths and distance are output. + +.. option:: -t<a> + + Where *a* specifies a character employed as the first character to denote a control + line to be passed through without processing. + +.. option:: -le + + Gives a listing of all the ellipsoids that may be selected with the + *+ellps=* option. + +.. option:: -lu + + Gives a listing of all the units that may be selected with the *+units=* + option. (Default units are meters.) + +.. option:: -f <format> + + Where *format* is a printf format string to control the output form of the + geographic coordinate values. The default mode is DMS. + +.. option:: -F <format> + + Where *format* is a printf format string to control the output form of the distance + value. The default mode is ``"%.3f"``. + +.. option:: -w<n> + + Where *n* is the number of significant fractional digits to employ for seconds + output (when the option is not specified, ``-w3`` is assumed). + +.. option:: -W<n> + + Where *n* is the number of significant fractional digits to employ for seconds + output. When ``-W`` is employed the fields will be constant width + with leading zeroes. + +.. option:: -p + + This option causes the azimuthal values to be output as unsigned DMS + numbers between 0 and 360 degrees. Also note :option:`-f`. + +The *+opt* command-line options are associated with geodetic +parameters for specifying the ellipsoidal or sphere to use. +controls. The options are processed in left to right order +from the command line. Reentry of an option is ignored with +the first occurrence assumed to be the desired value. + +.. only:: html + + See :ref:`projections_intro` for full + list of these parameters and controls. + +.. only:: man + + See the PROJ documentation for a full list of these parameters and + controls. + +One or more files (processed in left to right order) specify +the source of data to be transformed. A ``-`` will specify the +location of processing standard input. If no files are specified, +the input is assumed to be from stdin. + +For direct determinations input data must be in latitude, longitude, +azimuth and distance order and output will be latitude, +longitude and back azimuth of the terminus point. Latitude, +longitude of the initial and terminus point are input for the +inverse mode and respective forward and back azimuth from the +initial and terminus points are output along with the distance +between the points. + +Input geographic coordinates (latitude and longitude) and +azimuthal data must be in decimal degrees or DMS format and +input distance data must be in units consistent with the ellipsoid +major axis or sphere radius units. The latitude must lie +in the range [-90d,90d]. Output geographic coordinates will be +in DMS (if the :option:`-f` switch is not employed) to 0.001" with trailing, +zero-valued minute-second fields deleted. Output distance +data will be in the same units as the ellipsoid or sphere +radius. + +The Earth's ellipsoidal figure may be selected in the same manner +as program :program:`proj` by using *+ellps=*, *+a=*, *+es=*, etc. + +:program:`geod` may also be used to determine intermediate points along +either a geodesic line between two points or along an arc of +specified distance from a geographic point. In both cases an +initial point must be specified with *+lat_1=lat* and *+lon_1=lon* +parameters and either a terminus point *+lat_2=lat* and +*+lon_2=lon* or a distance and azimuth from the initial point +with *+S=distance* and *+A=azimuth* must be specified. + +If points along a geodesic are to be determined then either +*+n_S=integer* specifying the number of intermediate points +and/or *+del_S=distance* specifying the incremental distance +between points must be specified. + +To determine points along an arc equidistant from the initial +point both *+del_A=angle* and *+n_A=integer* must be specified +which determine the respective angular increments and number of +points to be determined. + +Examples +******** + +The following script determines the geodesic azimuths and distance in U.S. +statute miles from Boston, MA, to Portland, OR: + +.. code-block:: console + + geod +ellps=clrk66 <<EOF -I +units=us-mi + 42d15'N 71d07'W 45d31'N 123d41'W + EOF + +which gives the results: + +.. code-block:: console + + -66d31'50.141" 75d39'13.083" 2587.504 + +where the first two values are the azimuth from Boston to Portland, +the back azimuth from Portland to Boston followed by the distance. + +An example of forward geodesic use is to use the Boston location +and determine Portland's location by azimuth and distance: + +.. code-block:: console + + geod +ellps=clrk66 <<EOF +units=us-mi + 42d15'N 71d07'W -66d31'50.141" 2587.504 + EOF + +which gives: + +.. code-block:: console + + 45d31'0.003"N 123d40'59.985"W 75d39'13.094" + +.. note:: + Lack of precision in the distance value compromises the + precision of the Portland location. + +Further reading +*************** + +#. `GeographicLib <https://geographiclib.sourceforge.io>`_. + +#. C. F. F. Karney, `Algorithms for Geodesics <https://doi.org/10.1007/s00190-012-0578-z>`_, J. Geodesy **87**\ (1), 43–55 (2013); + `addenda <https://geographiclib.sourceforge.io/geod-addenda.html>`_. + +#. `A geodesic bibliography <https://geographiclib.sourceforge.io/geodesic-papers/biblio.html>`_. + +.. only:: man + + See also + ******** + + **proj(1)**, **cs2cs(1)**, **cct(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/gie.rst.txt b/_sources/apps/gie.rst.txt new file mode 100644 index 00000000..73d29e04 --- /dev/null +++ b/_sources/apps/gie.rst.txt @@ -0,0 +1,398 @@ +.. _gie: + +================================================================================ +gie +================================================================================ + +.. Index:: gie + +.. only:: html + + The Geospatial Integrity Investigation Environment + +Synopsis +******** + + **gie** [ **-hovql** [ args ] ] file[s] + +Description +*********** + +:program:`gie`, the Geospatial Integrity Investigation Environment, is a +regression testing environment for the PROJ transformation library. Its primary +design goal is to be able to perform regression testing of code that are a part +of PROJ, while not requiring any other kind of tooling than the same C compiler +already employed for compiling the library. + +.. option:: -h, --help + + Print usage information + +.. option:: -o <file>, --output <file> + + Specify output file name + +.. option:: -v, --verbose + + Verbose: Provide non-essential informational output. Repeat :option:`-v` for + more verbosity (e.g. ``-vv``) + +.. option:: -q, --quiet + + Quiet: Opposite of verbose. In quiet mode not even errors are + reported. Only interaction is through the return code (0 on success, + non-zero indicates number of FAILED tests) + +.. option:: -l, --list + + List the PROJ internal system error codes + +.. option:: --version + + Print version number + +Tests for :program:`gie` are defined in simple text files. Usually having the +extension ``.gie``. Test for :program:`gie` are written in the purpose-build command language for gie. +The basic functionality of the gie command language is implemented through just +3 command verbs: ``operation``, which defines the PROJ operation to test, +``accept``, which defines the input coordinate to read, and ``expect``, which +defines the result to expect. + +A sample test file for :program:`gie` that uses the three above basic commands looks +like: + +.. code-block:: console + + <gie> + + -------------------------------------------- + Test output of the UTM projection + -------------------------------------------- + operation +proj=utm +zone=32 +ellps=GRS80 + -------------------------------------------- + accept 12 55 + expect 691_875.632_14 6_098_907.825_05 + + </gie> + +Parsing of a :program:`gie` file starts at ``<gie>`` and ends when ``</gie>`` +is reached. Anything before ``<gie>`` and after ``</gie>`` is not considered. +Test cases are created by defining an :option:`operation` which +:option:`accept` an input coordinate and :option:`expect` an output +coordinate. + +Because :program:`gie` tests are wrapped in the ``<gie>``/``</gie>`` tags it is +also possible to add test cases to custom made :ref:`init files <init_files>`. +The tests will be ignore by PROJ when reading the init file with *+init* and +:program:`gie` ignores anything not wrapped in ``<gie>``/``</gie>``. + +:program:`gie` tests are defined by a set of commands like :option:`operation`, +:option:`accept` and :option:`expect` in the example above. Together the +commands make out the :program:`gie` command language. Any line in a +:program:`gie` file that does not start with a command is ignored. In the +example above it is seen how this can be used to add comments and styling to +:program:`gie` test files in order to make them more readable as well as +documenting what the purpose of the various tests are. + +Below the :ref:`gie_commands` is explained in details. + +Examples +********* + +1. Run all tests in a file with all debug information turned on + +.. code-block:: console + + gie -vvvv corner-cases.gie + +2. Run all tests in several files + +.. code-block:: console + + gie foo bar + +.. _gie_commands: + +gie command language +******************** + + +.. option:: operation <+args> + + Define a PROJ operation to test. Example: + + .. code-block:: console + + operation proj=utm zone=32 ellps=GRS80 + # test 4D function + accept 12 55 0 0 + expect 691875.63214 6098907.82501 0 0 + + # test 2D function + accept 12 56 + expect 687071.4391 6210141.3267 + +.. option:: accept <x y [z [t]]> + + Define the input coordinate to read. Takes test coordinate. The coordinate + can be defined by either 2, 3 or 4 values, where the first two values are + the x- and y-components, the 3rd is the z-component and the 4th is the time + component. The number of components in the coordinate determines which + version of the operation is tested (2D, 3D or 4D). Many coordinates can be + accepted for one :option:`operation`. For each :option:`accept` an + accompanying :option:`expect` is needed. + + Note that :program:`gie` accepts the underscore (``_``) as a thousands + separator. It is not required (in fact, it is entirely ignored by the + input routine), but it significantly improves the readability of the very + long strings of numbers typically required in projected coordinates. + + + See :option:`operation` for an example. + +.. option:: expect <x y [z [t]]> | <error code> + + Define the expected coordinate that will be returned from accepted + coordinate passed though an operation. The expected coordinate can be + defined by either 2, 3 or 4 components, similarly to :option:`accept`. + Many coordinates can be expected for one :option:`operation`. For each + :option:`expect` an accompanying :option:`accept` is needed. + + See :option:`operation` for an example. + + In addition to expecting a coordinate it is also possible to expect a + PROJ error code in case an operation can't be created. This is useful when + testing that errors are caught and handled correctly. Below is an example of + that tests that the pipeline operator fails correctly when a non-invertible + pipeline is constructed. + + .. code-block:: console + + operation proj=pipeline step + proj=urm5 n=0.5 inv + expect failure pjd_err_malformed_pipeline + + See :option:`gie --list<--list>` for a list of error codes that can be expected. + +.. option:: tolerance <tolerance> + + The :option:`tolerance` command controls how much accepted coordinates + can deviate from the expected coordinate. This is handy to test that an + operation meets a certain numerical tolerance threshold. Some operations + are expected to be accurate within millimeters where others might only be + accurate within a few meters. :option:`tolerance` should + + .. code-block:: console + + operation proj=merc + # test coordinate as returned by ```echo 12 55 | proj +proj=merc`` + tolerance 1 cm + accept 12 55 + expect 1335833.89 7326837.72 + + # test that the same coordinate with a 50 m false easting as determined + # by ``echo 12 55 |proj +proj=merc +x_0=50`` is still within a 100 m + # tolerance of the unaltered coordinate from proj=merc + tolerance 100 m + accept 12 55 + expect 1335883.89 7326837.72 + + The default tolerance is 0.5 mm. See :option:`proj -lu` for a list of possible + units. + +.. option:: roundtrip <n> <tolerance> + + Do a roundtrip test of an operation. :option:`roundtrip` needs a + :option:`operation` and a :option:`accept` command + to function. The accepted coordinate is passed to the operation first in + it's forward mode, then the output from the forward operation is passed + back to the inverse operation. This procedure is done ``n`` times. If the + resulting coordinate is within the set tolerance of the initial coordinate, + the test is passed. + + Example with the default 100 iterations and the default tolerance: + + .. code-block:: console + + operation proj=merc + accept 12 55 + roundtrip + + Example with count and default tolerance: + + .. code-block:: console + + operation proj=merc + accept 12 55 + roundtrip 10000 + + Example with count and tolerance: + + .. code-block:: console + + operation proj=merc + accept 12 55 + roundtrip 10000 5 mm + +.. option:: direction <direction> + + The :option:`direction` command specifies in which direction an operation + is performed. This can either be ``forward`` or ``inverse``. An example of + this is seen below where it is tested that a symmetrical transformation + pipeline returns the same results in both directions. + + .. code-block:: console + + operation proj=pipeline zone=32 step + proj=utm ellps=GRS80 step + proj=utm ellps=GRS80 inv + tolerance 0.1 mm + + accept 12 55 0 0 + expect 12 55 0 0 + + # Now the inverse direction (still same result: the pipeline is symmetrical) + + direction inverse + expect 12 55 0 0 + + The default direction is "forward". + +.. option:: ignore <error code> + + This is especially + useful in test cases that rely on a grid that is not guaranteed to be + available. Below is an example of that situation. + + .. code-block:: console + + operation proj=hgridshift +grids=nzgd2kgrid0005.gsb ellps=GRS80 + tolerance 1 mm + ignore pjd_err_failed_to_load_grid + accept 172.999892181021551 -45.001620431954613 + expect 173 -45 + + + See :option:`gie --list<--list>` for a list of error codes that can be ignored. + +.. option:: require_grid <grid_name> + + Checks the availability of the grid <grid_name>. If it is not found, then + all :option:`accept`/:option:`expect` pairs until the next + :option:`operation` will be skipped. + :option:`require_grid` can be repeated several times to specify several grids whose + presence is required. + +.. option:: echo <text> + + Add user defined text to the output stream. See the example below. + + .. code-block:: console + + <gie> + echo ** Mercator projection tests ** + operation +proj=merc + accept 0 0 + expect 0 0 + </gie> + + which returns + + .. code-block:: console + + ------------------------------------------------------------------------------- + Reading file 'test.gie' + ** Mercator projection test ** + ------------------------------------------------------------------------------- + total: 1 tests succeeded, 0 tests skipped, 0 tests failed. + ------------------------------------------------------------------------------- + +.. option:: skip + + Skip any test after the first occurrence of :option:`skip`. In the example below only + the first test will be performed. The second test is skipped. This feature is mostly + relevant for debugging when writing new test cases. + + .. code-block:: console + + <gie> + operation proj=merc + accept 0 0 + expect 0 0 + skip + accept 0 1 + expect 0 110579.9 + </gie> + + +Strict mode +*********** + +.. versionadded:: 7.1 + +A stricter variant of normal gie syntax can be used by wrapping gie commands +between ``<gie-strict>`` and ``</gie-strict>``. In strict mode, comment lines +must start with a sharp character. Unknown commands will be considered as an error. +A command can still be split on several lines, but intermediate lines must +end with the space character followed by backslash to mark the continuation. + + .. code-block:: console + + <gie-strict> + # This is a comment. The following line with multiple repeated characters too + ------------------------------------------------- + # A command on several lines must use " \" continuation + operation proj=hgridshift +grids=nzgd2kgrid0005.gsb \ + ellps=GRS80 + tolerance 1 mm + ignore pjd_err_failed_to_load_grid + accept 172.999892181021551 -45.001620431954613 + expect 173 -45 + </gie-strict> + + +Background +********** + +More importantly than being an acronym for "Geospatial Integrity Investigation +Environment", gie were also the initials, user id, and USGS email address of +Gerald Ian Evenden (1935--2016), the geospatial visionary, who, already in the +1980s, started what was to become the PROJ of today. + +Gerald's clear vision was that map projections are *just special functions*. +Some of them rather complex, most of them of two variables, but all of them +*just special functions*, and not particularly more special than the :c:func:`sin()`, +:c:func:`cos()`, :c:func:`tan()`, and :c:func:`hypot()` already available in the C standard library. + +And hence, according to Gerald, *they should not be particularly much harder +to use*, for a programmer, than the :c:func:`sin()`'s, :c:func:`tan()`'s and +:c:func:`hypot()`'s so readily available. + +Gerald's ingenuity also showed in the implementation of the vision, where +he devised a comprehensive, yet simple, system of key-value pairs for +parameterising a map projection, and the highly flexible :c:type:`PJ` struct, storing +run-time compiled versions of those key-value pairs, hence making a map +projection function call, ``pj_fwd(PJ, point)``, as easy as a traditional function +call like ``hypot(x,y)``. + +While today, we may have more formally well defined metadata systems (most +prominent the OGC WKT2 representation), nothing comes close being as easily +readable ("human compatible") as Gerald's key-value system. This system in +particular, and the PROJ system in general, was Gerald's great gift to anyone +using and/or communicating about geodata. + +It is only reasonable to name a program, keeping an eye on the +integrity of the PROJ system, in honour of Gerald. + +So in honour, and hopefully also in the spirit, of Gerald Ian Evenden +(1935--2016), this is the Geospatial Integrity Investigation Environment. + + +.. only:: man + + See also + ******** + + **proj(1)**, **cs2cs(1)**, **cct(1)**, **geod(1)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/index.rst.txt b/_sources/apps/index.rst.txt new file mode 100644 index 00000000..61448e49 --- /dev/null +++ b/_sources/apps/index.rst.txt @@ -0,0 +1,28 @@ +.. _apps: + +================================================================================ +Applications +================================================================================ + +Bundled with PROJ comes a set of small command line utilities. The :program:`proj` +program is limited to converting between geographic and projection coordinates +within one datum. The :program:`cs2cs` program operates similarly, but allows +translation between any pair of definable coordinate systems, including support +for datum transformation. The :program:`geod` program provides the ability to do +geodesic (great circle) computations. :program:`gie` is the program used for +regression tests in PROJ. :program:`cct`, a 4D equivalent to the :program:`proj` +program, performs transformation coordinate systems on a set of input points. +:program:`projinfo` performs queries for geodetic objects and coordinate +operations. :program:`projsync` is a tool for synchronizing PROJ datum and +transformation support data. + +.. toctree:: + :maxdepth: 1 + + cct + cs2cs + geod + gie + proj + projinfo + projsync diff --git a/_sources/apps/proj.rst.txt b/_sources/apps/proj.rst.txt new file mode 100644 index 00000000..0c62ec7e --- /dev/null +++ b/_sources/apps/proj.rst.txt @@ -0,0 +1,219 @@ +.. _proj: + +================================================================================ +proj +================================================================================ + +.. only:: html + + Cartographic projection filter. + +.. Index:: proj + +Synopsis +******** + **proj** [**-beEfiIlmorsStTvVwW**] [args]] [*+opt[=arg]* ...] file ... + + **invproj** [**-beEfiIlmorsStTvVwW**] [args]] [*+opt[=arg]* ...] file ... + + +Description +*********** +:program:`proj` and :program:`invproj` perform respective forward and inverse +conversion of cartographic data to or from cartesian data with a wide +range of selectable projection functions. + +:program:`invproj` may not be available on all platforms; in this case +use :option:`proj -I` instead. + +The following control parameters can appear in any order + +.. program:: proj + +.. option:: -b + + Special option for binary coordinate data input and output through standard + input and standard output. Data is assumed to be in system type double + floating point words. This option is to be used when :program:`proj` is a child process + and allows bypassing formatting operations. + +.. option:: -d <n> + +.. versionadded:: 5.2.0 + + Specify the number of decimals in the output. + +.. option:: -i + + Selects binary input only (see :option:`-b`). + +.. option:: -I + + Alternate method to specify inverse projection. Redundant when used with + :program:`invproj`. + +.. option:: -o + + Selects binary output only (see :option:`-b`). + +.. option:: -t<a> + + Where *a* specifies a character employed as the first character to denote a + control line to be passed through without processing. This option + applicable to ASCII input only. (# is the default value). + +.. option:: -e <string> + + Where *string* is an arbitrary string to be output if an error is detected during + data transformations. The default value is a three character string: ``*\t*``. + Note that if the :option:`-b`, :option:`-i` or :option:`-o` options are employed, an error + is returned as HUGE_VAL value for both return values. + +.. option:: -E + + Causes the input coordinates to be copied to the output line prior to + printing the converted values. + +.. option:: -l<[=id]> + + List projection identifiers that can be selected with *+proj*. ``proj -l=id`` + gives expanded description of projection *id*, e.g. ``proj -l=merc``. + +.. option:: -lp + + List of all projection id that can be used with the *+proj* parameter. + Equivalent to ``proj -l``. + +.. option:: -lP + + Expanded description of all projections that can be used with the *+proj* + parameter. + +.. option:: -le + + List of all ellipsoids that can be selected with the *+ellps* parameters. + +.. option:: -lu + + List of all distance units that can be selected with the *+units* parameter. + +.. option:: -r + + This options reverses the order of the expected input from + longitude-latitude or x-y to latitude-longitude or y-x. + +.. option:: -s + + This options reverses the order of the output from x-y or longitude-latitude + to y-x or latitude-longitude. + +.. option:: -S + + Causes estimation of meridional and parallel scale factors, area scale + factor and angular distortion, and maximum and minimum scale factors to be + listed between <> for each input point. For conformal projections meridional + and parallel scales factors will be equal and angular distortion zero. Equal + area projections will have an area factor of 1. + +.. option:: -m <mult> + + The cartesian data may be scaled by the *mult* parameter. When processing data + in a forward projection mode the cartesian output values are multiplied by + *mult* otherwise the input cartesian values are divided by *mult* before inverse + projection. If the first two characters of *mult* are 1/ or 1: then the + reciprocal value of *mult* is employed. + +.. option:: -f <format> + + Where *format* is a printf format string to control the form of the output values. + For inverse projections, the output will be in degrees when this option is + employed. The default format is ``"%.2f"`` for forward projection and DMS for + inverse. + +.. option:: -w<n> + + Where *n* is the number of significant fractional digits to employ for seconds + output (when the option is not specified, ``-w3`` is assumed). + +.. option:: -W<n> + + Where *n* is the number of significant fractional digits to employ for seconds + output. When ``-W`` is employed the fields will be constant width + with leading zeroes. + +.. option:: -v + + Causes a listing of cartographic control parameters tested for and used by + the program to be printed prior to input data. + +.. option:: -V + + This option causes an expanded annotated listing of the characteristics of + the projected point. :option:`-v` is implied with this option. + + +The *+opt* run-line arguments are associated with cartographic parameters. +Additional projection control parameters may be contained in two auxiliary +control files: the first is optionally referenced with the +*+init=file:id* and the second is always processed after the name of the +projection has been established from either the run-line or the contents of ++init file. The environment parameter :envvar:`PROJ_LIB` establishes the +default directory for a file reference without an absolute path. This is +also used for supporting files like datum shift files. + +.. only:: html + + Usage of *+opt* varies with projection and for a complete description + consult the :ref:`projection pages <projections>`. + + +One or more files (processed in left to right order) specify the source of +data to be converted. A ``-`` will specify the location of processing standard +input. If no files are specified, the input is assumed to be from stdin. +For ASCII input data the two data values must be in the first two white space +separated fields and when both input and output are ASCII all trailing +portions of the input line are appended to the output line. + +Input geographic data (longitude and latitude) must be in DMS or decimal degrees format and input +cartesian data must be in units consistent with the ellipsoid major axis or +sphere radius units. Output geographic coordinates will be in DMS (if the +``-w`` switch is not employed) and precise to 0.001" with trailing, zero-valued +minute-second fields deleted. + +Example +******* +The following script + +.. code-block:: console + + proj +proj=utm +lon_0=112w +ellps=clrk66 -r <<EOF + 45d15'33.1" 111.5W + 45d15.551666667N -111d30 + +45.25919444444 111d30'000w + EOF + +will perform UTM forward projection with a standard UTM central meridian +nearest longitude 112W. The geographic values of this example are equivalent +and meant as examples of various forms of DMS input. The x-y output +data will appear as three lines of:: + + 460769.27 5011648.45 + +.. only:: man + + Other programs + ************** + + The :program:`proj` program is limited to converting between geographic and + projected coordinates within one datum. + + The :program:`cs2cs` program operates similarly, but allows translation + between any pair of definable coordinate reference systems, including + support for datum translation. + + See also + ******** + + **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/projinfo.rst.txt b/_sources/apps/projinfo.rst.txt new file mode 100644 index 00000000..04ee7578 --- /dev/null +++ b/_sources/apps/projinfo.rst.txt @@ -0,0 +1,606 @@ +.. _projinfo: + +================================================================================ +projinfo +================================================================================ + +.. Index:: projinfo + +.. only:: html + + .. versionadded:: 6.0.0 + + Geodetic object and coordinate operation queries + +Synopsis +******** + + | **projinfo** + | [-o formats] [-k crs|operation|datum|ensemble|ellipsoid] [--summary] [-q] + | [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] + | [--spatial-test contains|intersects] + | [--crs-extent-use none|both|intersection|smallest] + | [--grid-check none|discard_missing|sort|known_available] + | [--pivot-crs always|if_no_direct_transformation|never|{auth:code[,auth:code]*}] + | [--show-superseded] [--hide-ballpark] [--accuracy {accuracy}] + | [--allow-ellipsoidal-height-as-vertical-crs] + | [--boundcrs-to-wgs84] + | [--authority name] + | [--main-db-path path] [--aux-db-path path]* + | [--dump-db-structure] + | [--identify] [--3d] + | [--output-id AUTH:CODE] + | [--c-ify] [--single-line] + | --searchpaths | --remote-data | + | --list-crs [list-crs-filter] | + | --dump-db-structure [{object_definition} | {object_reference}] | + | {object_definition} | {object_reference} | (-s {srs_def} -t {srs_def}) + | + + where {object_definition} or {srs_def} is one of the possibilities accepted + by :c:func:`proj_create` + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671"), + - an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as + uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match. + - a OGC URN combining references for compound coordinate reference systems + (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated + syntax "EPSG:2393+5717"), + - a OGC URN combining references for references for projected or derived CRSs + e.g. for Projected 3D CRS "UTM zone 31N / WGS 84 (3D)": + "urn:ogc:def:crs,crs:EPSG::4979,cs:PROJ::ENh,coordinateOperation:EPSG::16031" + (*added in 6.2*) + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") + - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.4/projjson.schema.json (*added in 6.2*) + - a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (*added in 7.1*) + + {object_reference} is a filename preceded by the '@' character. The + file referenced by the {object_reference} must contain a valid + {object_definition}. + +Description +*********** + +:program:`projinfo` is a program that can query information on a geodetic object, +coordinate reference system (CRS) or coordinate operation, when the ``-s`` and ``-t`` +options are specified, and display it under different formats (PROJ string, WKT string +or PROJJSON string). + +It can also be used to query coordinate operations available between two CRS. + +The program is named with some reference to the GDAL :program:`gdalsrsinfo` that offers +partly similar services. + + +The following control parameters can appear in any order: + +.. program:: projinfo + +.. option:: -o formats + + formats is a comma separated combination of: + ``all``, ``default``, ``PROJ``, ``WKT_ALL``, ``WKT2:2015``, ``WKT2:2019``, ``WKT1:GDAL``, ``WKT1:ESRI``, ``PROJJSON``, ``SQL``. + + Except ``all`` and ``default``, other formats can be preceded by ``-`` to disable them. + + .. note:: WKT2_2019 was previously called WKT2_2018. + + .. note:: Before PROJ 6.3.0, WKT1:GDAL was implicitly calling --boundcrs-to-wgs84. + This is no longer the case. + + .. note:: When SQL is specified, :option:`--output-id` must be specified. + +.. option:: -k crs|operation|datum|ensemble|ellipsoid + + When used to query a single object with a AUTHORITY:CODE, determines the (k)ind of the object + in case there are CRS, coordinate operations or ellipsoids with the same CODE. + The default is crs. + +.. option:: --summary + + When listing coordinate operations available between 2 CRS, return the + result in a summary format, mentioning only the name of the coordinate + operation, its accuracy and its area of use. + + .. note:: only used for coordinate operation computation + +.. option:: -q + + Turn on quiet mode. Quiet mode is only available for queries on single objects, + and only one output format is selected. In that mode, only the PROJ, WKT or PROJJSON + string is displayed, without other introduction output. The output is then + potentially compatible of being piped in other utilities. + +.. option:: --area name_or_code + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest can be specified either + as a name (e.g "Denmark - onshore") or a AUTHORITY:CODE (EPSG:3237) + This option is exclusive of :option:`--bbox`. + + .. note:: only used for coordinate operation computation + +.. option:: --bbox west_long,south_lat,east_long,north_lat + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest is specified as a + bounding box with geographic coordinates, expressed in degrees in a + unspecified geographic CRS. + `west_long` and `east_long` should be in the [-180,180] range, and + `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than + `east_long`, except in the case where the area of interest crosses the antimeridian. + + .. note:: only used for coordinate operation computation + +.. option:: --spatial-test contains|intersects + + Specify how the area of use of coordinate operations found in the database + are compared to the area of use specified explicitly with :option:`--area` or :option:`--bbox`, + or derived implicitly from the area of use of the source and target CRS. + By default, :program:`projinfo` will only keep coordinate operations whose are of use + is strictly within the area of interest (``contains`` strategy). + If using the ``intersects`` strategy, the spatial test is relaxed, and any + coordinate operation whose area of use at least partly intersects the + area of interest is listed. + + .. note:: only used for coordinate operation computation + +.. option:: --crs-extent-use none|both|intersection|smallest + + Specify which area of interest to consider when no explicit one is specified + with :option:`--area` or :option:`--bbox` options. + By default (``smallest`` strategy), the area of + use of the source or target CRS will be looked, and the one that is the + smallest one in terms of area will be used as the area of interest. + If using ``none``, no area of interest is used. + If using ``both``, only coordinate operations that relate (contain or intersect + depending of the :option:`--spatial-test` strategy) to the area of use of both CRS + are selected. + If using ``intersection``, the area of interest is the intersection of the + bounding box of the area of use of the source and target CRS + + .. note:: only used for coordinate operation computation + +.. option:: --grid-check none|discard_missing|sort|known_available + + Specify how the presence or absence of a horizontal or vertical shift grid + required for a coordinate operation affects the results returned when + researching coordinate operations between 2 CRS. + The default strategy is ``sort`` (if :envvar:`PROJ_NETWORK` is not defined). + In that case, all candidate + operations are returned, but the actual availability of the grids is used + to determine the sorting order. That is, if a coordinate operation involves + using a grid that is not available in the PROJ resource directories + (determined by the :envvar:`PROJ_LIB` environment variable, it will be listed in + the bottom of the results. + The ``none`` strategy completely disables the checks of presence of grids and + this returns the results as if all the grids where available. + The ``discard_missing`` strategy discards results that involve grids not + present in the PROJ resource directories. + The ``known_available`` strategy discards results that involve grids not + present in the PROJ resource directories and that are not known of the CDN. + This is the default strategy is :envvar:`PROJ_NETWORK` is set to ``ON``. + + .. note:: only used for coordinate operation computation + +.. option:: --pivot-crs always|if_no_direct_transformation|never|{auth:code[,auth:code]*} + + Determine if intermediate (pivot) CRS can be used when researching coordinate + operation between 2 CRS. A typical example is the WGS84 pivot. By default, + :program:`projinfo` will consider any potential pivot if there is no direct transformation + ( ``if_no_direct_transformation``). If using the ``never`` strategy, + only direct transformations between the source and target CRS will be + used. If using the ``always`` strategy, intermediate CRS will be considered + even if there are direct transformations. + It is also possible to restrict the pivot CRS to consider by specifying + one or several CRS by their AUTHORITY:CODE. + + .. note:: only used for coordinate operation computation + +.. option:: --show-superseded + + When enabled, coordinate operations that are superseded by others will be + listed. Note that supersession is not equivalent to deprecation: superseded + operations are still considered valid although they have a better equivalent, + whereas deprecated operations have been determined to be erroneous and are + not considered at all. + + .. note:: only used for coordinate operation computation + +.. option:: --hide-ballpark + + .. versionadded:: 7.1 + + Hides any coordinate operation that is, or contains, a + :term:`Ballpark transformation` + + .. note:: only used for coordinate operation computation + +.. option:: --accuracy {accuracy} + + .. versionadded:: 8.0 + + Sets the minimum desired accuracy for returned coordinate operations. + + .. note:: only used for coordinate operation computation + +.. option:: --allow-ellipsoidal-height-as-vertical-crs + + .. versionadded:: 8.0 + + Allows exporting a geographic or projected 3D CRS as a compound CRS whose + vertical CRS represents the ellipsoidal height. + + .. note:: only used for CRS, and with WKT1:GDAL output format + +.. option:: --boundcrs-to-wgs84 + + When specified, this option researches a coordinate operation from the + base geographic CRS of the single CRS, source or target CRS to the WGS84 + geographic CRS, and if found, wraps those CRS into a BoundCRS object. + This is mostly to be used for early-binding approaches. + +.. option:: --authority name + + Specify the name of the authority into which to restrict looks up for + objects, when specifying an object by name or when coordinate operations are + computed. The default is to allow all authorities. + + When used with SQL output, this restricts the authorities to which intermediate + objects can belong to (the default is EPSG and PROJ). Note that the authority + of the :option:`--output-id` option will also be implicitly added. + +.. option:: --main-db-path path + + Specify the name and path of the database to be used by :program:`projinfo`. + The default is :file:`proj.db` in the PROJ resource directories. + +.. option:: --aux-db-path path + + Specify the name and path of auxiliary databases, that are to be combined + with the main database. Those auxiliary databases must have a table + structure that is identical to the main database, but can be partly filled + and their entries can refer to entries of the main database. + The option may be repeated to specify several auxiliary databases. + +.. option:: --identify + + When used with an object definition, this queries the PROJ database to find + known objects, typically CRS, that are close or identical to the object. + Each candidate object is associated with an approximate likelihood percentage. + This is useful when used with a WKT string that lacks a EPSG identifier, + such as ESRI WKT1. This might also be used with PROJ strings. + For example, `+proj=utm +zone=31 +datum=WGS84 +type=crs` will be identified + with a likelihood of 70% to EPSG:32631 + +.. option:: --dump-db-structure + + .. versionadded:: 8.1 + + Outputs the sequence of SQL statements to create a new empty valid auxiliary + database. This option can be specified as the only switch of the utility. + If also specifying a CRS object and the :option:`--output-id` option, the + definition of the object as SQL statements will be appended. + +.. option:: --list-crs [list-crs-filter] + + .. versionadded:: 8.1 + + Outputs a list (authority name:code and CRS name) of the filtered CRSs from the database. + If no filter is provided all authority names and types of non deprecated CRSs are dumped. + list-crs-filter is a comma separated combination of: allow_deprecated,geodetic,geocentric, + geographic,geographic_2d,geographic_3d,vertical,projected,compound. + Affected by options :option:`--authority`, :option:`--area`, :option:`--bbox` and :option:`--spatial-test` + +.. option:: --3d + + .. versionadded:: 6.3 + + "Promote" the CRS(s) to their 3D version. In the context of researching + available coordinate transformations, explicitly specifying this option is + not necessary, because when one of the source or target CRS has a vertical + component but not the other one, the one that has no vertical component is + automatically promoted to a 3D version, where its vertical axis is the + ellipsoidal height in metres, using the ellipsoid of the base geodetic CRS. + +.. option:: --output-id=AUTH:NAME + + .. versionadded:: 8.1 + + Identifier to assign to the object (for SQL output). + + It is strongly recommended that new objects should not be added in common + registries, such as ``EPSG``, ``ESRI``, ``IAU``, etc. + Users should use a custom authority name instead. If a new object should be + added to the official EPSG registry, users are invited to follow the + procedure explained at https://epsg.org/dataset-change-requests.html. + + Combined with :option:`--dump-db-structure`, users can create + auxiliary databases, instead of directly modifying the main :file:`proj.db` database. + See the :ref:`example how to export to an auxiliary database <projinfo_aux_db_example>`. + + Those auxiliary databases can be specified through + :cpp:func:`proj_context_set_database_path` or the :envvar:`PROJ_AUX_DB` + environment variable. + +.. option:: --c-ify + + For developers only. Modify the string output of the utility so that it + is easy to put those strings in C/C++ code + +.. option:: --single-line + + Output PROJ, WKT or PROJJSON strings on a single line, instead of multiple + indented lines by default. + +.. option:: --searchpaths + + .. versionadded:: 7.0 + + Output the directories into which PROJ resources will be looked for + (if not using C API such as :cpp:func:`proj_context_set_search_paths` + that will override them. + +.. option:: --remote-data + + .. versionadded:: 7.0 + + Display information regarding if :ref:`network` is enabled, and the + related URL. + +Examples +******** + +1. Query the CRS object corresponding to EPSG:4326 + +.. code-block:: console + + projinfo EPSG:4326 + +Output: + +:: + + PROJ.4 string: + +proj=longlat +datum=WGS84 +no_defs +type=crs + + WKT2:2019 string: + GEOGCRS["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]], + USAGE[ + SCOPE["unknown"], + AREA["World"], + BBOX[-90,-180,90,180]], + ID["EPSG",4326]] + + +2. List the coordinate operations between NAD27 (designed with its CRS name) + and NAD83 (designed with its EPSG code 4269) within an area of interest + +.. code-block:: console + + projinfo -s NAD27 -t EPSG:4269 --area "USA - Missouri" + +Output: + +:: + + DERIVED_FROM(EPSG):1241, NAD27 to NAD83 (1), 0.15 m, USA - CONUS including EEZ + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 +step +proj=unitconvert \ + +xy_in=deg +xy_out=rad +step +proj=hgridshift +grids=conus \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1 + + WKT2:2019 string: + COORDINATEOPERATION["NAD27 to NAD83 (1)", + SOURCECRS[ + GEOGCRS["NAD27", + DATUM["North American Datum 1927", + ELLIPSOID["Clarke 1866",6378206.4,294.978698213898, + 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]]]], + TARGETCRS[ + GEOGCRS["NAD83", + DATUM["North American Datum 1983", + ELLIPSOID["GRS 1980",6378137,298.257222101, + 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]]]], + METHOD["CTABLE2"], + PARAMETERFILE["Latitude and longitude difference file","conus"], + OPERATIONACCURACY[0.15], + USAGE[ + SCOPE["unknown"], + AREA["USA - CONUS including EEZ"], + BBOX[23.81,-129.17,49.38,-65.69]], + ID["DERIVED_FROM(EPSG)",1241]] + +3. Export an object as a PROJJSON string + +.. code-block:: console + + projinfo GDA94 -o PROJJSON -q + +Output: + +.. code-block:: json + + { + "type": "GeographicCRS", + "name": "GDA94", + "datum": { + "type": "GeodeticReferenceFrame", + "name": "Geocentric Datum of Australia 1994", + "ellipsoid": { + "name": "GRS 1980", + "semi_major_axis": 6378137, + "inverse_flattening": 298.257222101 + } + }, + "coordinate_system": { + "subtype": "ellipsoidal", + "axis": [ + { + "name": "Geodetic latitude", + "abbreviation": "Lat", + "direction": "north", + "unit": "degree" + }, + { + "name": "Geodetic longitude", + "abbreviation": "Lon", + "direction": "east", + "unit": "degree" + } + ] + }, + "area": "Australia - GDA", + "bbox": { + "south_latitude": -60.56, + "west_longitude": 93.41, + "north_latitude": -8.47, + "east_longitude": 173.35 + }, + "id": { + "authority": "EPSG", + "code": 4283 + } + } + +.. _projinfo_aux_db_example: + +4. Exporting the SQL statements to insert a new CRS in an auxiliary database. + +.. code-block:: console + + # Get the SQL statements for a custom CRS + projinfo "+proj=merc +lat_ts=5 +datum=WGS84 +type=crs +title=my_crs" --output-id HOBU:MY_CRS -o SQL -q > my_crs.sql + cat my_crs.sql + + # Initialize an auxiliary database with the schema of the reference database + echo ".schema" | sqlite3 /path/to/proj.db | sqlite3 aux.db + + # Append the content of the definition of HOBU:MY_CRS + sqlite3 aux.db < my_crs.db + + # Check that everything works OK + projinfo --aux-db-path aux.db HOBU:MY_CRS + +or more simply: + +.. code-block:: console + + # Create an auxiliary database with the definition of a custom CRS. + projinfo "+proj=merc +lat_ts=5 +datum=WGS84 +type=crs +title=my_crs" --output-id HOBU:MY_CRS --dump-db-structure | sqlite3 aux.db + + # Check that everything works OK + projinfo --aux-db-path aux.db HOBU:MY_CRS + +Output: + +.. code-block:: sql + + INSERT INTO geodetic_crs VALUES('HOBU','GEODETIC_CRS_MY_CRS','unknown','','geographic 2D','EPSG','6424','EPSG','6326',NULL,0); + INSERT INTO usage VALUES('HOBU','USAGE_GEODETIC_CRS_MY_CRS','geodetic_crs','HOBU','GEODETIC_CRS_MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); + INSERT INTO conversion VALUES('HOBU','CONVERSION_MY_CRS','unknown','','EPSG','9805','Mercator (variant B)','EPSG','8823','Latitude of 1st standard parallel',5,'EPSG','9122','EPSG','8802','Longitude of natural origin',0,'EPSG','9122','EPSG','8806','False easting',0,'EPSG','9001','EPSG','8807','False northing',0,'EPSG','9001',NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,0); + INSERT INTO usage VALUES('HOBU','USAGE_CONVERSION_MY_CRS','conversion','HOBU','CONVERSION_MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); + INSERT INTO projected_crs VALUES('HOBU','MY_CRS','my_crs','','EPSG','4400','HOBU','GEODETIC_CRS_MY_CRS','HOBU','CONVERSION_MY_CRS',NULL,0); + INSERT INTO usage VALUES('HOBU','USAGE_PROJECTED_CRS_MY_CRS','projected_crs','HOBU','MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); + +:: + + PROJ.4 string: + +proj=merc +lat_ts=5 +lon_0=0 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs +type=crs + + WKT2:2019 string: + PROJCRS["my_crs", + BASEGEOGCRS["unknown", + ENSEMBLE["World Geodetic System 1984 ensemble", + MEMBER["World Geodetic System 1984 (Transit)"], + MEMBER["World Geodetic System 1984 (G730)"], + MEMBER["World Geodetic System 1984 (G873)"], + MEMBER["World Geodetic System 1984 (G1150)"], + MEMBER["World Geodetic System 1984 (G1674)"], + MEMBER["World Geodetic System 1984 (G1762)"], + ELLIPSOID["WGS 84",6378137,298.257223563, + LENGTHUNIT["metre",1]], + ENSEMBLEACCURACY[2.0]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + ID["HOBU","GEODETIC_CRS_MY_CRS"]], + CONVERSION["unknown", + METHOD["Mercator (variant B)", + ID["EPSG",9805]], + PARAMETER["Latitude of 1st standard parallel",5, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8823]], + PARAMETER["Longitude of natural origin",0, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8802]], + PARAMETER["False easting",0, + 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]], + ID["HOBU","MY_CRS"]] + +5. Get the WKT representation of EPSG:25832 in the WKT1:GDAL output format and on a single line + +.. code-block:: console + + projinfo -o WKT1:GDAL --single-line EPSG:25832 + +Output: + +:: + + WKT1:GDAL string: + PROJCS["ETRS89 / UTM zone 32N",GEOGCS["ETRS89",DATUM["European_Terrestrial_Reference_System_1989",SPHEROID["GRS 1980",6378137,298.257222101,AUTHORITY["EPSG","7019"]],AUTHORITY["EPSG","6258"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4258"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",9],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",0],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","25832"]] + +.. only:: man + + See also + ******** + + **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **proj(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/projsync.rst.txt b/_sources/apps/projsync.rst.txt new file mode 100644 index 00000000..7722e52e --- /dev/null +++ b/_sources/apps/projsync.rst.txt @@ -0,0 +1,177 @@ +.. _projsync: + +================================================================================ +projsync +================================================================================ + +.. Index:: projsync + +.. only:: html + + .. versionadded:: 7.0.0 + + Tool for synchronizing PROJ datum and transformation support data. + +Synopsis +******** + + | **projsync** + | [--endpoint URL] + | [--local-geojson-file FILENAME] + | ([--user-writable-directory] | [--system-directory] | [--target-dir DIRNAME]) + | [--bbox west_long,south_lat,east_long,north_lat] + | [--spatial-test contains|intersects] + | [--source-id ID] [--area-of-use NAME] + | [--file NAME] + | [--all] [--exclude-world-coverage] + | [--quiet | --verbose] [--dry-run] [--list-files] + | [--no-version-filtering] + +Description +*********** + +:program:`projsync` is a program that downloads remote resource files +into a local directory. This is an alternative to downloading a proj-data-X.Y.Z +archive file, or using the on-demand :ref:`networking capabilities <network>` of PROJ. + +The following control parameters can appear in any order: + +.. program:: projsync + +.. option:: --endpoint URL + + Defines the URL where to download the master :file:`files.geojson` file and then + the resource files. Defaults to the value set in :ref:`proj-ini` + +.. option:: --local-geojson-file FILENAME + + Defines the filename for the master GeoJSON files that references resources. + Defaults to ``${endpoint}/files.geojson`` + +.. option:: --user-writable-directory + + Specifies that resource files must be downloaded in the + :ref:`user writable directory <user_writable_directory>`. This is the default. + +.. option:: --system-directory + + Specifies that resource files must be downloaded in the + ${installation_prefix}/share/proj directory. The user launching projsync + should make sure it has writing rights in that directory. + +.. option:: --target-dir DIRNAME + + Directory into which resource files must be downloaded. + +.. option:: --bbox west_long,south_lat,east_long,north_lat + + Specify an area of interest to restrict the resources to download. + The area of interest is specified as a + bounding box with geographic coordinates, expressed in degrees in a + unspecified geographic CRS. + `west_long` and `east_long` should be in the [-180,180] range, and + `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than + `east_long`, except in the case where the area of interest crosses the antimeridian. + +.. option:: --spatial-test contains|intersects + + Specify how the extent of the resource files + are compared to the area of use specified explicitly with :option:`--bbox`. + By default, any resource files whose extent intersects the value specified + by :option:`--bbox` will be selected. + If using the ``contains`` strategy, only resource files whose extent is + contained in the value specified by :option:`--bbox` will be selected. + +.. option:: --source-id ID + + Restrict resource files to be downloaded to those whose source_id property + contains the ID value. Specifying ``?`` as ID will list all possible values. + +.. option:: --area-of-use NAME + + Restrict resource files to be downloaded to those whose area_of_use property + contains the NAME value. Specifying ``?`` as NAME will list all possible values. + +.. option:: --file NAME + + Restrict resource files to be downloaded to those whose name property + contains the NAME value. Specifying ``?`` as NAME will list all possible values. + +.. option:: --all + + Ask to download all files. + +.. option:: --exclude-world-coverage + + Exclude files which have world coverage. + +.. option:: -q / --quiet + + Quiet mode + +.. option:: --verbose + + .. versionadded:: 8.1 + + Verbose mode (more than default) + +.. option:: --dry-run + + Simulate the behavior of the tool without downloading resource files. + +.. option:: --list-files + + List file names, with the source_id and area_of_use properties. + +.. option:: --no-version-filtering + + .. versionadded:: 8.1 + + By default, projsync only downloads files that are compatible of + the PROJ_DATA.VERSION metadata of :file:`proj.db`, taking into account the + ``version_added`` and ``version_removed`` properties of entries in :file:`files.geojson`. + When specifying this switch, all files referenced in :file:`files.geojson` + will be candidate (combined with other filters). + + +At least one of :option:`--list-files`, :option:`--file`, :option:`--source-id`, +:option:`--area-of-use`, :option:`--bbox` or :option:`--all` must be specified. + +Options :option:`--file`, :option:`--source-id`, :option:`--area-of-use` and +:option:`--bbox` are combined with a AND logic. + +Examples +******** + +1. Download all resource files + +.. code-block:: console + + projsync --all + +2. Download resource files covering specified point and attributing to an agency + +.. code-block:: console + + projsync --source-id fr_ign --bbox 2,49,2,49 + + +.. only:: man + + See also + ******** + + **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **proj(1)**, **projinfo(1)** + + Bugs + **** + + A list of known bugs can be found at https://github.com/OSGeo/PROJ/issues + where new bug reports can be submitted to. + Bugs specific to resource files should be submitted to + https://github.com/OSGeo/PROJ-data/issues + + Home page + ********* + + https://proj.org/ diff --git a/_sources/community/channels.rst.txt b/_sources/community/channels.rst.txt new file mode 100644 index 00000000..1d67ef52 --- /dev/null +++ b/_sources/community/channels.rst.txt @@ -0,0 +1,46 @@ +.. _channels: + +=========================== +Communication channels +=========================== + +Mailing list +------------------------------------------------------------------------------- + +Users and developers of the library are using the mailing list to discuss all +things related to PROJ. The mailing list is the primary forum for asking for +help with use of PROJ. The mailing list is also used for announcements, discussions +about the development of the library and from time to time interesting discussions +on geodesy appear as well. You are more than welcome to join in on the discussions! + + +The PROJ mailing list can be found at https://lists.osgeo.org/mailman/listinfo/proj + + +GitHub +------------------------------------------------------------------------------- + +GitHub is the development platform we use for collaborating on the PROJ code. +We use GitHub to keep track of the changes in the code and to index bug reports +and feature requests. We are happy to take contributions in any form, either +as code, bug reports, documentation or feature requests. See :ref:`contributing` +for more info on how you can help improve PROJ. + +The PROJ GitHub page can be found at https://github.com/OSGeo/PROJ + +.. note:: + + The issue tracker on GitHub is only meant to keep track of bugs, feature + request and other things related to the development of PROJ. Please ask + your questions about the use of PROJ on the mailing list instead. + + +Gitter +------------------------------------------------------------------------------- + +Gitter is the instant messaging alternative to the mailing list. PROJ has a +room under the OSGeo organization. Most of the core developers stop by from +time to time for an informal chat. You are more than welcome to join the +discussion. + +The Gitter room can be found at https://gitter.im/OSGeo/proj.4 diff --git a/_sources/community/code_contributions.rst.txt b/_sources/community/code_contributions.rst.txt new file mode 100644 index 00000000..a21b590b --- /dev/null +++ b/_sources/community/code_contributions.rst.txt @@ -0,0 +1,177 @@ +.. _code_contributions: + +================================================================================ +Guidelines for PROJ code contributors +================================================================================ + +This is a guide for PROJ, casual or regular, code contributors. + +Code contributions. +############################################################################### + +Code contributions can be either bug fixes or new features. The process +is the same for both, so they will be discussed together in this +section. + +Making Changes +~~~~~~~~~~~~~~ + +- Create a topic branch from where you want to base your work. +- You usually should base your topic branch off of the master branch. +- To quickly create a topic branch: ``git checkout -b my-topic-branch`` +- Make commits of logical units. +- Check for unnecessary whitespace with ``git diff --check`` before + committing. +- Make sure your commit messages are in the `proper + format <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`__. +- Make sure you have added the necessary tests for your changes. +- Make sure that all tests pass + +Submitting Changes +~~~~~~~~~~~~~~~~~~ + +- Push your changes to a topic branch in your fork of the repository. +- Submit a pull request to the PROJ repository in the OSGeo + organization. +- If your pull request fixes/references an issue, include that issue + number in the pull request. For example: + +:: + + Wiz the bang + + Fixes #123. + +- PROJ developers will look at your patch and take an appropriate + action. + +Coding conventions +~~~~~~~~~~~~~~~~~~ + +Programming language +^^^^^^^^^^^^^^^^^^^^ + +PROJ was originally developed in ANSI C. Today PROJ is mostly developed in C++11, +with a few parts of the code base still being C. Most of the older parts of the +code base is effectively C with a few modifications so that it compiles better as +C++. + +Coding style +^^^^^^^^^^^^ + +The parts of the code base that has started its life as C++ is formatted with +``clang-format`` using the script ``scripts/reformat_cpp.sh``. This is mostly +contained to the code in `src/iso19111/` but a few other `.cpp`-files are +covered as well. + +For the rest of the code base, which has its origin in C, we don't enforce any +particular coding style, but please try to keep it as simple as possible. If +improving existing code, please try to conform with the style of the locally +surrounding code. + +Whitespace +^^^^^^^^^^ + +Throughout the PROJ code base you will see differing whitespace use. +The general rule is to keep whitespace in whatever form it is in the +file you are currently editing. If the file has a mix of tabs and space +please convert the tabs to space in a separate commit before making any +other changes. This makes it a lot easier to see the changes in diffs +when evaluating the changed code. New files should use spaces as +whitespace. + + +Tools +############################################################################### + +Reformatting C++ code +~~~~~~~~~~~~~~~~~~~~~~~~ + +The script in ``scripts/reformat_cpp.sh`` will reformat C++ code in accordance +to the project preference. + +If you are writing a new ``.cpp``-file it should be added to the list in the +reformatting script. + + +cppcheck static analyzer +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can run locally ``scripts/cppcheck.sh`` that is a wrapper script around the +cppcheck utility. This tool is used as part of the quality control of the code. + +cppcheck can have false positives. In general, it is preferable to rework the +code a bit to make it more 'obvious' and avoid those false positives. When not +possible, you can add a comment in the code like + +:: + + /* cppcheck-suppress duplicateBreak */ + +in the preceding line. Replace +duplicateBreak with the actual name of the violated rule emitted by cppcheck. + +Clang Static Analyzer (CSA) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CSA is run by a GitHub Actions workflow. You may also run it locally. + +Preliminary step: install clang. For example: + +:: + + wget https://releases.llvm.org/9.0.0/clang+llvm-9.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz + tar xJf clang+llvm-9.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz + mv clang+llvm-9.0.0-x86_64-linux-gnu-ubuntu-18.04 clang+llvm-9 + export PATH=$PWD/clang+llvm-9/bin:$PATH + +Configure PROJ with the :program:`scan-build` utility of clang: + +:: + mkdir csa_build + cd csa_build + scan-build cmake .. + +Build using :program:`scan-build`: + +:: + + scan-build make [-j8] + +If CSA finds errors, they will be emitted during the build. And in which case, +at the end of the build process, :program:`scan-build` will emit a warning message +indicating errors have been found and how to display the error report. This +is with something like + +:: + + scan-view /tmp/scan-build-2021-03-15-121416-17476-1 + + +This will open a web browser with the interactive report. + +CSA may also have false positives. In general, this happens when the code is +non-trivial / makes assumptions that hard to check at first sight. You will +need to add extra checks or rework it a bit to make it more "obvious" for CSA. +This will also help humans reading your code ! + +Typo detection and fixes +~~~~~~~~~~~~~~~~~~~~~~~~ + +Run ``scripts/fix_typos.sh`` + +Include What You Use (IWYU) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Managing C includes is a pain. IWYU makes updating headers a bit +easier. IWYU scans the code for functions that are called and makes +sure that the headers for all those functions are present and in +sorted order. However, you cannot blindly apply IWYU to PROJ. It +does not understand ifdefs, other platforms, or the order requirements +of PROJ internal headers. So the way to use it is to run it on a copy +of the source and merge in only the changes that make sense. +Additions of standard headers should always be safe to merge. The +rest require careful evaluation. See the IWYU documentation for +motivation and details. + +`IWYU docs <https://github.com/include-what-you-use/include-what-you-use/tree/master/docs>`_ diff --git a/_sources/community/code_of_conduct.rst.txt b/_sources/community/code_of_conduct.rst.txt new file mode 100644 index 00000000..175b184a --- /dev/null +++ b/_sources/community/code_of_conduct.rst.txt @@ -0,0 +1,92 @@ +.. _code_of_conduct: + +=========================== +Code of Conduct +=========================== + +The PROJ project has adopted the +`Contributor Covenant Code of Conduct <https://www.contributor-covenant.org/>`_. +Everyone who participates in the PROJ community is expected to follow the +code of conduct as written below. + + +Our Pledge +---------- + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +Our Standards +------------- + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +Our Responsibilities +-------------------- + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +Scope +----- + +This Code of Conduct applies within all project spaces, and it also applies when +an individual is representing the project or its community in public spaces. +Examples of representing a project or community include using an official +project e-mail address, posting via an official social media account, or acting +as an appointed representative at an online or offline event. Representation of +a project may be further defined and clarified by project maintainers. + +Enforcement +----------- + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at `kristianevers@gmail.com <mailto:kristianevers@gmail.com>`_. +All complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +Attribution +----------- + +This Code of Conduct is adapted from the +`Contributor Covenant <https://www.contributor-covenant.org>`_, version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq + diff --git a/_sources/community/contributing.rst.txt b/_sources/community/contributing.rst.txt new file mode 100644 index 00000000..5d24e111 --- /dev/null +++ b/_sources/community/contributing.rst.txt @@ -0,0 +1,175 @@ +.. _contributing: + +=========================== +Contributing +=========================== + +PROJ has a wide and varied user base. Some are highly skilled +geodesists with a deep knowledge of map projections and reference +systems, some are GIS software developers and others are GIS users. All +users, regardless of the profession or skill level, has the ability to +contribute to PROJ. Here's a few suggestion on how: + +- Help PROJ-users that is less experienced than yourself. +- Write a bug report +- Request a new feature +- Write documentation for your favorite map projection +- Fix a bug +- Implement a new feature + +In the following sections you can find some guidelines on how to +contribute. As PROJ is managed on GitHub most contributions require +that you have a GitHub account. Familiarity with +`issues <https://guides.github.com/features/issues/>`__ and the `GitHub +Flow <https://guides.github.com/introduction/flow/>`__ is an advantage. + +Help a fellow PROJ user +------------------------- + +The main forum for support for PROJ is the mailing list. You can +subscribe to the mailing list +`here <http://lists.maptools.org/mailman/listinfo/proj>`__ and read the +archive `here <http://lists.maptools.org/pipermail/proj/>`__. + +If you have questions about the usage of PROJ the mailing list is also +the place to go. Please *do not* use the GitHub issue tracker as a +support forum. Your question is much more likely to be answered on the +mailing list, as many more people follow that than the issue tracker. + +.. _add_bug_report: + +Adding bug reports +------------------ + +Bug reports are handled in the `issue +tracker <https://github.com/OSGeo/PROJ/issues>`__ on PROJ's home on +GitHub. Writing a good bug report is not easy. But fixing a poorly +documented bug is not easy either, so please put in the effort it takes +to create a thorough bug report. + +A good bug report includes at least: + +- A title that quickly explains the problem +- A description of the problem and how it can be reproduced +- Version of PROJ being used +- Version numbers of any other relevant software being used, e.g. + operating system +- A description of what already has been done to solve the problem + +The more information that is given up front, the more likely it is that +a developer will find interest in solving the problem. You will probably +get follow-up questions after submitting a bug report. Please answer +them in a timely manner if you have an interest in getting the issue +solved. + +Finally, please only submit bug reports that are actually related to +PROJ. If the issue materializes in software that uses PROJ it is +likely a problem with that particular software. Make sure that it +actually is a PROJ problem before you submit an issue. If you can +reproduce the problem only by using tools from PROJ it is definitely a +problem with PROJ. + +Feature requests +---------------- + +Got an idea for a new feature in PROJ? Submit a thorough description +of the new feature in the `issue +tracker <https://github.com/OSGeo/PROJ/issues>`__. Please include any +technical documents that can help the developer make the new feature a +reality. An example of this could be a publicly available academic paper +that describes a new projection. Also, including a numerical test case +will make it much easier to verify that an implementation of your +requested feature actually works as you expect. + +Note that not all feature requests are accepted. + +Write documentation +------------------- + +PROJ is in dire need of better documentation. Any contributions of +documentation are greatly appreciated. The PROJ documentation is +available on `proj.org <https://proj.org>`__. The website is generated +with `Sphinx <http://www.sphinx-doc.org/en/stable/>`__. Contributions to +the documentation should be made as `Pull +Requests <https://github.com/OSGeo/PROJ/pulls>`__ on GitHub. + +If you intend to document one of PROJ's supported projections please +use the :doc:`Mercator projection <../operations/projections/merc>` +as a template. + +Code contributions +------------------ + +See :doc:`Code contributions <code_contributions>` + +Legalese +~~~~~~~~ + +Committers are the front line gatekeepers to keep the code base clear of +improperly contributed code. It is important to the PROJ users, +developers and the OSGeo foundation to avoid contributing any code to +the project without it being clearly licensed under the project license. + +Generally speaking the key issues are that those providing code to be +included in the repository understand that the code will be released +under the MIT/X license, and that the person providing the code has the +right to contribute the code. For the committer themselves understanding +about the license is hopefully clear. For other contributors, the +committer should verify the understanding unless the committer is very +comfortable that the contributor understands the license (for instance +frequent contributors). + +If the contribution was developed on behalf of an employer (on work +time, as part of a work project, etc) then it is important that an +appropriate representative of the employer understand that the code will +be contributed under the MIT/X license. The arrangement should be +cleared with an authorized supervisor/manager, etc. + +The code should be developed by the contributor, or the code should be +from a source which can be rightfully contributed such as from the +public domain, or from an open source project under a compatible +license. + +All unusual situations need to be discussed and/or documented. + +Committers should adhere to the following guidelines, and may be +personally legally liable for improperly contributing code to the source +repository: + +- Make sure the contributor (and possibly employer) is aware of the + contribution terms. +- Code coming from a source other than the contributor (such as adapted + from another project) should be clearly marked as to the original + source, copyright holders, license terms and so forth. This + information can be in the file headers, but should also be added to + the project licensing file if not exactly matching normal project + licensing (COPYING). +- Existing copyright headers and license text should never be stripped + from a file. If a copyright holder wishes to give up copyright they + must do so in writing to the foundation before copyright messages are + removed. If license terms are changed it has to be by agreement + (written in email is ok) of the copyright holders. +- Code with licenses requiring credit, or disclosure to users should be + added to COPYING. +- When substantial contributions are added to a file (such as + substantial patches) the author/contributor should be added to the + list of copyright holders for the file. +- If there is uncertainty about whether a change is proper to + contribute to the code base, please seek more information from the + project steering committee, or the foundation legal counsel. + +Additional Resources +-------------------- + +- `General GitHub documentation <https://help.github.com/>`__ +- `GitHub pull request + documentation <https://help.github.com/articles/about-pull-requests/>`__ + +Acknowledgements +---------------- + +The *code contribution* section of this CONTRIBUTING file is inspired by +`PDAL's <https://github.com/PDAL/PDAL/blob/master/CONTRIBUTING.md>`__ +and the *legalese* section is modified from `GDAL committer +guidelines <https://trac.osgeo.org/gdal/wiki/rfc3_commiters>`__ + diff --git a/_sources/community/index.rst.txt b/_sources/community/index.rst.txt new file mode 100644 index 00000000..e5e94d7e --- /dev/null +++ b/_sources/community/index.rst.txt @@ -0,0 +1,32 @@ +.. _community: + +Community +=============================================================================== + +The PROJ community is what makes the software stand out from its competitors. +PROJ is used and developed by group of very enthusiastic, knowledgeable and +friendly people. Whether you are a first time user of PROJ or a long-time +contributor the community is always very welcoming. + +.. toctree:: + :maxdepth: 1 + + channels + contributing + code_contributions + code_of_conduct + rfc/index + +Conference +---------- + +.. image:: ../../images/foss4g2021.jpg + :alt: FOSS4G 2021 + :target: https://2021.foss4g.org/ + +`FOSS4G 2021 <https://2021.foss4g.org/>`_ is the leading annual conference for +free and open source geospatial software. It will include presentations related +to PROJ, and some of the PROJ development community will be attending. It is the +event for those interested in PROJ, other FOSS geospatial technologies and the +community around them. The conference will due to COVID-19 be held in a virtual +setting September 27th - October 2nd, 2021. diff --git a/_sources/community/rfc/index.rst.txt b/_sources/community/rfc/index.rst.txt new file mode 100644 index 00000000..53087129 --- /dev/null +++ b/_sources/community/rfc/index.rst.txt @@ -0,0 +1,20 @@ +.. _rfcs: + +***************************************************************************** + Request for Comments +***************************************************************************** + +A PROJ RFC describes a major change in the technological underpinnings of +PROJ, major additions to functionality, or changes in the direction of +the project. + +.. toctree:: + :maxdepth: 1 + + rfc-1 + rfc-2 + rfc-3 + rfc-4 + rfc-5 + rfc-6 + rfc-7 diff --git a/_sources/community/rfc/rfc-1.rst.txt b/_sources/community/rfc/rfc-1.rst.txt new file mode 100644 index 00000000..f3228e0c --- /dev/null +++ b/_sources/community/rfc/rfc-1.rst.txt @@ -0,0 +1,172 @@ +.. _rfc1: + +==================================================================== +PROJ RFC 1: Project Committee Guidelines +==================================================================== + +:Author: Frank Warmerdam, Howard Butler +:Contact: howard@hobu.co +:Status: Passed +:Last Updated: 2018-06-08 + +Summary +----------- + +This document describes how the PROJ Project Steering Committee (PSC) +determines membership, and makes decisions on all aspects of the +PROJ project - both technical and non-technical. + +Examples of PSC management responsibilities: + +* setting the overall development road map +* developing technical standards and policies (e.g. coding standards, + file naming conventions, etc...) +* ensuring regular releases (major and maintenance) of PROJ software +* reviewing RFC for technical enhancements to the software +* project infrastructure (e.g. GitHub, continuous integration hosting options, etc...) +* formalization of affiliation with external entities such as OSGeo +* setting project priorities, especially with respect to project sponsorship +* creation and oversight of specialized sub-committees (e.g. project + infrastructure, training) + +In brief the project team votes on proposals on the `proj mailing list`_. Proposals are available for review for at least two days, and a single +veto is sufficient delay progress though ultimately a majority of members can +pass a proposal. + +.. _`proj mailing list`: http://lists.maptools.org/mailman/listinfo/proj + +List of PSC Members +------------------- +(up-to-date as of 2018-06) + +* Kristian Evers `@kbevers <https://github.com/kbevers>`_ (DK) **Chair** +* Howard Butler `@hobu <https://github.com/hobu>`_ (USA) +* Charles Karney `@cffk <https://github.com/cffk>`_ (USA) +* Thomas Knudsen `@busstoptaktik <https://github.com/busstoptaktik>`_ (DK) +* Even Rouault `@rouault <https://github.com/rouault>`_ (FR) +* Kurt Schwehr `@schwehr <https://github.com/schwehr>`_ (USA) +* Frank Warmerdam `@warmerdam <https://github.com/warmerdam>`_ (USA) **Emeritus** + +Detailed Process +----------------------- + +* Proposals are written up and submitted on the `proj mailing list`_ + for discussion and voting, by any interested party, not just + committee members. +* Proposals need to be available for review for at least two business + days before a final decision can be made. +* Respondents may vote "+1" to indicate support for the proposal and a + willingness to support implementation. +* Respondents may vote "-1" to veto a proposal, but must provide clear + reasoning and alternate approaches to resolving the problem within + the two days. +* A vote of -0 indicates mild disagreement, but has no effect. A 0 + indicates no opinion. A +0 indicate mild support, but has no + effect. +* Anyone may comment on proposals on the list, but only members of the + Project Steering Committee's votes will be counted. +* A proposal will be accepted if it receives +2 (including the + author) and no vetoes (-1). +* If a proposal is vetoed, and it cannot be revised to satisfy all + parties, then it can be resubmitted for an override vote in which a + majority of all eligible voters indicating +1 is sufficient to pass it. + Note that this is a majority of all committee members, not just those who + actively vote. +* Upon completion of discussion and voting the author should announce + whether they are proceeding (proposal accepted) or are withdrawing + their proposal (vetoed). +* The Chair gets a vote. +* The Chair is responsible for keeping track of who is a member of the + Project Steering Committee (perhaps as part of a PSC file in CVS). +* Addition and removal of members from the committee, as well as selection + of a Chair should be handled as a proposal to the committee. +* The Chair adjudicates in cases of disputes about voting. + +RFC Origin +............. + +PROJ RFC and Project Steering Committee is derived from similar governance +bodies in both the `GDAL <https://trac.osgeo.org/gdal/wiki/rfc1_pmc>`__ and +`MapServer <http://mapserver.org/development/rfc/ms-rfc-23.html>`__ software +projects. + +When is Vote Required? +----------------------- + +* Any change to committee membership (new members, removing inactive members) +* Changes to project infrastructure (e.g. tool, location or substantive + configuration) +* Anything that could cause backward compatibility issues. +* Adding substantial amounts of new code. +* Changing inter-subsystem APIs, or objects. +* Issues of procedure. +* When releases should take place. +* Anything dealing with relationships with external entities such as OSGeo +* Anything that might be controversial. + +Observations +---------------- + +* The Chair is the ultimate adjudicator if things break down. +* The absolute majority rule can be used to override an obstructionist + veto, but it is intended that in normal circumstances vetoers need to be + convinced to withdraw their veto. We are trying to reach consensus. + +Committee Membership +--------------------- + +The PSC is made up of individuals consisting of technical contributors +(e.g. developers) and prominent members of the PROJ user community. +There is no set number of members for the PSC although the initial desire +is to set the membership at 6. + +Adding Members +.............. + +Any member of the `proj mailing list`_ may nominate someone for +committee membership at any time. Only existing PSC committee members may +vote on new members. Nominees must receive a majority vote from existing +members to be added to the PSC. + +Stepping Down +............. + +If for any reason a PSC member is not able to fully participate then they +certainly are free to step down. If a member is not active (e.g. no +voting, no IRC or email participation) for a period of two months then +the committee reserves the right to seek nominations to fill that position. +Should that person become active again (hey, it happens) then they would +certainly be welcome, but would require a nomination. + +Membership Responsibilities +----------------------------- + +Guiding Development +............................... + +Members should take an active role guiding the development of new features +they feel passionate about. Once a change request has been accepted +and given a green light to proceed does not mean the members are free of +their obligation. PSC members voting "+1" for a change request are +expected to stay engaged and ensure the change is implemented and +documented in a way that is most beneficial to users. Note that this +applies not only to change requests that affect code, but also those +that affect the web site, technical infrastructure, policies and standards. + +Mailing List Participation +............................... + +PSC members are expected to be active on the +`proj mailing list`_, subject to Open Source mailing list +etiquette. Non-developer members of the PSC are not expected to respond +to coding level questions on the developer mailing list, however they +are expected to provide their thoughts and opinions on user level +requirements and compatibility issues when RFC discussions take place. + + +Updates +--------- + +**June 2018** + +RFC 1 was ratified by the following members diff --git a/_sources/community/rfc/rfc-2.rst.txt b/_sources/community/rfc/rfc-2.rst.txt new file mode 100644 index 00000000..7da1bc4f --- /dev/null +++ b/_sources/community/rfc/rfc-2.rst.txt @@ -0,0 +1,933 @@ +.. _rfc2: + +==================================================================== +PROJ RFC 2: Initial integration of "GDAL SRS barn" work +==================================================================== + +:Author: Even Rouault +:Contact: even.rouault at spatialys.com +:Status: Adopted, implemented in PROJ 6.0 +:Initial version: 2018-10-09 +:Last Updated: 2018-10-31 + +Summary +------- + +This RFC is the result of a first phase of the `GDAL Coordinate System Barn Raising`_ +efforts. In its current state, this work mostly consists of: + + - a C++ implementation of the ISO-19111:2018 / OGC Topic 2 "Referencing by + coordinates" classes to represent Datums, Coordinate systems, CRSs + (Coordinate Reference Systems) and Coordinate Operations. + - methods to convert between this C++ modeling and WKT1, WKT2 and PROJ string representations of those objects + - management and query of a SQLite3 database of CRS and Coordinate Operation definition + - a C API binding part of those capabilities + +.. _`GDAL Coordinate System Barn Raising`: https://gdalbarn.com/ + + +Related standards +----------------- + +Consult `Applicable standards`_ + +.. _`Applicable standards`: http://even.rouault.free.fr/proj_cpp_api/html/general_doc.html#standards + +(They will be linked from the PROJ documentation) + + +Details +------- + +Structure in packages / namespaces +********************************** + +The C++ implementation of the (upcoming) ISO-19111:2018 / OGC Topic 2 "Referencing by +coordinates" classes follows this abstract modeling as much as possible, using +package names as C++ namespaces, abstract classes and method names. A new +BoundCRS class has been added to cover the modeling of the WKT2 BoundCRS +construct, that is a generalization of the WKT1 TOWGS84 concept. It is +strongly recommended to have the ISO-19111 standard open to have an introduction +for the concepts when looking at the code. A few classes have also been +inspired by the GeoAPI + +The classes are organized into several namespaces: + + - osgeo::proj::util + A set of base types from ISO 19103, GeoAPI and other PROJ "technical" + specific classes + + Template optional<T>, classes BaseObject, IComparable, BoxedValue, + ArrayOfBaseObject, PropertyMap, LocalName, NameSpace, GenericName, + NameFactory, CodeList, Exception, InvalidValueTypeException, + UnsupportedOperationException + + - osgeo::proj::metadata: + Common classes from ISO 19115 (Metadata) standard + + Classes Citation, GeographicExtent, GeographicBoundingBox, + TemporalExtent, VerticalExtent, Extent, Identifier, PositionalAccuracy, + + - osgeo::proj::common: + Common classes: UnitOfMeasure, Measure, Scale, Angle, Length, DateTime, + DateEpoch, IdentifiedObject, ObjectDomain, ObjectUsage + + - osgeo::proj::cs: + Coordinate systems and their axis + + Classes AxisDirection, Meridian, CoordinateSystemAxis, CoordinateSystem, + SphericalCS, EllipsoidalCS, VerticalCS, CartesianCS, OrdinalCS, + ParametricCS, TemporalCS, DateTimeTemporalCS, TemporalCountCS, + TemporalMeasureCS + + - osgeo::proj::datum: + Datum (the relationship of a coordinate system to the body) + + Classes Ellipsoid, PrimeMeridian, Datum, DatumEnsemble, + GeodeticReferenceFrame, DynamicGeodeticReferenceFrame, + VerticalReferenceFrame, DynamicVerticalReferenceFrame, TemporalDatum, + EngineeringDatum, ParametricDatum + + - osgeo::proj::crs: + CRS = coordinate reference system = coordinate system with a datum + + Classes CRS, GeodeticCRS, GeographicCRS, DerivedCRS, ProjectedCRS, + VerticalCRS, CompoundCRS, BoundCRS, TemporalCRS, EngineeringCRS, + ParametricCRS, DerivedGeodeticCRS, DerivedGeographicCRS, + DerivedProjectedCRS, DerivedVerticalCRS + + - osgeo::proj::operation: + Coordinate operations (relationship between any two coordinate + reference systems) + + Classes CoordinateOperation, GeneralOperationParameter, + OperationParameter, GeneralParameterValue, ParameterValue, + OperationParameterValue, OperationMethod, InvalidOperation, + SingleOperation, Conversion, Transformation, PointMotionOperation, + ConcatenatedOperation + + - osgeo::proj::io: + I/O classes: WKTFormatter, PROJStringFormatter, FormattingException, + ParsingException, IWKTExportable, IPROJStringExportable, WKTNode, + WKTParser, PROJStringParser, DatabaseContext, AuthorityFactory, + FactoryException, NoSuchAuthorityCodeException + +What does what? +*************** + +The code to parse WKT and PROJ strings and build ISO-19111 objects is +contained in `io.cpp`_ + +The code to format WKT and PROJ strings from ISO-19111 objects is mostly +contained in the related exportToWKT() and exportToPROJString() methods +overridden in the applicable classes. `io.cpp`_ contains the general mechanics +to build such strings. + +Regarding WKT strings, three variants are handled in import and export: + + - WKT2_2018: variant corresponding to the upcoming ISO-19162:2018 standard + + - WKT2_2015: variant corresponding to the current ISO-19162:2015 standard + + - WKT1_GDAL: variant corresponding to the way GDAL understands the OGC + 01-099 and OGC 99-049 standards + +Regarding PROJ strings, two variants are handled in import and export: + + - PROJ5: variant used by PROJ >= 5, possibly using pipeline constructs, + and avoiding +towgs84 / +nadgrids legacy constructs. This variant honours + axis order and input/output units. That is the pipeline for the conversion + of EPSG:4326 to EPSG:32631 will assume that the input coordinates are in + latitude, longitude order, with degrees. + + - PROJ4: variant used by PROJ 4.x + +The raw query of the proj.db database and the upper level construction of +ISO-19111 objects from the database contents is done in `factory.cpp`_ + +A few design principles +*********************** + +Methods generally take and return xxxNNPtr objects, that is non-null shared +pointers (pointers with internal reference counting). The advantage of this +approach is that the user has not to care about the life-cycle of the +instances (and this makes the code leak-free by design). The only point of +attention is to make sure no reference cycles are made. This is the case for +all classes, except the CoordinateOperation class that point to CRS for +sourceCRS and targetCRS members, whereas DerivedCRS point to a Conversion +instance (which derives from CoordinateOperation). This issue was detected in +the ISO-19111 standard. The solution adopted here is to use std::weak_ptr +in the CoordinateOperation class to avoid the cycle. This design artefact is +transparent to users. + +Another important design point is that all ISO19111 objects are immutable after +creation, that is they only have getters that do not modify their states. +Consequently they could possibly use in a thread-safe way. There are however +classes like PROJStringFormatter, WKTFormatter, DatabaseContext, AuthorityFactory +and CoordinateOperationContext whose instances are mutable and thus can not be +used by multiple threads at once. + +Example how to build the EPSG:4326 / WGS84 Geographic2D definition from scratch: + +:: + + auto greenwich = PrimeMeridian::create( + util::PropertyMap() + .set(metadata::Identifier::CODESPACE_KEY, + metadata::Identifier::EPSG) + .set(metadata::Identifier::CODE_KEY, 8901) + .set(common::IdentifiedObject::NAME_KEY, "Greenwich"), + common::Angle(0)); + // actually predefined as PrimeMeridian::GREENWICH constant + + auto ellipsoid = Ellipsoid::createFlattenedSphere( + util::PropertyMap() + .set(metadata::Identifier::CODESPACE_KEY, metadata::Identifier::EPSG) + .set(metadata::Identifier::CODE_KEY, 7030) + .set(common::IdentifiedObject::NAME_KEY, "WGS 84"), + common::Length(6378137), + common::Scale(298.257223563)); + // actually predefined as Ellipsoid::WGS84 constant + + auto datum = GeodeticReferenceFrame::create( + util::PropertyMap() + .set(metadata::Identifier::CODESPACE_KEY, metadata::Identifier::EPSG) + .set(metadata::Identifier::CODE_KEY, 6326) + .set(common::IdentifiedObject::NAME_KEY, "World Geodetic System 1984"); + ellipsoid + util::optional<std::string>(), // anchor + greenwich); + // actually predefined as GeodeticReferenceFrame::EPSG_6326 constant + + auto geogCRS = GeographicCRS::create( + util::PropertyMap() + .set(metadata::Identifier::CODESPACE_KEY, metadata::Identifier::EPSG) + .set(metadata::Identifier::CODE_KEY, 4326) + .set(common::IdentifiedObject::NAME_KEY, "WGS 84"), + datum, + cs::EllipsoidalCS::createLatitudeLongitude(scommon::UnitOfMeasure::DEGREE)); + // actually predefined as GeographicCRS::EPSG_4326 constant + +Algorithmic focus +***************** + +On the algorithmic side, a somewhat involved logic is the +CoordinateOperationFactory::createOperations() in `coordinateoperation.cpp`_ +that takes a pair of source and target CRS and returns a set of possible +`coordinate operations`_ (either single operations like a Conversion or a +Transformation, or concatenated operations). It uses the intrinsic structure +of those objects to create the coordinate operation pipeline. That is, if +going from a ProjectedCRS to another one, by doing first the inverse conversion +from the source ProjectedCRS to its base GeographicCRS, then finding the +appropriate transformation(s) from this base GeographicCRS to the base +GeographicCRS of the target CRS, and then applying the conversion from this +base GeographicCRS to the target ProjectedCRS. At each step, it queries the +database to find if one or several transformations are available. The +resulting coordinate operations are filtered, and sorted, with user provided hints: + + - desired accuracy + - area of use, defined as a bounding box in longitude, latitude space (its + actual CRS does not matter for the intended use) + - if no area of use is defined, if and how the area of use of the source + and target CRS should be used. By default, the smallest area of use is + used. The rationale is for example when transforming between a national + ProjectedCRS and a world-scope GeographicCRS to use the are of use of + this ProjectedCRS to select the appropriate datum shifts. + - how the area of use of the candidate transformations and the desired area of + use (either explicitly or implicitly defined, as explained above) are + compared. By default, only transformations whose area of use is fully + contained in the desired area of use are selected. It is also possible + to relax this test by specifying that only an intersection test must be used. + - whether `PROJ transformation grid`_ names should be substituted to the + official names, when a match is found in the `grid_alternatives` table + of the database. Defaults to true + - whether the availability of those grids should be used to filter and sort + the results. By default, the transformations using grids available in the + system will be presented first. + +The results are sorted, with the most relevant ones appearing first in the +result vector. The criteria used are in that order + + - grid actual availability: operations referencing grids not available will be + listed after ones with available grids + - grid potential availability: operation referencing grids not known at + all in the proj.db will be listed after operations with grids known, but + not available. + - known accuracy: operations with unknown accuracies will be listed + after operations with known accuracy + - area of use: operations with smaller area of use (the intersection of the + operation area of used with the desired area of use) will be listed after + the ones with larger area of use + - accuracy: operations with lower accuracy will be listed after operations + with higher accuracy (caution: lower accuracy actually means a higher numeric + value of the accuracy property, since it is a precision in metre) + +All those settings can be specified in the CoordinateOperationContext instance +passed to createOperations(). + +An interesting example to understand how those parameters play together is +to use `projinfo -s EPSG:4267 -t EPSG:4326` (NAD27 to WGS84 conversions), +and see how specifying desired area of use, spatial criterion, grid availability, +etc. affects the results. + +The following command currently returns 78 results: + +:: + + projinfo -s EPSG:4267 -t EPSG:4326 --summary --spatial-test intersects + +The createOperations() algorithm also does a kind of "CRS routing". +A typical example is if wanting to transform between CRS A and +CRS B, but no direct transformation is referenced in proj.db between those. +But if there are transformations between A <--> C and B <--> C, then it +is possible to build a concatenated operation A --> C --> B. The typical +example is when C is WGS84, but the implementation is generic and just finds +a common pivot from the database. An example of finding a non-WGS84 pivot is +when searching a transformation between EPSG:4326 and EPSG:6668 (JGD2011 - +Japanese Geodetic Datum 2011), which has no direct transformation registered +in the EPSG database . However there are transformations between those two +CRS and JGD2000 (and also Tokyo datum, but that one involves less accurate +transformations) + +:: + + projinfo -s EPSG:4326 -t EPSG:6668 --grid-check none --bbox 135.42,34.84,142.14,41.58 --summary + + Candidate operations found: 7 + unknown id, Inverse of JGD2000 to WGS 84 (1) + JGD2000 to JGD2011 (1), 1.2 m, Japan - northern Honshu + unknown id, Inverse of JGD2000 to WGS 84 (1) + JGD2000 to JGD2011 (2), 2 m, Japan excluding northern main province + unknown id, Inverse of Tokyo to WGS 84 (108) + Tokyo to JGD2011 (2), 9.2 m, Japan onshore excluding northern main province + unknown id, Inverse of Tokyo to WGS 84 (108) + Tokyo to JGD2000 (2) + JGD2000 to JGD2011 (1), 9.4 m, Japan - northern Honshu + unknown id, Inverse of Tokyo to WGS 84 (2) + Tokyo to JGD2011 (2), 13.2 m, Japan - onshore mainland and adjacent islands + unknown id, Inverse of Tokyo to WGS 84 (2) + Tokyo to JGD2000 (2) + JGD2000 to JGD2011 (1), 13.4 m, Japan - northern Honshu + unknown id, Inverse of Tokyo to WGS 84 (1) + Tokyo to JGD2011 (2), 29.2 m, Asia - Japan and South Korea + + +.. _`coordinate operations`: https://proj.org/operations/index.html + +.. _`PROJ transformation grid`: https://proj.org/resource_files.html#transformation-grids + + +Code repository +--------------- + +The current state of the work can be found in the +`iso19111 branch of rouault/proj.4 repository`_ , and is also available as +a GitHub pull request at https://github.com/OSGeo/proj.4/pull/1040 + +Here is a not-so-usable `comparison with a fixed snapshot of master branch`_ + +.. _`iso19111 branch of rouault/proj.4 repository`: https://github.com/rouault/proj.4/tree/iso19111 + +.. _`comparison with a fixed snapshot of master branch`: https://github.com/OSGeo/proj.4/compare/iso19111_dev...rouault:iso19111 + + +Database +-------- + +Content +******* + +The database contains CRS and coordinate operation definitions from the `EPSG`_ +database (IOGP’s EPSG Geodetic Parameter Dataset) v9.5.3, +`IGNF registry`_ (French National Geographic Institute), ESRI database, as well +as a few customizations. + +.. _`EPSG`: http://www.epsg.org/ +.. _`IGNF registry`: https://geodesie.ign.fr/index.php?page=documentation#titre3 + +Building (for PROJ developers creating the database) +**************************************************** + +The building of the database is a several stage process: + +Construct SQL scripts for EPSG +++++++++++++++++++++++++++++++ + +The first stage consists in constructing .sql scripts mostly with +CREATE TABLE and INSERT statements to create the database structure and +populate it. There is one .sql file for each database table, populated +with the content of the EPSG database, automatically +generated with the `build_db.py`_ script, which processes the PostgreSQL +dumps issued by IOGP. A number of other scripts are dedicated to manual +editing, for example `grid_alternatives.sql`_ file that binds official +grid names to PROJ grid names + +Concert UTF8 SQL to sqlite3 db +++++++++++++++++++++++++++++++ + +The second stage is done automatically by the make process. It pipes the +.sql script, in the right order, to the sqlite3 binary to generate a +first version of the proj.db SQLite3 database. + +Add extra registries +++++++++++++++++++++ + +The third stage consists in creating additional .sql files from the +content of other registries. For that process, we need to bind some +definitions of those registries to those of the EPSG database, to be +able to link to existing objects and detect some boring duplicates. +The `ignf.sql`_ file has been generated using +the `build_db_create_ignf.py`_ script from the current data/IGNF file +that contains CRS definitions (and implicit transformations to WGS84) +as PROJ.4 strings. +The `esri.sql`_ file has been generated using the `build_db_from_esri.py`_ +script, from the .csv files in +https://github.com/Esri/projection-engine-db-doc/tree/master/csv + +Finalize proj.db +++++++++++++++++ + +The last stage runs make again to incorporate the new .sql files generated +in the previous stage (so the process of building the database involves +a kind of bootstrapping...) + +Building (for PROJ users) +************************* + +The make process just runs the second stage mentioned above from the .sql +files. The resulting proj.db is currently 5.3 MB large. + +Structure +********* + +The database is structured into the following tables and views. They generally +match a ISO-19111 concept, and is generally close to the general structure of +the EPSG database. Regarding identification of objects, where the EPSG database +only contains a 'code' numeric column, the PROJ database identifies objects +with a (auth_name, code) tuple of string values, allowing several registries to +be combined together. + +- Technical: + - `authority_list`: view enumerating the authorities present in the database. Currently: EPSG, IGNF, PROJ + - `metadata`: a few key/value pairs, for example to indicate the version of the registries imported in the database + - `object_view`: synthetic view listing objects (ellipsoids, datums, CRS, coordinate operations...) code and name, and the table name where they are further described + - `alias_names`: list possible alias for the `name` field of object table + - `link_from_deprecated_to_non_deprecated`: to handle the link between old ESRI to new ESRI/EPSG codes + +- Common: + - `unit_of_measure`: table with UnitOfMeasure definitions. + - `area`: table with area-of-use (bounding boxes) applicable to CRS and coordinate operations. + +- Coordinate systems: + - `axis`: table with CoordinateSystemAxis definitions. + - `coordinate_system`: table with CoordinateSystem definitions. + +- Ellipsoid and datums: + - `ellipsoid`: table with ellipsoid definitions. + - `prime_meridian`: table with PrimeMeridian definitions. + - `geodetic_datum`: table with GeodeticReferenceFrame definitions. + - `vertical_datum`: table with VerticalReferenceFrame definitions. + +- CRS: + - `geodetic_crs`: table with GeodeticCRS and GeographicCRS definitions. + - `projected_crs`: table with ProjectedCRS definitions. + - `vertical_crs`: table with VerticalCRS definitions. + - `compound_crs`: table with CompoundCRS definitions. + +- Coordinate operations: + - `coordinate_operation_view`: view giving a number of common attributes shared by the concrete tables implementing CoordinateOperation + - `conversion`: table with definitions of Conversion (mostly parameter and values of Projection) + - `concatenated_operation`: table with definitions of ConcatenatedOperation. + - `grid_transformation`: table with all grid-based transformations. + - `grid_packages`: table listing packages in which grids can be found. ie "proj-datumgrid", "proj-datumgrid-europe", ... + - `grid_alternatives`: table binding official grid names to PROJ grid names. e.g "Und_min2.5x2.5_egm2008_isw=82_WGS84_TideFree.gz" --> "egm08_25.gtx" + - `helmert_transformation`: table with all Helmert-based transformations. + - `other_transformation`: table with other type of transformations. + +The main departure with the structure of the EPSG database is the split of +the various coordinate operations over several tables. This was done mostly +for human-readability as the EPSG organization of coordoperation, +coordoperationmethod, coordoperationparam, coordoperationparamusage, +coordoperationparamvalue tables makes it hard to grasp at once all the +parameters and values for a given operation. + + +Utilities +--------- + +A new `projinfo` utility has been added. It enables the user to enter a CRS or +coordinate operation by a AUTHORITY:CODE, PROJ string or WKT string, and see +it translated in the different flavors of PROJ and WKT strings. +It also enables to build coordinate operations between two CRSs. + +Usage +***** + +:: + + usage: projinfo [-o formats] [-k crs|operation] [--summary] [-q] + [--bbox min_long,min_lat,max_long,max_lat] + [--spatial-test contains|intersects] + [--crs-extent-use none|both|intersection|smallest] + [--grid-check none|discard_missing|sort] + [--boundcrs-to-wgs84] + {object_definition} | (-s {srs_def} -t {srs_def}) + + -o: formats is a comma separated combination of: all,default,PROJ4,PROJ,WKT_ALL,WKT2_2015,WKT2_2018,WKT1_GDAL + Except 'all' and 'default', other format can be preceded by '-' to disable them + +Examples +******** + +Specify CRS by AUTHORITY:CODE ++++++++++++++++++++++++++++++ + +:: + + $ projinfo EPSG:4326 + + PROJ string: + +proj=pipeline +step +proj=longlat +ellps=WGS84 +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1 + + WKT2_2015 string: + 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]] + + +Specify CRS by PROJ string and specify output formats +++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +:: + + $ projinfo -o PROJ4,PROJ,WKT1_GDAL,WKT2_2018 "+title=IGN 1972 Nuku Hiva - UTM fuseau 7 Sud +proj=tmerc +towgs84=165.7320,216.7200,180.5050,-0.6434,-0.4512,-0.0791,7.420400 +a=6378388.0000 +rf=297.0000000000000 +lat_0=0.000000000 +lon_0=-141.000000000 +k_0=0.99960000 +x_0=500000.000 +y_0=10000000.000 +units=m +no_defs" + + PROJ string: + Error when exporting to PROJ string: BoundCRS cannot be exported as a PROJ.5 string, but its baseCRS might + + PROJ.4 string: + +proj=utm +zone=7 +south +ellps=intl +towgs84=165.732,216.72,180.505,-0.6434,-0.4512,-0.0791,7.4204 + + WKT2_2018 string: + BOUNDCRS[ + SOURCECRS[ + PROJCRS["IGN 1972 Nuku Hiva - UTM fuseau 7 Sud", + BASEGEOGCRS["unknown", + DATUM["unknown", + ELLIPSOID["International 1909 (Hayford)",6378388,297, + LENGTHUNIT["metre",1, + ID["EPSG",9001]]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8901]]], + CONVERSION["unknown", + METHOD["Transverse Mercator", + ID["EPSG",9807]], + PARAMETER["Latitude of natural origin",0, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8801]], + PARAMETER["Longitude of natural origin",-141, + 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",10000000, + LENGTHUNIT["metre",1], + ID["EPSG",8807]]], + CS[Cartesian,2], + AXIS["(E)",east, + ORDER[1], + LENGTHUNIT["metre",1, + ID["EPSG",9001]]], + AXIS["(N)",north, + ORDER[2], + LENGTHUNIT["metre",1, + ID["EPSG",9001]]]]], + TARGETCRS[ + GEOGCRS["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["latitude",north, + ORDER[1], + ANGLEUNIT["degree",0.0174532925199433]], + AXIS["longitude",east, + ORDER[2], + ANGLEUNIT["degree",0.0174532925199433]], + ID["EPSG",4326]]], + ABRIDGEDTRANSFORMATION["Transformation from unknown to WGS84", + METHOD["Position Vector transformation (geog2D domain)", + ID["EPSG",9606]], + PARAMETER["X-axis translation",165.732, + ID["EPSG",8605]], + PARAMETER["Y-axis translation",216.72, + ID["EPSG",8606]], + PARAMETER["Z-axis translation",180.505, + ID["EPSG",8607]], + PARAMETER["X-axis rotation",-0.6434, + ID["EPSG",8608]], + PARAMETER["Y-axis rotation",-0.4512, + ID["EPSG",8609]], + PARAMETER["Z-axis rotation",-0.0791, + ID["EPSG",8610]], + PARAMETER["Scale difference",1.0000074204, + ID["EPSG",8611]]]] + + WKT1_GDAL: + PROJCS["IGN 1972 Nuku Hiva - UTM fuseau 7 Sud", + GEOGCS["unknown", + DATUM["unknown", + SPHEROID["International 1909 (Hayford)",6378388,297], + TOWGS84[165.732,216.72,180.505,-0.6434,-0.4512,-0.0791,7.4204]], + PRIMEM["Greenwich",0, + AUTHORITY["EPSG","8901"]], + UNIT["degree",0.0174532925199433, + AUTHORITY["EPSG","9122"]], + AXIS["Longitude",EAST], + AXIS["Latitude",NORTH]], + PROJECTION["Transverse_Mercator"], + PARAMETER["latitude_of_origin",0], + PARAMETER["central_meridian",-141], + PARAMETER["scale_factor",0.9996], + PARAMETER["false_easting",500000], + PARAMETER["false_northing",10000000], + UNIT["metre",1, + AUTHORITY["EPSG","9001"]], + AXIS["Easting",EAST], + AXIS["Northing",NORTH]] + + +Find transformations between 2 CRS +++++++++++++++++++++++++++++++++++ + +Between "Poland zone I" (based on Pulkovo 42 datum) and "UTM WGS84 zone 34N" + +Summary view: + +:: + + $ projinfo -s EPSG:2171 -t EPSG:32634 --summary + + Candidate operations found: 1 + unknown id, Inverse of Poland zone I + Pulkovo 1942(58) to WGS 84 (1) + UTM zone 34N, 1 m, Poland - onshore + +Display of pipelines: + +:: + + $ PROJ_LIB=data src/projinfo -s EPSG:2171 -t EPSG:32634 -o PROJ + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 +step +inv +proj=sterea +lat_0=50.625 +lon_0=21.0833333333333 +k=0.9998 +x_0=4637000 +y_0=5647000 +ellps=krass +step +proj=cart +ellps=krass +step +proj=helmert +x=33.4 +y=-146.6 +z=-76.3 +rx=-0.359 +ry=-0.053 +rz=0.844 +s=-0.84 +convention=position_vector +step +inv +proj=cart +ellps=WGS84 +step +proj=utm +zone=34 +ellps=WGS84 + + +Impacted files +-------------- + +New files (excluding makefile.am, CMakeLists.txt and other build infrastructure +artefacts): + + * include/proj/: Public installed C++ headers + - `common.hpp`_: declarations of osgeo::proj::common namespace. + - `coordinateoperation.hpp`_: declarations of osgeo::proj::operation namespace. + - `coordinatesystem.hpp`_: declarations of osgeo::proj::cs namespace. + - `crs.hpp`_: declarations of osgeo::proj::crs namespace. + - `datum.hpp`_: declarations of osgeo::proj::datum namespace. + - `io.hpp`_: declarations of osgeo::proj::io namespace. + - `metadata.hpp`_: declarations of osgeo::proj::metadata namespace. + - `util.hpp`_: declarations of osgeo::proj::util namespace. + - `nn.hpp`_: Code from https://github.com/dropbox/nn to manage Non-nullable pointers for C++ + + .. _`common.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/common.hpp + .. _`coordinateoperation.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/coordinateoperation.hpp + .. _`coordinatesystem.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/coordinatesystem.hpp + .. _`crs.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/crs.hpp + .. _`datum.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/datum.hpp + .. _`io.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/io.hpp + .. _`metadata.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/metadata.hpp + .. _`nn.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/nn.hpp + .. _`util.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/util.hpp + + * include/proj/internal: Private non-installed C++ headers + - `coordinateoperation_internal.hpp`_: classes InverseCoordinateOperation, InverseConversion, InverseTransformation, PROJBasedOperation, and functions to get conversion mappings between WKT and PROJ syntax + - `coordinateoperation_constants.hpp`_: Select subset of conversion/transformation EPSG names and codes for the purpose of translating them to PROJ strings + - `coordinatesystem_internal.hpp`_: classes AxisDirectionWKT1, AxisName and AxisAbbreviation + - `internal.hpp`_: a few helper functions, mostly to do string-based operations + - `io_internal.hpp`_: class WKTConstants + - `helmert_constants.hpp`_: Helmert-based transformation & parameters names and codes. + - `lru_cache.hpp`_: code from https://github.com/mohaps/lrucache11 to have a generic Least-Recently-Used cache of objects + + .. _`coordinateoperation_internal.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/coordinateoperation_internal.hpp + .. _`coordinatesystem_internal.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/coordinatesystem_internal.hpp + .. _`internal.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/internal.hpp + .. _`io_internal.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/io_internal.hpp + .. _`coordinateoperation_constants.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/coordinateoperation_constants.hpp + .. _`helmert_constants.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/helmert_constants.hpp + .. _`lru_cache.hpp`: https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/lru_cache.hpp + + * src/: + - `c_api.cpp`_: C++ API mapped to C functions + - `common.cpp`_: implementation of `common.hpp`_ + - `coordinateoperation.cpp`_: implementation of `coordinateoperation.hpp`_ + - `coordinatesystem.cpp`_: implementation of `coordinatesystem.hpp`_ + - `crs.cpp`_: implementation of `crs.hpp`_ + - `datum.cpp`_: implementation of `datum.hpp`_ + - `factory.cpp`_: implementation of AuthorityFactory class (from `io.hpp`_) + - `internal.cpp`_: implementation of `internal.hpp`_ + - `io.cpp`_: implementation of `io.hpp`_ + - `metadata.cpp`_: implementation of `metadata.hpp`_ + - `static.cpp`_: a number of static constants (like pre-defined well-known ellipsoid, datum and CRS), put in the right order for correct static initializations + - `util.cpp`_: implementation of `util.hpp`_ + - `projinfo.cpp`_: new 'projinfo' binary + - `general.dox`_: generic introduction documentation. + + .. _`c_api.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/c_api.cpp + .. _`common.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/common.cpp + .. _`coordinateoperation.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/coordinateoperation.cpp + .. _`coordinatesystem.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/coordinatesystem.cpp + .. _`crs.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/crs.cpp + .. _`datum.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/datum.cpp + .. _`factory.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/factory.cpp + .. _`internal.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/internal.cpp + .. _`io.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/io.cpp + .. _`metadata.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/metadata.cpp + .. _`projinfo.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/projinfo.cpp + .. _`static.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/static.cpp + .. _`util.cpp`: https://github.com/rouault/proj.4/blob/iso19111/src/util.cpp + .. _`general.dox`: https://github.com/rouault/proj.4/blob/iso19111/src/general.dox + + * data/sql/: + - `area.sql`_: generated by `build_db.py`_ + - `axis.sql`_: generated by `build_db.py`_ + - `begin.sql`_: hand generated (trivial) + - `commit.sql`_: hand generated (trivial) + - `compound_crs.sql`_: generated by `build_db.py`_ + - `concatenated_operation.sql`_: generated by `build_db.py`_ + - `conversion.sql`_: generated by `build_db.py`_ + - `coordinate_operation.sql`_: generated by `build_db.py`_ + - `coordinate_system.sql`_: generated by `build_db.py`_ + - `crs.sql`_: generated by `build_db.py`_ + - `customizations.sql`_: hand generated (empty) + - `ellipsoid.sql`_: generated by `build_db.py`_ + - `geodetic_crs.sql`_: generated by `build_db.py`_ + - `geodetic_datum.sql`_: generated by `build_db.py`_ + - `grid_alternatives.sql`_: hand-generated. Contains links between official registry grid names and PROJ ones + - `grid_transformation.sql`_: generated by `build_db.py`_ + - `grid_transformation_custom.sql`_: hand-generated + - `helmert_transformation.sql`_: generated by `build_db.py`_ + - `ignf.sql`_: generated by `build_db_create_ignf.py`_ + - `esri.sql`_: generated by `build_db_from_esri.py`_ + - `metadata.sql`_: hand-generated + - `other_transformation.sql`_: generated by `build_db.py`_ + - `prime_meridian.sql`_: generated by `build_db.py`_ + - `proj_db_table_defs.sql`_: hand-generated. Database structure: CREATE TABLE / CREATE VIEW / CREATE TRIGGER + - `projected_crs.sql`_: generated by `build_db.py`_ + - `unit_of_measure.sql`_: generated by `build_db.py`_ + - `vertical_crs.sql`_: generated by `build_db.py`_ + - `vertical_datum.sql`_: generated by `build_db.py`_ + + .. _`area.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/area.sql + .. _`axis.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/axis.sql + .. _`begin.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/begin.sql + .. _`commit.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/commit.sql + .. _`compound_crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/compound_crs.sql + .. _`concatenated_operation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/concatenated_operation.sql + .. _`conversion.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/conversion.sql + .. _`coordinate_operation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/coordinate_operation.sql + .. _`coordinate_system.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/coordinate_system.sql + .. _`crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/crs.sql + .. _`customizations.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/customizations.sql + .. _`ellipsoid.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/ellipsoid.sql + .. _`geodetic_crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/geodetic_crs.sql + .. _`geodetic_datum.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/geodetic_datum.sql + .. _`grid_alternatives.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_alternatives.sql + .. _`grid_transformation_custom.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_transformation_custom.sql + .. _`grid_transformation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_transformation.sql + .. _`helmert_transformation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/helmert_transformation.sql + .. _`ignf.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/ignf.sql + .. _`esri.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/esri.sql + .. _`metadata.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/metadata.sql + .. _`other_transformation.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/other_transformation.sql + .. _`prime_meridian.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/prime_meridian.sql + .. _`proj_db_table_defs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/proj_db_table_defs.sql + .. _`projected_crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/projected_crs.sql + .. _`unit_of_measure.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/unit_of_measure.sql + .. _`vertical_crs.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/vertical_crs.sql + .. _`vertical_datum.sql`: https://github.com/rouault/proj.4/blob/iso19111/data/sql/vertical_datum.sql + + * scripts/: + - `build_db.py`_ : generate .sql files from EPSG database dumps + - `build_db_create_ignf.py`_: generates data/sql/`ignf.sql`_ + - `build_db_from_esri.py`_: generates data/sql/`esri.sql`_ + - `doxygen.sh`_: generates Doxygen documentation + - `gen_html_coverage.sh`_: generates HTML report of the coverage for --coverage build + - `filter_lcov_info.py`_: utility used by gen_html_coverage.sh + - `reformat.sh`_: used by reformat_cpp.sh + - `reformat_cpp.sh`_: reformat all .cpp/.hpp files according to LLVM-style formatting rules + + .. _`build_db.py`: https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py + .. _`build_db_create_ignf.py`: https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_create_ignf.py + .. _`build_db_from_esri.py`: https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_from_esri.py + .. _`doxygen.sh`: https://github.com/rouault/proj.4/blob/iso19111/scripts/doxygen.sh + .. _`gen_html_coverage.sh`: https://github.com/rouault/proj.4/blob/iso19111/scripts/gen_html_coverage.sh + .. _`filter_lcov_info.py`: https://github.com/rouault/proj.4/blob/iso19111/scripts/filter_lcov_info.py + .. _`reformat.sh`: https://github.com/rouault/proj.4/blob/iso19111/scripts/reformat.sh + .. _`reformat_cpp.sh`: https://github.com/rouault/proj.4/blob/iso19111/scripts/reformat_cpp.sh + + * tests/unit/ + - `test_c_api.cpp`_: test of src/c_api.cpp + - `test_common.cpp`_: test of src/common.cpp + - `test_util.cpp`_: test of src/util.cpp + - `test_crs.cpp`_: test of src/crs.cpp + - `test_datum.cpp`_: test of src/datum.cpp + - `test_factory.cpp`_: test of src/factory.cpp + - `test_io.cpp`_: test of src/io.cpp + - `test_metadata.cpp`_: test of src/metadata.cpp + - `test_operation.cpp`_: test of src/operation.cpp + + .. _`test_c_api.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_c_api.cpp + .. _`test_common.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_common.cpp + .. _`test_util.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_util.cpp + .. _`test_crs.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_crs.cpp + .. _`test_datum.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_datum.cpp + .. _`test_factory.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_factory.cpp + .. _`test_io.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_io.cpp + .. _`test_metadata.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_metadata.cpp + .. _`test_operation.cpp`: https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_operation.cpp + +C API +----- + +`proj.h`_ has been extended to bind a number of C++ classes/methods to a C API. + +The main structure is an opaque PJ_OBJ* roughly encapsulating a osgeo::proj::BaseObject, +that can represent a CRS or a CoordinateOperation object. A number of the +C functions will work only if the right type of underlying C++ object is used +with them. Misuse will be properly handled at runtime. If a user passes +a PJ_OBJ* representing a coordinate operation to a pj_obj_crs_xxxx() function, +it will properly error out. This design has been chosen over creating a +dedicate PJ_xxx object for each C++ class, because such an approach would +require adding many conversion and free functions for little benefit. + +This C API is incomplete. In particular, it does not allow to +build ISO19111 objects at hand. However it currently permits a number of +actions: + + - building CRS and coordinate operations from WKT and PROJ strings, or + from the proj.db database + - exporting CRS and coordinate operations as WKT and PROJ strings + - querying main attributes of those objects + - finding coordinate operations between two CRS. + +`test_c_api.cpp`_ should demonstrates simple usage of the API (note: +for the conveniency of writing the tests in C++, test_c_api.cpp wraps the C PJ_OBJ* +instances in C++ 'keeper' objects that automatically call the pj_obj_unref() +function at function end. In a pure C use, the caller must use pj_obj_unref() +to prevent leaks.) + +.. _`proj.h`: http://even.rouault.free.fr/proj_cpp_api/html/proj_8h.html + + +Documentation +------------- + +All public C++ classes and methods and C functions are documented with +Doxygen. + +`Current snapshot of Class list`_ + +`Spaghetti inheritance diagram`_ + +.. _`Current snapshot of Class list`: http://even.rouault.free.fr/proj_cpp_api/html/annotated.html +.. _`Spaghetti inheritance diagram`: http://even.rouault.free.fr/proj_cpp_api/html/inherits.html + +A basic integration of the Doxygen XML output into the general PROJ +documentation (using reStructuredText format) has been done with the +Sphinx extension `Breathe`_, producing: + + * `One section with the C++ API`_ + * `One section with the C API`_ + +.. _`Breathe`: https://breathe.readthedocs.io/en/latest/ +.. _`One section with the C++ API`: http://even.rouault.free.fr/proj_cpp_api/rst_generated/html/development/reference/cpp/index.html +.. _`One section with the C API`: http://even.rouault.free.fr/proj_cpp_api/rst_generated/html/development/reference/functions.html#c-api-for-iso-19111-functionality + +Testing +------- + +Nearly all exported methods are tested by a unit test. Global line coverage +of the new files is 92%. Those tests represent 16k lines of codes. + + +Build requirements +------------------ + +The new code leverages on a number of C++11 features (auto keyword, constexpr, +initializer list, std::shared_ptr, lambda functions, etc.), which means that +a C++11-compliant compiler must be used to generate PROJ: + + * gcc >= 4.8 + * clang >= 3.3 + * Visual Studio >= 2015. + +Compilers tested by the Travis-CI and AppVeyor continuous integration +environments: + + * GCC 4.8 + * mingw-w64-x86-64 4.8 + * clang 5.0 + * Apple LLVM version 9.1.0 (clang-902.0.39.2) + * MSVC 2015 32 and 64 bit + * MSVC 2017 32 and 64 bit + +The libsqlite3 >= 3.7 development package must also be available. And the sqlite3 +binary must be available to build the proj.db files from the .sql files. + +Runtime requirements +-------------------- + +* libc++/libstdc++/MSVC runtime consistent with the compiler used +* libsqlite3 >= 3.7 + + +Backward compatibility +---------------------- + +At this stage, no backward compatibility issue is foreseen, as no +existing functional C code has been modified to use the new capabilities + +Future work +----------- + +The work described in this RFC will be pursued in a number of directions. +Non-exhaustively: + + - Support for ESRI WKT1 dialect (PROJ currently ingest the ProjectedCRS in + `esri.sql`_ in that dialect, but there is no mapping between it and EPSG + operation and parameter names, so conversion to PROJ strings does not + always work. + + - closer integration with the existing code base. In particular, the +init=dict:code + syntax should now go first to the database (then the `epsg` and `IGNF` + files can be removed). Similarly proj_create_crs_to_crs() could use the + new capabilities to find an appropriate coordinate transformation. + + - and whatever else changes are needed to address GDAL and libgeotiff needs + + +Adoption status +--------------- + +The RFC has been adopted with support from PSC members Kurt Schwehr, Kristian +Evers, Howard Butler and Even Rouault. diff --git a/_sources/community/rfc/rfc-3.rst.txt b/_sources/community/rfc/rfc-3.rst.txt new file mode 100644 index 00000000..439f22d1 --- /dev/null +++ b/_sources/community/rfc/rfc-3.rst.txt @@ -0,0 +1,151 @@ +.. _rfc3: + +==================================================================== +PROJ RFC 3: Dependency management +==================================================================== + +:Author: Kristian Evers +:Contact: kreve@sdfe.dk +:Status: Adopted +:Last Updated: 2019-01-16 + +Summary +------------------------------------------------------------------------------- + +This document defines a set of guidelines for dependency management in PROJ. +With PROJ being a core component in many downstream software packages clearly +stating which dependencies the library has is of great value. This document +concern both programming language standards as well as minimum required +versions of library dependencies and build tools. + +It is proposed to adopt a rolling update scheme that ensures that PROJ is +sufficiently accessible, even on older systems, as well as keeping up with the +technological evolution. The scheme is divided in two parts, one concerning +versions of used programming languages within PROJ and the other concerning +software packages that PROJ depend on. + +With adoption of this RFC, versions used for + +1. programming languages will always be at least two revisions behind the most + recent standard +2. software packages will always be at least two years old + (patch releases are exempt) + +A change in programming language standard can only be introduced with a new +major version release of PROJ. Changes for software package dependencies can be +introduced with minor version releases of PROJ. Changing the version +requirements for a dependency needs to be approved by the PSC. + +Following the above rule set will ensure that all but the most conservative +users of PROJ will be able to build and use the most recent version of the +library. + +In the sections below details concerning programming languages and software +dependencies are outlined. The RFC is concluded with a bootstrapping section +that details the state of dependencies after the accept of the RFC. + + +Background +------------------------------------------------------------------------------- + +PROJ has traditionally been written in C89. Until recently, no formal +requirements of e.g. build systems has been defined and formally accepted by +the project. :ref:`RFC2 <rfc2>` formally introduces dependencies on C++11 and +SQLite 3.7. + +In this RFC a rolling update of version or standard requirements is described. +The reasoning behind a rolling update scheme is that it has become increasingly +evident that C89 is becoming outdated and creating a less than optimal +development environment for contributors. It has been noted that the most +commonly used compilers all now support more recent versions of C, so the +strict usage of C89 is no longer as critical as it used to be. + +Similarly, rolling updates to other tools and libraries that PROJ depend on +will ensure that the code base can be kept modern and in line with the rest of +the open source software ecosphere. + + +C and C++ +------------------------------------------------------------------------------- + +Following :ref:`RFC2 <rfc2>` PROJ is written in both C and C++. At the time of +writing the core library is C based and the code described in RFC2 is written +in C++. While the core library is mostly written in C it is compiled as C++. +Minor sections of PROJ, like the geodesic algorithms are still compiled as C +since there is no apparent benefit of compiling with a C++ compiler. This may +change in the future. + +Both the C and C++ standards are updated with regular intervals. After an +update of a standard it takes time for compiler manufacturers to implement the +standards fully, which makes adaption of new standards potentially troublesome +if done too soon. On the other hand, waiting too long to adopt new standards +will eventually make the code base feel old and new contributors are more +likely to stay away because they don't want to work using tools of the past. +With a rolling update scheme both concerns can be managed by always staying +behind the most recent standard, but not so far away that potential +contributors are scared away. Keeping a policy of always lagging behind be two +iterations of the standard is thought to be the best comprise between the two +concerns. + +C comes in four ISO standardised varieties: C89, C99, C11, C18. In this +document we refer to their informal names for ease of reading. C++ exists in +five varieties: C++98, C++03, C++11, C++14, C++17. Before adoption of this RFC +PROJ uses C89 and C++11. For C, that means that the used standard is three +iterations behind the most recent standard. C++ is two iterations behind. +Following the rules in this RFC the required C standard used in PROJ is at +allowed to be two iterations behind the most recent standard. That means that a +change to C99 is possible, as long as the PROJ PSC acknowledges such a change. + +When a new standard for either C or C++ is released PROJ should consider +changing its requirement to the next standard in the line. For C++ that means a +change in standard roughly every three years, for C the periods between +standard updates is expected to be longer. Adaptation of new programming +language standards should be coordinated with a major version release of PROJ. + + +Software dependencies +------------------------------------------------------------------------------- + +At the time of writing PROJ is dependent on very few external packages. In +fact only one runtime dependency is present: SQLite. Building PROJ also +requires one of two external dependencies for configuration: Autotools or +CMake. + +As with programming language standards it is preferable that software +dependencies are a bit behind the most recent development. For this reason it +is required that the minimum version supported in PROJ dependencies is at least +two years old, preferably more. It is not a requirement that the minimum +version of dependencies is always kept strictly two years behind current +development, but it is allowed in case future development of PROJ warrants an +update. Changes in minimum version requirements are allowed to happen with +minor version releases of PROJ. + +At the time of writing the minimum version required for SQLite it 3.7 which was +released in 2010. CMake currently is required to be at least at version 2.8.3 +which was also released in 2010. + + +Bootstrapping +------------------------------------------------------------------------------- + +This RFC comes with a set of guidelines for handling dependencies for PROJ in +the future. Up until now dependencies hasn't been handled consistently, with +some dependencies not being approved formally by the projects governing body. +Therefore minimum versions of PROJ dependencies is proposed so that at the +acception of this RFC PROJ will have the following external requirements: + +* C99 (was C89) +* C++11 (already approved in :ref:`RFC2 <rfc2>`) +* SQLite 3.7 (already approved in :ref:`RFC2 <rfc2>`) +* CMake 3.5 (was 2.8.3) + + +Adoption status +------------------------------------------------------------------------------- + +The RFC was adopted on 2018-01-19 with +1's from the following PSC members + +* Kristian Evers +* Even Rouault +* Thomas Knudsen +* Howard Butler diff --git a/_sources/community/rfc/rfc-4.rst.txt b/_sources/community/rfc/rfc-4.rst.txt new file mode 100644 index 00000000..9673c898 --- /dev/null +++ b/_sources/community/rfc/rfc-4.rst.txt @@ -0,0 +1,804 @@ +.. _rfc4: + +==================================================================== +PROJ RFC 4: Remote access to grids and GeoTIFF grids +==================================================================== + +:Author: Even Rouault, Howard Butler +:Contact: even.rouault@spatialys.com, howard@hobu.co +:Status: Adopted +:Implementation target: PROJ 7 +:Last Updated: 2020-01-10 + +Motivation +------------------------------------------------------------------------------- + +PROJ 6 brings undeniable advances in the management of coordinate +transformations between datums by relying and applying information available in +the PROJ database. PROJ's rapid evolution from a cartographic projections +library with a little bit of geodetic capability to a full geodetic +transformation and description environment has highlighted the importance of +the support data. Users desire the convenience of software doing the right +thing with the least amount of fuss, and survey organizations wish to deliver +their models across as wide a software footprint as possible. To get results +with the highest precision, a grid file that defines a model that provides +dimension shifts is often needed. The proj-datumgrid project centralizes grids +available under an open data license and bundles them in different archives +split along major geographical regions of the world . + +It is assumed that a PROJ user has downloaded and installed grid files that are +referred to in the PROJ database. These files can be quite large in aggregate, +and packaging support by major distribution channels is somewhat uneven due to +their size, sometimes ambiguous licensing story, and difficult-to-track +versioning and lineage. It is not always clear to the user, especially to +those who may not be so familiar with geodetic operations, that the highest +precision transformation may not always being applied if grid data is not +available. Users want both convenience and correctness, and management of the +shift files can be challenging to those who may not be aware of their +importance to the process. + +The computing environment in which PROJ operates is also changing. Because the +shift data can be so large (currently more than 700 MB of uncompressed data, +and growing), deployment of high accuracy operations can be limited due to +deployment size constraints (serverless operations, for example). Changing to a +delivery format that supports incremental access over a network along with +convenient access and compression will ease the resource burden the shift files +present while allowing the project to deliver transformation capability with +the highest known precision provided by the survey organizations. + +Adjustment grids also tend to be provided in many different formats depending +on the organization and country that produced them. In PROJ, we have over time +"standardized" on using horizontal shift grids as NTv2 and vertical shift grids +using GTX. Both have poor general support as dedicated formats, limited +metadata capabilities, and neither are not necessarily "cloud optimized" for +incremental access across a network. + +Summary of work planned by this RFC +------------------------------------------------------------------------------- + +- Grids will be hosted by one or several Content Delivery Networks (CDN) +- Grid loading mechanism will be reworked to be able to download grids or parts + of grids from a online repository. When opted in, users will no longer have to + manually fetch grid files and place them in PROJ_LIB. + Full and accurate capability of the software will no longer require hundreds + of megabytes of grid shift files in advance, even if only just a few of them + are needed for the transformations done by the user. +- Local caching of grid files, or even part of files, so that users end up + mirroring what they actually use. +- A grid shift format, for both horizontal and vertical shift grids (and in + potential future steps, for other needs, such as deformation models) will be + implemented. + +The use of grids locally available will of course still be available, and will +be the default behavior. + +Network access to grids +------------------------------------------------------------------------------- + +curl will be an optional build dependency of PROJ, added in autoconf and cmake +build systems. It can be disabled at build time, but this must be +an explicit setting of configure/cmake as the resulting builds have less functionality. +When curl is enabled at build time, download of grids themselves will not be +enabled by default at runtime. It will require explicit consent of the user, either +through the API +(:c:func:`proj_context_set_enable_network`) through the PROJ_NETWORK=ON +environment variable, or the ``network = on`` setting of proj.ini. + +Regarding the minimum version of libcurl required, given GDAL experience that +can build with rather ancient libcurl for similar functionality, we can aim for +libcurl >= 7.29.0 (as being available in RHEL 7). + +An alternate pluggable network interface can also be set by the user in case +support for libcurl was not built in, or if for the desired context of use, the +user wishes to provide the network implementation (a typical use case could be +QGIS that would use its QT-based networking facilities to solve issues with +SSL, proxy, authentication, etc.) + +A text configuration file, installed in ${installation_prefix}/share/proj/proj.ini +(or ${PROJ_LIB}/proj.ini) +will contain the URL of the CDN that will be used. +The user may also override this setting with the +:c:func:`proj_context_set_url_endpoint` or through the PROJ_NETWORK_ENDPOINT +environment variable. + +The rationale for putting proj.ini in that location is +that it is a well-known place by PROJ users, with the existing PROJ_LIB mechanics +for systems like Windows where hardcoded paths at runtime aren't generally usable. + +C API ++++++ + +The preliminary C API for the above is: + +.. code-block:: c + + /** Enable or disable network access. + * + * @param ctx PROJ context, or NULL + * @return TRUE if network access is possible. That is either libcurl is + * available, or an alternate interface has been set. + */ + int proj_context_set_enable_network(PJ_CONTEXT* ctx, int enable); + + /** Define URL endpoint to query for remote grids. + * + * This overrides the default endpoint in the PROJ configuration file or with + * the PROJ_NETWORK_ENDPOINT environment variable. + * + * @param ctx PROJ context, or NULL + * @param url Endpoint URL. Must NOT be NULL. + */ + void proj_context_set_url_endpoint(PJ_CONTEXT* ctx, const char* url); + + /** Opaque structure for PROJ. Implementations might cast it to their + * structure/class of choice. */ + typedef struct PROJ_NETWORK_HANDLE PROJ_NETWORK_HANDLE; + + /** Network access: open callback + * + * Should try to read the size_to_read first bytes at the specified offset of + * the file given by URL url, + * and write them to buffer. *out_size_read should be updated with the actual + * amount of bytes read (== size_to_read if the file is larger than size_to_read). + * During this read, the implementation should make sure to store the HTTP + * headers from the server response to be able to respond to + * proj_network_get_header_value_cbk_type callback. + * + * error_string_max_size should be the maximum size that can be written into + * the out_error_string buffer (including terminating nul character). + * + * @return a non-NULL opaque handle in case of success. + */ + typedef PROJ_NETWORK_HANDLE* (*proj_network_open_cbk_type)( + PJ_CONTEXT* ctx, + const char* url, + unsigned long long offset, + size_t size_to_read, + void* buffer, + size_t* out_size_read, + size_t error_string_max_size, + char* out_error_string, + void* user_data); + + /** Network access: close callback */ + typedef void (*proj_network_close_cbk_type)(PJ_CONTEXT* ctx, + PROJ_NETWORK_HANDLE* handle, + void* user_data); + + /** Network access: get HTTP headers */ + typedef const char* (*proj_network_get_header_value_cbk_type)( + PJ_CONTEXT* ctx, + PROJ_NETWORK_HANDLE* handle, + const char* header_name, + void* user_data); + + /** Network access: read range + * + * Read size_to_read bytes from handle, starting at offset, into + * buffer. + * During this read, the implementation should make sure to store the HTTP + * headers from the server response to be able to respond to + * proj_network_get_header_value_cbk_type callback. + * + * error_string_max_size should be the maximum size that can be written into + * the out_error_string buffer (including terminating nul character). + * + * @return the number of bytes actually read (0 in case of error) + */ + typedef size_t (*proj_network_read_range_type)( + PJ_CONTEXT* ctx, + PROJ_NETWORK_HANDLE* handle, + unsigned long long offset, + size_t size_to_read, + void* buffer, + size_t error_string_max_size, + char* out_error_string, + void* user_data); + + /** Define a custom set of callbacks for network access. + * + * All callbacks should be provided (non NULL pointers). + * + * @param ctx PROJ context, or NULL + * @param open_cbk Callback to open a remote file given its URL + * @param close_cbk Callback to close a remote file. + * @param get_header_value_cbk Callback to get HTTP headers + * @param read_range_cbk Callback to read a range of bytes inside a remote file. + * @param user_data Arbitrary pointer provided by the user, and passed to the + * above callbacks. May be NULL. + * @return TRUE in case of success. + */ + int proj_context_set_network_callbacks( + PJ_CONTEXT* ctx, + proj_network_open_cbk_type open_cbk, + proj_network_close_cbk_type close_cbk, + proj_network_get_header_value_cbk_type get_header_value_cbk, + proj_network_read_range_type read_range_cbk, + void* user_data); + + +To make network access efficient, PROJ will internally have a in-memory cache +of file ranges to only issue network requests by chunks of 16 KB or multiple of them, +to limit the number of HTTP GET requests and minimize latency caused by network +access. This is very similar to the behavior of the GDAL +`/vsicurl/ <https://gdal.org/user/virtual_file_systems.html#vsicurl-http-https-ftp-files-random-access>`_ +I/O layer. The plan is to mostly copy GDAL's vsicurl implementation inside PROJ, with +needed adjustments and proper namespacing of it. + +A retry strategy (typically a delay with an exponential back-off and some random +jitter) will be added to account for intermittent network or server-side failure. + +URL building +++++++++++++ + +The PROJ database has a ``grid_transformation`` grid whose column ``grid_name`` +(and possibly ``grid2_name``) contain the name of the grid as indicated by the +authority having registered the transformation (typically EPSG). As those +grid names are not generally directly usable by PROJ, the PROJ database has +also a ``grid_alternatives`` table that link original grid names to the ones used +by PROJ. When network access will be available and needed due to lack of a +local grid, the full URL will be the +endpoint from the configuration or set by the user, the basename of the PROJ +usable filename, and the "tif" suffix. So if the CDN is at http://example.com +and the name from ``grid_alternatives`` is egm96_15.gtx, then the URL will +be http://example.com/egm96_15.tif + +Grid loading +++++++++++++ + +The following files will be affected, in one way or another, by the above describes +changes: +nad_cvt.cpp, nad_intr.cpp, nad_init.cpp, grid_info.cpp, grid_list.cpp, apply_gridshift.cpp, +apply_vgridshift.cpp. + +In particular the current logic that consists to ingest all the values of a +grid/subgrid in the ct->cvs array will be completely modified, to enable +access to grid values at a specified (x,y) location. + +proj_create_crs_to_crs() / proj_create_operations() impacts ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Once network access is available, all grids known to the PROJ database +(grid_transformation + grid_alternatives table) will be assumed to be available, +when computing the potential pipelines between two CRS. + +Concretely, this will be equivalent to calling +:cpp:func:`proj_operation_factory_context_set_grid_availability_use` +with the ``use`` argument set to a new enumeration value + +.. code-block:: c + + /** Results will be presented as if grids known to PROJ (that is + * registered in the grid_alternatives table of its database) were + * available. Used typically when networking is enabled. + */ + PROJ_GRID_AVAILABILITY_KNOWN_AVAILABLE + + +Local on-disk caching of remote grids ++++++++++++++++++++++++++++++++++++++ + +As many workflows will tend to use the same grids over and over, a local +on-disk caching of remote grids will be added. The cache will be a single +SQLite3 database, in a user-writable directory shared by all applications using +PROJ. + +Its total size will be configurable, with a default maximum size of 100 MB +in proj.ini. The cache will also keep the timestamp of the last time it checked +various global properties of the file (its size, Last-Modified and ETag headers). +A time-to-live parameter, with a default of 1 day in proj.ini, will be used to +determine whether the CDN should be hit to verify if the information in the +cache is still up-to-date. + +.. code-block:: c + + /** Enable or disable the local cache of grid chunks + * + * This overrides the setting in the PROJ configuration file. + * + * @param ctx PROJ context, or NULL + * @param enabled TRUE if the cache is enabled. + */ + void proj_grid_cache_set_enable(PJ_CONTEXT *ctx, int enabled); + + /** Override, for the considered context, the path and file of the local + * cache of grid chunks. + * + * @param ctx PROJ context, or NULL + * @param fullname Full name to the cache (encoded in UTF-8). If set to NULL, + * caching will be disabled. + */ + void proj_grid_cache_set_filename(PJ_CONTEXT* ctx, const char* fullname); + + /** Override, for the considered context, the maximum size of the local + * cache of grid chunks. + * + * @param ctx PROJ context, or NULL + * @param max_size_MB Maximum size, in mega-bytes (1024*1024 bytes), or + * negative value to set unlimited size. + */ + void proj_grid_cache_set_max_size(PJ_CONTEXT* ctx, int max_size_MB); + + /** Override, for the considered context, the time-to-live delay for + * re-checking if the cached properties of files are still up-to-date. + * + * @param ctx PROJ context, or NULL + * @param ttl_seconds Delay in seconds. Use negative value for no expiration. + */ + void proj_grid_cache_set_ttl(PJ_CONTEXT* ctx, int ttl_seconds); + + /** Clear the local cache of grid chunks. + * + * @param ctx PROJ context, or NULL. + */ + void proj_grid_cache_clear(PJ_CONTEXT* ctx); + +The planned database structure is: + +.. code-block:: sql + + -- General properties on a file + CREATE TABLE properties( + url TEXT PRIMARY KEY NOT NULL, + lastChecked TIMESTAMP NOT NULL, + fileSize INTEGER NOT NULL, + lastModified TEXT, + etag TEXT + ); + + -- Store chunks of data. To avoid any potential fragmentation of the + -- cache, the data BLOB is always set to the maximum chunk size of 16 KB + -- (right padded with 0-byte) + -- The actual size is stored in chunks.data_size + CREATE TABLE chunk_data( + id INTEGER PRIMARY KEY AUTOINCREMENT CHECK (id > 0), + data BLOB NOT NULL + ); + + -- Record chunks of data by (url, offset) + CREATE TABLE chunks( + id INTEGER PRIMARY KEY AUTOINCREMENT CHECK (id > 0), + url TEXT NOT NULL, + offset INTEGER NOT NULL, + data_id INTEGER NOT NULL, + data_size INTEGER NOT NULL, + CONSTRAINT fk_chunks_url FOREIGN KEY (url) REFERENCES properties(url), + CONSTRAINT fk_chunks_data FOREIGN KEY (data_id) REFERENCES chunk_data(id) + ); + CREATE INDEX idx_chunks ON chunks(url, offset); + + -- Doubly linked list of chunks. The next link is to go to the least-recently + -- used entries. + CREATE TABLE linked_chunks( + id INTEGER PRIMARY KEY AUTOINCREMENT CHECK (id > 0), + chunk_id INTEGER NOT NULL, + prev INTEGER, + next INTEGER, + CONSTRAINT fk_links_chunkid FOREIGN KEY (chunk_id) REFERENCES chunks(id), + CONSTRAINT fk_links_prev FOREIGN KEY (prev) REFERENCES linked_chunks(id), + CONSTRAINT fk_links_next FOREIGN KEY (next) REFERENCES linked_chunks(id) + ); + CREATE INDEX idx_linked_chunks_chunk_id ON linked_chunks(chunk_id); + + -- Head and tail pointers of the linked_chunks. The head pointer is for + -- the most-recently used chunk. + -- There should be just one row in this table. + CREATE TABLE linked_chunks_head_tail( + head INTEGER, + tail INTEGER, + CONSTRAINT lht_head FOREIGN KEY (head) REFERENCES linked_chunks(id), + CONSTRAINT lht_tail FOREIGN KEY (tail) REFERENCES linked_chunks(id) + ); + INSERT INTO linked_chunks_head_tail VALUES (NULL, NULL); + +The chunks table will store 16 KB chunks (or less for terminating chunks). +The linked_chunks and linked_chunks_head_tail table swill act as a doubly linked +list of chunks, with the least recently used ones at the end of the list, which +will be evicted when the cache saturates. + +The directory used to locate this database will be ${XDG_DATA_HOME}/proj +(per https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) +where ${XDG_DATA_HOME} defaults to ${HOME}/.local/share on Unix builds +and ${LOCALAPPDATA} on Windows builds. Exact details to be sorted out, but +https://github.com/ActiveState/appdirs/blob/a54ea98feed0a7593475b94de3a359e9e1fe8fdb/appdirs.py#L45-L97 +can be a good reference. + +As this database might be accessed by several threads or processes at the same +time, the code accessing to it will carefully honour SQLite3 errors regarding +to locks, to do appropriate retries if another thread/process is currently +locking the database. Accesses requiring a modification of the database will +start with a BEGIN IMMEDIATE transaction so as to acquire a write lock. + +.. note:: This database should be hosted on a local disk, not a network one. + Otherwise SQLite3 locking issues are to be expected. + +CDN provider +++++++++++++ + +`Amazon Public Datasets <https://aws.amazon.com/opendata/public-datasets/>`_ +has offered to be a storage and CDN provider. + +The program covers storage and egress (bandwidth) of the data. +They generally don't allow usage of CloudFront +(their CDN) as part of the program (we would usually look to have it covered +by credits), but in this instance, they would be fine to provide it. +They'd only ask that we keep the CloudFront URL "visible" (as appropriate for +the use case) so people can see where the data is hosted in case they go looking. +Their terms can be seen at https://aws.amazon.com/service-terms/ and CloudFront +has its own, small section. Those terms may change a bit from time to time for +minor changes. Major changing service terms is assumed to be unfrequent. +There are also the Public Dataset Program terms at http://aws.amazon.com/public-datasets/terms/. +Those also do not effectively change over time and are renewed on a 2 year basis. + +Criteria for grid hosting ++++++++++++++++++++++++++ + +The grids hosted on the CDN will be exactly the ones collected, +currently and in the future, by the `proj-datumgrid <https://github.com/OSGeo/proj-datumgrid/>`_ +initiative. In particular, new grids are accepted as long as +they are released under a license that is compatible with the +`Open Source Definition <https://opensource.org/osd-annotated>`_ and the source +of the grid is clearly stated and verifiable. Suitable licenses include: + +- Public domain +- X/MIT +- BSD 2/3/4 clause +- CC0 +- CC-BY (v3.0 or later) +- CC-BY-SA (v3.0 or later) + +For new grids to be transparently used by the proj_create_crs_to_crs() mechanics, +they must be registered in the PROJ database (proj.db) in the ``grid_transformation`` and +``grid_alternatives`` table. The nominal path to have a new record in the grid_transformation +is to have a transformation being registered in the EPSG dataset (if there is no +existing one), which will be subsequently imported into the PROJ database. + +Versioning, historical preservation of grids +++++++++++++++++++++++++++++++++++++++++++++ + +The policy regarding this should be similar to the one applied to +`proj-datumgrid <https://github.com/OSGeo/proj-datumgrid/>`_, which even if +not formalized, is around the following lines: + +- Geodetic agencies release regularly new version of grids. Typically for the + USA, NOAA has released GEOID99, GEOID03, GEOID06, GEOID09, GEOID12A, GEOID12B, + GEOID18 for the NAVD88 to NAD83/NAD83(2011) vertical adjustments. Each of these + grids is considered by EPSG and PROJ has a separate object, with distinct filenames. + The release of a new version does not cause the old grid to be automatically removed. + That said, due to advertized accuracies and supersession rules of the EPSG dataset, the + most recent grid will generally be used for a CRS -> CRS transformation if the + user uses proj_create_crs_to_crs() (with the exception that if a VERT_CRS WKT + includes a GEOID_MODEL known to PROJ, an old version of the grid will be used). + If the user specifies a whole pipeline with an explicit grid name, it will be + of course strictly honoured. + As time goes, the size of the datasets managed by proj-datumgrid will be increasing, + we will have to explore on we managed that for the distributed .zip / .tar.gz + archives. This should not be a concern for CDN hosted content. + +- In case software-related conversion errors from the original grid format to the + one used by PROJ (be it GTX, NTv2 or GeoTIFF) would happen, the previous erroneous + version of the dataset would be replaced by the corrected one. In that situation, + this might have an effect with the local on-disk caching of remote grids. We will + have to see with the CDN providers used if we can use for example the ETag HTTP header + on the client to detect a change, so that old cached content is not erroneously + reused (if not possible, we'll have to use some text file listing the grid names and their + current md5sum) + + +Grids in GeoTIFF format +------------------------------------------------------------------------------- + +Limitations of current formats +++++++++++++++++++++++++++++++ + +Several formats exist depending on the ad-hoc needs and ideas of the original +data producer. It would be appropriate to converge on a common format able to +address the different use cases. + +- Not tiled. Tiling is a nice to have property for cloud-friendly access to + large files. +- No support for compression +- The NTv2 structures is roughly: header of main grid, data of main grid, + header of subgrid 1, data of subgrid 1, header of subgrid 2, data of subgrid 2, + etc.Due to the headers being scattered through the file, it is not possibly + to retrieve with a single HTTP GET request all header information. +- GTX format has no provision to store metadata besides the minimum georeferencing + of the grid. NTv2 is a bit richer, but no extensible metadata possible. + +Discussion on choice of format +++++++++++++++++++++++++++++++ + +We have been made recently aware of other initiatives from the industry to come +with a common format to store geodetic adjustment data. Some discussions have +happen recently within the OGC CRS Working group. Past efforts include the +Esri's proposed Geodetic data Grid eXchange Format, GGXF, briefly mentioned at +page 86 of +https://iag.dgfi.tum.de/fileadmin/IAG-docs/Travaux2015/01_Travaux_Template_Comm_1_tvd.pdf +and page 66 of ftp://ftp.iaspei.org/pub/meetings/2010-2019/2015-Prague/IAG-Geodesy.pdf +The current trend of those works would be to use a netCDF / HDF5 container. + +So, for the sake of completeness, we list hereafter a few potential candidate +formats and their pros and cons. + +TIFF/GeoTIFF +************ + +Strong points: + +* TIFF is a well-known and widespread format. + +* The GeoTIFF encoding is a widely industry supported scheme to encode georeferencing. + It is now a `OGC standard <https://www.opengeospatial.org/standards/geotiff>`_ + +* There are independent initiatives to share grids as GeoTIFF, like + `that one <https://www.agisoft.com/downloads/geoids/>`_ + +* TIFF can contain multiple images (IFD: Image File Directory) chained together. + This is the mechanism used for multiple-page scanned TIFF files, or in the + geospatial field to store multi-resolution/pyramid rasters. So it can be + used with sub-grids as in the NTv2 format. + +* Extensive experience with the TIFF format, and its appropriateness for network + access, in particular through the `Cloud Optimized GeoTIFF initiative <https://www.cogeo.org/>`_ + whose layout can make use of sub-grids efficient from a network access + perspective, because grid headers can be put at the beginning of the file, and + so being retrieved in a single HTTP GET request. + +* TIFF can be tiled. + +* TIFF can be compressed. Commonly found compression formats are DEFLATE, LZW, + combined with differential integer or floating point predictors + +* A TIFF image can contain a configurable number of channels/bands/samples. + In the rest of the document, we will use the sample terminology for this concept. + +* TIFF sample organization can be configured: either the values of different + samples are packed together (`PlanarConfiguration <https://www.awaresystems.be/imaging/tiff/tifftags/planarconfiguration.html>`_ = Contig), or put in separate tiles/strips + (PlanarConfiguration = Separate) + +* libtiff is a dependency commonly found in binary distributions of the + "ecosystem" to which PROJ belongs too + +* libtiff benefits from many years of efforts to increase its security, for + example being integrated to the oss-fuzz initiative. Given the potential + fetching of grids, using security tested components is an important concern. + +* Browser-side: there are "ports" of libtiff/libgeotiff in the browser such + as https://geotiffjs.github.io/ which could potentially make a port of PROJ + easier. + +Weak points: + +* we cannot use libgeotiff, since it depends itself on PROJ (to resolve CRS + or components of CRS from their EPSG codes). That said, for PROJ intended + use, we only need to decode the ModelTiepointTag and ModelPixelScaleTag TIFF + tags, so this can be done "at hand" + +* the metadata capabilities of TIFF baseline are limited. The TIFF format comes + with a predefined set of metadata items whose keys have numeric values. That + said, GDAL has used for the last 20 years or so a dedicated tag, + `GDAL_METADATA <https://www.awaresystems.be/imaging/tiff/tifftags/gdal_metadata.html>`_ + of code 42112 that holds a XML-formatted string being able to store arbitrary + key-pair values. + +netCDF v3 +********* + +Strong points: + +* The binary format description as given in + `OGC 10-092r3 <http://portal.opengeospatial.org/files/?artifact_id=43734>`_ is relatively simple, + but it would still probably be necessary to use libnetcdf-c to access it + +* Metadata can be stored easily in netCDF attributes + + +Weak points: + +* No compression in netCDF v3 + +* No tiling in netCDF v3 + +* Multi-samples variables are located in different sections of the files + (correspond to TIFF PlanarConfiguration = Separate) + +* No natural way of having hierarchical / multigrids. They must be encoded as + separate variables + +* georeferencing in netCDF is somewhat less standardized than TIFF/GeoTIFF. + The generally used model is `the conventions for CF (Climate and Forecast) + metadata <http://cfconventions.org/>`_ + but there is nothing really handy in them for simple georeferencing with + the coordinate of the upper-left pixel and the resolution. The practice is + to write explicit lon and lat variables with all values taken by the grid. + GDAL has for many years supported a simpler syntax, using a GeoTransform + attribute. + +* From the format description, its layout could be relatively cloud friendly, + except that libnetcdf has no API to plug an alternate I/O layer. + +* Most binary distributions of netCDF nowadays are based on libnetcdf v4, which + implies the HDF5 dependency. + +* From a few issues we identified a few years ago regarding crashes on corrupted + datasets, we contacted libnetcdf upstream, but they did not seem to be + interested in addressing those security issues. + +netCDF v4 / HDF5 +**************** + +Note: The netCDF v4 format is a profile of the HDF5 file format. + +Strong points: + +* Compression supported (ZLIB and SZIP predefined) + +* Tiling (chunking) supported + +* Values of Multi-sample variables can be interleaved together (similarly + to TIFF PlanarConfiguration = Contig) by using compound data types. + +* Hierarchical organization with groups + +* While the netCDF API does not provide an alternate I/O layer, this is + possible with the HDF5 API. + +* Grids can be indexed by more than 2 dimensions (for current needs, we + don't need more than 2D support) + +Weak points: + +* The `HDF 5 File format <https://support.hdfgroup.org/HDF5/doc/H5.format.html>`_ + is more complex than netCDF v3, and likely more than TIFF. We do not have + in-depth expertise of it to assess its cloud-friendliness. + +* The ones mentioned for netCDF v3 regarding georeferencing and security apply. + + +GeoPackage +********** + +As PROJ has already a SQLite3 dependency, GeoPackage could be examined as a +potential solution. + +Strong points: + +* SQLite3 dependency + +* OGC standard + +* Multi-grid capabilities + +* Tiling + +* Compression + +* Metadata capabilities + +Weak points: + +* GeoPackage mostly address the RGB(A) Byte use case, or via the tile gridded + data extension, single-sample non-Byte data. No native support for multi-sample + non-Byte data: each sample should be put in a separate raster table. + +* Experience shows that SQLite3 layout (at least the layout adopted when using + the standard libsqlite3) is not cloud friendly. Indices may be scattered in + different places of the file. + +Conclusions +*********** + +The 2 major contenders regarding our goals and constraints are GeoTIFF and HDF5. +Given past positive experience and its long history, GeoTIFF remains our preferred +choice. + + +.. _description_geotiff_format: + +Format description +++++++++++++++++++ + +The format description is available in a dedicated :ref:`geodetictiffgrids` +document. + +Tooling ++++++++ + +A script will be developed to accept a list of individual grids to combine +together into a single file. + +A ntv2_to_gtiff.py convenience script will be created to convert NTv2 grids, +including their subgrids, to the above +described GeoTIFF layout. + +A validation Python script will be created to check that a file meets the above +described requirements and recommendations. + +Build requirements +++++++++++++++++++ + +The minimum libtiff version will be 4.0 (RHEL 7 ships with libtiff 4.0.3). +To be able to read grids stored on the CDN, libtiff will need to build against +zlib to have DEFLATE and LZW support, which is met by all known binary distributions +of libtiff. + +The libtiff dependency can be disabled at build time, but this must be +an explicit setting of configure/cmake as the resulting builds have less functionality. + +Dropping grid catalog functionality +------------------------------------------------------------------------------- + +While digging through existing code, I more or less discovered that the PROJ +code base has the concept of a grid catalog. This is a feature apparently triggered by +using the +catalog=somefilename.csv in a PROJ string, where the CSV file list +grid names, their extent, priority and date. It seems to be an alternative to using ++nadgrids with multiple grids, with the extra ability to interpolate shift values between +several grids if a +date parameter is provided and the grid catalog mentions a +date for each grids. +It was added in June 2012 per `commit fcb186942ec8532655ff6cf4cc990e5da669a3bc +<https://github.com/OSGeo/PROJ/commit/fcb186942ec8532655ff6cf4cc990e5da669a3bc>`_ + +This feature is likely unknown to most users as there is no known documentation for +it (neither in current documentation, nor in `historic one <https://web.archive.org/web/20160601000000*/http://trac.osgeo.org/proj/wiki/GenParms>`_). +It is not either tested by PROJ tests, so its working status is unknown. It would +likely make implementation of this RFC easier if this was removed. This would result in +completely dropping the gridcatalog.cpp and gc_reader.cpp files, their call sites +and the catalog_name and datum_date parameter from the PJ structure. + +In case similar functionality would be be needed, it might be later reintroduced +as an extra mode of :ref:`hgridshift`, or using a dedicated transformation method, +similarly to the :ref:`deformation` one, +and possibly combining the several grids to interpolate among in the same file, +with a date metadata item. + +Backward compatibility issues +------------------------------------------------------------------------------- + +None anticipated, except the removal of the (presumably little used) grid catalog +functionality. + +Potential future related work +----------------------------- + +The foundations set in the definition of the GeoTIFF grid format should hopefully +be reused to extend them to support deformation models (was initially discussed +per https://github.com/OSGeo/PROJ/issues/1001). + +Definition of such an extension is out of scope of this RFC. + +Documentation +------------------------------------------------------------------------------- + +- New API function will be documented. +- A dedicated documentation page will be created to explain the working of + network-based access. +- A dedicated documentation page will be created to describe the GeoTIFF based + grid format. Mostly reusing above material. + +Testing +------------------------------------------------------------------------------- + +Number of GeoTIFF formulations (tiled vs untiled, PlanarConfiguration Separate vs +Contig, data types, scale+offset vs not, etc.) will be tested. + +For testing of network capabilities, a mix of real hits to the CDN and use of +the alternate pluggable network interface to test edge cases will be used. + +Proposed implementation +------------------------------------------------------------------------------- + +A proposed implementation is available at https://github.com/OSGeo/PROJ/pull/1817 + +Tooling scripts are currently available at https://github.com/rouault/sample_proj_gtiff_grids/ +(will be ultimately stored in PROJ repository) + +Adoption status +------------------------------------------------------------------------------- + +The RFC was adopted on 2020-01-10 with +1's from the following PSC members + +* Kristian Evers +* Even Rouault +* Thomas Knudsen +* Howard Butler +* Kurt Schwehr diff --git a/_sources/community/rfc/rfc-5.rst.txt b/_sources/community/rfc/rfc-5.rst.txt new file mode 100644 index 00000000..44811d58 --- /dev/null +++ b/_sources/community/rfc/rfc-5.rst.txt @@ -0,0 +1,135 @@ +.. _rfc5: + +==================================================================== +PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ +==================================================================== + +:Author: Even Rouault +:Contact: even.rouault@spatialys.com +:Status: Adopted +:Implementation target: PROJ 7 +:Last Updated: 2020-01-28 + +Motivation +------------------------------------------------------------------------------- + +This RFC is a continuation of :ref:`rfc4`. With RFC4, PROJ can, upon request +of the user, download grids from a CDN in a progressive way. There is also API, +such as :cpp:func:`proj_download_file` to be able to download a GeoTIFF grid in +the user writable directory. The content of the CDN at https://cdn.proj.org +is https://github.com/OSGeo/PROJ-data , which has the same content +as https://github.com/OSGeo/proj-datumgrid converted in GeoTIFF files. In the +current state, we could have a somewhat inconsistency between users relying on +the proj-datumgrid, proj-datumgrid-[world,northamerica,oceania,europe] packages +of mostly NTv2 and GTX files, and what is shipped through the CDN. Maintaining +two repositories is also a maintenance burden in the long term. + +It is thus desirable to have a single source of truth, and we propose it to be +based on the GeoTIFF grids. + +Summary of work planned by this RFC and related decisions +------------------------------------------------------------------------------- + +- https://github.com/OSGeo/PROJ-data/ will be used, starting with + PROJ 7.0, to create "static" grid packages. + +- For now, a single package of, mostly GeoTIFF grids (a few text files for + PROJ init style files, as well as a few edge cases for deformation models where + grids have not been converted), will be delivered. + Its size at the time of writing is 486 MB (compared to 1.5 GB of uncompressed + NTv2 + GTX content, compressed to ~ 700 MB currently) + +- The content of this archive will be flat, i.e. no subdirectories + +- Each file will be named according to the following pattern + ``${agency_name}_${filename}[.ext]``. For example fr_ign_ntf_r93.tif + This convention should allow packagers, if the need arise, to be able to + split the monolithic package in smaller ones, based on criterion related to + the country. + + The agency name is the one you can see from the directory names at + https://github.com/OSGeo/PROJ-data/. + ``${agency_name}`` itself is structure like ``${two_letter_country_code_of_agency_nationality}_${some_abbreviation}`` + (with the exception of eur_nkg, for the Nordic Geodetic Commission which + isn't affiliated to a single country but to some European countries, and + follows the general scheme) + +- https://github.com/OSGeo/proj-datumgrid and related packages will only be + maintained during the remaining lifetime of PROJ 6.x. After that, the + repository will no longer receive any update and will be put in archiving + state (see https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-archiving-repositories) + +- PROJ database ``grid_alternatives`` table will be updated to point to the new + TIFF filenames. It will also maintain the old names as used by current + proj-datumgrid packages to be able to provide backward compatibility when + a PROJ string refers to a grid by its previous name. + +- Upon adoption of this RFC, new grids referenced by PROJ database will only + point to GeoTIFF grid names. + +- Related to the above point, if a PROJ string refers to a grid name, let's + say foo.gsb. This grid will first be looked for in all the relevant locations + under this name. If no match is found, then a lookup in the + ``grid_alternatives`` table will be done to retrieve the potential new name + (GeoTIFF file), and if there's such match, a new look-up in the file system + will be done with the name of this GeoTIFF file. + +- The ``package_name`` column of grid_alternatives will no longer be filled. + And ``url`` will be filled with the direct URL to the grid in the CDN, for + example: https://cdn.proj.org/fr_ign_ntf_r93.tif + +- The Python scripts to convert grids (NTv2, GTX) to GeoTIFF currently available at + https://github.com/rouault/sample_proj_gtiff_grids/ will be moved to a + grid_tools/ subdirectories of https://github.com/OSGeo/PROJ-data/ + Documentation for those utilities will be added to PROJ documentation. + +- Obviously, all the above assumes PROJ builds to have libtiff enabled. + Non-libtiff builds are not considered as nominal PROJ builds (if a PROJ master + build is attempted and libtiff is not detected, it fails. The user has to + explicitly ask to disable TIFF support), and users deciding to go through that + route will have to deal with the consequences (that is that + grid-based transformations generated by PROJ will likely be non working) + +Backward compatibility +------------------------------------------------------------------------------- + +This change is considered to be *mostly* backward compatible. There might be +impacts for software using :cpp:func:`proj_coordoperation_get_grid_used` and +assuming that the url returned is one of the proj-datumgrid-xxx files at +https://download.osgeo.org. As mentioned in +https://lists.osgeo.org/pipermail/proj/2020-January/009274.html , this +assumption was not completely bullet-proof either. +There will be impacts on software checking the value of PROJ pipeline strings +resulting :cpp:func:`proj_create_crs_to_crs`. The new grid names will now +be returned (the most impacted software will likely be PROJ's own test suite) + +Although discouraged, people not using the new proj-datumgrid-geotiff-XXX.zip +archives, should still be able to use the old archives made of NTv2/GTX files, +at least as long as the PROJ database does not only point to a GeoTIFF grid. +So this might be a short-term partly working solution, but at time goes, it +will become increasingly non-working. The nominal combination will be +PROJ 7.0 + proj-datumgrid-geotiff-1.0.zip + +Testing +------------------------------------------------------------------------------- + +PROJ test suite will have to be adapted for the new TIFF based filenames. + +Mechanism to auto-promote existing NTv2/GTX names to TIFF ones will be exercised. + +Proposed implementation +------------------------------------------------------------------------------- + +https://github.com/OSGeo/PROJ/pull/1891 and https://github.com/OSGeo/PROJ-data/pull/5 + +Adoption status +------------------------------------------------------------------------------- + +The RFC was adopted on 2020-01-28 with +1's from the following PSC members + +* Kristian Evers +* Even Rouault +* Thomas Knudsen +* Howard Butler +* Kurt Schwehr + diff --git a/_sources/community/rfc/rfc-6.rst.txt b/_sources/community/rfc/rfc-6.rst.txt new file mode 100644 index 00000000..ed8115df --- /dev/null +++ b/_sources/community/rfc/rfc-6.rst.txt @@ -0,0 +1,368 @@ +.. _rfc6: + +==================================================================== +PROJ RFC 6: Triangulation-based transformations +==================================================================== + +:Author: Even Rouault +:Contact: even.rouault@spatialys.com +:Status: Adopted +:Implementation target: PROJ 7.2 +:Last Updated: 2020-09-02 + +Summary +------------------------------------------------------------------------------- + +This RFC adds a new transformation method, ``tinshift`` (TIN stands for +Triangulated Irregular Network) + +The motivation for this work is to be able to handle the official transformations +created by National Land Survey of Finland, for: + +- horizontal transformation between the KKJ and ETRS89 horizontal datums +- vertical transformations between N43 and N60 heights, and N60 and N2000 heights. + +Such transformations are somehow related to traditional grid-based transformations, +except that the correction values are hold by the vertices of the triangulation, +instead of being at nodes of a grid. + +Triangulation are in a number of cases the initial product of a geodesic adjustment, +with grids being a derived product. The Swiss grids have for example +derived products of an original triangulation. + +Grid-based transformations remain very convenient to use because accessing +correction values is really easy and efficient, so triangulation-based transformations +are not meant as replacing them, but more about it being a complement, that is +sometimes necessary to be able to replicate the results of a officially vetted +transformation to a millimetric or better precision (speaking here about reproducibility +of numeric results, rather than the physical accuracy of the transformation that +might rather be centimetric). It is always possible to approach the result of +the triangulation with a grid, but that may require to adopt a small grid step, +and thus generate a grid that can be much larger than the original triangulation. + +Details +------------------------------------------------------------------------------- + +Transformation +++++++++++++++ + +A new transformation method, ``tinshift``, is added. It takes one mandatory +argument, ``file``, that points to a JSON file, which contains the triangulation +and associated metadata. Input and output coordinates must be geographic or projected. +Depending on the content +of the JSON file, horizontal, vertical or both components of the coordinates may +be transformed. + +The transformation is used like: + +:: + + $ echo 3210000.0000 6700000.0000 0 2020 | cct +proj=tinshift +file=./triangulation_kkj.json + + 209948.3217 6697187.0009 0.0000 2020 + +The transformation is invertible, with the same computational complexity than +the forward transformation. + +Algorithm ++++++++++ + +Internally, ``tinshift`` ingest the whole file into memory. It is considered that +triangulation should be small enough for that. The above mentioned KKJ to ETRS89 +triangulation fits into 65 KB of JSON, for 1449 triangles and 767 vertices. + +When a point is transformed, one must find the triangle into which it falls into. +Instead of iterating over all triangles, we build a in-memory quadtree to speed-up +the identification of candidates triangles. On the above mentioned KKJ -> ETRS89 +triangulation, this speeds up the whole transformation by a factor of 10. The +quadtree structure is a very good compromise between the performance gain it brings +and the simplicity of its implementation (we have ported the implementation coming +from GDAL, inherit from the one used for shapefile .spx spatial indices). + +To determine if a point falls into a triangle, one computes its 3 +`barycentric coordinates <https://en.wikipedia.org/wiki/Barycentric_coordinate_system#Conversion_between_barycentric_and_Cartesian_coordinates>`_ +from its projected coordinates, :math:`\lambda_i` for :math:`i=1,2,3`. +They are real values (in the [0,1] range for a point inside the triangle), +giving the weight of each of the 3 vertices of the triangles. + +Once those weights are known, interpolating the target horizontal +coordinate is a matter of doing the linear combination of those weights with +the target horizontal coordinates at the 3 vertices of the triangle (:math:`Xt_i` and :math:`Yt_i`): + +.. math:: + + X_{target} = Xt_1 * \lambda_1 + Xt_2 * \lambda_2 + Xt_3 * \lambda_3 + + Y_{target} = Yt_1 * \lambda_1 + Yt_2 * \lambda_2 + Yt_3 * \lambda_3 + +This interpolation is exact at the vertices of the triangulation, and has linear properties +inside each triangle. It is completely equivalent to other formulations of +triangular interpolation, such as + +.. math:: + + X_{target} = A + X_{source} * B + Y_{source} * C + + Y_{target} = D + X_{source} * E + Y_{source} * F + +where the A, B, C, D, E, F constants (for a given triangle) are found by solving +the 2 systems of 3 linear equations, constraint by the source and target coordinate pairs +of the 3 vertices of the triangle: + +.. math:: + + Xt_i = A + Xs_i * B + Ys_i * C + + Yt_i = D + Xs_i * E + Ys_i * F + + +.. note:: + + From experiments, the interpolation using barycentric coordinates is slightly + more numerically robust when interpolating projected coordinates of amplitude of the + order of 1e5 / 1e6, due to computations involving differences of coordinates. + Whereas the formulation with the A, B, C, D, E, F tends to have big values for + the A and D constants, and values clause to 0 for C and E, and close to 1 for + B and F. However, the difference between the two approaches is negligible for + practical purposes (below micrometre precision) + +Similarly for a vertical coordinate transformation, where :math:`Zoff_i` is the vertical +offset at each vertex of the triangle: + +.. math:: + + Z_{target} = Z_{source} + Zoff_1 * \lambda_1 + Zoff_2 * \lambda_2 + Zoff_3 * \lambda_3 + +Constraints on the triangulation +++++++++++++++++++++++++++++++++ + +No check is done on the consistence of the triangulation. It is highly +recommended that triangles do not overlap each other (when considering the +source coordinates or the forward transformation, or the target coordinates for +the inverse transformation), otherwise which triangle will be selected is +unspecified. Besides that, the triangulation does not need to have particular +properties (like being a Delaunay triangulation) + +File format ++++++++++++ + +To the best of our knowledge, there are no established file formats to convey +geodetic transformations as triangulations. Potential similar formats to store TINs +are `ITF <http://vterrain.org/Implementation/Formats/ITF.html>`_ or +`XMS <https://www.xmswiki.com/wiki/TIN_Files>`_. +Both of them would need to be extended in order to handle datum shift information, +since they are both intended for mostly DEM use. + +We thus propose a text-based format, using JSON as a serialization. Using a text-based +format could potentially be thought as a limitation performance-wise compared to +binary formats, but for the size of triangulations considered (a few thousands triangles / vertices), +there is no issue. Loading such file is a matter of 20 milliseconds or so. For reference, +loading a triangulation of about 115 000 triangles and 71 000 vertices takes 450 ms. + +Using JSON provides generic formatting and parsing rules, and convenience to +create it from Python script for examples. This could also be easily generated "at hand" +by non-JSON aware writers. + +For generic metadata, we reuse closely what has been used for the +`Deformation model master file <https://github.com/linz/deformation-model-format>`_ + +Below a minimal example, from the KKJ to ETRS89 transformation, with just a +single triangle: + +.. code-block:: json + + { + "file_type": "triangulation_file", + "format_version": "1.0", + "name": "Name", + "version": "Version", + "publication_date": "2018-07-01T00:00:00Z", + "license": "Creative Commons Attribution 4.0 International", + "description": "Test triangulation", + "authority": { + "name": "Authority name", + "url": "http://example.com", + "address": "Address", + "email": "test@example.com" + }, + "links": [ + { + "href": "https://example.com/about.html", + "rel": "about", + "type": "text/html", + "title": "About" + }, + { + "href": "https://example.com/download", + "rel": "source", + "type": "application/zip", + "title": "Authoritative source" + }, + { + "href": "https://creativecommons.org/licenses/by/4.0/", + "rel": "license", + "type": "text/html", + "title": "Creative Commons Attribution 4.0 International license" + }, + { + "href": "https://example.com/metadata.xml", + "rel": "metadata", + "type": "application/xml", + "title": " ISO 19115 XML encoded metadata regarding the triangulation" + } + ], + "input_crs": "EPSG:2393", + "target_crs": "EPSG:3067", + "transformed_components": [ "horizontal" ], + "vertices_columns": [ "source_x", "source_y", "target_x", "target_y" ], + "triangles_columns": [ "idx_vertex1", "idx_vertex2", "idx_vertex3" ], + "vertices": [ [3244102.707, 6693710.937, 244037.137, 6690900.686], + [3205290.722, 6715311.822, 205240.895, 6712492.577], + [3218328.492, 6649538.429, 218273.648, 6646745.973] ], + "triangles": [ [0, 1, 2] ] + } + +So after the generic metadata, we define the input and output CRS (informative +only), and that the transformation affects horizontal components of +coordinates. We name the columns of the ``vertices`` and ``triangles`` arrays. +We defined the source and target coordinates of each vertex, and define a +triangle by referring to the index of its vertices in the ``vertices`` array. + +More formally, the specific items for the triangulation file are: + +input_crs + String identifying the CRS of source coordinates + in the vertices. Typically ``EPSG:XXXX``. If the transformation is for vertical + component, this should be the code for a compound CRS (can be EPSG:XXXX+YYYY + where XXXX is the code of the horizontal CRS and YYYY the code of the vertical CRS). + For example, for the KKJ->ETRS89 transformation, this is EPSG:2393 + (``KKJ / Finland Uniform Coordinate System``). The input coordinates are assumed + to be passed in the "normalized for visualisation" / "GIS friendly" order, + that is longitude, latitude for geographic coordinates and + easting, northing for projected coordinates. + + +output_crs + String identifying the CRS of target coordinates in the vertices. + Typically ``EPSG:XXXX``. If the transformation is for vertical component, + this should be the code for a compound CRS (can be EPSG:XXXX+YYYY where + XXXX is the code of the horizontal CRS and YYYY the code of the vertical CRS). + For example, for the KKJ->ETRS89 transformation, this is EPSG:3067 + (\"ETRS89 / TM35FIN(E,N)\"). The output coordinates will be returned in + the "normalized for visualisation" / "GIS friendly" order, + that is longitude, latitude for geographic coordinates and + easting, northing for projected coordinates. + + +transformed_components + Array which may contain one or two strings: "horizontal" when horizontal + components of the coordinates are transformed and/or "vertical" when the + vertical component is transformed. + + +vertices_columns + Specify the name of the columns of the rows in the ``vertices`` + array. There must be exactly as many elements in ``vertices_columns`` as in a + row of ``vertices``. The following names have a special meaning: ``source_x``, + ``source_y``, ``target_x``, ``target_y``, ``source_z``, ``target_z`` and + ``offset_z``. ``source_x`` and ``source_y`` are compulsory. + ``source_x`` is for the source longitude (in degree) or easting. + ``source_y`` is for the source latitude (in degree) or northing. + ``target_x`` and ``target_y`` are compulsory when ``horizontal`` is specified + in ``transformed_components``. (``source_z`` and ``target_z``) or + ``offset_z`` are compulsory when ``vertical`` is specified in ``transformed_components`` + + +triangles_columns + Specify the name of the columns of the rows in the + ``triangles`` array. There must be exactly as many elements in ``triangles_columns`` + as in a row of ``triangles``. The following names have a special meaning: + ``idx_vertex1``, ``idx_vertex2``, ``idx_vertex3``. They are compulsory. + + +vertices + An array whose items are themselves arrays with as many columns as + described in ``vertices_columns``. + + +triangles + An array whose items are themselves arrays with as many columns as + described in ``triangles_columns``. + The value of the ``idx_vertexN`` columns must be indices + (between 0 and len(``vertices``-1) of items of the ``vertices`` array. + +Code impacts +++++++++++++ + +The following new files are added in src/transformations: + +- tinshift.cpp: PROJ specific code for defining the new operation. Takes care + of the input and output coordinate conversions (between input_crs and triangulation_source_crs, + and triangulation_target_crs and output_crs), when needed. +- tinshift.hpp: Header-based implementation. This file contains the API. +- tinshift_exceptions.hpp: Exceptions that can be raised during file parsing +- tinshift_impl.hpp: Implementation of file loading, triangle search and interpolation. + +This is the approach that has been followed for the deformation model implementation, +and which makes it easier to do unit test. + +src/quadtree.hpp contains a quadtree implementation. + +Performance indications ++++++++++++++++++++++++ + +Tested on Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz, transforming 4 million points + +For the KKJ to ETRS89 transformation (1449 triangles and 767 vertices), +4.4 million points / sec can be transformed. + +For comparison, the Helmert-based KKJ to ETRS89 transformation operates at +1.6 million points / sec. + +A triangulation with about 115 000 triangles and 71 000 vertices +operates at 2.2 million points / sec +(throughput on more points would be better since the initial loading of the +triangulation is non-negligible here) + +Backward compatibility +------------------------------------------------------------------------------- + +New functionality fully backward compatible. + +Testing +------------------------------------------------------------------------------- + +The PROJ test suite will be enhanced to test the new transformation, with a +new .gie file, and a C++ unit test to test at a lower level. + +Documentation +------------------------------------------------------------------------------- + +- The tinshift method will be documented. +- The JSON format will be documented under https://proj.org/specifications/ +- A JSON schema will also be provided. + +Proposed implementation +------------------------------------------------------------------------------- + +An initial implementation is available at https://github.com/rouault/PROJ/tree/tinshift + +References +------------------------------------------------------------------------------- + +`Finnish coordinate transformation (automated translation to English) <https://translate.google.fr/translate?sl=auto&tl=en&u=https%3A%2F%2Fwww.maanmittauslaitos.fi%2Fkartat-ja-paikkatieto%2Fasiantuntevalle-kayttajalle%2Fkoordinaattimuunnokset>`_ + +Adoption status +------------------------------------------------------------------------------- + +The RFC was adopted on 2020-09-02 with +1's from the following PSC members + +* Kristian Evers +* Charles Karney +* Thomas Knudsen +* Even Rouault + +Funding +------------------------------------------------------------------------------- + +This work is funded by `National Land Survey of Finland <https://www.maanmittauslaitos.fi/en>`_ diff --git a/_sources/community/rfc/rfc-7.rst.txt b/_sources/community/rfc/rfc-7.rst.txt new file mode 100644 index 00000000..b1ca3547 --- /dev/null +++ b/_sources/community/rfc/rfc-7.rst.txt @@ -0,0 +1,135 @@ +.. _rfc7: + +==================================================================== +PROJ RFC 7: Drop Autotools, maintain CMake +==================================================================== + +:Author: Mike Taves +:Contact: mwtoews@gmail.com +:Status: Adopted +:Implementation target: PROJ 9.0 +:Last Updated: 2021-10-27 + +Summary +------------------------------------------------------------------------------- + +This RFC proposes to drop Autotools for PROJ 9.0, and to maintain CMake +for build automation, testing and packaging. This will reduce the overall +maintenance for PROJ and will enable the library to be integrated into other +projects that use CMake. + +Background +------------------------------------------------------------------------------- + +Here is a short timeline of the build tools used for PROJ: + +- Throughout the mid-1990s, Gerald Evenden maintained a Unix build system with + a few scripts (some derived from Autoconf), and Makefile templates. +- In 2000, Frank Warmerdam wrote Autoconf and Automake configurations for + PROJ 4.4.0. +- This was followed by a NMake configuration to build PROJ 4.4.2 for Windows. +- In 2014, a CMake build setup was introduced by Howard Butler for + PROJ 4.9.0RC1. The CMake configuration was improved for the 4.9.1 release, + but not considered at feature parity with the Autotools builds at the time. +- The NMake build setup was removed for PROJ 6.0.0, as its functionality had + been replaced by CMake. + +Motivation +------------------------------------------------------------------------------- + +The primary motivation in removing Autotools is to reduce the burden of +maintaining multiple build configurations, which requires developers to be +familiar with different tools and configuration files. There are several other +benefits in maintaining a single build system: + +- Remove extra configuration and m4 macro files from source repository, +- Simplify scripts used for running tests for CI services (GitHub Actions, + TravisCI), +- Reduce compilation time (and carbon footprint) used for testing on CI + services, +- Ease development effort, particularly with new contributors. + +Why drop Autotools? +------------------------------------------------------------------------------- + +The GNU Build System or Autotools consist of a suite of tools including +Autoconf and Automake, which can be used to build software on Unix-like +systems. These tools are not cross-platform, and do not naively integrate +with development environments on Microsoft Windows. Furthermore, the existing +PROJ Autotools builds do not install the CMake configuration files required to +find PROJ from other projects that use CMake +(`#2546 <https://github.com/OSGeo/PROJ/issues/2546>`_). + +Why use CMake? +------------------------------------------------------------------------------- + +CMake is an open source cross-platform tool for build automation, testing and +packaging of software. It does not directly compile the software, but manages +the build process using generators, including Unix Makefiles and Ninja among +other command-based and IDE tools. The CMake software has been under active +development since its origins in 2000. The CMake language is carefully +developed with backwards-compatible policies that aim to provide consistent +behaviour across different versions. CMake is currently the preferred build +tool for PROJ for the following reasons: + +- It has existed in the PROJ code base since 2014, and is familiar to active + PROJ contributors, +- It can install configuration files that can be used by other software that + use CMake to find PROJ for linking via ``find_package()``, +- CMake configurations are used in 3rd-party binary packages of PROJ, + including conda-forge and vcpkg, +- It can be used to build PROJ on all major operating systems and compiler + combinations (where compatible), +- It has integration with modern IDEs and tools, including + Microsoft Visual Studio and Qt Creator. + +Why not CMake? +------------------------------------------------------------------------------- + +Other modern cross-platform build systems exist, including Meson and Bazel, +which have many advantages over CMake. However, they are currently not widely +used by active PROJ contributors. This RFC should not restrict future build +system configurations being introduced to PROJ, if they are proven to have +advantages to CMake over time. + +Potential impacts +------------------------------------------------------------------------------- + +Binary packagers that currently rely on Autotools would obviously need to +transition building and testing PROJ with CMake. Issues related to +multiarch builds of PROJ may become apparent, which can be patched and/or +reported to PROJ developers. One feature of Autotools is that both static and +dynamic (shared) libraries are built, which packagers may distribute. This +feature is currently not set-up for PROJ, as it would need to be configured +and built twice. + +End-users that use binary packages of PROJ should not be impacted. PROJ should +be discoverable via both pkg-config and CMake's ``find_package()``. +Other projects that use Autotools will continue to work as expected, +linking statically or dynamically to PROJ built by CMake. + +Transition plan +------------------------------------------------------------------------------- + +If this proposal is approved, the following tasks should be completed: + +- Rewrite CI tests to only use CMake for packaging, building, testing, + installation and post-install tests, +- Remove files only used by Autotools, also update ``.gitignore``, +- Update documentation and ``HOWTORELEASE`` notes. + +Related issues will be tracked on GitHub with a tag +`RFC7: Autotools→CMake <https://github.com/OSGeo/PROJ/labels/RFC7%3A%20Autotools%E2%86%92CMake>`_. + +Adoption status +------------------------------------------------------------------------------- + +The RFC was adopted on 2021-10-26 with +1's from the following PSC members + +* Kristian Evers +* Even Rouault +* Howard Butler +* Thomas Knudsen +* Kurt Schwehr +* Charles Karney +* Thomas Knudsen diff --git a/_sources/development/bindings.rst.txt b/_sources/development/bindings.rst.txt new file mode 100644 index 00000000..c2d13077 --- /dev/null +++ b/_sources/development/bindings.rst.txt @@ -0,0 +1,63 @@ +.. _bindings: + +******************************************************************************** +Language bindings +******************************************************************************** + +PROJ bindings are available for a number of different development platforms. + +Python +====== +`pyproj <https://pypi.python.org/pypi/pyproj>`_: +Python interface (wrapper for PROJ) + +Ruby +======= + +`proj4rb <https://github.com/cfis/proj4rb>`_: +Bindings for PROJ in ruby + +Rust +======= + +`proj <https://github.com/georust/proj>`_: +Rust bindings for the latest stable version of PROJ + +Go (Golang) +=========== +`go-proj <https://github.com/everystreet/go-proj>`_: +Go bindings and idiomatic wrapper for PROJ + +Julia +===== +`Proj4.jl <https://github.com/JuliaGeo/Proj4.jl>`_: +Julia bindings and idiomatic wrapper for PROJ. + +TCL +======== +`proj4tcl <http://wiki.tcl.tk/41270>`_: +Bindings for PROJ in tcl (critcl source) + +MySQL +===== + +`fProj4 <https://sourceforge.net/projects/mysqlscientific/files/fPROJ4/>`_: +Bindings for PROJ in MySQL + +Excel +======== + +`proj.xll <https://github.com/jbuonagurio/proj.xll>`_: +Excel add-in for PROJ map projections + +Visual Basic +================== + +`PROJ VB Wrappers <http://ftp.dfg.ca.gov/Public/BDB/Tools/proj4/proj_api.zip>`_: +By Eric G. Miller. + +Fortran +======= + +`Fortran-Proj <https://gitlab.com/likeno/fortran-proj>`_: +Bindings for PROJ in Fortran (By João Macedo @likeno) diff --git a/_sources/development/cmake.rst.txt b/_sources/development/cmake.rst.txt new file mode 100644 index 00000000..d1bbf42c --- /dev/null +++ b/_sources/development/cmake.rst.txt @@ -0,0 +1,38 @@ +.. _cmake: + +******************************************************************************** +Using PROJ in CMake projects +******************************************************************************** + +The recommended way to use the PROJ library in a CMake project is to +link to the imported library target ``PROJ::proj`` provided by +the CMake configuration which comes with the library. Typical usage is: + +.. code:: + + find_package(PROJ CONFIG REQUIRED) + + target_link_libraries(MyApp PRIVATE PROJ::proj) + +By adding the imported library target ``PROJ::proj`` to the +target link libraries, CMake will also pass the include directories to +the compiler. + +The CMake command ``find_package`` will look for the configuration in a +number of places. The lookup can be adjusted for all packages by setting +the cache variable or environment variable ``CMAKE_PREFIX_PATH``. In +particular, CMake will consult (and set) the cache variable +``PROJ_DIR``. + +The old CMake name for the PROJ project was "PROJ4" and the switch to +the name "PROJ" was made with version 7.0. So if you expect your +package to work with pre-7.0 versions of PROJ, you will need to use + +.. code:: + + find_package(PROJ4) + target_link_libraries(MyApp PRIVATE ${PROJ4_LIBRARIES}) + include_directories(${PROJ4_INCLUDE_DIRS}) + +This will also find version 7.0. This use of the PROJ4 name will be +phased out at some point. diff --git a/_sources/development/errorhandling.rst.txt b/_sources/development/errorhandling.rst.txt new file mode 100644 index 00000000..021d2fb7 --- /dev/null +++ b/_sources/development/errorhandling.rst.txt @@ -0,0 +1,65 @@ +.. _errorhandling: + +================================================================================ +Error handling +================================================================================ + +PROJ maintains an internal error state, which is local to a +:c:type:`PJ_CONTEXT` thread context. + +See :doc:`quickstart` for more information about how to create and use a thread +context object. + +If you receive an abnormal return from a PROJ API function (e.g. a NULL +pointer) you may wish to discover more information about the error. + +In this case you can make a call to :c:func:`proj_context_errno`, passing in +your thread context. This will return an integer error code. + +If the error code is zero, the last PROJ operation was deemed successful and no +error has been detected. + +If the error code is non-zero, an error has been detected. You can pass your +thread context together with this error code to +:c:func:`proj_context_errno_string` to retrieve a string describing the error +condition. + +A basic example showing how a C program might catch and report errors follows: + +.. code-block:: c + :caption: errorhandling.c + :linenos: + + #include <stdio.h> + #include <proj.h> + + int main (void) { + PJ_CONTEXT *c; + PJ *p; + int errno; + const char *errstr; + + c = proj_context_create(); + p = proj_create_crs_to_crs(c, "EPSG:4326", "EPSG:3857", NULL); + + if (p == 0) { + /* Something is wrong, let's try to get details ... */ + errno = proj_context_errno(c); + if (errno == 0) { + /* This should be impossible. */ + fprintf(stderr, "Failed to create transformation, reason unknown.\n"); + } else { + errstr = proj_context_errno_string(c, errno); + fprintf(stderr, "Failed to create transformation: %s.\n", errstr); + } + proj_context_destroy(c); + return 1; + } + + /* transformation object is valid, do work ... */ + + proj_destroy(p); + proj_context_destroy(c); + + return 0; + } diff --git a/_sources/development/index.rst.txt b/_sources/development/index.rst.txt new file mode 100644 index 00000000..06e1d36a --- /dev/null +++ b/_sources/development/index.rst.txt @@ -0,0 +1,47 @@ +.. _development: + +================================================================================ +Development +================================================================================ + +These pages are primarily focused towards developers either contributing to the +PROJ project or using the library in their own software. + + +.. toctree:: + :maxdepth: 1 + + quickstart + transformations + errorhandling + reference/index + cmake + bindings + migration + +The source code for PROJ is maintained in a +`git repository on GitHub <https://github.com/OSGeo/PROJ>`_. +Additionally, a collection of PROJ-compatible transformation grids +are maintained in a `separate git repository <https://github.com/OSGeo/proj-datumgrid>`_. + +.. attention:: + + The :file:`projects.h` header and the functions related to it is considered + deprecated from version 5.0.0 and onwards. The header has been removed + PROJ in version 6.0.0 released February 1st 2019. + +.. attention:: + + The nmake build system on Windows is on longer supported in + version 6.0.0 on onwards. Use CMake instead. + +.. attention:: + + The :file:`proj_api.h` header and the functions related to it is + considered deprecated from version 5.0.0 and onwards. The header has been + removed in version 8.0.0 released March 1st 2021. + +.. attention:: + + With the introduction of PROJ 5, behavioural changes has been made to + existing functionality. Consult :ref:`differences` for the details. diff --git a/_sources/development/migration.rst.txt b/_sources/development/migration.rst.txt new file mode 100644 index 00000000..4c0113e5 --- /dev/null +++ b/_sources/development/migration.rst.txt @@ -0,0 +1,387 @@ +.. _API_migration: + +================================================================================ +Version 4 to 6 API Migration +================================================================================ + +This is a transition guide for developers wanting to migrate their code to use +PROJ version 6. + +Code example +############################################################################### + +The difference between the old and new API is shown here with a few examples. Below +we implement the same program with the two different API's. The program reads +input longitude and latitude from the command line and convert them to +projected coordinates with the Mercator projection. + +We start by writing the program for PROJ 4: + +.. code-block:: C + + #include <proj_api.h> + + main(int argc, char **argv) { + projPJ pj_merc, pj_longlat; + double x, y; + int p; + + if (!(pj_longlat = pj_init_plus("+proj=longlat +ellps=clrk66")) ) + return 1; + if (!(pj_merc = pj_init_plus("+proj=merc +datum=clrk66 +lat_ts=33")) ) + return 1; + + while (scanf("%lf %lf", &x, &y) == 2) { + x *= DEG_TO_RAD; /* longitude */ + y *= DEG_TO_RAD; /* latitude */ + p = pj_transform(pj_longlat, pj_merc, 1, 1, &x, &y, NULL); + printf("%.2f\t%.2f\n", x, y); + } + + pj_free(pj_longlat); + pj_free(pj_merc); + + return 0; + } + +The same program implemented using PROJ 6: + +.. code-block:: C + + #include <proj.h> + + main(int argc, char **argv) { + PJ *P; + PJ_COORD c, c_out; + + /* NOTE: the use of PROJ strings to describe CRS is strongly discouraged */ + /* in PROJ 6, as PROJ strings are a poor way of describing a CRS, and */ + /* more precise its geodetic datum. */ + /* Use of codes provided by authorities (such as "EPSG:4326", etc...) */ + /* or WKT strings will bring the full power of the "transformation */ + /* engine" used by PROJ to determine the best transformation(s) between */ + /* two CRS. */ + P = proj_create_crs_to_crs(PJ_DEFAULT_CTX, + "+proj=longlat +ellps=clrs66", + "+proj=merc +ellps=clrk66 +lat_ts=33", + NULL); + if (P==0) + return 1; + + { + /* For that particular use case, this is not needed. */ + /* proj_normalize_for_visualization() ensures that the coordinate */ + /* order expected and returned by proj_trans() will be longitude, */ + /* latitude for geographic CRS, and easting, northing for projected */ + /* CRS. If instead of using PROJ strings as above, "EPSG:XXXX" codes */ + /* had been used, this might had been necessary. */ + PJ* P_for_GIS = proj_normalize_for_visualization(PJ_DEFAULT_CTX, P); + if( 0 == P_for_GIS ) { + proj_destroy(P); + return 1; + } + proj_destroy(P); + P = P_for_GIS; + } + + /* For reliable geographic <--> geocentric conversions, z shall not */ + /* be some random value. Also t shall be initialized to HUGE_VAL to */ + /* allow for proper selection of time-dependent operations if one of */ + /* the CRS is dynamic. */ + c.lpzt.z = 0.0; + c.lpzt.t = HUGE_VAL; + + while (scanf("%lf %lf", &c.lpzt.lam, &c.lpzt.phi) == 2) { + /* No need to convert to radian */ + c_out = proj_trans(P, PJ_FWD, c); + printf("%.2f\t%.2f\n", c_out.xy.x, c_out.xy.y); + } + + proj_destroy(P); + + return 0; + } + + +Function mapping from old to new API +############################################################################### + ++---------------------------------------+-------------------------------------------------+ +| Old API functions | New API functions | ++=======================================+=================================================+ +| ``pj_fwd`` | :c:func:`proj_trans` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_inv`` | :c:func:`proj_trans` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_fwd3`` | :c:func:`proj_trans` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_inv3`` | :c:func:`proj_trans` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_transform`` | :c:func:`proj_create_crs_to_crs` | +| | or :c:func:`proj_create_crs_to_crs_from_pj` + | +| | (:c:func:`proj_normalize_for_visualization` +) | +| | :c:func:`proj_trans`, | +| | :c:func:`proj_trans_array` or | +| | :c:func:`proj_trans_generic` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_init`` | :c:func:`proj_create` / | +| | :c:func:`proj_create_crs_to_crs` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_init`` | :c:func:`proj_create` / | +| | :c:func:`proj_create_crs_to_crs` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_free`` | :c:func:`proj_destroy` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_is_latlong`` | :c:func:`proj_get_type` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_is_geocent`` | :c:func:`proj_get_type` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_get_def`` | :c:func:`proj_pj_info` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_latlong_from_proj`` | *No direct equivalent*, but can be accomplished | +| | by chaining :c:func:`proj_create`, | +| | :c:func:`proj_crs_get_horizontal_datum` and | +| | :c:func:`proj_create_geographic_crs_from_datum` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_set_finder`` | :c:func:`proj_context_set_file_finder` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_set_searchpath`` | :c:func:`proj_context_set_search_paths` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_deallocate_grids`` | *No equivalent* | ++---------------------------------------+-------------------------------------------------+ +| ``pj_strerrno`` | *No equivalent* | ++---------------------------------------+-------------------------------------------------+ +| ``pj_get_errno_ref`` | :c:func:`proj_errno` | ++---------------------------------------+-------------------------------------------------+ +| ``pj_get_release`` | :c:func:`proj_info` | ++---------------------------------------+-------------------------------------------------+ + + +Backward incompatibilities +############################################################################### + +Access to the :file:`proj_api.h` is still possible but requires to define the +``ACCEPT_USE_OF_DEPRECATED_PROJ_API_H`` macro. + +The emulation of the now deprecated ``+init=epsg:XXXX`` syntax in PROJ 6 is not +fully compatible with previous versions. + +In particular, when used with the ``pj_transform()`` function, no datum shift term +(``towgs84``, ``nadgrids``, ``geoidgrids``) will be added during the expansion of the +``+init=epsg:XXXX`` string to ``+proj=YYYY ....``. If you still uses ``pj_transform()`` +and want datum shift to be applied, then you need to provide a fully expanded +string with appropriate ``towgs84``, ``nadgrids`` or ``geoidgrids`` terms to ``pj_init()``. + +To use the ``+init=epsg:XXXX`` syntax with :c:func:`proj_create` and then +:c:func:`proj_create_crs_to_crs`, ``proj_context_use_proj4_init_rules(ctx, TRUE)`` +or the ``PROJ_USE_PROJ4_INIT_RULES=YES`` environment variable must have been +previously set. In that context, datum shift will be researched. However they +might be different than with PROJ 4 or PROJ 5, since a "late-binding" approach +will be used (that is trying to find as much as possible the most direct +transformation between the source and target datum), whereas PROJ 4 or PROJ 5 +used an "early-binding" approach consisting in always going to EPSG:4326 / WGS 84. + + +Feedback from downstream projects on the PROJ 6 migration +############################################################################### + +* `PROJ 6 adoption by Spatialite <https://www.gaia-gis.it/fossil/libspatialite/wiki?name=PROJ.6>`_ + +* `On GDA2020, PROJ 6 and QGIS: Lessons learnt and recommendations for handling GDA2020 within geospatial software development <https://www.icsm.gov.au/sites/default/files/North%20Road%20Handling%20GDA2020%20within%20Geospatial%20Software%20Development.pdf>`_ + +================================================================================ +Version 4 to 5 API Migration +================================================================================ + +This is a transition guide for developers wanting to migrate their code to use +PROJ version 5. + + +Background +############################################################################### + +Before we go on, a bit of background is needed. The new API takes a different +view of the world than the old because it is needed in order to obtain high +accuracy transformations. The old API is constructed in such a way that any transformation +between two coordinate reference systems *must* pass through the ill-defined +WGS84 reference frame, using it as a hub. The new API does away with this limitation to +transformations in PROJ. It is still possible to do that type of transformations +but in many cases there will be a better alternative. + +The world view represented by the old API is always sufficient if all you care about is +meter level accuracy - and in many cases it will provide much higher accuracy +than that. But the view that “WGS84 is the *true* foundation of the world, and +everything else can be transformed natively to and from WGS84” is inherently flawed. + +First and foremost because any time WGS84 is mentioned, you should ask yourself +“Which of the six WGS84 realizations are we talking about here?”. + +Second, because for many (especially legacy) systems, it may not be straightforward +to transform to WGS84 (or actually ITRF-something, ETRS-something or NAD-something +which appear to be the practical meaning of the term WGS84 in everyday PROJ related +work), while centimeter-level accurate transformations may exist between pairs of +older systems. + +The concept of a hub reference frame (“datum”) is not inherently bad, but in many +cases you need to handle and select that datum with more care than the old API allows. +The primary aim of the new API is to allow just that. And to do that, you must realize +that the world is inherently 4 dimensional. You may in many cases assume one or more of +the coordinates to be constant, but basically, to obtain geodetic accuracy transformations, +you need to work in 4 dimensions. + +Now, having described the background for introducing the new API, let's try to show +how to use it. First note that in order to go from system A to system B, the old API +starts by doing an **inverse** transformation from system A to WGS84, then does a +**forward** transformation from WGS84 to system B. + +With :program:`cs2cs` being the command line interface to the old API, and +:program:`cct` being the same for the new, this example of doing the same +thing in both world views will should give an idea of the differences: + +:: + + $ echo 300000 6100000 | cs2cs +proj=utm +zone=33 +ellps=GRS80 +to +proj=utm +zone=32 +ellps=GRS80 + 683687.87 6099299.66 0.00 + + + $ echo 300000 6100000 0 0 | cct +proj=pipeline +step +inv +proj=utm +zone=33 +ellps=GRS80 +step +proj=utm +zone=32 +ellps=GRS80 + 683687.8667 6099299.6624 0.0000 0.0000 + +Lookout for the ``+inv`` in the first ``+step``, indicating an inverse transform. + + +Code example +############################################################################### + +The difference between the old and new API is shown here with a few examples. Below +we implement the same program with the two different API's. The program reads +input longitude and latitude from the command line and convert them to +projected coordinates with the Mercator projection. + +We start by writing the program for PROJ v. 4: + +.. code-block:: C + + #include <proj_api.h> + + main(int argc, char **argv) { + projPJ pj_merc, pj_longlat; + double x, y; + + if (!(pj_longlat = pj_init_plus("+proj=longlat +ellps=clrk66")) ) + return 1; + if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) ) + return 1; + + while (scanf("%lf %lf", &x, &y) == 2) { + x *= DEG_TO_RAD; /* longitude */ + y *= DEG_TO_RAD; /* latitude */ + p = pj_transform(pj_longlat, pj_merc, 1, 1, &x, &y, NULL ); + printf("%.2f\t%.2f\n", x, y); + } + + pj_free(pj_longlat); + pj_free(pj_merc); + + return 0; + } + +The same program implemented using PROJ v. 5: + +.. code-block:: C + + #include <proj.h> + + main(int argc, char **argv) { + PJ *P; + PJ_COORD c; + + P = proj_create(PJ_DEFAULT_CTX, "+proj=merc +ellps=clrk66 +lat_ts=33"); + if (P==0) + return 1; + + while (scanf("%lf %lf", &c.lp.lam, &c.lp.phi) == 2) { + c.lp.lam = proj_torad(c.lp.lam); + c.lp.phi = proj_torad(c.lp.phi); + c = proj_trans(P, PJ_FWD, c); + printf("%.2f\t%.2f\n", c.xy.x, c.xy.y); + } + + proj_destroy(P); + } + +Looking at the two different programs, there's a few immediate +differences that catches the eye. First off, the included header file describing +the API has changed from ``proj_api.h`` to simply ``proj.h``. All functions in ``proj.h`` +belongs to the ``proj_`` namespace. + +With the new API also comes new datatypes. E.g. the transformation object ``projPJ`` +which has been changed to a pointer of type ``PJ``. This is done to highlight the +actual nature of the object, instead of hiding it away behind a typedef. New data +types for handling coordinates have also been introduced. In the above example we +use the ``PJ_COORD``, which is a union of various types. The benefit of this is that +it is possible to use the various structs in the union to communicate what state +the data is in at different points in the program. For instance as in the above +example where the coordinate is read from STDIN as a geodetic coordinate, +communicated to the reader of the code by using the ``c.lp`` struct. +After it has been projected we print it to STDOUT by accessing the individual +elements in ``c.xy`` to illustrate that the coordinate is now in projected space. +Data types are prefixed with `PJ_`. + +The final, and perhaps biggest, change is that the fundamental concept of +transformations in PROJ are now handled in a single transformation object (``PJ``) +and not by stating the source and destination systems as previously. It is of +course still possible to do just that, but the transformation object now +captures the whole transformation from source to destination in one. In the +example with the old API the source system is described as +``+proj=latlon +ellps=clrk66`` and the destination system is described as +``+proj=merc +ellps=clrk66 +lat_ts=33``. Since the Mercator projection accepts +geodetic coordinates as its input, the description of the source in this case +is superfluous. We use that to our advantage in the new API and simply state +the destination. This is simple at a glance, but is actually a big conceptual +change. We are now focused on the path between two systems instead of what the +source and destination systems are. + +Function mapping from old to new API +############################################################################### + ++---------------------------------------+---------------------------------------+ +| Old API functions | New API functions | ++=======================================+=======================================+ +| ``pj_fwd`` | :c:func:`proj_trans` | ++---------------------------------------+---------------------------------------+ +| ``pj_inv`` | :c:func:`proj_trans` | ++---------------------------------------+---------------------------------------+ +| ``pj_fwd3`` | :c:func:`proj_trans` | ++---------------------------------------+---------------------------------------+ +| ``pj_inv3`` | :c:func:`proj_trans` | ++---------------------------------------+---------------------------------------+ +| ``pj_transform`` | :c:func:`proj_trans_array` or | +| | :c:func:`proj_trans_generic` | ++---------------------------------------+---------------------------------------+ +| ``pj_init`` | :c:func:`proj_create` | ++---------------------------------------+---------------------------------------+ +| ``pj_init_plus`` | :c:func:`proj_create` | ++---------------------------------------+---------------------------------------+ +| ``pj_free`` | :c:func:`proj_destroy` | ++---------------------------------------+---------------------------------------+ +| ``pj_is_latlong`` | :c:func:`proj_angular_output` | ++---------------------------------------+---------------------------------------+ +| ``pj_is_geocent`` | :c:func:`proj_angular_output` | ++---------------------------------------+---------------------------------------+ +| ``pj_get_def`` | :c:func:`proj_pj_info` | ++---------------------------------------+---------------------------------------+ +| ``pj_latlong_from_proj`` | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| ``pj_set_finder`` | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| ``pj_set_searchpath`` | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| ``pj_deallocate_grids`` | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| ``pj_strerrno`` | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| ``pj_get_errno_ref`` | :c:func:`proj_errno` | ++---------------------------------------+---------------------------------------+ +| ``pj_get_release`` | :c:func:`proj_info` | ++---------------------------------------+---------------------------------------+ diff --git a/_sources/development/quickstart.rst.txt b/_sources/development/quickstart.rst.txt new file mode 100644 index 00000000..5be85641 --- /dev/null +++ b/_sources/development/quickstart.rst.txt @@ -0,0 +1,200 @@ +.. _dev_quickstart: + +================================================================================ +Quick start +================================================================================ + +This is a short introduction to the PROJ API. In the following section we +create a simple program that transforms a geodetic coordinate to UTM and back +again. The program is explained a few lines at a time. The complete program can +be seen at the end of the section. + +See the following sections for more in-depth descriptions of different parts of +the PROJ API or consult the :doc:`API reference <reference/index>` for specifics. + +Before the PROJ API can be used it is necessary to include the :file:`proj.h` header +file. Here :file:`stdio.h` is also included so we can print some text to the screen: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 39-40 + +Let's declare a few variables that'll be used later in the program. Each variable +will be discussed below. +See the :doc:`reference for more info on data types <reference/datatypes>`. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 43-46 + :dedent: 4 + +For use in multi-threaded programs the :c:type:`PJ_CONTEXT` threading-context +is used. In this particular example it is not needed, but for the sake of +completeness we demonstrate its use here. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 50 + :dedent: 4 + +Next we create the :c:type:`PJ` transformation object ``P`` with the function +:c:func:`proj_create_crs_to_crs`. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 52-60 + :dedent: 4 + +Here we have set up a transformation from geographic coordinates to UTM zone +32N. + +:c:func:`proj_create_crs_to_crs` takes as its arguments: + +- the threading context ``C`` created above, +- a string that describes the source coordinate reference system (CRS), +- a string that describes the target CRS and +- an optional description of the area of use. + +It is recommended to create one threading context per thread used by the +program. This ensures that all :c:type:`PJ` objects created in the same +context will be sharing resources such as error-numbers and loaded grids. + +If you are sure that ``P`` will only be used by a single program thread, you +may pass ``NULL`` for the threading context. This will assign the default +thread context to ``P``. + +The strings for the source and target CRS may be any of: + +- PROJ strings, e.g. ``+proj=longlat +datum=WGS84 +type=crs``, +- CRS identified by their code, e.g. ``EPSG:4326`` or + ``urn:ogc:def:crs:EPSG::4326``, or +- a well-known text (WKT) string, e.g.: + +:: + + GEOGCRS["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]], + USAGE[ + SCOPE["unknown"], + AREA["World"], + BBOX[-90,-180,90,180]], + ID["EPSG",4326]] + +.. warning:: + + The use of PROJ strings to describe a CRS is not recommended. One of the + main weaknesses of PROJ strings is their inability to describe a geodetic + datum, other than the few ones hardcoded in the ``+datum`` parameter. + +:c:func:`proj_create_crs_to_crs` will return a pointer to a :c:type:`PJ` +object, or a null pointer in the case of an error. The details of the error +can be retrieved using :c:func:`proj_context_errno`. See :doc:`errorhandling` +for further details. + +Now that we have a normalized transformation object in ``P``, we can use it +with :c:func:`proj_trans` to transform coordinates from the source CRS to the +target CRS, but first we will discuss the interpretation of coordinates. + +By default, a :c:type:`PJ` transformation object accepts coordinates expressed +in the units and axis order of the source CRS, and returns transformed +coordinates in the units and axis order of the target CRS. + +For most geographic CRS, the units will be in degrees. In rare cases, such as +EPSG:4807 / NTF (Paris), this can be grads. For geographic CRS defined by the +EPSG authority, the order of coordinates is latitude first, longitude second. +When using a PROJ string, the order is the reverse; longitude first, latitude +second. + +For projected CRS, the units may vary (metre, us-foot, etc.). For projected CRS +defined by the EPSG authority, and with EAST / NORTH directions, the order +might be easting first, northing second, or the reverse. When using a PROJ +string, the order will be easting first, northing second, except if the +``+axis`` parameter modifies it. + +If you prefer to work with a uniform axis order, regardless of the axis orders +mandated by the source and target CRS, you can use the +:c:func:`proj_normalize_for_visualization` function. + +:c:func:`proj_normalize_for_visualization` takes a threading context and an +existing :c:type:`PJ` object, and generates from it a new :c:type:`PJ` that +accepts as input and returns as output coordinates using the traditional GIS +order. That is, longitude followed by latitude, optionally followed by +elevation and time for geographic CRS, and easting followed by northing for +most projected CRS. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 65-71 + :dedent: 4 + +Next we create a :c:type:`PJ_COORD` coordinate object, using the function +:c:func:`proj_coord`. + +The following example creates a coordinate for 55°N 12°E (Copenhagen). + +Because we have normalized the transformation object with +:c:func:`proj_normalize_for_visualization`, the order of coordinates is +longitude followed by latitude, and the units are degrees. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 76 + :dedent: 4 + +Now we are ready to transform the coordinate into UTM zone 32, using the +function :c:func:`proj_trans`. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 79-80 + :dedent: 4 + +:c:func:`proj_trans` takes as its arguments: + +- a :c:type:`PJ` transformation object, +- a :c:type:`PJ_DIRECTION` direction, and +- the :c:type:`PJ_COORD` coordinate to transform. + +The direction argument can be one of: + +- ``PJ_FWD`` -- "forward" transformation from source CRS to target CRS. +- ``PJ_IDENT`` -- "identity", return the source coordinate unchanged. +- ``PJ_INV`` -- "inverse" transformation from target CRS to source CRS. + +It returns the new transformed :c:type:`PJ_COORD` coordinate. + +We can perform the transformation in reverse (from UTM zone 32 back to +geographic) as follows: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 82-83 + :dedent: 4 + +Before ending the program, we need to release the memory allocated to our +objects: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 86-87 + :dedent: 4 + + +A complete compilable version of the example code can be seen below: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :linenos: + :lines: 39- + diff --git a/_sources/development/reference/cpp/common.rst.txt b/_sources/development/reference/cpp/common.rst.txt new file mode 100644 index 00000000..4e92f6b2 --- /dev/null +++ b/_sources/development/reference/cpp/common.rst.txt @@ -0,0 +1,8 @@ +.. _common: + +common namespace +---------------- + +.. doxygennamespace:: osgeo::proj::common + :project: doxygen_api + :members: diff --git a/_sources/development/reference/cpp/cpp_general.rst.txt b/_sources/development/reference/cpp/cpp_general.rst.txt new file mode 100644 index 00000000..4d27814f --- /dev/null +++ b/_sources/development/reference/cpp/cpp_general.rst.txt @@ -0,0 +1,7 @@ +.. _cpp_general: + +General documentation +--------------------- + +.. doxygenpage:: general_doc + :project: doxygen_api diff --git a/_sources/development/reference/cpp/crs.rst.txt b/_sources/development/reference/cpp/crs.rst.txt new file mode 100644 index 00000000..f8df118e --- /dev/null +++ b/_sources/development/reference/cpp/crs.rst.txt @@ -0,0 +1,8 @@ +.. _crs: + +crs namespace +------------- + +.. doxygennamespace:: osgeo::proj::crs + :project: doxygen_api + :members: diff --git a/_sources/development/reference/cpp/cs.rst.txt b/_sources/development/reference/cpp/cs.rst.txt new file mode 100644 index 00000000..376ae6a6 --- /dev/null +++ b/_sources/development/reference/cpp/cs.rst.txt @@ -0,0 +1,8 @@ +.. _cs: + +cs namespace +------------ + +.. doxygennamespace:: osgeo::proj::cs + :project: doxygen_api + :members: diff --git a/_sources/development/reference/cpp/datum.rst.txt b/_sources/development/reference/cpp/datum.rst.txt new file mode 100644 index 00000000..0a545a68 --- /dev/null +++ b/_sources/development/reference/cpp/datum.rst.txt @@ -0,0 +1,8 @@ +.. _datum: + +datum namespace +--------------- + +.. doxygennamespace:: osgeo::proj::datum + :project: doxygen_api + :members: diff --git a/_sources/development/reference/cpp/index.rst.txt b/_sources/development/reference/cpp/index.rst.txt new file mode 100644 index 00000000..bedfbe52 --- /dev/null +++ b/_sources/development/reference/cpp/index.rst.txt @@ -0,0 +1,19 @@ +.. _cpp: + +================================================================================ +C++ API +================================================================================ + +.. toctree:: + :maxdepth: 1 + + cpp_general + common + util + metadata + cs + datum + crs + operation + io + diff --git a/_sources/development/reference/cpp/io.rst.txt b/_sources/development/reference/cpp/io.rst.txt new file mode 100644 index 00000000..9729af90 --- /dev/null +++ b/_sources/development/reference/cpp/io.rst.txt @@ -0,0 +1,8 @@ +.. _io: + +io namespace +------------ + +.. doxygennamespace:: osgeo::proj::io + :project: doxygen_api + :members: diff --git a/_sources/development/reference/cpp/metadata.rst.txt b/_sources/development/reference/cpp/metadata.rst.txt new file mode 100644 index 00000000..348627e8 --- /dev/null +++ b/_sources/development/reference/cpp/metadata.rst.txt @@ -0,0 +1,8 @@ +.. _metadata: + +metadata namespace +------------------ + +.. doxygennamespace:: osgeo::proj::metadata + :project: doxygen_api + :members: diff --git a/_sources/development/reference/cpp/operation.rst.txt b/_sources/development/reference/cpp/operation.rst.txt new file mode 100644 index 00000000..88096cb8 --- /dev/null +++ b/_sources/development/reference/cpp/operation.rst.txt @@ -0,0 +1,8 @@ +.. _operation: + +operation namespace +------------------- + +.. doxygennamespace:: osgeo::proj::operation + :project: doxygen_api + :members: diff --git a/_sources/development/reference/cpp/util.rst.txt b/_sources/development/reference/cpp/util.rst.txt new file mode 100644 index 00000000..bc9676a4 --- /dev/null +++ b/_sources/development/reference/cpp/util.rst.txt @@ -0,0 +1,8 @@ +.. _util: + +util namespace +-------------- + +.. doxygennamespace:: osgeo::proj::util + :project: doxygen_api + :members: diff --git a/_sources/development/reference/datatypes.rst.txt b/_sources/development/reference/datatypes.rst.txt new file mode 100644 index 00000000..e7b5cca0 --- /dev/null +++ b/_sources/development/reference/datatypes.rst.txt @@ -0,0 +1,999 @@ +.. _datatypes: + +================================================================================ +Data types +================================================================================ + +This section describes the numerous data types in use in PROJ.4. As a rule +of thumb PROJ.4 data types are prefixed with ``PJ_``, or in one particular case, +is simply called :c:type:`PJ`. A few notable exceptions can be traced +back to the very early days of PROJ.4 when the ``PJ_`` prefix was not +consistently used. + +Transformation objects +-------------------------------------------------------------------------------- + +.. c:type:: PJ + + Object containing everything related to a given projection or transformation. + As a user of the PROJ.4 library you are only exposed to pointers to this + object and the contents is hidden behind the public API. :c:type:`PJ` objects + are created with :c:func:`proj_create` and destroyed with + :c:func:`proj_destroy`. + +.. c:type:: PJ_DIRECTION + + Enumeration that is used to convey in which direction a given transformation + should be performed. Used in transformation function call as described in + the section on :ref:`transformation functions <coord_trans_functions>`. + + Forward transformations are defined with the :c: + + .. code-block:: C + + typedef enum proj_direction { + PJ_FWD = 1, /* Forward */ + PJ_IDENT = 0, /* Do nothing */ + PJ_INV = -1 /* Inverse */ + } PJ_DIRECTION; + + .. cpp:enumerator:: PJ_FWD + + Perform transformation in the forward direction. + + .. cpp:enumerator:: PJ_IDENT + + Identity. Do nothing. + + .. cpp:enumerator:: PJ_INV + + Perform transformation in the inverse direction. + +.. c:type:: PJ_CONTEXT + + Context objects enable safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` + object is connected to a context (if not specified, the default context is + used). All operations within a context should be performed in the same thread. + :c:type:`PJ_CONTEXT` objects are created with :c:func:`proj_context_create` + and destroyed with :c:func:`proj_context_destroy`. + + +.. c:type:: PJ_AREA + + .. versionadded:: 6.0.0 + + Opaque object describing an area in which a transformation is performed. + + It is used with :c:func:`proj_create_crs_to_crs` to select the best transformation + between the two input coordinate reference systems. + +2 dimensional coordinates +-------------------------------------------------------------------------------- + +Various 2-dimensional coordinate data types. + +.. c:type:: PJ_LP + + Geodetic coordinate, latitude and longitude. Usually in radians. + + .. code-block:: C + + typedef struct { double lam, phi; } PJ_LP; + + .. c:member:: double PJ_LP.lam + + Longitude. Lambda. + + .. c:member:: double PJ_LP.phi + + Latitude. Phi. + + +.. c:type:: PJ_XY + + 2-dimensional cartesian coordinate. + + .. code-block:: C + + typedef struct { double x, y; } PJ_XY; + + + .. c:member:: double PJ_XY.x + + Easting. + + .. c:member:: double PJ_XY.y + + Northing. + + +.. c:type:: PJ_UV + + 2-dimensional generic coordinate. Usually used when contents can be either + a :c:type:`PJ_XY` or :c:type:`PJ_LP`. + + .. code-block:: C + + typedef struct {double u, v; } PJ_UV; + + + .. c:member:: double PJ_UV.u + + Longitude or easting, depending on use. + + .. c:member:: double PJ_UV.v + + Latitude or northing, depending on use. + + +3 dimensional coordinates +-------------------------------------------------------------------------------- + +The following data types are the 3-dimensional equivalents to the data +types above. + +.. c:type:: PJ_LPZ + + 3-dimensional version of :c:type:`PJ_LP`. Holds longitude, latitude and + a vertical component. + + .. code-block:: C + + typedef struct { double lam, phi, z; } PJ_LPZ; + + .. c:member:: double PJ_LPZ.lam + + Longitude. Lambda. + + .. c:member:: double PJ_LPZ.phi + + Latitude. Phi. + + .. c:member:: double PJ_LPZ.z + + Vertical component. + + +.. c:type:: PJ_XYZ + + Cartesian coordinate in 3 dimensions. Extension of :c:type:`PJ_XY`. + + .. code-block:: C + + typedef struct { double x, y, z; } PJ_XYZ; + + .. c:member:: double PJ_XYZ.x + + Easting or the X component of a 3D cartesian system. + + .. c:member:: double PJ_XYZ.y + + Northing or the Y component of a 3D cartesian system. + + .. c:member:: double PJ_XYZ.z + + Vertical component or the Z component of a 3D cartesian system. + + +.. c:type:: PJ_UVW + + 3-dimensional extension of :c:type:`PJ_UV`. + + .. code-block:: C + + typedef struct {double u, v, w; } PJ_UVW; + + .. c:member:: double PJ_UVW.u + + Longitude or easting, depending on use. + + .. c:member:: double PJ_UVW.v + + Latitude or northing, depending on use. + + .. c:member:: double PJ_UVW.w + + Vertical component. + + +Spatiotemporal coordinate types +-------------------------------------------------------------------------------- + +The following data types are extensions of the triplets above into the time +domain. + + +.. c:type:: PJ_LPZT + + Spatiotemporal version of :c:type:`PJ_LPZ`. + + .. code-block:: C + + typedef struct { + double lam; + double phi; + double z; + double t; + } PJ_LPZT; + + + .. c:member:: double PJ_LPZT.lam + + Longitude. + + .. c:member:: double PJ_LPZT.phi + + Latitude + + .. c:member:: double PJ_LPZT.z + + Vertical component. + + .. c:member:: double PJ_LPZT.t + + Time component. + +.. c:type:: PJ_XYZT + + Generic spatiotemporal coordinate. Useful for e.g. cartesian coordinates with + an attached time-stamp. + + .. code-block:: C + + typedef struct { + double x; + double y; + double z; + double t; + } PJ_XYZT; + + + .. c:member:: double PJ_XYZT.x + + Easting or the X component of a 3D cartesian system. + + .. c:member:: double PJ_XYZT.y + + Northing or the Y component of a 3D cartesian system. + + .. c:member:: double PJ_XYZT.z + + Vertical or the Z component of a 3D cartesian system. + + .. c:member:: double PJ_XYZT.t + + Time component. + + +.. c:type:: PJ_UVWT + + Spatiotemporal version of :c:type:`PJ_UVW`. + + .. code-block:: C + + typedef struct { double u, v, w, t; } PJ_UVWT; + + .. c:member:: double PJ_UVWT.e + + First horizontal component. + + .. c:member:: double PJ_UVWT.n + + Second horizontal component. + + .. c:member:: double PJ_UVWT.w + + Vertical component. + + .. c:member:: double PJ_UVWT.t + + Temporal component. + + +Ancillary types for geodetic computations +-------------------------------------------------------------------------------- + + +.. c:type:: PJ_OPK + + Rotations, for instance three euler angles. + + .. code-block:: C + + typedef struct { double o, p, k; } PJ_OPK; + + .. c:member:: double PJ_OPK.o + + First rotation angle, omega. + + .. c:member:: double PJ_OPK.p + + Second rotation angle, phi. + + .. c:member:: double PJ_OPK.k + + Third rotation angle, kappa. + +.. c:type:: PJ_ENU + + East, north and up components. + + .. code-block:: c + + typedef struct { double e, n, u; } PJ_ENU; + + .. c:member:: double PJ_ENU.e + + East component. + + .. c:member:: double PJ_ENU.n + + North component. + + .. c:member:: double PJ_ENU.u + + Up component. + + +.. c:type:: PJ_GEOD + + Geodesic length, forward and reverse azimuths. + + .. code-block:: C + + typedef struct { double s, a1, a2; } PJ_GEOD; + + .. c:member:: double PJ_GEOD.s + + Geodesic length. + + .. c:member:: double PJ_GEOD.a1 + + Forward azimuth. + + .. c:member:: double PJ_GEOD.a2 + + Reverse azimuth. + + + +Complex coordinate types +-------------------------------------------------------------------------------- + + +.. c:type:: PJ_COORD + + General purpose coordinate union type, applicable in two, three and four dimensions. + This is the default coordinate datatype used in PROJ. + + .. code-block:: C + + typedef union { + double v[4]; + PJ_XYZT xyzt; + PJ_UVWT uvwt; + PJ_LPZT lpzt; + PJ_GEOD geod; + PJ_OPK opk; + PJ_ENU enu; + PJ_XYZ xyz; + PJ_UVW uvw; + PJ_LPZ lpz; + PJ_XY xy; + PJ_UV uv; + PJ_LP lp; + } PJ_COORD ; + + .. c:member:: double v[4] + + Generic four-dimensional vector. + + .. c:member:: PJ_XYZT PJ_COORD.xyzt + + Spatiotemporal cartesian coordinate. + + .. c:member:: PJ_UVWT PJ_COORD.uvwt + + Spatiotemporal generic coordinate. + + .. c:member:: PJ_LPZT PJ_COORD.lpzt + + Longitude, latitude, vertical and time components. + + .. c:member:: PJ_GEOD PJ_COORD.geod + + Geodesic length, forward and reverse azimuths. + + .. c:member:: PJ_OPK PJ_COORD.opk + + Rotations, for instance three euler angles. + + .. c:member:: PJ_ENU PJ_COORD.enu + + East, north and up components. + + .. c:member:: PJ_XYZ PJ_COORD.xyz + + 3-dimensional cartesian coordinate. + + .. c:member:: PJ_UVW PJ_COORD.uvw + + 3-dimensional generic coordinate. + + .. c:member:: PJ_LPZ PJ_COORD.lpz + + Longitude, latitude and vertical component. + + .. c:member:: PJ_XY PJ_COORD.xy + + 2-dimensional cartesian coordinate. + + .. c:member:: PJ_UV PJ_COORD.uv + + 2-dimensional generic coordinate. + + .. c:member:: PJ_LP PJ_COORD.lp + + Longitude and latitude. + + +Projection derivatives +------------------------------------------------------------------------------- + +.. c:type:: PJ_FACTORS + + Various cartographic properties, such as scale factors, angular distortion + and meridian convergence. Calculated with :c:func:`proj_factors`. + + .. code-block:: C + + typedef struct { + double meridional_scale; + double parallel_scale; + double areal_scale; + + double angular_distortion; + double meridian_parallel_angle; + double meridian_convergence; + + double tissot_semimajor; + double tissot_semiminor; + + double dx_dlam; + double dx_dphi; + double dy_dlam; + double dy_dphi; + } PJ_FACTORS; + + .. c:member:: double PJ_FACTORS.meridional_scale + + Meridional scale at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.parallel_scale + + Parallel scale at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.areal_scale + + Areal scale factor at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.angular_distortion + + Angular distortion at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.meridian_parallel_angle + + Meridian/parallel angle, :math:`\theta^\prime`, at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.meridian_convergence + + Meridian convergence at coordinate :math:`\left(\lambda,\phi\right)`. + Sometimes also described as *grid declination*. + + + .. c:member:: double PJ_FACTORS.tissot_semimajor + + Maximum scale factor. + + .. c:member:: double PJ_FACTORS.tissot_semiminor + + Minimum scale factor. + + + .. c:member:: double PJ_FACTORS.dx_dlam + + Partial derivative :math:`\frac{\partial x}{\partial \lambda}` of coordinate + :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.dy_dlam + + Partial derivative :math:`\frac{\partial y}{\partial \lambda}` of coordinate + :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.dx_dphi + + Partial derivative :math:`\frac{\partial x}{\partial \phi}` of coordinate + :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.dy_dphi + + Partial derivative :math:`\frac{\partial y}{\partial \phi}` of coordinate + :math:`\left(\lambda,\phi\right)`. + +List structures +------------------------------------------------------------------------------- + +.. c:type:: PJ_OPERATIONS + + Description a PROJ.4 operation + + .. code-block:: C + + struct PJ_OPERATIONS { + const char *id; /* operation keyword */ + PJ *(*proj)(PJ *); /* operation entry point */ + char * const *descr; /* description text */ + }; + + .. c:member:: const char *id + + Operation keyword. + + .. c:member:: PJ *(*op)(PJ *) + + Operation entry point. + + .. c:member:: char * const * descr + + Description of operation. + + +.. c:type:: PJ_ELLPS + + Description of ellipsoids defined in PROJ.4 + + .. code-block:: C + + struct PJ_ELLPS { + const char *id; + const char *major; + const char *ell; + const char *name; + }; + + .. c:member:: const char *id + + Keyword name of the ellipsoid. + + .. c:member:: const char *major + + Semi-major axis of the ellipsoid, or radius in case of a sphere. + + .. c:member:: const char *ell + + Elliptical parameter, e.g. ``rf=298.257`` or ``b=6356772.2``. + + .. c:member:: const char *name + + Name of the ellipsoid + +.. c:type:: PJ_UNITS + + Distance units defined in PROJ. + + .. code-block:: C + + struct PJ_UNITS { + const char *id; /* units keyword */ + const char *to_meter; /* multiply by value to get meters */ + const char *name; /* comments */ + double factor; /* to_meter factor in actual numbers */ + }; + + .. c:member:: const char *id + + Keyword for the unit. + + .. c:member:: const char *to_meter + + Text representation of the factor that converts a given unit to meters + + .. c:member:: const char *name + + Name of the unit. + + .. c:member:: double factor + + Conversion factor that converts the unit to meters. + +.. c:type:: PJ_PRIME_MERIDIANS + + Prime meridians defined in PROJ. + + .. code-block:: C + + struct PJ_PRIME_MERIDIANS { + const char *id; + const char *defn; + }; + + .. c:member:: const char *id + + Keyword for the prime meridian + + .. c:member:: const char *def + + Offset from Greenwich in DMS format. + +Info structures +------------------------------------------------------------------------------- + +.. c:type:: PJ_INFO + + Struct holding information about the current instance of PROJ. Struct is + populated by :c:func:`proj_info`. + + .. code-block:: C + + typedef struct { + int major; + int minor; + int patch; + const char *release; + const char *version; + const char *searchpath; + } PJ_INFO; + + .. c:member:: const char *PJ_INFO.release + + Release info. Version number and release date, + e.g. "Rel. 4.9.3, 15 August 2016". + + .. c:member:: const char *PJ_INFO.version + + Text representation of the full version number, + e.g. "4.9.3". + + .. c:member:: int PJ_INFO.major + + Major version number. + + .. c:member:: int PJ_INFO.minor + + Minor version number. + + .. c:member:: int PJ_INFO.patch + + Patch level of release. + + .. c:member:: const char PJ_INFO.searchpath + + Search path for PROJ. List of directories separated by + semicolons (Windows) or colons (non-Windows), e.g. + ``C:\\Users\\doctorwho;C:\\OSGeo4W64\\share\\proj``. + Grids and :ref:`init files <init_files>` are looked for in + directories in the search path. + +.. c:type:: PJ_PROJ_INFO + + Struct holding information about a :c:type:`PJ` object. Populated by + :c:func:`proj_pj_info`. The :c:type:`PJ_PROJ_INFO` object provides a + view into the internals of a :c:type:`PJ`, so once the :c:type:`PJ` + is destroyed or otherwise becomes invalid, so does the + :c:type:`PJ_PROJ_INFO` + + .. code-block:: C + + typedef struct { + const char *id; + const char *description; + const char *definition; + int has_inverse; + double accuracy; + } PJ_PROJ_INFO; + + .. c:member:: const char *PJ_PROJ_INFO.id + + Short ID of the operation the :c:type:`PJ` object is based on, that is, + what comes after the ``+proj=`` in a proj-string, e.g. "*merc*". + + .. c:member:: const char *PJ_PROJ_INFO.description + + Long describes of the operation the :c:type:`PJ` object is based on, + e.g. "*Mercator Cyl, Sph&Ell lat_ts=*". + + .. c:member:: const char *PJ_PROJ_INFO.definition + + The proj-string that was used to create the :c:type:`PJ` object with, + e.g. "*+proj=merc +lat_0=24 +lon_0=53 +ellps=WGS84*". + + .. c:member:: int PJ_PROJ_INFO.has_inverse + + 1 if an inverse mapping of the defined operation exists, otherwise 0. + + .. c:member:: double PJ_PROJ_INFO.accuracy + + Expected accuracy of the transformation. -1 if unknown. + +.. c:type:: PJ_GRID_INFO + + Struct holding information about a specific grid in the search path of + PROJ. Populated with the function :c:func:`proj_grid_info`. + + .. code-block:: C + + typedef struct { + char gridname[32]; + char filename[260]; + char format[8]; + LP lowerleft; + LP upperright; + int n_lon, n_lat; + double cs_lon, cs_lat; + } PJ_GRID_INFO; + + .. c:member:: char PJ_GRID_INFO.gridname[32] + + Name of grid, e.g. "*BETA2007.gsb*". + + .. c:member:: char PJ_GRID_INFO + + Full path of grid file, e.g. *"C:\\OSGeo4W64\\share\\proj\\BETA2007.gsb"* + + .. c:member:: char PJ_GRID_INFO.format[8] + + File format of grid file, e.g. "*ntv2*" + + .. c:member:: LP PJ_GRID_INFO.lowerleft + + Geodetic coordinate of lower left corner of grid. + + .. c:member:: LP PJ_GRID_INFO.upperright + + Geodetic coordinate of upper right corner of grid. + + .. c:member:: int PJ_GRID_INFO.n_lon + + Number of grid cells in the longitudinal direction. + + .. c:member:: int PJ_GRID_INFO.n_lat + + Number of grid cells in the latitudinal direction. + + .. c:member:: double PJ_GRID_INFO.cs_lon + + Cell size in the longitudinal direction. In radians. + + .. c:member:: double PJ_GRID_INFO.cs_lat + + Cell size in the latitudinal direction. In radians. + + +.. c:type:: PJ_INIT_INFO + + Struct holding information about a specific init file in the search path of + PROJ. Populated with the function :c:func:`proj_init_info`. + + .. code-block:: C + + typedef struct { + char name[32]; + char filename[260]; + char version[32]; + char origin[32]; + char lastupdate[16]; + } PJ_INIT_INFO; + + .. c:member:: char PJ_INIT_INFO.name[32] + + Name of init file, e.g. "*epsg*". + + .. c:member:: char PJ_INIT_INFO.filename[260] + + Full path of init file, e.g. "*C:\\OSGeo4W64\\share\\proj\\epsg*" + + .. c:member:: char PJ_INIT_INFO.version[32] + + Version number of init file, e.g. "*9.0.0*" + + .. c:member:: char PJ_INIT_INFO.origin[32] + + Originating entity of the init file, e.g. "*EPSG*" + + .. c:member:: char PJ_INIT_INFO.lastupdate + + Date of last update of the init file. + + +.. _error_codes: + +Error codes +----------- + +.. versionadded:: 8.0.0 + +Three classes of errors are defined below. The belonging of a given error +code to a class can bit tested with a binary and test. The error class itself +can be used as an error value in some rare cases where the error does not +fit into a more precise error value. + +Those error codes are still quite generic for a number of them. Details on the +actual errors will be typically logged with the PJ_LOG_ERROR level. + +Errors in class PROJ_ERR_INVALID_OP ++++++++++++++++++++++++++++++++++++ + +.. c:macro:: PROJ_ERR_INVALID_OP + + Class of error codes typically related to coordinate operation initialization, + typically when creating a PJ* object from a PROJ string. + + .. note:: some of them can also be emitted during coordinate transformation, + like PROJ_ERR_INVALID_OP_FILE_NOT_FOUND_OR_INVALID in case the resource loading + is deferred until it is really needed. + +.. c:macro:: PROJ_ERR_INVALID_OP_WRONG_SYNTAX + + Invalid pipeline structure, missing +proj argument, etc. + +.. c:macro:: PROJ_ERR_INVALID_OP_MISSING_ARG + + Missing required operation parameter + +.. c:macro:: PROJ_ERR_INVALID_OP_ILLEGAL_ARG_VALUE + + One of the operation parameter has an illegal value. + +.. c:macro:: PROJ_ERR_INVALID_OP_MUTUALLY_EXCLUSIVE_ARGS + + Mutually exclusive arguments + +.. c:macro:: PROJ_ERR_INVALID_OP_FILE_NOT_FOUND_OR_INVALID + + File not found or with invalid content (particular case of PROJ_ERR_INVALID_OP_ILLEGAL_ARG_VALUE) + +Errors in class PROJ_ERR_COORD_TRANSFM +++++++++++++++++++++++++++++++++++++++ + +.. c:macro:: PROJ_ERR_COORD_TRANSFM + + Class of error codes related to transformation on a specific coordinate. + +.. c:macro:: PROJ_ERR_COORD_TRANSFM_INVALID_COORD + + Invalid input coordinate. e.g. a latitude > 90°. + +.. c:macro:: PROJ_ERR_COORD_TRANSFM_OUTSIDE_PROJECTION_DOMAIN + + Coordinate is outside of the projection domain. e.g. approximate mercator + with \|longitude - lon_0\| > 90°, or iterative convergence method failed. + +.. c:macro:: PROJ_ERR_COORD_TRANSFM_NO_OPERATION + + No operation found, e.g. if no match the required accuracy, or if ballpark transformations + were asked to not be used and they would be only such candidate. + +.. c:macro:: PROJ_ERR_COORD_TRANSFM_OUTSIDE_GRID + + Point to transform falls outside grid/subgrid/TIN. + +.. c:macro:: PROJ_ERR_COORD_TRANSFM_GRID_AT_NODATA + + Point to transform falls in a grid cell that evaluates to nodata. + +Errors in class PROJ_ERR_OTHER +++++++++++++++++++++++++++++++ + +.. c:macro:: PROJ_ERR_OTHER + + Class of error codes that do not fit into one of the above class. + +.. c:macro:: PROJ_ERR_OTHER_API_MISUSE + + Error related to a misuse of PROJ API. + +.. c:macro:: PROJ_ERR_OTHER_NO_INVERSE_OP + + No inverse method available + +.. c:macro:: PROJ_ERR_OTHER_NETWORK_ERROR + + Failure when accessing a network resource. + + +Logging +------------------------------------------------------------------------------- + +.. c:type:: PJ_LOG_LEVEL + + Enum of logging levels in PROJ. Used to set the logging level in PROJ. + Usually using :c:func:`proj_log_level`. + + .. cpp:enumerator:: PJ_LOG_NONE + + Don't log anything. + + .. cpp:enumerator:: PJ_LOG_ERROR + + Log only errors. + + .. cpp:enumerator:: PJ_LOG_DEBUG + + Log errors and additional debug information. + + .. cpp:enumerator:: PJ_LOG_TRACE + + Highest logging level. Log everything including very detailed debug + information. + + .. cpp:enumerator:: PJ_LOG_TELL + + Special logging level that when used in :c:func:`proj_log_level` + will return the current logging level set in PROJ. + + .. versionadded:: 5.1.0 + +.. c:type:: PJ_LOG_FUNC + + Function prototype for the logging function used by PROJ. + Defined as + + .. code-block:: C + + typedef void (*PJ_LOG_FUNCTION)(void *, int, const char *); + + where the first argument (void pointer) references a data structure used by the + calling application, the second argument (int type) is used to set the logging level + and the third argument (const char pointer) is the string that will be logged + by the function. + + + .. versionadded:: 5.1.0 + + +Setting custom I/O functions +------------------------------------------------------------------------------- + +.. versionadded:: 7.0.0 + +.. doxygenstruct:: PROJ_FILE_API + :project: doxygen_api + :members: + +.. doxygentypedef:: PROJ_FILE_HANDLE + :project: doxygen_api + +.. doxygenenum:: PROJ_OPEN_ACCESS + :project: doxygen_api + + +Network related functionality +------------------------------------------------------------------------------- + +.. versionadded:: 7.0.0 + +.. doxygentypedef:: PROJ_NETWORK_HANDLE + :project: doxygen_api + +.. doxygentypedef:: proj_network_open_cbk_type + :project: doxygen_api + +.. doxygentypedef:: proj_network_close_cbk_type + :project: doxygen_api + +.. doxygentypedef:: proj_network_get_header_value_cbk_type + :project: doxygen_api + +.. doxygentypedef:: proj_network_read_range_type + :project: doxygen_api + + +C API for ISO-19111 functionality +------------------------------------------------------------------------------- + +.. doxygengroup:: iso19111_types + :project: doxygen_api + :content-only: + :members: + + diff --git a/_sources/development/reference/functions.rst.txt b/_sources/development/reference/functions.rst.txt new file mode 100644 index 00000000..7a6b37a1 --- /dev/null +++ b/_sources/development/reference/functions.rst.txt @@ -0,0 +1,970 @@ +.. _functions: + +================================================================================ +Functions +================================================================================ + +Threading contexts +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_CONTEXT* proj_context_create(void) + + Create a new threading-context. + + :returns: a new context + +.. c:function:: PJ_CONTEXT* proj_context_clone(PJ_CONTEXT *ctx) + + .. versionadded:: 7.2 + + Create a new threading-context based on an existing context. + + :returns: a new context + +.. c:function:: void proj_context_destroy(PJ_CONTEXT *ctx) + + Deallocate a threading-context. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + + +Transformation setup +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The objects returned by the functions defined in this section have minimal +interaction with the functions of the +`C API for ISO-19111 functionality`_, and vice versa. See its introduction +paragraph for more details. + +.. c:function:: PJ* proj_create(PJ_CONTEXT *ctx, const char *definition) + + Create a transformation object, or a CRS object, from: + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671"), + - an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as + uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match. + - a OGC URN combining references for compound coordinate reference systems + (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated + syntax "EPSG:2393+5717"), + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") + - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.4/projjson.schema.json (*added in 6.2*) + - a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (*added in 7.1*) + + Example call: + + .. code-block:: C + + PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel"); + + If a proj-string contains a +type=crs option, then it is interpreted as + a CRS definition. In particular geographic CRS are assumed to have axis + in the longitude, latitude order and with degree angular unit. The use + of proj-string to describe a CRS is discouraged. It is a legacy means of + conveying CRS descriptions: use of object codes (EPSG:XXXX typically) or + WKT description is recommended for better expressivity. + + If a proj-string does not contain +type=crs, then it is interpreted as a + coordination operation / transformation. + + If creation of the transformation object fails, the function returns `0` and + the PROJ error number is updated. The error number can be read with + :c:func:`proj_errno` or :c:func:`proj_context_errno`. + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + :param definition: Proj-string of the desired transformation. + :type definition: `const char*` + + +.. c:function:: PJ* proj_create_argv(PJ_CONTEXT *ctx, int argc, char **argv) + + Create a transformation object, or a CRS object, with argc/argv-style initialization. For this + application each parameter in the defining proj-string is an entry in :c:data:`argv`. + + Example call: + + .. code-block:: C + + char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"}; + PJ* P = proj_create_argv(0, 3, args); + + If there is a type=crs argument, then the arguments are interpreted as + a CRS definition. In particular geographic CRS are assumed to have axis + in the longitude, latitude order and with degree angular unit. + + If there is no type=crs argument, then it is interpreted as a + coordination operation / transformation. + + If creation of the transformation object fails, the function returns `0` and + the PROJ error number is updated. The error number can be read with + :c:func:`proj_errno` or :c:func:`proj_context_errno`. + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + :param argc: Count of arguments in :c:data:`argv` + :type argc: `int` + :param argv: Array of strings with proj-string parameters, e.g. ``+proj=merc`` + :type argv: `char **` + :returns: :c:type:`PJ` * + +.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *source_crs, const char *target_crs, PJ_AREA *area) + + Create a transformation object that is a pipeline between two known + coordinate reference systems. + + source_crs and target_crs can be : + + - a "AUTHORITY:CODE", like EPSG:25832. When using that syntax for a source + CRS, the created pipeline will expect that the values passed to :c:func:`proj_trans` + respect the axis order and axis unit of the official definition ( + so for example, for EPSG:4326, with latitude first and longitude next, + in degrees). Similarly, when using that syntax for a target CRS, output + values will be emitted according to the official definition of this CRS. + + - a PROJ string, like "+proj=longlat +datum=WGS84". + When using that syntax, the axis order and unit for geographic CRS will + be longitude, latitude, and the unit degrees. + + - the name of a CRS as found in the PROJ database, e.g "WGS84", "NAD27", etc. + + - more generally any string accepted by :c:func:`proj_create` representing + a CRS + + An "area of use" can be specified in area. When it is supplied, the more + accurate transformation between two given systems can be chosen. + + When no area of use is specific and several coordinate operations are possible + depending on the area of use, this function will internally store those + candidate coordinate operations in the return PJ object. Each subsequent + coordinate transformation done with :c:func:`proj_trans` will then select + the appropriate coordinate operation by comparing the input coordinates with + the area of use of the candidate coordinate operations. + + Example call: + + .. code-block:: C + + PJ *P = proj_create_crs_to_crs(0, "EPSG:25832", "EPSG:25833", 0); + + If creation of the transformation object fails, the function returns `0` and + the PROJ error number is updated. The error number can be read with + :c:func:`proj_errno` or :c:func:`proj_context_errno`. + + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + :param `source_crs`: Source CRS. + :type `source_crs`: `const char*` + :param `target_crs`: Destination SRS. + :type `target_crs`: `const char*` + :param `area`: Descriptor of the desired area for the transformation. + :type `area`: :c:type:`PJ_AREA` * + :returns: :c:type:`PJ` * + +.. c:function:: PJ* proj_create_crs_to_crs_from_pj(PJ_CONTEXT *ctx, PJ *source_crs, PJ *target_crs, PJ_AREA *area, const char* const *options) + + .. versionadded:: 6.2.0 + + Create a transformation object that is a pipeline between two known + coordinate reference systems. + + This is the same as :c:func:`proj_create_crs_to_crs` except that the source and + target CRS are passed as PJ* objects which must be of the CRS variety. + + :param `options`: a list of NUL terminated options, or NULL. + + The list of supported options is: + + - AUTHORITY=name: to restrict the authority of coordinate operations + looked up in the database. When not specified, coordinate + ``operations from any authority`` will be searched, with the restrictions set + in the authority_to_authority_preference database table related to the authority + of the source/target CRS themselves. + If authority is set to "any", then coordinate operations from any authority will be searched + If authority is a non-empty string different of ``any``, then coordinate operations + will be searched only in that authority namespace (e.g ``EPSG``). + + - ACCURACY=value: to set the minimum desired accuracy (in metres) of the + candidate coordinate operations. + + - ALLOW_BALLPARK=YES/NO: can be set to NO to disallow the use of + :term:`Ballpark transformation` in the candidate coordinate operations. + + - FORCE_OVER=YES/NO: can be set to YES to force the +over flag on the transformation + returned by this function. + +.. doxygenfunction:: proj_normalize_for_visualization + :project: doxygen_api + +.. c:function:: PJ* proj_destroy(PJ *P) + + Deallocate a :c:type:`PJ` transformation object. + + :param `P`: Transformation object + :type `P`: const :c:type:`PJ` * + :returns: :c:type:`PJ` * + +Area of interest +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. versionadded:: 6.0.0 + + +.. c:function:: PJ_AREA* proj_area_create(void) + + Create an area of use. + + Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to + specify the area of use for the choice of relevant coordinate operations. + + :returns: :c:type:`PJ_AREA` * to be deallocated with :c:func:`proj_area_destroy` + + +.. c:function:: void proj_area_set_bbox(PJ_AREA *area, double west_lon_degree, double south_lat_degree, double east_lon_degree, double north_lat_degree) + + Set the bounding box of the area of use + + Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to + specify the area of use for the choice of relevant coordinate operations. + + In the case of an area of use crossing the antimeridian (longitude +/- 180 degrees), + `west_lon_degree` will be greater than `east_lon_degree`. + + :param `area`: Pointer to an object returned by :c:func:`proj_area_create`. + :param `west_lon_degree`: West longitude, in degrees. In [-180,180] range. + :param `south_lat_degree`: South latitude, in degrees. In [-90,90] range. + :param `east_lon_degree`: East longitude, in degrees. In [-180,180] range. + :param `north_lat_degree`: North latitude, in degrees. In [-90,90] range. + +.. c:function:: void proj_area_destroy(PJ_AREA* area) + + Deallocate a :c:type:`PJ_AREA` object. + + :param PJ_AREA* area + + +.. _coord_trans_functions: + +Coordinate transformation +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +.. c:function:: PJ_COORD proj_trans(PJ *P, PJ_DIRECTION direction, PJ_COORD coord) + + Transform a single :c:type:`PJ_COORD` coordinate. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Transformation direction. + :type `direction`: PJ_DIRECTION + :param coord: Coordinate that will be transformed. + :type coord: :c:type:`PJ_COORD` + :returns: :c:type:`PJ_COORD` + + +.. c:function:: size_t proj_trans_generic(PJ *P, PJ_DIRECTION direction, \ + double *x, size_t sx, size_t nx, \ + double *y, size_t sy, size_t ny, \ + double *z, size_t sz, size_t nz, \ + double *t, size_t st, size_t nt) + + Transform a series of coordinates, where the individual coordinate dimension + may be represented by an array that is either + + 1. fully populated + 2. a null pointer and/or a length of zero, which will be treated as a + fully populated array of zeroes + 3. of length one, i.e. a constant, which will be treated as a fully + populated array of that constant value + + .. note:: Even though the coordinate components are named :c:data:`x`, :c:data:`y`, + :c:data:`z` and :c:data:`t`, axis ordering of the to and from CRS + is respected. Transformations exhibit the same behavior + as if they were gathered in a :c:type:`PJ_COORD` struct. + + + The strides, :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, + represent the step length, in bytes, between + consecutive elements of the corresponding array. This makes it possible for + :c:func:`proj_trans_generic` to handle transformation of a large class of application + specific data structures, without necessarily understanding the data structure + format, as in: + + .. code-block:: C + + typedef struct { + double x, y; + int quality_level; + char surveyor_name[134]; + } XYQS; + + XYQS survey[345]; + double height = 23.45; + size_t stride = sizeof (XYQS); + + ... + + proj_trans_generic ( + P, PJ_INV, + &(survey[0].x), stride, 345, /* We have 345 eastings */ + &(survey[0].y), stride, 345, /* ...and 345 northings. */ + &height, sizeof(double), 1, /* The height is the constant 23.45 m */ + 0, 0, 0 /* and the time is the constant 0.00 s */ + ); + + This is similar to the inner workings of the deprecated :c:func:`pj_transform` + function, but the stride functionality has been generalized to work for any + size of basic unit, not just a fixed number of doubles. + + In most cases, the stride will be identical for x, y, z, and t, since they will + typically be either individual arrays (``stride = sizeof(double)``), or strided + views into an array of application specific data structures (``stride = sizeof (...)``). + + But in order to support cases where :c:data:`x`, :c:data:`y`, :c:data:`z`, + and :c:data:`t` come from heterogeneous sources, individual strides, + :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, are used. + + .. note:: Since :c:func:`proj_trans_generic` does its work *in place*, + this means that even the supposedly constants (i.e. length 1 arrays) + will return from the call in altered state. Hence, remember to + reinitialize between repeated calls. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param direction: Transformation direction. + :type direction: PJ_DIRECTION + :param x: Array of x-coordinates + :type x: `double *` + :param sx: Step length, in bytes, between consecutive elements of the corresponding array + :type sx: `size_t` + :param nx: Number of elements in the corresponding array + :type nx: `size_t` + :param y: Array of y-coordinates + :type y: `double *` + :param sy: Step length, in bytes, between consecutive elements of the corresponding array + :type sy: `size_t` + :param ny: Number of elements in the corresponding array + :type ny: `size_t` + :param z: Array of z-coordinates + :type z: `double *` + :param sz: Step length, in bytes, between consecutive elements of the corresponding array + :type sz: `size_t` + :param nz: Number of elements in the corresponding array + :type nz: `size_t` + :param t: Array of t-coordinates + :type t: `double *` + :param st: Step length, in bytes, between consecutive elements of the corresponding array + :type st: `size_t` + :param nt: Number of elements in the corresponding array + :type nt: `size_t` + :returns: Number of transformations successfully completed + + + +.. c:function:: int proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) + + Batch transform an array of :c:type:`PJ_COORD`. + + Performs transformation on all points, even if errors occur on some points + (new to 8.0. Previous versions would exit early in case of failure on a given point) + + Individual points that fail to transform will have their components set to + ``HUGE_VAL`` + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Transformation direction. + :type `direction`: PJ_DIRECTION + :param n: Number of coordinates in :c:data:`coord` + :type n: `size_t` + :returns: `int` 0 if all observations are transformed without error, otherwise returns error number. + This error number will be a precise error number if all coordinates that fail to transform + for the same reason, or a generic error code if they fail for different + reasons. + + + +.. doxygenfunction:: proj_trans_bounds + :project: doxygen_api + + +Error reporting +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: int proj_errno(PJ *P) + + Get a reading of the current error-state of :c:data:`P`. An non-zero error + codes indicates an error either with the transformation setup or during a + transformation. In cases :c:data:`P` is `0` the error number of the default + context is read. A text representation of the error number can be retrieved + with :c:func:`proj_errno_string`. + + Consult :ref:`error_codes` for the list of error codes (PROJ >= 8.0) + + :param P: Transformation object + :type P: :c:type:`PJ` * + + :returns: `int` + +.. c:function:: int proj_context_errno(PJ_CONTEXT *ctx) + + Get a reading of the current error-state of :c:data:`ctx`. An non-zero error + codes indicates an error either with the transformation setup or during a + transformation. A text representation of the error number can be retrieved + with :c:func:`proj_errno_string`. + + Consult :ref:`error_codes` for the list of error codes (PROJ >= 8.0) + + :param ctx: threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + + :returns: `int` + +.. c:function:: void proj_errno_set(PJ *P, int err) + + Change the error-state of :c:data:`P` to `err`. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param err: Error number. + :type err: `int` + +.. c:function:: int proj_errno_reset(PJ *P) + + Clears the error number in :c:data:`P`, and bubbles it up to the context. + + Example: + + .. code-block:: C + + void foo (PJ *P) { + int last_errno = proj_errno_reset (P); + + do_something_with_P (P); + + /* failure - keep latest error status */ + if (proj_errno(P)) + return; + /* success - restore previous error status */ + proj_errno_restore (P, last_errno); + return; + } + + :param P: Transformation object + :type P: :c:type:`PJ` * + + :returns: `int` Returns the previous value of the errno, for convenient reset/restore operations. + +.. c:function:: void proj_errno_restore(PJ *P, int err) + + Reduce some mental impedance in the canonical reset/restore use case: + Basically, :c:func:`proj_errno_restore()` is a synonym for + :c:func:`proj_errno_set()`, but the use cases are very different: + *set* indicate an error to higher level user code, *restore* passes previously + set error indicators in case of no errors at this level. + + Hence, although the inner working is identical, we provide both options, + to avoid some rather confusing real world code. + + See usage example under :c:func:`proj_errno_reset` + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param err: Error number. + :type err: `int` + +.. c:function:: const char* proj_errno_string(int err) + + .. versionadded:: 5.1.0 + + Get a text representation of an error number. + + .. deprecated:: This function is potentially thread-unsafe, replaced by :c:func:`proj_context_errno_string`. + + :param err: Error number. + :type err: `int` + + :returns: `const char*` String with description of error. + +.. c:function:: const char* proj_context_errno_string(PJ_CONTEXT* ctx, int err) + + .. versionadded:: 8.0.0 + + Get a text representation of an error number. + + :param ctx: threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + + :param err: Error number. + :type err: `int` + + :returns: `const char*` String with description of error. + +Logging +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_LOG_LEVEL proj_log_level (PJ_CONTEXT *ctx, PJ_LOG_LEVEL level) + + Get and set logging level for a given context. Changes the log level to + :c:data:`level` and returns the previous logging level. If called with + :c:data:`level` set to :c:type:`PJ_LOG_TELL` the function returns the current + logging level without changing it. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + :param level: New logging level. + :type level: PJ_LOG_LEVEL + + :returns: :c:type:`PJ_LOG_LEVEL` + + .. versionadded:: 5.1.0 + +.. c:function:: void proj_log_func (PJ_CONTEXT *ctx, void *app_data, PJ_LOG_FUNCTION logf) + + Override the internal log function of PROJ. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + :param app_data: Pointer to data structure used by the calling application. + :type app_data: `void *` + :param logf: Log function that overrides the PROJ log function. + :type logf: :c:type:`PJ_LOG_FUNCTION` + + .. versionadded:: 5.1.0 + +Info functions +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_INFO proj_info(void) + + Get information about the current instance of the PROJ library. + + :returns: :c:type:`PJ_INFO` + +.. c:function:: PJ_PROJ_INFO proj_pj_info(const PJ *P) + + Get information about a specific transformation object, :c:data:`P`. + + :param P: Transformation object + :type P: const :c:type:`PJ` * + :returns: :c:type:`PJ_PROJ_INFO` + +.. c:function:: PJ_GRID_INFO proj_grid_info(const char *gridname) + + Get information about a specific grid. + + :param `gridname`: Gridname in the PROJ searchpath + :type `gridname`: `const char*` + :returns: :c:type:`PJ_GRID_INFO` + +.. c:function:: PJ_INIT_INFO proj_init_info(const char *initname) + + Get information about a specific init file. + + :param `initname`: Init file in the PROJ searchpath + :type `initname`: `const char*` + :returns: :c:type:`PJ_INIT_INFO` + +Lists +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: const PJ_OPERATIONS* proj_list_operations(void) + + Get a pointer to an array of all operations in PROJ. The last entry + of the returned array is a NULL-entry. The array is statically allocated + and does not need to be freed after use. + + Print a list of all operations in PROJ: + + .. code-block:: C + + PJ_OPERATIONS *ops; + for (ops = proj_list_operations(); ops->id; ++ops) + printf("%s\n", ops->id); + + + :returns: const :c:type:`PJ_OPERATIONS` * + +.. c:function:: const PJ_ELLPS* proj_list_ellps(void) + + Get a pointer to an array of ellipsoids defined in PROJ. The last entry + of the returned array is a NULL-entry. The array is statically allocated + and does not need to be freed after use. + + :returns: const :c:type:`PJ_ELLPS` * + +.. c:function:: const PJ_UNITS* proj_list_units(void) + + Get a pointer to an array of distance units defined in PROJ. The last + entry of the returned array is a NULL-entry. The array is statically + allocated and does not need to be freed after use. + + Note: starting with PROJ 7.1, this function is deprecated by + :cpp:func:`proj_get_units_from_database` + + :returns: const :c:type:`PJ_UNITS` * + +.. c:function:: const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void) + + Get a pointer to an array of prime meridians defined in PROJ. The last + entry of the returned array is a NULL-entry. The array is statically + allocated and does not need to be freed after use. + + :returns: const :c:type:`PJ_PRIME_MERIDIANS` * + +Distances +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b) + + Calculate geodesic distance between two points in geodetic coordinates. The + calculated distance is between the two points located on the ellipsoid. + + The coordinates in :c:data:`a` and :c:data:`b` needs to be given as longitude + and latitude in radians. Note that the axis order of the :c:data:`P` object + is not taken into account in this function, so even though a CRS object comes + with axis ordering latitude/longitude coordinates used in this function should + be reordered as longitude/latitude. + + :param P: Transformation or CRS object + :type P: const :c:type:`PJ` * + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point + :returns: `double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_lpz_dist(const PJ *P, PJ_COORD a, PJ_COORD b) + + Calculate geodesic distance between two points in geodetic coordinates. + Similar to :c:func:`proj_lp_dist` but also takes the height above the ellipsoid + into account. + + The coordinates in :c:data:`a` and :c:data:`b` needs to be given as longitude + and latitude in radians. Note that the axis order of the :c:data:`P` object + is not taken into account in this function, so even though a CRS object comes + with axis ordering latitude/longitude coordinates used in this function should + be reordered as longitude/latitude. + + :param P: Transformation or CRS object + :type P: const :c:type:`PJ` * + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point + :returns: `double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xy_dist(PJ_COORD a, PJ_COORD b) + + Calculate 2-dimensional euclidean between two projected coordinates. + + :param PJ_COORD a: First coordinate + :param PJ_COORD b: Second coordinate + :returns: `double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xyz_dist(PJ_COORD a, PJ_COORD b) + + Calculate 3-dimensional euclidean between two projected coordinates. + + :param PJ_COORD a: First coordinate + :param PJ_COORD b: Second coordinate + :returns: `double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: PJ_COORD proj_geod(const PJ *P, PJ_COORD a, PJ_COORD b) + + Calculate the geodesic distance as well as forward and reverse azimuth + between two points on the ellipsoid. + + The coordinates in :c:data:`a` and :c:data:`b` needs to be given as longitude + and latitude in radians. Note that the axis order of the :c:data:`P` object + is not taken into account in this function, so even though a CRS object comes + with axis ordering latitude/longitude coordinates used in this function should + be reordered as longitude/latitude. + + :param P: Transformation or CRS object + :type P: const :c:type:`PJ` * + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point + :returns: `PJ_COORD` where the first value is the distance between :c:data:`a` + and :c:data:`b` in meters, the second value is the forward azimuth + and the third value is the reverse azimuth. The fourth coordinate + value is unused. + + + +Various +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t) + + Initializer for the :c:type:`PJ_COORD` union. The function is + shorthand for the otherwise convoluted assignment. + Equivalent to + + .. code-block:: C + + PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}}; + + or + + .. code-block:: C + + PJ_COORD c; + // Assign using the PJ_XYZT struct in the union + c.xyzt.x = 10.0; + c.xyzt.y = 20.0; + c.xyzt.z = 30.0; + c.xyzt.t = 40.0; + + Since :c:type:`PJ_COORD` is a union of structs, the above assignment can + also be expressed in terms of the other types in the union, e.g. + :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`. + + + :param x: 1st component in a :c:type:`PJ_COORD` + :type x: `double` + :param y: 2nd component in a :c:type:`PJ_COORD` + :type y: `double` + :param z: 3rd component in a :c:type:`PJ_COORD` + :type z: `double` + :param t: 4th component in a :c:type:`PJ_COORD` + :type t: `double` + :returns: :c:type:`PJ_COORD` + + +.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coord) + + Measure internal consistency of a given transformation. The function + performs :c:data:`n` round trip transformations starting in either + the forward or reverse :c:data:`direction`. Returns the euclidean + distance of the starting point :c:data:`coo` and the resulting + coordinate after :c:data:`n` iterations back and forth. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :param n: Number of roundtrip transformations + :type n: `int` + :param coord: Input coordinate + :type coord: :c:type:`PJ_COORD` * + :returns: `double` Distance between original coordinate and the \ + resulting coordinate after :c:data:`n` transformation iterations. + +.. c:function:: PJ_FACTORS proj_factors(PJ *P, PJ_COORD lp) + + Calculate various cartographic properties, such as scale factors, angular + distortion and meridian convergence. Depending on the underlying projection + values will be calculated either numerically (default) or analytically. + + Starting with PROJ 8.2, the P object can be a projected CRS, for example + instantiated from a EPSG CRS code. The factors computed will be those of the + map projection implied by the transformation from the base geographic CRS of + the projected CRS to the projected CRS. + + The input geodetic coordinate lp should be such that lp.lam is the longitude + in radian, and lp.phi the latitude in radian (thus independently of the + definition of the base CRS, if P is a projected CRS). + + The function also calculates the partial derivatives of the given + coordinate. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `lp`: Geodetic coordinate + :type `lp`: :c:type:`PJ_COORD` + :returns: :c:type:`PJ_FACTORS` + +.. c:function:: double proj_torad(double angle_in_degrees) + + Convert degrees to radians. + + :param angle_in_degrees: Degrees + :type angle_in_degrees: `double` + :returns: `double` Radians + +.. c:function:: double proj_todeg(double angle_in_radians) + + Convert radians to degrees + + :param angle_in_radians: Radians + :type angle_in_radians: `double` + :returns: `double` Degrees + +.. c:function:: double proj_dmstor(const char *is, char **rs) + + Convert string of degrees, minutes and seconds to radians. + Works similarly to the C standard library function :c:func:`strtod`. + + :param `is`: Value to be converted to radians + :type `is`: `const char*` + :param `rs`: Reference to an already allocated char*, whose value is \ + set by the function to the next character in :c:data:`is` \ + after the numerical value. + +.. c:function:: char *proj_rtodms(char *s, double r, int pos, int neg) + + Convert radians to string representation of degrees, minutes and seconds. + + :param s: Buffer that holds the output string + :type s: `char *` + :param r: Value to convert to dms-representation + :type r: `double` + :param pos: Character denoting positive direction, typically `'N'` or `'E'`. + :type pos: `int` + :param neg: Character denoting negative direction, typically `'S'` or `'W'`. + :type neg: `int` + :returns: `char*` Pointer to output buffer (same as :c:data:`s`) + + +.. c:function:: int proj_angular_input (PJ *P, enum PJ_DIRECTION dir) + + Check if an operation expects input in radians or not. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: `int` 1 if input units is expected in radians, otherwise 0 + +.. c:function:: int proj_angular_output (PJ *P, enum PJ_DIRECTION dir) + + Check if an operation returns output in radians or not. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: `int` 1 if output units is expected in radians, otherwise 0 + +.. c:function:: int proj_degree_input (PJ *P, enum PJ_DIRECTION dir) + + .. versionadded:: 7.1.0 + + Check if an operation expects input in degrees or not. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: `int` 1 if input units is expected in degrees, otherwise 0 + +.. c:function:: int proj_degree_output (PJ *P, enum PJ_DIRECTION dir) + + .. versionadded:: 7.1.0 + + Check if an operation returns output in degrees or not. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: `int` 1 if output units is expected in degrees, otherwise 0 + + +Setting custom I/O functions +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. versionadded:: 7.0.0 + +.. doxygenfunction:: proj_context_set_fileapi + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_sqlite3_vfs_name + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_file_finder + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_search_paths + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_ca_bundle_path + :project: doxygen_api + + +Network related functionality +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. versionadded:: 7.0.0 + +.. doxygenfunction:: proj_context_set_network_callbacks + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_enable_network + :project: doxygen_api + +.. doxygenfunction:: proj_context_is_network_enabled + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_url_endpoint + :project: doxygen_api + +.. doxygenfunction:: proj_context_get_url_endpoint + :project: doxygen_api + +.. doxygenfunction:: proj_context_get_user_writable_directory + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_set_enable + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_set_filename + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_set_max_size + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_set_ttl + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_clear + :project: doxygen_api + +.. doxygenfunction:: proj_is_download_needed + :project: doxygen_api + +.. doxygenfunction:: proj_download_file + :project: doxygen_api + + +Cleanup +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: void proj_cleanup() + + .. versionadded:: 6.2.0 + + This function frees global resources (grids, cache of +init files). It + should be called typically before process termination, and *after* having + freed PJ and PJ_CONTEXT objects. + + +C API for ISO-19111 functionality ++++++++++++++++++++++++++++++++++ + +.. versionadded:: 6.0.0 + +The PJ* objects returned by :c:func:`proj_create_from_wkt`, +:c:func:`proj_create_from_database` and other functions in that section +will have generally minimal interaction with the functions declared in the +previous sections (calling those functions on those objects +will either return an error or default/nonsensical values). The exception is +for ISO19111 objects of type CoordinateOperation that can be exported as a +valid PROJ pipeline. In this case, objects will work for example with +:c:func:`proj_trans_generic`. +Conversely, objects returned by :c:func:`proj_create` and :c:func:`proj_create_argv`, +which are not of type CRS (can be tested with :c:func:`proj_is_crs`), +will return an error when used with functions of this section. + +.. doxygengroup:: iso19111_functions + :project: doxygen_api + :content-only: + diff --git a/_sources/development/reference/index.rst.txt b/_sources/development/reference/index.rst.txt new file mode 100644 index 00000000..f04f4b3e --- /dev/null +++ b/_sources/development/reference/index.rst.txt @@ -0,0 +1,13 @@ +.. _reference: + +================================================================================ +Reference +================================================================================ + +.. toctree:: + :maxdepth: 1 + + macros + datatypes + functions + cpp/index.rst diff --git a/_sources/development/reference/macros.rst.txt b/_sources/development/reference/macros.rst.txt new file mode 100644 index 00000000..c25aeed2 --- /dev/null +++ b/_sources/development/reference/macros.rst.txt @@ -0,0 +1,39 @@ +.. _macros: + +================================================================================ +Macros +================================================================================ + +.. c:macro:: PROJ_VERSION_MAJOR + + Major version number, e.g. 8 for PROJ 8.0.1 + +.. c:macro:: PROJ_VERSION_MINOR + + Minor version number, e.g. 0 for PROJ 8.0.1 + +.. c:macro:: PROJ_VERSION_PATCH + + Patch version number, e.g. 1 for PROJ 8.0.1 + +.. c:macro:: PROJ_COMPUTE_VERSION(maj,min,patch) + + .. versionadded:: 8.0.1 + + Compute the version number from the major, minor and patch numbers. + +.. c:macro:: PROJ_VERSION_NUMBER + + .. versionadded:: 8.0.1 + + Total version number, equal to + ``PROJ_COMPUTE_VERSION(PROJ_VERSION_MAJOR, PROJ_VERSION_MINOR, PROJ_VERSION_PATCH)`` + +.. c:macro:: PROJ_AT_LEAST_VERSION(maj,min,patch) + + .. versionadded:: 8.0.1 + + Macro that returns true if the current PROJ version is at least the version + specified by (maj,min,patch) + + Equivalent to ``PROJ_VERSION_NUMBER >= PROJ_COMPUTE_VERSION(maj,min,patch)`` diff --git a/_sources/development/transformations.rst.txt b/_sources/development/transformations.rst.txt new file mode 100644 index 00000000..b03ce368 --- /dev/null +++ b/_sources/development/transformations.rst.txt @@ -0,0 +1,7 @@ +.. _dev_transformations: + +================================================================================ +Transformations +================================================================================ + + diff --git a/_sources/download.rst.txt b/_sources/download.rst.txt new file mode 100644 index 00000000..60b053ab --- /dev/null +++ b/_sources/download.rst.txt @@ -0,0 +1,150 @@ +.. _download: + +================================================================================ +Download +================================================================================ + +Here you can download current and previous releases of PROJ. We only supply a +distribution of the source code and various resource file archives. See +:ref:`install` for information on how to get pre-built packages of PROJ. + +.. _current_release: + +Current Release +-------------------------------------------------------------------------------- + +* **2022-03-01** `proj-9.0.0.tar.gz`_ (`md5`_) +* **2022-03-01** `proj-data-1.9.tar.gz`_ +* **PDF Manual** `proj.pdf`_ + +.. note:: + + The proj-datumgrid packages have been deprecated with PROJ 7.0.0. + The proj-data package should be used with PROJ 7.0.0 and newer + + The proj-datumgrid packages should be used with PROJ releases from the 5.x + and 6.x branches. + +Past Releases +-------------------------------------------------------------------------------- + +* **2022-01-01** `proj-8.2.1.tar.gz`_ +* **2021-11-01** `proj-8.2.0.tar.gz`_ +* **2021-09-01** `proj-8.1.1.tar.gz`_ +* **2021-07-01** `proj-8.1.0.tar.gz`_ +* **2021-05-05** `proj-8.0.1.tar.gz`_ +* **2021-03-01** `proj-8.0.0.tar.gz`_ +* **2021-01-01** `proj-7.2.1.tar.gz`_ +* **2020-11-01** `proj-7.2.0.tar.gz`_ +* **2020-09-01** `proj-7.1.1.tar.gz`_ +* **2020-07-01** `proj-7.1.0.tar.gz`_ +* **2020-05-01** `proj-6.3.2.tar.gz`_ +* **2020-05-01** `proj-7.0.1.tar.gz`_ +* **2020-03-01** `proj-7.0.0.tar.gz`_ +* **2020-02-11** `proj-6.3.1.tar.gz`_ +* **2020-01-01** `proj-6.3.0.tar.gz`_ +* **2019-11-01** `proj-6.2.1.tar.gz`_ +* **2019-09-01** `proj-6.2.0.tar.gz`_ +* **2019-07-01** `proj-6.1.1.tar.gz`_ +* **2019-05-15** `proj-6.1.0.tar.gz`_ +* **2019-03-01** `proj-6.0.0.tar.gz`_ +* **2018-09-15** `proj-5.2.0.tar.gz`_ +* **2018-06-01** `proj-5.1.0.tar.gz`_ +* **2018-04-01** `proj-5.0.1.tar.gz`_ +* **2018-03-01** `proj-5.0.0.tar.gz`_ +* **2016-09-02** `proj-4.9.3.tar.gz`_ +* **2015-09-13** `proj-4.9.2.tar.gz`_ +* **2015-03-04** `proj-4.9.1.tar.gz`_ + +* **2021-11-01** `proj-data-1.8.tar.gz`_ +* **2021-07-01** `proj-data-1.7.tar.gz`_ +* **2021-05-05** `proj-data-1.6.tar.gz`_ +* **2021-03-01** `proj-data-1.5.tar.gz`_ +* **2021-01-01** `proj-data-1.4.tar.gz`_ +* **2020-11-01** `proj-data-1.3.tar.gz`_ +* **2020-09-01** `proj-data-1.2.tar.gz`_ +* **2020-05-01** `proj-data-1.1.tar.gz`_ +* **2020-03-01** `proj-data-1.0.tar.gz`_ + +* **2018-09-15** `proj-datumgrid-1.8.zip`_ +* **2020-03-01** `proj-datumgrid-europe-1.6.zip`_ +* **2020-03-01** `proj-datumgrid-north-america-1.4.zip`_ +* **2020-03-01** `proj-datumgrid-oceania-1.2.zip`_ +* **2019-03-01** `proj-datumgrid-world-1.0.zip`_ +* **2018-03-01** `proj-datumgrid-1.7.zip`_ +* **2016-09-11** `proj-datumgrid-1.6.zip`_ +* **2019-09-01** `proj-datumgrid-europe-1.5.zip`_ +* **2019-09-01** `proj-datumgrid-europe-1.4.zip`_ +* **2019-07-01** `proj-datumgrid-europe-1.3.zip`_ +* **2019-03-01** `proj-datumgrid-europe-1.2.zip`_ +* **2018-09-15** `proj-datumgrid-europe-1.1.zip`_ +* **2018-03-01** `proj-datumgrid-europe-1.0.zip`_ +* **2019-03-01** `proj-datumgrid-north-america-1.3.zip`_ +* **2019-03-01** `proj-datumgrid-north-america-1.2.zip`_ +* **2018-09-15** `proj-datumgrid-north-america-1.1.zip`_ +* **2018-03-01** `proj-datumgrid-north-america-1.0.zip`_ +* **2018-03-01** `proj-datumgrid-oceania-1.1.zip`_ +* **2018-03-01** `proj-datumgrid-oceania-1.0.zip`_ + +.. _`proj-9.0.0.tar.gz`: https://download.osgeo.org/proj/proj-9.0.0.tar.gz +.. _`md5`: https://download.osgeo.org/proj/proj-9.0.0.tar.gz.md5 +.. _`proj-8.2.1.tar.gz`: https://download.osgeo.org/proj/proj-8.2.1.tar.gz +.. _`proj-8.2.0.tar.gz`: https://download.osgeo.org/proj/proj-8.2.0.tar.gz +.. _`proj-8.2.0.tar.gz`: https://download.osgeo.org/proj/proj-8.2.0.tar.gz +.. _`proj-8.1.1.tar.gz`: https://download.osgeo.org/proj/proj-8.1.1.tar.gz +.. _`proj-8.1.0.tar.gz`: https://download.osgeo.org/proj/proj-8.1.0.tar.gz +.. _`proj-8.0.1.tar.gz`: https://download.osgeo.org/proj/proj-8.0.1.tar.gz +.. _`proj-8.0.0.tar.gz`: https://download.osgeo.org/proj/proj-8.0.0.tar.gz +.. _`proj-7.2.1.tar.gz`: https://download.osgeo.org/proj/proj-7.2.1.tar.gz +.. _`proj-7.2.0.tar.gz`: https://download.osgeo.org/proj/proj-7.2.0.tar.gz +.. _`proj-7.1.1.tar.gz`: https://download.osgeo.org/proj/proj-7.1.1.tar.gz +.. _`proj-7.1.0.tar.gz`: https://download.osgeo.org/proj/proj-7.1.0.tar.gz +.. _`proj-7.0.1.tar.gz`: https://download.osgeo.org/proj/proj-7.0.1.tar.gz +.. _`proj-7.0.0.tar.gz`: https://download.osgeo.org/proj/proj-7.0.0.tar.gz +.. _`proj-6.3.2.tar.gz`: https://download.osgeo.org/proj/proj-6.3.2.tar.gz +.. _`proj-6.3.1.tar.gz`: https://download.osgeo.org/proj/proj-6.3.1.tar.gz +.. _`proj-6.3.0.tar.gz`: https://download.osgeo.org/proj/proj-6.3.0.tar.gz +.. _`proj-6.2.1.tar.gz`: https://download.osgeo.org/proj/proj-6.2.1.tar.gz +.. _`proj-6.2.0.tar.gz`: https://download.osgeo.org/proj/proj-6.2.0.tar.gz +.. _`proj-6.1.1.tar.gz`: https://download.osgeo.org/proj/proj-6.1.1.tar.gz +.. _`proj-6.1.0.tar.gz`: https://download.osgeo.org/proj/proj-6.1.0.tar.gz +.. _`proj-6.0.0.tar.gz`: https://download.osgeo.org/proj/proj-6.0.0.tar.gz +.. _`proj-5.2.0.tar.gz`: https://download.osgeo.org/proj/proj-5.2.0.tar.gz +.. _`proj-5.1.0.tar.gz`: https://download.osgeo.org/proj/proj-5.1.0.tar.gz +.. _`proj-5.0.1.tar.gz`: https://download.osgeo.org/proj/proj-5.0.1.tar.gz +.. _`proj-5.0.0.tar.gz`: https://download.osgeo.org/proj/proj-5.0.0.tar.gz +.. _`proj-4.9.1.tar.gz`: https://download.osgeo.org/proj/proj-4.9.1.tar.gz +.. _`proj-4.9.2.tar.gz`: https://download.osgeo.org/proj/proj-4.9.2.tar.gz +.. _`proj-4.9.3.tar.gz`: https://download.osgeo.org/proj/proj-4.9.3.tar.gz + +.. _`proj-data-1.9.tar.gz`: https://download.osgeo.org/proj/proj-data-1.9.tar.gz +.. _`proj-data-1.8.tar.gz`: https://download.osgeo.org/proj/proj-data-1.8.tar.gz +.. _`proj-data-1.7.tar.gz`: https://download.osgeo.org/proj/proj-data-1.7.tar.gz +.. _`proj-data-1.6.tar.gz`: https://download.osgeo.org/proj/proj-data-1.6.tar.gz +.. _`proj-data-1.5.tar.gz`: https://download.osgeo.org/proj/proj-data-1.5.tar.gz +.. _`proj-data-1.4.tar.gz`: https://download.osgeo.org/proj/proj-data-1.4.tar.gz +.. _`proj-data-1.3.tar.gz`: https://download.osgeo.org/proj/proj-data-1.3.tar.gz +.. _`proj-data-1.2.tar.gz`: https://download.osgeo.org/proj/proj-data-1.2.tar.gz +.. _`proj-data-1.1.tar.gz`: https://download.osgeo.org/proj/proj-data-1.1.tar.gz +.. _`proj-data-1.0.tar.gz`: https://download.osgeo.org/proj/proj-data-1.0.tar.gz + +.. _`proj-datumgrid-1.6.zip`: https://download.osgeo.org/proj/proj-datumgrid-1.6.zip +.. _`proj-datumgrid-1.7.zip`: https://download.osgeo.org/proj/proj-datumgrid-1.7.zip +.. _`proj-datumgrid-1.8.zip`: https://download.osgeo.org/proj/proj-datumgrid-1.8.zip +.. _`proj-datumgrid-europe-1.0.zip`: https://download.osgeo.org/proj/proj-datumgrid-europe-1.0.zip +.. _`proj-datumgrid-europe-1.1.zip`: https://download.osgeo.org/proj/proj-datumgrid-europe-1.1.zip +.. _`proj-datumgrid-europe-1.2.zip`: https://download.osgeo.org/proj/proj-datumgrid-europe-1.2.zip +.. _`proj-datumgrid-europe-1.3.zip`: https://download.osgeo.org/proj/proj-datumgrid-europe-1.3.zip +.. _`proj-datumgrid-europe-1.4.zip`: https://download.osgeo.org/proj/proj-datumgrid-europe-1.4.zip +.. _`proj-datumgrid-europe-1.5.zip`: https://download.osgeo.org/proj/proj-datumgrid-europe-1.5.zip +.. _`proj-datumgrid-europe-1.6.zip`: https://download.osgeo.org/proj/proj-datumgrid-europe-1.6.zip +.. _`proj-datumgrid-north-america-1.0.zip`: https://download.osgeo.org/proj/proj-datumgrid-north-america-1.0.zip +.. _`proj-datumgrid-north-america-1.1.zip`: https://download.osgeo.org/proj/proj-datumgrid-north-america-1.1.zip +.. _`proj-datumgrid-north-america-1.2.zip`: https://download.osgeo.org/proj/proj-datumgrid-north-america-1.2.zip +.. _`proj-datumgrid-north-america-1.3.zip`: https://download.osgeo.org/proj/proj-datumgrid-north-america-1.3.zip +.. _`proj-datumgrid-north-america-1.4.zip`: https://download.osgeo.org/proj/proj-datumgrid-north-america-1.4.zip +.. _`proj-datumgrid-oceania-1.0.zip`: https://download.osgeo.org/proj/proj-datumgrid-oceania-1.0.zip +.. _`proj-datumgrid-oceania-1.1.zip`: https://download.osgeo.org/proj/proj-datumgrid-oceania-1.1.zip +.. _`proj-datumgrid-oceania-1.2.zip`: https://download.osgeo.org/proj/proj-datumgrid-oceania-1.2.zip +.. _`proj-datumgrid-world-1.0.zip`: https://download.osgeo.org/proj/proj-datumgrid-world-1.0.zip +.. _`proj.pdf`: https://raw.githubusercontent.com/OSGeo/PROJ/gh-pages/proj.pdf diff --git a/_sources/faq.rst.txt b/_sources/faq.rst.txt new file mode 100644 index 00000000..c34d6235 --- /dev/null +++ b/_sources/faq.rst.txt @@ -0,0 +1,195 @@ +.. _faq: + +****************************************************************************** +FAQ +****************************************************************************** + +.. only:: not latex + + .. contents:: + :depth: 3 + :backlinks: none + +Which file formats does PROJ support? +-------------------------------------------------------------------------------- + +The :ref:`command line applications <apps>` that come with PROJ only support text +input and output (apart from :program:`proj` which accepts a simple binary data +stream as well). :program:`proj`, :program:`cs2cs` and :program:`cct` expects +text files with one coordinate per line with each coordinate dimension in a +separate column. + +.. note:: + + If your data is stored in a common geodata file format chances are that + you can use `GDAL <https://gdal.org/>`_ as a frontend to PROJ and transform your data with the + :program:`ogr2ogr` application. + +Can I transform from *abc* to *xyz*? +-------------------------------------------------------------------------------- + +Probably. PROJ supports transformations between most coordinate reference systems +registered in the EPSG registry, as well as a number of other coordinate reference +systems. The best way to find out is to test it with the :program:`projinfo` +application. Here's an example checking if there's a transformation between +ETRS89/UTM32N (EPSG:25832) and ETRS89/DKTM1 (EPSG:4093): + +.. code-block:: console + + $ ./projinfo -s EPSG:25832 -t EPSG:4093 -o PROJ + Candidate operations found: 1 + ------------------------------------- + Operation No. 1: + + unknown id, Inverse of UTM zone 32N + DKTM1, 0 m, World + + PROJ string: + +proj=pipeline + +step +inv +proj=utm +zone=32 +ellps=GRS80 + +step +proj=tmerc +lat_0=0 +lon_0=9 +k=0.99998 +x_0=200000 +y_0=-5000000 + +ellps=GRS80 + +See the :program:`projinfo` :ref:`documentation <projinfo>` for more info on +how to use it. + +Coordinate reference system *xyz* is not in the EPSG registry, what do I do? +-------------------------------------------------------------------------------- + +Generally PROJ will accept coordinate reference system descriptions in the form +of WKT, WKT2 and PROJ strings. If you are able to describe your desired CRS +in either of those formats there's a good chance that PROJ will be able to make +sense of it. + +If it is important to you that a given CRS is added to the EPSG registry, you +should contact your local geodetic authority and ask them to submit the CRS for +inclusion in the registry. + +I found a bug in PROJ, how do I get it fixed? +-------------------------------------------------------------------------------- + +Please report bugs that you find to the issue tracker on GitHub. :ref:`Here's how +<add_bug_report>`. + +If you know how to program you can also try to fix it yourself. You are welcome +to ask for guidance on one of the :ref:`communication channels <channels>` used +by the project. + +How do I contribute to PROJ? +-------------------------------------------------------------------------------- + +Any contributions from the PROJ community is welcome. See :ref:`contributing` for +more details. + +How do I calculate distances/directions on the surface of the earth? +-------------------------------------------------------------------------------- + +These are called geodesic calculations. There is a page about it here: +:ref:`geodesic`. + +What is the best format for describing coordinate reference systems? +-------------------------------------------------------------------------------- + +A coordinate reference system (CRS) can in PROJ be described in several ways: +As PROJ strings, Well-Known Text (WKT) and as spatial reference ID's (such as EPSG +codes). Generally, WKT or SRID's are preferred over PROJ strings as they can +contain more information about a given CRS. Conversions between WKT and PROJ +strings will in most cases cause a loss of information, potentially leading to +erroneous transformations. + +For compatibility reasons PROJ supports several WKT dialects +(see :option:`projinfo -o`). If possible WKT2 should be used. + +Why is the axis ordering in PROJ not consistent? +-------------------------------------------------------------------------------- + +PROJ respects the axis ordering as it was defined by the authority in charge of +a given coordinate reference system. This is in accordance to the ISO19111 standard +:cite:`ISO19111`. Unfortunately most GIS software on the market doesn't follow this +standard. Before version 6, PROJ did not respect the standard either. This causes +some problems while the rest of the industry conforms to the standard. PROJ intends +to spearhead this effort, hopefully setting a good example for the rest of the +geospatial industry. + +Customarily in GIS the first component in a coordinate tuple has been aligned with +the east/west direction and the second component with the north/south direction. +For many coordinate reference systems this is also what is defined by the authority. +There are however exceptions, especially when dealing with coordinate systems that +don't align with the cardinal directions of a compass. For example it is not +obvious which coordinate component aligns to which axis in a skewed coordinate +system with a 45 degrees angle against the north direction. Similarly, a geocentric +cartesian coordinate system usually has the z-component aligned with the rotational +axis of the earth and hence the axis points towards north. Both cases are +incompatible with the convention of always having the x-component be the east/west +axis, the y-component the north/south axis and the z-component the up/down axis. + +In most cases coordinate reference systems with geodetic coordinates expect the +input ordered as latitude/longitude (typically with the EPSG dataset), however, +internally PROJ expects an longitude/latitude ordering for all projections. This +is generally hidden for users but in a few cases it is exposed at the surface +level of PROJ, most prominently in the :program:`proj` utility which expects +longitude/latitude ordering of input date (unless :option:`proj -r` is used). + +In case of doubt about the axis order of a specific CRS :program:`projinfo` is +able to provide an answer. Simply look up the CRS and examine the axis specification +of the Well-Known Text output: + +.. code-block:: console + + projinfo EPSG:4326 + PROJ.4 string: + +proj=longlat +datum=WGS84 +no_defs +type=crs + + WKT2:2019 string: + GEOGCRS["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]], + USAGE[ + SCOPE["unknown"], + AREA["World"], + BBOX[-90,-180,90,180]], + ID["EPSG",4326]] + +Why am I getting the error "Cannot find proj.db"? +-------------------------------------------------------------------------------- +The file :ref:`proj.db<proj-db>` must be readable for the library to properly +function. Like other :doc:`resource files<../resource_files>`, +it is located using a set of search +paths. In most cases, the following paths are checked in order: + + - A path provided by the environment variable :envvar:`PROJ_LIB`. + - A path built into PROJ as its resource installation directory + (typically ../share/proj relative to the PROJ library). + - The current directory. + +Note that if you're using conda, activating an environment sets +:envvar:`PROJ_LIB` to a resource directory located in that environment. + + +What happened to PROJ.4? +-------------------------------------------------------------------------------- + +The first incarnation of PROJ saw the light of day in 1983. Back then it +was simply known as PROJ. Eventually a new version was released, known +as PROJ.2 in order to distinguish between the two versions. Later on both +PROJ.3 and PROJ.4 was released. By the time PROJ.4 was released the +software had matured enough that a new major version release wasn't an +immediate necessity. PROJ.4 was around for more than 25 years before it +again became time for an update. This left the project in a bit of a +conundrum regarding the name. For the majority of the life-time of the product it was known as PROJ.4, but with the release of version 5 the name +was no longer aligned with the version number. As a consequence, it was +decided to decouple the name from the version number and once again simply +call the software PROJ. + +Use of name PROJ.4 is now strictly reserved for describing legacy behavior +of the software, e.g. "PROJ.4 strings" as seen in :program:`projinfo` +output. diff --git a/_sources/geodesic.rst.txt b/_sources/geodesic.rst.txt new file mode 100644 index 00000000..4094458d --- /dev/null +++ b/_sources/geodesic.rst.txt @@ -0,0 +1,170 @@ +.. _geodesic: + +Geodesic calculations +===================== + +Introduction +------------ + +Consider an ellipsoid of revolution with equatorial radius :math:`a`, polar +semi-axis :math:`b`, and flattening :math:`f=(a-b)/a`. Points on +the surface of the ellipsoid are characterized by their latitude :math:`\phi` +and longitude :math:`\lambda`. (Note that latitude here means the +*geographical latitude*, the angle between the normal to the ellipsoid +and the equatorial plane). + +The shortest path between two points on the ellipsoid at +:math:`(\phi_1,\lambda_1)` and :math:`(\phi_2,\lambda_2)` +is called the geodesic. Its length is +:math:`s_{12}` and the geodesic from point 1 to point 2 has forward +azimuths :math:`\alpha_1` and :math:`\alpha_2` at the two end +points. In this figure, we have :math:`\lambda_{12}=\lambda_2-\lambda_1`. + + .. raw:: html + + <center> + <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/c/cb/Geodesic_problem_on_an_ellipsoid.svg/320px-Geodesic_problem_on_an_ellipsoid.svg.png" + alt="Figure from wikipedia" + width="320"> + </center> + +A geodesic can be extended indefinitely by requiring that any +sufficiently small segment is a shortest path; geodesics are also the +straightest curves on the surface. + +Solution of geodesic problems +----------------------------- + +Traditionally two geodesic problems are considered: + +* the direct problem — given :math:`\phi_1`, + :math:`\lambda_1`, :math:`\alpha_1`, :math:`s_{12}`, + determine :math:`\phi_2`, :math:`\lambda_2`, :math:`\alpha_2`. + +* the inverse problem — given :math:`\phi_1`, + :math:`\lambda_1`, :math:`\phi_2`, :math:`\lambda_2`, + determine :math:`s_{12}`, :math:`\alpha_1`, + :math:`\alpha_2`. + +PROJ incorporates `C library for Geodesics +<https://geographiclib.sourceforge.io/1.52/C/>`_ from `GeographicLib +<https://geographiclib.sourceforge.io>`_. This library provides +routines to solve the direct and inverse geodesic problems. Full double +precision accuracy is maintained provided that +:math:`\lvert f\rvert<\frac1{50}`. Refer to the `application programming interface +<https://geographiclib.sourceforge.io/1.52/C/geodesic_8h.html>`_ +for full documentation. A brief summary of the routines is given in +geodesic(3). + +The interface to the geodesic routines differ in two respects from the +rest of PROJ: + +* angles (latitudes, longitudes, and azimuths) are in degrees (instead + of in radians); +* the shape of ellipsoid is specified by the flattening :math:`f`; this can + be negative to denote a prolate ellipsoid; setting :math:`f=0` corresponds + to a sphere, in which case the geodesic becomes a great circle. + +PROJ also includes a command line tool, :ref:`geod`\ (1), for performing +simple geodesic calculations. + +Additional properties +--------------------- + +The routines also calculate several other quantities of interest + +* :math:`S_{12}` is the area between the geodesic from point 1 to + point 2 and the equator; i.e., it is the area, measured + counter-clockwise, of the quadrilateral with corners + :math:`(\phi_1,\lambda_1)`, :math:`(0,\lambda_1)`, + :math:`(0,\lambda_2)`, and + :math:`(\phi_2,\lambda_2)`. It is given in + meters\ :sup:`2`. +* :math:`m_{12}`, the reduced length of the geodesic is defined such + that if the initial azimuth is perturbed by :math:`d\alpha_1` + (radians) then the second point is displaced by :math:`m_{12}\,d\alpha_1` + in the direction perpendicular to the + geodesic. :math:`m_{12}` is given in meters. On a curved surface + the reduced length obeys a symmetry relation, :math:`m_{12}+m_{21}=0`. + On a flat surface, we have :math:`m_{12}=s_{12}`. +* :math:`M_{12}` and :math:`M_{21}` are geodesic scales. If two + geodesics are parallel at point 1 and separated by a small distance + :math:`dt`, then they are separated by a distance :math:`M_{12}\,dt` at + point 2. :math:`M_{21}` is defined similarly (with the geodesics + being parallel to one another at point 2). :math:`M_{12}` and + :math:`M_{21}` are dimensionless quantities. On a flat surface, + we have :math:`M_{12}=M_{21}=1`. +* :math:`\sigma_{12}` is the arc length on the auxiliary sphere. + This is a construct for converting the problem to one in spherical + trigonometry. The spherical arc length from one equator crossing to + the next is always :math:`180^\circ`. + +If points 1, 2, and 3 lie on a single geodesic, then the following +addition rules hold: + +* :math:`s_{13}=s_{12}+s_{23}`, +* :math:`\sigma_{13}=\sigma_{12}+\sigma_{23}`, +* :math:`S_{13}=S_{12}+S_{23}`, +* :math:`m_{13}=m_{12}M_{23}+m_{23}M_{21}`, +* :math:`M_{13}=M_{12}M_{23}-(1-M_{12}M_{21})m_{23}/m_{12}`, +* :math:`M_{31}=M_{32}M_{21}-(1-M_{23}M_{32})m_{12}/m_{23}`. + +Multiple shortest geodesics +--------------------------- + +The shortest distance found by solving the inverse problem is +(obviously) uniquely defined. However, in a few special cases there are +multiple azimuths which yield the same shortest distance. Here is a +catalog of those cases: + +* :math:`\phi_1=-\phi_2` (with neither point at + a pole). If :math:`\alpha_1=\alpha_2`, the geodesic + is unique. Otherwise there are two geodesics and the second one is + obtained by setting + :math:`[\alpha_1,\alpha_2]\leftarrow[\alpha_2,\alpha_1]`, + :math:`[M_{12},M_{21}]\leftarrow[M_{21},M_{12}]`, + :math:`S_{12}\leftarrow-S_{12}`. + (This occurs when the longitude difference is near :math:`\pm180^\circ` + for oblate ellipsoids.) +* :math:`\lambda_2=\lambda_1\pm180^\circ` (with + neither point at a pole). If :math:`\alpha_1=0^\circ` or + :math:`\pm180^\circ`, the geodesic is unique. Otherwise there are two + geodesics and the second one is obtained by setting + :math:`[\alpha_1,\alpha_2]\leftarrow[-\alpha_1,-\alpha_2]`, + :math:`S_{12}\leftarrow-S_{12}`. (This occurs when + :math:`\phi_2` is near :math:`-\phi_1` for prolate + ellipsoids.) +* Points 1 and 2 at opposite poles. There are infinitely many + geodesics which can be generated by setting + :math:`[\alpha_1,\alpha_2]\leftarrow[\alpha_1,\alpha_2]+[\delta,-\delta]`, + for arbitrary :math:`\delta`. + (For spheres, this prescription applies when points 1 and 2 are + antipodal.) +* :math:`s_{12}=0` (coincident points). There are infinitely many + geodesics which can be generated by setting + :math:`[\alpha_1,\alpha_2]\leftarrow[\alpha_1,\alpha_2]+[\delta,\delta]`, + for arbitrary :math:`\delta`. + +Background +---------- + +The algorithms implemented by this package are given in :cite:`Karney2013` +(`addenda <https://geographiclib.sourceforge.io/geod-addenda.html>`_) +and are based on :cite:`Bessel1825` and :cite:`Helmert1880`; the algorithm for +areas is based on :cite:`Danielsen1989`. These improve on the work of +:cite:`Vincenty1975` in the following respects: + +* The results are accurate to round-off for terrestrial ellipsoids (the + error in the distance is less than 15 nanometers, compared to 0.1 mm + for Vincenty). +* The solution of the inverse problem is always found. (Vincenty's + method fails to converge for nearly antipodal points.) +* The routines calculate differential and integral properties of a + geodesic. This allows, for example, the area of a geodesic polygon to + be computed. + +Additional background material is provided in GeographicLib's `geodesic +bibliography <https://geographiclib.sourceforge.io/geodesic-papers/biblio.html>`_, +Wikipedia's article "`Geodesics on an ellipsoid +<https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid>`_", and :cite:`Karney2011` +(`errata <https://geographiclib.sourceforge.io/geod-addenda.html#geod-errata>`_). diff --git a/_sources/glossary.rst.txt b/_sources/glossary.rst.txt new file mode 100644 index 00000000..147645ad --- /dev/null +++ b/_sources/glossary.rst.txt @@ -0,0 +1,56 @@ +.. _glossary: + +================================================================================ +Glossary +================================================================================ + +.. glossary:: + + Ballpark transformation + + For a transformation between two geographic CRS, a ballpark + transformation is a coordinate operation that only takes into account + potential difference of axis orders (long-lat vs lat-long), + units (degree vs grads) and prime meridian (Greenwich vs Paris/Rome/other + historic prime meridians). It does not attempt any datum shift, hence + the "ballpark" qualifier in its name. Its accuracy is unknown, and could + lead in some cases to errors of a few hundreds of metres. + + For a transformation between two vertical CRS or a vertical CRS and + a geographic CRS, a ballpark transformation only takes into account + potential different in units (e.g. metres vs feet). Its accuracy is + unknown, and could lead in some cases to errors of a few tens of metres. + + .. note:: + + The term "Ballpark transformation" is specific to PROJ. + + Pseudocylindrical Projection + + Pseudocylindrical projections have the mathematical characteristics of + + .. math:: + + x &= f(\lambda,\phi) + + y &= g(\phi) + + where the parallels of latitude are straight lines, like cylindrical + projections, but the meridians are curved toward the center as they + depart from the equator. This is an effort to minimize the distortion + of the polar regions inherent in the cylindrical projections. + + Pseudocylindrical projections are almost exclusively used for small + scale global displays and, except for the Sinusoidal projection, only + derived for a spherical Earth. Because of the basic definition none of + the pseudocylindrical projections are conformal but many are equal + area. + + To further reduce distortion, pseudocylindrical are often presented in + interrupted form that are made by joining several regions with + appropriate central meridians and false easting and clipping + boundaries. Interrupted Homolosine constructions are suited for showing + respective global land and oceanic regions, for example. To reduce the + lateral size of the map, some uses remove an irregular, North-South + strip of the mid-Atlantic region so that the western tip of Africa is + plotted north of the eastern tip of South America. diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt new file mode 100644 index 00000000..3a2df4b4 --- /dev/null +++ b/_sources/index.rst.txt @@ -0,0 +1,37 @@ +.. _home: + +PROJ +############################################################################### + +.. toctree:: + :maxdepth: 4 + :hidden: + + about + news + download + install + usage/index + apps/index + operations/index + resource_files + geodesic + development/index + specifications/index + community/index + faq + glossary + zreferences + +.. only:: html + + .. include:: about_core.rst + + You can download the source code for PROJ on the :ref:`download section<download>` + and find links to prepackaged executables in the + :ref:`installation section<install>`. + + In addition to this website the PROJ documentation is also available in `PDF`_ + form. + +.. _`PDF`: https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf diff --git a/_sources/install.rst.txt b/_sources/install.rst.txt new file mode 100644 index 00000000..17d31488 --- /dev/null +++ b/_sources/install.rst.txt @@ -0,0 +1,492 @@ +.. _install: + +================================================================================ +Installation +================================================================================ + +These pages describe how to install PROJ on your computer without compiling it +yourself. Below are guides for installing on Windows, Linux and Mac OS X. This +is a good place to get started if this is your first time using PROJ. More +advanced users may want to compile the software themselves. + +Installation from package management systems +################################################################################ + + +Cross platform +-------------------------------------------------------------------------------- + +PROJ is also available via cross platform package managers. + +Conda +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The conda package manager includes several PROJ packages. We recommend installing +from the ``conda-forge`` channel:: + + conda install -c conda-forge proj + +Using ``conda`` you can also install the PROJ data package. Here's how to install +the `proj-data` package:: + + conda install -c conda-forge proj-data + +Available is also the legacy packages ``proj-datumgrid-europe``, +``proj-datumgrid-north-america``, ``proj-datumgrid-oceania`` and +``proj-datumgrid-world``. + +.. tip:: + Read more about the various datumgrid packages available :ref:`here<datumgrid>`. + +Docker ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +A `Docker`_ image with just PROJ binaries and a full compliment of grid shift +files is available on `DockerHub`_. Get the package with:: + + docker pull osgeo/proj + +.. _`Docker`: https://www.docker.com/ +.. _`DockerHub`: https://hub.docker.com/r/osgeo/proj/ + +Windows +-------------------------------------------------------------------------------- + +The simplest way to install PROJ on Windows is to use the `OSGeo4W`_ software +distribution. OSGeo4W provides easy access to many popular open source geospatial +software packages. After installation you can use PROJ from the OSGeo4W shell. +To install PROJ do the following: + +.. note:: + If you have already installed software via OSGeo4W on your computer, or if + you have already installed QGIS on your computer, it is likely that PROJ is + already installed. Type "OSGeo4W Shell" in your start menu and check whether + that gives a match. + +1. Download either the `32 bit`_ or `64 bit`_ installer. +2. Run the OSGeo4W setup program. +3. Select "Advanced Install" and press Next. +4. Select "Install from Internet" and press Next. +5. Select a installation directory. The default suggestion is fine in most cases. Press Next. +6. Select "Local package directory". The default suggestion is fine in most cases. Press Next. +7. Select "Direct connection" and press Next. +8. Choose the download.osgeo.org server and press Next. +9. Find "proj" under "Commandline_Utilities" and click the package in the "New" column until the version you want to install appears. +10. Press next to install PROJ. + +You should now have a "OSGeo" menu in your start menu. Within that menu you can +find the "OSGeo4W Shell" where you have access to all the OSGeo4W applications, +including proj. + +For those who are more inclined to the command line, steps 2--10 above can be +accomplished by executing the following command:: + + C:\temp\osgeo4w-setup-x86-64.exe -q -k -r -A -s https://download.osgeo.org/osgeo4w/ -a x86_64 -P proj + +.. _`OSGeo4W`: https://trac.osgeo.org/osgeo4w/ +.. _`32 bit`: https://download.osgeo.org/osgeo4w/osgeo4w-setup-x86.exe +.. _`64 bit`: https://download.osgeo.org/osgeo4w/osgeo4w-setup-x86_64.exe + +Linux +-------------------------------------------------------------------------------- + +How to install PROJ on Linux depends on which distribution you are using. Below +is a few examples for some of the more common Linux distributions: + +Debian +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +On Debian and similar systems (e.g. Ubuntu) the APT package manager is used:: + + sudo apt-get install proj-bin + +Fedora +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +On Fedora the :program:`dnf` package manager is used:: + + sudo dnf install proj + +Red Hat +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +On Red Hat based system packages are installed with :program:`yum`:: + + sudo yum install proj + + +Mac OS X +-------------------------------------------------------------------------------- + +On OS X PROJ can be installed via the Homebrew package manager:: + + brew install proj + +PROJ is also available from the MacPorts system:: + + sudo ports install proj + +Compilation and installation from source code +################################################################################ + +The classic way of installing PROJ is via the source code distribution. The +most recent version is available from the :ref:`download page<current_release>`. + +The following guides show how to compile and install the software using CMake. + + .. note:: + + Support for Autotools was maintained until PROJ 8.2 (see :ref:`RFC7`). + PROJ 9.0 and later releases only support builds using CMake. + + +Build requirements +-------------------------------------------------------------------------------- + +- C99 compiler +- C++11 compiler +- CMake >= 3.9 +- SQLite3 >= 3.11: headers and library for target architecture, and sqlite3 executable for build architecture. +- libtiff >= 4.0 (optional but recommended) +- curl >= 7.29.0 (optional but recommended) + +Build steps +-------------------------------------------------------------------------------- + +With the CMake build system you can compile and install PROJ on more or less any +platform. After unpacking the source distribution archive step into the source- +tree:: + + cd proj-{PROJVERSION} + +Create a build directory and step into it:: + + mkdir build + cd build + +From the build directory you can now configure CMake, build and install the binaries:: + + cmake .. + cmake --build . + cmake --build . --target install + +On Windows, one may need to specify generator:: + + cmake -G "Visual Studio 15 2017" .. + +If the SQLite3 dependency is installed in a custom location, specify the +paths to the include directory and the library:: + + cmake -DSQLITE3_INCLUDE_DIR=/opt/SQLite/include -DSQLITE3_LIBRARY=/opt/SQLite/lib/libsqlite3.so .. + +Alternatively, the custom prefix for SQLite3 can be specified:: + + cmake -DCMAKE_PREFIX_PATH=/opt/SQLite .. + + +Tests are run with:: + + ctest + +With a successful install of PROJ we can now install data files using the +:program:`projsync` utility:: + + projsync --system-directory + +which will download all resource files currently available for PROJ. If less than +the entire collection of resource files is needed the call to :program:`projsync` +can be modified to suit the users needs. See :ref:`projsync` for more options. + +.. note:: + + The use of :program:`projsync` requires that network support is enabled (the + default option). If the resource files are not installed using + :program:`projsync` PROJ will attempt to fetch them automatically when a + transformation needs a specific data file. This requires that + :envvar:`PROJ_NETWORK` is set to ``ON``. + + As an alternative on systems where network access is disabled, the + :ref:`proj-data <datumgrid>` + package can be downloaded and added to the :envvar:`PROJ_LIB` directory. + + + + +CMake configure options +-------------------------------------------------------------------------------- + +Options to configure a CMake are provided using ``-D<var>=<value>``. +All cached entries can be viewed using ``cmake -LAH`` from a build directory. + +.. option:: BUILD_APPS=ON + + Build PROJ applications. Default is ON. Control the default value for + BUILD_CCT, BUILD_CS2CS, BUILD_GEOD, BUILD_GIE, BUILD_PROJ, BUILD_PROJINFO + and BUILD_PROJSYNC. + Note that changing its value after having configured once will not change + the value of the individual BUILD_CCT, ... options. + + .. versionchanged:: 8.2 + +.. option:: BUILD_CCT=ON + + Build :ref:`cct`, default is the value of BUILD_APPS. + +.. option:: BUILD_CS2CS=ON + + Build :ref:`cs2cs`,default is the value of BUILD_APPS. + +.. option:: BUILD_GEOD=ON + + Build :ref:`geod`, default is the value of BUILD_APPS. + +.. option:: BUILD_GIE=ON + + Build :ref:`gie`, default is the value of BUILD_APPS. + +.. option:: BUILD_PROJ=ON + + Build :ref:`proj`, default is the value of BUILD_APPS. + +.. option:: BUILD_PROJINFO=ON + + Build :ref:`projinfo`, default is the value of BUILD_APPS. + +.. option:: BUILD_PROJSYNC=ON + + Build :ref:`projsync`, default is the value of BUILD_APPS. + +.. option:: BUILD_SHARED_LIBS + + Build PROJ library shared. Default is ON. See also the CMake + documentation for `BUILD_SHARED_LIBS + <https://cmake.org/cmake/help/v3.9/variable/BUILD_SHARED_LIBS.html>`_. + + .. versionchanged:: 7.0 + Renamed from ``BUILD_LIBPROJ_SHARED`` + + .. note:: before PROJ 9.0, the default was OFF for Windows builds. + +.. option:: BUILD_TESTING=ON + + CTest option to build the testing tree, which also downloads and installs + Googletest. Default is ON, but can be turned OFF if tests are not required. + + .. versionchanged:: 7.0 + Renamed from ``PROJ_TESTS`` + +.. option:: CMAKE_BUILD_TYPE + + Choose the type of build, options are: None (default), Debug, Release, + RelWithDebInfo, or MinSizeRel. See also the CMake documentation for + `CMAKE_BUILD_TYPE + <https://cmake.org/cmake/help/v3.9/variable/CMAKE_BUILD_TYPE.html>`_. + + .. note:: + A default build is not optimized without specifying + ``-DCMAKE_BUILD_TYPE=Release`` (or similar) during configuration, + or by specifying ``--config Release`` with CMake + multi-configuration build tools (see example below). + +.. option:: CMAKE_C_COMPILER + + C compiler. Ignored for some generators, such as Visual Studio. + +.. option:: CMAKE_C_FLAGS + + Flags used by the C compiler during all build types. This is + initialized by the :envvar:`CFLAGS` environment variable. + +.. option:: CMAKE_CXX_COMPILER + + C++ compiler. Ignored for some generators, such as Visual Studio. + +.. option:: CMAKE_CXX_FLAGS + + Flags used by the C++ compiler during all build types. This is + initialized by the :envvar:`CXXFLAGS` environment variable. + +.. option:: CMAKE_INSTALL_PREFIX + + Default for Windows is based on the environment variable + :envvar:`OSGEO4W_ROOT` (if set), otherwise is ``c:/OSGeo4W``. + Default for Unix-like is ``/usr/local/``. + +.. option:: ENABLE_IPO=OFF + + Build library using the compiler's `interprocedural optimization + <https://en.wikipedia.org/wiki/Interprocedural_optimization>`_ + (IPO), if available, default OFF. + + .. versionchanged:: 7.0 + Renamed from ``ENABLE_LTO``. + +.. option:: EXE_SQLITE3 + + Path to an ``sqlite3`` or ``sqlite3.exe`` executable. + +.. option:: SQLITE3_INCLUDE_DIR + + Path to an include directory with the ``sqlite3.h`` header file. + +.. option:: SQLITE3_LIBRARY + + Path to a shared or static library file, such as ``sqlite3.dll``, + ``libsqlite3.so``, ``sqlite3.lib`` or other name. + +.. option:: ENABLE_CURL=ON + + Enable CURL support, default ON. + +.. option:: CURL_INCLUDE_DIR + + Path to an include directory with the ``curl`` directory. + +.. option:: CURL_LIBRARY + + Path to a shared or static library file, such as ``libcurl.dll``, + ``libcurl.so``, ``libcurl.lib``, or other name. + +.. option:: ENABLE_TIFF=ON + + Enable TIFF support to use PROJ-data resource files, default ON. + +.. option:: TIFF_INCLUDE_DIR + + Path to an include directory with the ``tiff.h`` header file. + +.. option:: TIFF_LIBRARY_RELEASE + + Path to a shared or static library file, such as ``tiff.dll``, + ``libtiff.so``, ``tiff.lib``, or other name. A similar variable + ``TIFF_LIBRARY_DEBUG`` can also be specified to a similar library for + building Debug releases. + +.. option:: USE_CCACHE=OFF + + Configure CMake to use `ccache <https://ccache.dev/>`_ (or + `clcache <https://github.com/frerich/clcache>`_ for MSVC) + to build C/C++ objects. + + +Building on Windows with vcpkg and Visual Studio 2017 or 2019 +-------------------------------------------------------------------------------- + +This method is the preferred one to generate Debug and Release builds. + +Install git ++++++++++++ + +Install `git <https://git-scm.com/download/win>`_ + +Install Vcpkg ++++++++++++++ + +Assuming there is a c:\\dev directory + +:: + + cd c:\dev + git clone https://github.com/Microsoft/vcpkg.git + + cd vcpkg + .\bootstrap-vcpkg.bat + +Install PROJ dependencies ++++++++++++++++++++++++++ + +:: + + vcpkg.exe install sqlite3[core,tool]:x86-windows tiff:x86-windows curl:x86-windows + vcpkg.exe install sqlite3[core,tool]:x64-windows tiff:x64-windows curl:x64-windows + +.. note:: The tiff and curl dependencies are only needed since PROJ 7.0 + +Checkout PROJ sources ++++++++++++++++++++++ + +:: + + cd c:\dev + git clone https://github.com/OSGeo/PROJ.git + +Build PROJ +++++++++++ + +:: + + cd c:\dev\PROJ + mkdir build_vs2019 + cd build_vs2019 + cmake -DCMAKE_TOOLCHAIN_FILE=C:\dev\vcpkg\scripts\buildsystems\vcpkg.cmake .. + cmake --build . --config Debug -j 8 + + +Run PROJ tests +++++++++++++++ + +:: + + cd c:\dev\PROJ\build_vs2019 + ctest -V --build-config Debug + + +Building on Windows with Conda dependencies and Visual Studio 2017 or 2019 +-------------------------------------------------------------------------------- + +Variant of the above method but using Conda for SQLite3, TIFF and CURL dependencies. +It is less appropriate for Debug builds of PROJ than the method based on vcpkg. + +Install git ++++++++++++ + +Install `git <https://git-scm.com/download/win>`_ + +Install miniconda ++++++++++++++++++ + +Install `miniconda <https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe>`_ + +Install PROJ dependencies ++++++++++++++++++++++++++ + +Start a Conda enabled console and assuming there is a c:\\dev directory + +:: + + cd c:\dev + conda create --name proj + conda activate proj + conda install sqlite libtiff curl cmake + +.. note:: The libtiff and curl dependencies are only needed since PROJ 7.0 + +Checkout PROJ sources ++++++++++++++++++++++ + +:: + + cd c:\dev + git clone https://github.com/OSGeo/PROJ.git + +Build PROJ +++++++++++ + +From a Conda enabled console + +:: + + conda activate proj + cd c:\dev\PROJ + call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat" + cmake -S . -B _build.vs2019 -DCMAKE_LIBRARY_PATH:FILEPATH="%CONDA_PREFIX%/Library/lib" -DCMAKE_INCLUDE_PATH:FILEPATH="%CONDA_PREFIX%/Library/include" + cmake --build _build.vs2019 --config Release -j 8 + +Run PROJ tests +++++++++++++++ + +:: + + cd c:\dev\PROJ + cd _build.vs2019 + ctest -V --build-config Release diff --git a/_sources/news.rst.txt b/_sources/news.rst.txt new file mode 100644 index 00000000..da084c4b --- /dev/null +++ b/_sources/news.rst.txt @@ -0,0 +1,1925 @@ +.. _news: + +News +############################################################################### + +9.0.0 Release Notes ++++++++++++++++++++ +*March 1st 2022* + + +Breaking Changes +---------------- + +* Support for the autotools build system has been removed (`#3027 <https://github.com/OSGeo/PROJ/issues/3027>`_) + See RFC7 for details: https://proj.org/community/rfc/rfc-7.html + +Updates +-------- + +* Database updates: + + * ESRI projection engine db to version 12.9 (`#2943 <https://github.com/OSGeo/PROJ/issues/2943>`_) + + * EPSG v10.054 (`#3051 <https://github.com/OSGeo/PROJ/issues/3051>`_) + + * Vertical grid files for PL-geoid-2011, Polish geoid model (`#2960 <https://github.com/OSGeo/PROJ/issues/2960>`_) + + * Belgian geoid model hBG18 to grid alternatives (`#3044 <https://github.com/OSGeo/PROJ/issues/3044>`_) + +* Add new option to :c:func:`proj_create_crs_to_crs_from_pj` method to force ``+over`` on + transformation operations (`#2914 <https://github.com/OSGeo/PROJ/issues/2914>`_) + +* Specify ``CMAKE_INSTALL_RPATH`` for macOS; use ``-rpath LDFLAGS`` for tests (`#3009 <https://github.com/OSGeo/PROJ/issues/3009>`_) + +* Implement Geographic3D to Depth/Geog2D+Depth as used by ETRS89 to CD Norway + depth (`#3010 <https://github.com/OSGeo/PROJ/issues/3010>`_) + +* Allow ``PROJ_LIB`` paths wrapped with double quotes (`#3031 <https://github.com/OSGeo/PROJ/issues/3031>`_) + +* Use external gtest by default when possible (`#3035 <https://github.com/OSGeo/PROJ/issues/3035>`_) + +* CMake: make ``BUILD_SHARED_LIBS=ON`` the default even on Windows (`#3042 <https://github.com/OSGeo/PROJ/issues/3042>`_) + +* ``proj.ini``: add a ``ca_bundle_path`` variable (`#3049 <https://github.com/OSGeo/PROJ/issues/3049>`_) + + +Bug fixes +---------- + +* Fix extremely long parsing time on hostile PROJ strings (`#2968 <https://github.com/OSGeo/PROJ/issues/2968>`_) + +* CMake: fix warning with external googletest (`#2980 <https://github.com/OSGeo/PROJ/issues/2980>`_) + +* :c:func:`proj_get_crs_info_list_from_database()`: report ``PJ_TYPE_GEODETIC_CRS`` for + IAU_2015 -ocentric geodetic CRS (`#3013 <https://github.com/OSGeo/PROJ/issues/3013>`_) + +* peirce_q: rename ``+type`` parameter wrongly introduced in 8.2.1 to ``+shape`` (`#3014 <https://github.com/OSGeo/PROJ/issues/3014>`_) + +* Set more precise error code for parsing errors in :c:func:`proj_create()` (`#3037 <https://github.com/OSGeo/PROJ/issues/3037>`_) + +* :cpp:func:`createOperations()`: fix transformations from/to a BoundCRS of a + DerivedGeographicCRS coming from WKT (`#3046 <https://github.com/OSGeo/PROJ/issues/3046>`_) + +* Better deal with importing strings like ``+init=epsg:XXXX +over`` (`#3055 <https://github.com/OSGeo/PROJ/issues/3055>`_) + +* Fix importing CRS definition with ``+proj=peirce_q`` and ``+shape`` different from + square or diamond (`#3057 <https://github.com/OSGeo/PROJ/issues/3057>`_) + + +8.2.1 Release Notes ++++++++++++++++++++ +*January 1st 2022* + + +Updates +------- + +* Database updated with EPSG v. 10.041 (`#2974 <https://github.com/OSGeo/PROJ/issues/2974>`_) + +Bug fixes +--------- + +* BoundCRS WKT import: fix setting of name (`#2917 <https://github.com/OSGeo/PROJ/issues/2917>`_) + +* :cpp:func:`PROJStringFormatter::toString()`: avoid invalid iterator increment (`#2932 <https://github.com/OSGeo/PROJ/issues/2932>`_) + +* Ensure CApi test are cross-platform (`#2934 <https://github.com/OSGeo/PROJ/issues/2934>`_) + +* :cpp:func:`createOperations()`: do not stop at the first operation in the PROJ namespace for vertical transformations (`#2937 <https://github.com/OSGeo/PROJ/issues/2937>`_) + +* :cpp:func:`createOperationsCompoundToCompound()`: fix null pointer dereference when connection to ``proj.db`` doesn't exist. (`#2938 <https://github.com/OSGeo/PROJ/issues/2938>`_) + +* Fix ``windows.h`` conflict with ``Criterion::STRICT`` (`#2950 <https://github.com/OSGeo/PROJ/issues/2950>`_) + +* Cache result of :c:func:`proj_get_type()` to help for performance of :c:func:`proj_factors()` (`#2967 <https://github.com/OSGeo/PROJ/issues/2967>`_) + +* :cpp:func:`createOperations()`: improvement for "NAD83(CSRS) + CGVD28 height" to "NAD83(CSRS) + CGVD2013(CGG2013) height" (`#2977 <https://github.com/OSGeo/PROJ/issues/2977>`_) + +* WKT1 import: correctly deal with missing rectified_grid_angle parameter (`#2986 <https://github.com/OSGeo/PROJ/issues/2986>`_) + +* Fix and additional options for Peirce Quincuncial projections (`#2978 <https://github.com/OSGeo/PROJ/issues/2978>`_) + +* Fix build with Intel C++ compiler (`#2995 <https://github.com/OSGeo/PROJ/issues/2995>`_) + + + +8.2.0 Release Notes ++++++++++++++++++++ +*November 1st 2021* + + +Announcements +------------- + +From PROJ 9.0.0 and onwards CMake will be the only build system bundled +with the PROJ package. As a consequence support for Autotools builds will +stop when the 8.2 branch of PROJ reaches end of life. We encourage +everyone to adjust their build workflows as soon as possible and report +any discrepancies discovered between Autotools and CMake builds. + +Details about the build system unification can be found in :ref:`RFC7`. + +Note also that the "CMake: revise handling of symbol export and static builds" +change mentioned below may require changes for users of the library on Windows. + +Updates +------- + +* Added the S2 projection (`#2749 <https://github.com/OSGEO/PROJ/issues/2749>`_) + +* Added support for Degree Sign on input (`#2791 <https://github.com/OSGEO/PROJ/issues/2791>`_) + +* ESRI WKT: add support for import/export of (non interrupted) + Goode Homolosine (`#2827 <https://github.com/OSGEO/PROJ/issues/2827>`_) + +* Make filemanager aware of UWP Win32 API (`#2831 <https://github.com/OSGEO/PROJ/issues/2831>`_) + +* Add :c:func:`proj_create_conversion_pole_rotation_netcdf_cf_convention()` to + address netCDF datasets using a pole rotation method (`#2835 <https://github.com/OSGEO/PROJ/issues/2835>`_) + +* Emit better debug message when a grid isn't found (`#2838 <https://github.com/OSGEO/PROJ/issues/2838>`_) + +* Add support for GeodeticCRS using a Spherical planetocentric + coordinate system (`#2847 <https://github.com/OSGEO/PROJ/issues/2847>`_) + +* PROJJSON: support additional properties allowed in id object (version, + authority_citation, uri) for parity with WKT2:2019 (`#2850 <https://github.com/OSGEO/PROJ/issues/2850>`_) + +* Database layout modified to include "anchor" field to ``geodetic_datum`` and + ``vertical_datum`` tables, consequently database layout version is increased + to 1.2 (`#2859 <https://github.com/OSGEO/PROJ/issues/2859>`_) + +* :c:func:`proj_factors()`: accept `P` to be a projected CRS (`#2868 <https://github.com/OSGEO/PROJ/issues/2868>`_) + +* Add IAU_2015 CRS definitions (`#2876 <https://github.com/OSGEO/PROJ/issues/2876>`_) + +* :cpp:func:`CRS::extractGeodeticCRS()`: implement for ``DerivedProjectedCRS`` (`#2877 <https://github.com/OSGEO/PROJ/issues/2877>`_) + +* Added :c:func:`proj_trans_bounds()` (`#2882 <https://github.com/OSGEO/PROJ/issues/2882>`_) + +* CMake: add a ``BUILD_APPS`` to be able to disable build of all applications (`#2895 <https://github.com/OSGEO/PROJ/issues/2895>`_) + +* CMake: generate ``invproj``/``invgeod`` binaries (symlinks on Unix, copy otherwise) + (`#2897 <https://github.com/OSGEO/PROJ/issues/2897>`_) + +* CMake build: add ``generate_wkt1_parser`` and ``generate_wkt2_parser manual`` + target, and logic to detect when they must be run (`#2900 <https://github.com/OSGEO/PROJ/issues/2900>`_) + +* Add fallback strategy for tinshift transform to use closest triangle for + points not in any (`#2907 <https://github.com/OSGEO/PROJ/issues/2907>`_) + +* Database: update to EPSG v10.038 (`#2910 <https://github.com/OSGEO/PROJ/issues/2910>`_) + +* CMake: revise handling of symbol export and static builds (`#2912 <https://github.com/OSGEO/PROJ/issues/2912>`_) + + This requires changes for users of static builds on Windows that do not use CMake + config files. The empty ``PROJ_DLL=`` definition must now be defined when building + against a static build of PROJ. + For users of dynamic builds on Windows, the ``PROJ_MSVC_DLL_IMPORT`` definition is + no longer needed. + +Bug fixes +--------- + +* Fix O(n^2) performance patterns where n is the number of steps of + a pipeline (`#2820 <https://github.com/OSGEO/PROJ/issues/2820>`_) + +* Detect ESRI WKT better in certain circumstances (`#2823 <https://github.com/OSGEO/PROJ/issues/2823>`_) + +* Fix performance issue on pipeline instanciation of huge (broken) + pipelines (`#2824 <https://github.com/OSGEO/PROJ/issues/2824>`_) + +* Make sure to re-order projection parameters according to their canonical + order if needed (`#2842 <https://github.com/OSGEO/PROJ/issues/2842>`_) + +* Fix database access across fork() when SQLite3 doesn't use ``pread[64]()`` (`#2845 <https://github.com/OSGEO/PROJ/issues/2845>`_) + +* Fix error in implementation of Inverse ellipsoidal orthographic projection + that cause convergence to sometimes fail (`#2853 <https://github.com/OSGEO/PROJ/issues/2853>`_) + +* Fix handling of edge-case coordinates in invers ortho ellipsoidal + oblique (`#2855 <https://github.com/OSGEO/PROJ/issues/2855>`_) + +* :c:func:`proj_normalize_for_visualization()`: set input and output units when there + are several alternative transformations (`#2867 <https://github.com/OSGEO/PROJ/issues/2867>`_) + +* :cpp:func:`CRS::identify()`: fix ignoring CS order when identifying a geodetic CRS + by a PROJ string with just the ellipsoid (`#2881 <https://github.com/OSGEO/PROJ/issues/2881>`_) + +* Fix CRS Equality with PROJ parameter order (`#2887 <https://github.com/OSGEO/PROJ/issues/2887>`_) + +* WKT concatenated operation parsing: fix when a axis order reversal conversion + is the first or last operation (`#2891 <https://github.com/OSGEO/PROJ/issues/2891>`_) + +* WKT1 parser: recognize Lambert_Conformal_Conic as projection name for + LCC 1SP or 2SP (`#2893 <https://github.com/OSGEO/PROJ/issues/2893>`_) + +* CMake: Always build gie if testing is requested (`#2899 <https://github.com/OSGEO/PROJ/issues/2899>`_) + +* Geographic 3D CRS: allow to export to WKT1:ESRI if only the GEOGCS is known + (and thus extrapolating a VERTCS) (`#2902 <https://github.com/OSGEO/PROJ/issues/2902>`_) + +* ``lib_proj.cmake``: add a PROJ::proj alias and add BUILD_INTERFACE include + directories, so that proj can be used as a subdirectory of a larger + project (`#2913 <https://github.com/OSGEO/PROJ/issues/2913>`_) + + +8.1.1 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*September 1st 2021* + +Updates +------- + +* EPSG Database updated to version 10.028 (`#2773 <https://github.com/OSGeo/PROJ/issues/2773>`_) + +Bug Fixes +--------- + +* Include algorithm header file to avoid build errors on Alpine Linux (`#2769 <https://github.com/OSGeo/PROJ/issues/2769>`_) + +* CMake: fix installation of executables on iOS (`#2766 <https://github.com/OSGeo/PROJ/issues/2766>`_) + +* Associate extents to transformations of CRS's that include GEOIDMODEL (`#2769 <https://github.com/OSGeo/PROJ/issues/2769>`_) + +* Logging: avoid some overhead when logging is not enabled (`#2775 <https://github.com/OSGeo/PROJ/issues/2775>`_) + +* ortho: remove useless and invalid log trace (`#2777 <https://github.com/OSGeo/PROJ/issues/2777>`_) + +* CMake: remove external nlohmann_json from INTERFACE_LINK_LIBRARIES target (`#2781 <https://github.com/OSGeo/PROJ/issues/2781>`_) +* reateOperations(): fix SourceTargetCRSExtentUse::NONE mode (`#2783 <https://github.com/OSGeo/PROJ/issues/2783>`_) + +* GeoTIFF grid reading: perf improvements (`#2788 <https://github.com/OSGeo/PROJ/issues/2788>`_) + +* :cpp:func:`Conversion::createUTM()`: avoid integer overflow (`#2796 <https://github.com/OSGeo/PROJ/issues/2796>`_) + +* Inverse laea ellipsoidal: return ``PROJ_ERR_COORD_TRANSFM_OUTSIDE_PROJECTION_DOMAIN`` + when appropriates (`#2801 <https://github.com/OSGeo/PROJ/issues/2801>`_) + +* Make sure that :c:func:`proj_crs_promote_to_3D` returns a derived CRS (`#2806 <https://github.com/OSGeo/PROJ/issues/2806>`_) + +* :cpp:func:`createOperations()`: fix missing deg<-->rad conversion when transforming with a + CRS that has a fallback-to-PROJ4-string behaviour and is a BoundCRS of a + GeographicCRS (`#2808 <https://github.com/OSGeo/PROJ/issues/2808>`_) + +* WKT2 import/export: preserve PROJ.4 CRS extension string in REMARKS[] (`#2812 <https://github.com/OSGeo/PROJ/issues/2812>`_) + +* BoundCRS: accept importing/exporting in WKT2 and PROJJSON the + scope/area/extent/id attributes (`#2815 <https://github.com/OSGeo/PROJ/issues/2815>`_) + +* :cpp:func:`ConcatenatedOperation::fixStepsDirection()`: fix bad chaining of steps when + inverse map projection is involved in non-final step (`#2819 <https://github.com/OSGeo/PROJ/issues/2819>`_) + + + +8.1.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*July 1st 2021* + +Updates +------- + ++ **Database** + + * Update to EPSG v10.027 (`#2751 <https://github.com/OSGeo/PROJ/issues/2751>`_) + + * Decrease DB size by using ``WITHOUT ROWID`` tables (`#2730 <https://github.com/OSGeo/PROJ/issues/2730>`_) (#2647) + + * Add a ``ANALYZE`` step during ``proj.db`` creation allowing for faster lookups (`#2729 <https://github.com/OSGeo/PROJ/issues/2729>`_) + + * Added a ``PROJ.VERSION`` metadata entry (`#2646 <https://github.com/OSGeo/PROJ/issues/2646>`_) + + * Added NGO48 (EPSG:4273) to ETRS89 (EPSG:4258) triangulation-based transformation (`#2554 <https://github.com/OSGeo/PROJ/issues/2554>`_) + + * Additions to the norwegian NKG2020 transformation (`#2548 <https://github.com/OSGeo/PROJ/issues/2548>`_) + + * ESRI projection database updated to version 12.8 (`#2717 <https://github.com/OSGeo/PROJ/issues/2717>`_) + ++ **API additions** + + * Added :c:func:`proj_get_geoid_models_from_database()` function that returns a list of geoid models available for a given CRS (`#2681 <https://github.com/OSGeo/PROJ/issues/2681>`_) + + * Added :c:func`proj_get_celestial_body_list_from_database()` that returns a list of celestial bodies in the PROJ database (`#2667 <https://github.com/OSGeo/PROJ/issues/2667>`_) + + * Added :c:func:`proj_get_celestial_body_name()` (`#2662 <https://github.com/OSGeo/PROJ/issues/2662>`_) + ++ **Various improvements** + + * :c:func:`proj_trans()`/:program:`cs2cs`: If two operations have the same accuracy, use the one that is contained within a larger one (`#2750 <https://github.com/OSGeo/PROJ/issues/2750>`_) + + * Share SQLite database handle among all contexts (`#2738 <https://github.com/OSGeo/PROJ/issues/2738>`_) + + * Added ``proj/internal/mutex.hpp`` as compat layer for mingw32 for std::mutex (`#2736 <https://github.com/OSGeo/PROJ/issues/2736>`_) + + * :program:`projsync`: make it filter out files not intended for the current version (`#2725 <https://github.com/OSGeo/PROJ/issues/2725>`_) + + * Improvements related to ``DerivedVerticalCRS`` using Change Unit and + Height/Depth reversal methods (`#2696 <https://github.com/OSGeo/PROJ/issues/2696>`_) + + * Update internal ``nlohmann/json`` to 3.9.1, and add a CMake option to + be able to use external ``nlohmann/json`` (`#2686 <https://github.com/OSGeo/PROJ/issues/2686>`_) + + * :cpp:func:`createFromUserInput()`: change name of CRS built from URN combined references to match the convention of EPSG projected CRS (`#2677 <https://github.com/OSGeo/PROJ/issues/2677>`_) + + * Parse compound id with two authorities, like ESRI:103668+EPSG:5703 (`#2669 <https://github.com/OSGeo/PROJ/issues/2669>`_) + + * Added :program:`projinfo` option option ``--list-crs`` (supports ``--area``) (`#2663 <https://github.com/OSGeo/PROJ/issues/2663>`_) + + * Added support for hyperbolic Cassini-Soldner (`#2637 <https://github.com/OSGeo/PROJ/issues/2637>`_) + + * Added capability to get SQL statements to add custom CRS in the database (`#2577 <https://github.com/OSGeo/PROJ/issues/2577>`_) + +Bug fixes +--------- + +* Fix 'Please include winsock2.h before windows.h' warning with msys (`#2692 <https://github.com/OSGeo/PROJ/issues/2692>`_) + +* Minor changes to address lint in ``geodesic.c`` (`#2752 <https://github.com/OSGeo/PROJ/issues/2752>`_) + +* :cpp:func:`BoundCRS::identify()`: avoid incompatible transformation for WKT1 / TOWGS84 export (`#2747 <https://github.com/OSGeo/PROJ/issues/2747>`_) + +* :c:func:`proj_create()`: do not open proj.db if string is a PROJ string, even if :c:func:`proj_context_set_autoclose_database()` has been set (`#2735 <https://github.com/OSGeo/PROJ/issues/2735>`_) + +* Fix export of transformation to PROJ string in a particular situation where CompoundCRS are involved (`#2721 <https://github.com/OSGeo/PROJ/issues/2721>`_) + + +8.0.1 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*May 5th 2021* + +Updates +------- + +* Database: update to EPSG v10.018 (`#2636 <https://github.com/OSGeo/PROJ/issues/2636>`_) + +* Add transformations for CHGeo2004, Swiss geoid model (`#2604 <https://github.com/OSGeo/PROJ/issues/2604>`_) + +* Additions to the norwegian NKG2020 transformation (`#2600 <https://github.com/OSGeo/PROJ/issues/2600>`_) + +Bug fixes +--------- + +* :c:func:`pj_vlog()`: fix buffer overflow in case of super lengthy error message (`#2693 <https://github.com/OSGeo/PROJ/issues/2693>`_) + +* Revert ":c:func:`proj_create_crs_to_crs_from_pj()`: do not use PROJ_SPATIAL_CRITERION_PARTIAL_INTERSECTION if area is specified" (`#2679 <https://github.com/OSGeo/PROJ/issues/2679>`_) + +* UTM: error out when value of ``+zone=`` is not an integer (`#2672 <https://github.com/OSGeo/PROJ/issues/2672>`_) + +* :cpp:func:`getCRSInfoList()`: make result order deterministic (by increasing auth_name, + code) (`#2661 <https://github.com/OSGeo/PROJ/issues/2661>`_) + +* :cpp:func:`createOperation()`: make sure no to discard deprecated operations if the + replacement uses an unknow grid (`#2623 <https://github.com/OSGeo/PROJ/issues/2623>`_) + +* Fix build on Solaris 11.4 (`#2621 <https://github.com/OSGeo/PROJ/issues/2621>`_) + +* Add mapping of ESRI Equal_Area projection method to EPSG (`#2612 <https://github.com/OSGeo/PROJ/issues/2612>`_) + +* Fix incorrect EPGS extent code for EPSG:7789>EPSG:4976 NKG transformation (`#2599 <https://github.com/OSGeo/PROJ/issues/2599>`_) + +* fix wrong capitalization of CHENyx06_ETRS.gsb (`#2597 <https://github.com/OSGeo/PROJ/issues/2597>`_) + +* :cpp:func:`createOperations()`: improve handling of vertical transforms when + when compound CRSs are used (`#2592 <https://github.com/OSGeo/PROJ/issues/2592>`_) + +* :cpp:func:`CRS::promoteTo3D()`: propagate the extent from the 2D CRS (`#2589 <https://github.com/OSGeo/PROJ/issues/2589>`_) + +* :cpp:func:`createFromCRSCodesWithIntermediates()`: improve performance when there is + no match (`#2583 <https://github.com/OSGeo/PROJ/issues/2583>`_) + +* Fix :c:func:`proj_clone()` to work on 'meta' coordinate operation ``PJ*`` objects that + can be returned by :c:func:`proj_create_crs_to_crs()` (`#2582 <https://github.com/OSGeo/PROJ/issues/2582>`_) + +* add ``PROJ_COMPUTE_VERSION``, ``PROJ_VERSION_NUMBER``, + ``PROJ_AT_LEAST_VERSION`` macros (`#2581 <https://github.com/OSGeo/PROJ/issues/2581>`_) + +* Make :c:func:`proj_lp_dist()` and :c:func:`proj_geod()` work on a ``PJ*`` CRS object (`#2570 <https://github.com/OSGeo/PROJ/issues/2570>`_) + +* Fix gcc 11 ``-Wnonnull`` compilation warnings (`#2559 <https://github.com/OSGeo/PROJ/issues/2559>`_) + +* Fix use of uninitialized memory in gie tests (`#2558 <https://github.com/OSGeo/PROJ/issues/2558>`_) + +* :c:func:`createOperations()`: fix incorrect height transformation between 3D promoted RGF93 and CH1903+ (`#2555 <https://github.com/OSGeo/PROJ/issues/2555>`_) + + +8.0.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*March 1st 2021* + +With the release of PROJ 8 the ``proj_api.h`` API is finally removed. See +:ref:`API_migration` for more info on how to migrate from the old to the +``proj.h`` API. + +With the removal of ``proj_api.h`` it has been possible to simplify error codes +and messages given by the software. The error codes are exposed in the API. + +Several improvements has been made to the command line utilities as well as +tweaks in the underlying API. + +Updates +------- + +* Public header file ``proj_api.h`` removed (`#837 <https://github.com/OSGeo/PROJ/issues/837>`_) + +* Improved accuracy of the Mercator projection (`#2397 <https://github.com/OSGeo/PROJ/issues/2397>`_) + +* Copyright statement wording updated (`#2417 <https://github.com/OSGeo/PROJ/issues/2417>`_) + +* Allow :program:`cct` to instantiate operations via object codes or names (`#2419 <https://github.com/OSGeo/PROJ/issues/2419>`_) + +* Allow ``@filename`` syntax in :program:`cct` (`#2420 <https://github.com/OSGeo/PROJ/issues/2420>`_) + +* Added :ref:`topocentric` (``+proj=topocentric``) (`#2444 <https://github.com/OSGeo/PROJ/issues/2444>`_) + +* Update GeographicLib to version 1.51 (`#2445 <https://github.com/OSGeo/PROJ/issues/2445>`_) + +* Added option to allow export of Geographic/Projected 3D CRS + in WKT1_GDAL (`#2450 <https://github.com/OSGeo/PROJ/issues/2450>`_) + +* Added ``--area`` and ``--bbox`` options in :program:`cs2cs` to restrict candidate + coordinate operations (`#2466 <https://github.com/OSGeo/PROJ/issues/2466>`_) + +* Added build time option to make :envvar:`PROJ_LIB` env var tested last (`#2476 <https://github.com/OSGeo/PROJ/issues/2476>`_) + +* Added ``--authority`` switch in :program:`cs2cs` to control where coordinate operations + are looked for. C API function :c:func:`proj_create_crs_to_crs_from_pj()` updated + accordingly (`#2477 <https://github.com/OSGeo/PROJ/issues/2477>`_) + +* Error codes revised and exposed in the public API (`#2487 <https://github.com/OSGeo/PROJ/issues/2487>`_) + +* Added ``--accuracy`` options to :program:`projinfo`. C API function + :c:func:`proj_create_crs_to_crs_from_pj()` updated accordingly (`#2488 <https://github.com/OSGeo/PROJ/issues/2488>`_) + +* Added :c:func:`proj_crs_is_derived()` function to C API (`#2496 <https://github.com/OSGeo/PROJ/issues/2496>`_) + +* Enabled linking against static cURL on Windows (`#2514 <https://github.com/OSGeo/PROJ/issues/2514>`_) + +* Updated ESRI CRS database to 12.7 (10.8.1/2.6) (`#2519 <https://github.com/OSGeo/PROJ/issues/2519>`_) + +* Allow a WKT BoundCRS to use a PROJ string transformation (`#2521 <https://github.com/OSGeo/PROJ/issues/2521>`_) + +* Update to EPSG v10.015 (`#2539 <https://github.com/OSGeo/PROJ/issues/2539>`_) + +* Default log level set to ``PJ_LOG_ERROR`` (`#2542 <https://github.com/OSGeo/PROJ/issues/2542>`_) + +* CMake installs a pkg-config file ``proj.pc``, where supported (`#2547 <https://github.com/OSGeo/PROJ/issues/2547>`_) + +Bug fixes +--------- + +* Do not restrict longitude to [-90;90] range in spherical transverse Mercator + forward projection (`#2471 <https://github.com/OSGeo/PROJ/issues/2471>`_) + +* :cpp:func:`createOperations()`: fix Compound to Geog3D/Projected3D CRS with non-metre ellipsoidal height (`#2500 <https://github.com/OSGeo/PROJ/issues/2500>`_) + +* Avoid error messages to be emitted log level is set to ``PJ_LOG_NONE`` (`#2527 <https://github.com/OSGeo/PROJ/issues/2527>`_) + +* Close database connection when autoclose set to True (`#2532 <https://github.com/OSGeo/PROJ/issues/2532>`_) + + +7.2.1 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*January 1st 2021* + +Updates +------- + +* Add metadata with the version number of the database layout (`#2474 <https://github.com/OSGeo/PROJ/issues/2474>`_) + +* Split ``coordinateoperation.cpp`` and ``test_operation.cpp`` in several parts (`#2484 <https://github.com/OSGeo/PROJ/issues/2484>`_) + +* Update to EPSG v10.008 (`#2490 <https://github.com/OSGeo/PROJ/issues/2490>`_) + +* Added the NKG 2008 and 2020 transformations in ``proj.db`` (`#2495 <https://github.com/OSGeo/PROJ/issues/2495>`_) + +Bug fixes +--------- + +* Set ``CURL_ENABLED`` definition on projinfo build (`#2405 <https://github.com/OSGeo/PROJ/issues/2405>`_) + +* :c:func:`createBoundCRSToWGS84IfPossible()`: make it return same result with a CRS + built from EPSG code or WKT1 (`#2412 <https://github.com/OSGeo/PROJ/issues/2412>`_) + +* WKT2 parsing: several fixes related to map projection parameter units (`#2428 <https://github.com/OSGeo/PROJ/issues/2428>`_) + +* :c:func:`createOperation()`: make it work properly when one of the CRS is a BoundCRS of + a DerivedGeographicCRS (``+proj=ob_tran +o_proj=lonlat +towgs84=....``) (`#2441 <https://github.com/OSGeo/PROJ/issues/2441>`_) + +* WKT parsing: fix ingestion of WKT with a Geocentric CRS as the base of the + projected CRS (`#2443 <https://github.com/OSGeo/PROJ/issues/2443>`_) + +* ``GeographicCRS::_isEquivalentTo(EQUIVALENT_EXCEPT_AXIS_ORDER_GEOGCRS)``: + make it work when comparing easting,northing,up and northing,easting,up (`#2446 <https://github.com/OSGeo/PROJ/issues/2446>`_) + +* :c:func:`createOperation()`: add a ballpark vertical transformation when dealing + with ``GEOIDMODEL[]`` (`#2449 <https://github.com/OSGeo/PROJ/issues/2449>`_) + +* Use same arguments to printf format string for both radians and degrees in + output by cct (`#2453 <https://github.com/OSGeo/PROJ/issues/2453>`_) + +* PRIMEM WKT handling: fixes on import for 'sexagesimal DMS' or from WKT1:GDAL/ESRI + when GEOGCS UNIT != Degree; morph to ESRI the PRIMEM name on export (`#2455 <https://github.com/OSGeo/PROJ/issues/2455>`_) + +* :c:func:`createObjectsFromName()`: in exact match, make looking for 'ETRS89 / UTM zone 32N' + return only the exact match (`#2462 <https://github.com/OSGeo/PROJ/issues/2462>`_) + +* Inverse tmerc spherical: fix wrong sign of latitude when lat_0 is used (`#2469 <https://github.com/OSGeo/PROJ/issues/2469>`_) + +* Add option to allow export of Geographic/Projected 3D CRS in WKT1_GDAL (`#2470 <https://github.com/OSGeo/PROJ/issues/2470>`_) + +* Fix building ``proj.db`` with SQLite built with ``-DSQLITE_DQS=0`` (`#2480 <https://github.com/OSGeo/PROJ/issues/2480>`_) + +* Include JSON Schema files in CMake builds (`#2485 <https://github.com/OSGeo/PROJ/issues/2485>`_) + +* :c:func:`createOperations()`: fix inconsistent chaining exception when transforming from BoundCRS of projected CRS based on NTF Paris to BoundCRS of geog CRS NTF Paris (`#2486 <https://github.com/OSGeo/PROJ/issues/2486>`_) + + +7.2.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*November 1st 2020* + +Updates +------- + ++ **Command line tools** + + * Add multi-line PROJ string export capability, and use it by default in + :program:`projinfo` (unless ``--single-line`` is specified) (`#2381 <https://github.com/OSGeo/PROJ/issues/2381>`_) + ++ **Coordinate operations** + + * :ref:`col_urban` projection, implementing a EPSG projection method + used by a number of projected CRS in Colombia (`#2395 <https://github.com/OSGeo/PROJ/issues/2395>`_) + + * :ref:`tinshift` for triangulation-based transformations (`#2344 <https://github.com/OSGeo/PROJ/issues/2344>`_) + + * Added ellipsoidal formulation of :ref:`ortho` (`#2361 <https://github.com/OSGeo/PROJ/issues/2361>`_) + + ++ **Database** + + * Update to EPSG 10.003 and make code base robust to dealing with + WKT CRS with DatumEnsemble (`#2370 <https://github.com/OSGeo/PROJ/issues/2370>`_) + + * Added Finland tinshift operations (`#2392 <https://github.com/OSGeo/PROJ/issues/2392>`_) + + * Added transformation from JGD2011 Geographic 3D to JGD2011 + height using GSIGEO2011 (`#2393 <https://github.com/OSGeo/PROJ/issues/2393>`_) + + * Improve CompoundCRS identification and name morphing in VerticalCRS + with ESRI WKT1 (`#2386 <https://github.com/OSGeo/PROJ/issues/2386>`_) + + * Added OGC:CRS27 and OGC:CRS83 CRS entries for NAD27 and NAD83 + in longitude, latitude order (`#2350 <https://github.com/OSGeo/PROJ/issues/2350>`_) + ++ **API** + + * Added temporal, engineering, and parametric datum :c:type:`PJ_TYPE` enumerations (`#2274 <https://github.com/OSGeo/PROJ/issues/2274>`_) + + * Various improvements to context handling (#2329, #2331) + + * :c:func:`proj_create_vertical_crs_ex()`: add a ``ACCURACY`` option to provide + an explicit accuracy, or derive it from the grid name if it is + known (`#2342 <https://github.com/OSGeo/PROJ/issues/2342>`_) + + * :c:func:`proj_crs_create_bound_crs_to_WGS84()`: make it work on + verticalCRS/compoundCRS such as EPSG:4326+5773 and + EPSG:4326+3855 (`#2365 <https://github.com/OSGeo/PROJ/issues/2365>`_) + + * :cpp:func:`promoteTo3D()`: add a remark with the original CRS identifier (`#2369 <https://github.com/OSGeo/PROJ/issues/2369>`_) + + * Added :c:func:`proj_context_clone` (`#2383 <https://github.com/OSGeo/PROJ/issues/2383>`_) + + +Bug fixes +--------- + +* Avoid core dumps when copying contexts in certain scenarios (`#2324 <https://github.com/OSGeo/PROJ/issues/2324>`_) + +* :c:func:`proj_trans()`: reset errno before attemptying a retry with a new + coordinate operation (`#2353 <https://github.com/OSGeo/PROJ/issues/2353>`_) + +* PROJJSON schema corrected to allow prime meridians values with + explicitly stating a unit (degrees assumed) (`#2354 <https://github.com/OSGeo/PROJ/issues/2354>`_) + +* Adjust :cpp:func:`createBoundCRSToWGS84IfPossible()` and operation filtering + (for POSGAR 2007 to WGS84 issues) (`#2357 <https://github.com/OSGeo/PROJ/issues/2357>`_) + +* :cpp:func:`createOperations()`: several fixes affecting NAD83 -> NAD83(2011) (`#2364 <https://github.com/OSGeo/PROJ/issues/2364>`_) + +* WKT2:2019 import/export: handle DATUM (at top level object) with PRIMEM + +* WKT1_ESRI: fix import and export of CompoundCRS (`#2389 <https://github.com/OSGeo/PROJ/issues/2389>`_) + + +7.1.1 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*September 1st 2020* + + +Updates +------- + +* Added various Brazilian grids to the database (`#2277 <https://github.com/OSGeo/PROJ/issues/2277>`_) + +* Added geoid file for Canary Islands to the database (`#2312 <https://github.com/OSGeo/PROJ/issues/2312>`_) + +* Updated EPSG database to version 9.8.15 (`#2310 <https://github.com/OSGeo/PROJ/issues/2310>`_) + +Bug fixes +--------- + +* WKT parser: do not raise warning when parsing a WKT2:2015 TIMECRS + whose TIMEUNIT is at the CS level, and not inside (`#2281 <https://github.com/OSGeo/PROJ/issues/2281>`_) + +* Parse '+proj=something_not_latlong +vunits=' without +geoidgrids as a + Projected3D CRS and not a compound CRS with a unknown datum (`#2289 <https://github.com/OSGeo/PROJ/issues/2289>`_) + +* C API: Avoid crashing due to missing SANITIZE_CTX() in entry points (`#2293 <https://github.com/OSGeo/PROJ/issues/2293>`_) + +* CMake build: Check "target_clones" before use (`#2297 <https://github.com/OSGeo/PROJ/issues/2297>`_) + +* PROJ string export of +proj=krovak +czech: make sure we export +czech… (`#2301 <https://github.com/OSGeo/PROJ/issues/2301>`_) + +* Helmert 2D: do not require a useless +convention= parameter (`#2305 <https://github.com/OSGeo/PROJ/issues/2305>`_) + +* Fix a few spelling errors ("vgridshit" vs. "vgridshift") (`#2307 <https://github.com/OSGeo/PROJ/issues/2307>`_) + +* Fix ability to identify EPSG:2154 as a candidate for 'RGF93_Lambert_93' (`#2316 <https://github.com/OSGeo/PROJ/issues/2316>`_) + +* WKT importer: tune for Oracle WKT and 'Lambert Conformal Conic' (`#2322 <https://github.com/OSGeo/PROJ/issues/2322>`_) + +* Revert compiler generated Fused Multiply Addition optimized routines (`#2328 <https://github.com/OSGeo/PROJ/issues/2328>`_) + + + +7.1.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*July 1st 2020* + +Updates +------- + ++ **New transformations** + + * Add a +proj=defmodel transformation for multi-component time-based deformation models (`#2206 <https://github.com/OSGeo/PROJ/pull/2206>`_): + ++ **New projections** + + * Add square conformal projections from libproject (`#2148 <https://github.com/OSGeo/PROJ/issues/2148>`_): + + - :ref:`adams_hemi` + + - :ref:`adams_ws1` + + - :ref:`adams_ws2` + + - :ref:`guyou` + + - :ref:`peirce_q` + + * Adams Square II: map ESRI WKT to PROJ string, and implement iterative + inverse method (`#2157 <https://github.com/OSGeo/PROJ/issues/2157>`_) + + * Added :ref:`igh_o` projection (`#2226 <https://github.com/OSGeo/PROJ/issues/2226>`_) + + * Add :ref:`wink2` inverse by generic inversion of forward method (`#2243 <https://github.com/OSGeo/PROJ/issues/2243>`_) + ++ **Database** + + * Update to EPSG 9.8.12, ESRI 10.8.1 and import scope and remarks for + conversion (`#2238 <https://github.com/OSGeo/PROJ/issues/2238>`_) (#2267) + + * Map the Behrmann projection to ``cae`` when converting ESRI CRSes (`#1986 <https://github.com/OSGeo/PROJ/issues/1986>`_) + + * Support conversion of Flat_Polar_Quartic projection method (`#1987 <https://github.com/OSGeo/PROJ/issues/1987>`_) + + * Register 4 new Austrian height grids (see https://github.com/OSGeo/PROJ-data/pull/13) + and handle 'Vertical Offset by Grid Interpolation (BEV AT)' method (`#1989 <https://github.com/OSGeo/PROJ/issues/1989>`_) + + * Add ESRI projection method mappings for Mercator_Variant_A, Mercator_Variant_B + and Transverse_Cylindrical_Equal_Area and various grid mappings (`#2020 <https://github.com/OSGeo/PROJ/issues/2020>`_) (#2195) + + * Map ESRI Transverse_Mercator_Complex to Transverse Mercator (`#2040 <https://github.com/OSGeo/PROJ/issues/2040>`_) + + * Register grids for New Caledonia (see https://github.com/OSGeo/PROJ-data/pull/16) (`#2051 <https://github.com/OSGeo/PROJ/issues/2051>`_) (#2239) + + * Register NZGD2000 -> ITRF96 transformation for NZGD2000 database (`#2248 <https://github.com/OSGeo/PROJ/issues/2248>`_) + + * Register geoid file for UK added + (see https://github.com/OSGeo//PROJ-data/pull/25() (`#2250 <https://github.com/OSGeo/PROJ/issues/2250>`_) + + * Register Slovakian geoid transformations with needed code changes (`#2259 <https://github.com/OSGeo/PROJ/issues/2259>`_) + + * Register Spanish SPED2ETV2 grid for ED50->ETRS89 (`#2261 <https://github.com/OSGeo/PROJ/issues/2261>`_) + ++ **API** + + * Add API function :c:func:`proj_get_units_from_database()` (`#2065 <https://github.com/OSGeo/PROJ/issues/2065>`_) + + * Add API function :c:func:`proj_get_suggested_operation()` (`#2068 <https://github.com/OSGeo/PROJ/issues/2068>`_) + + * Add API functions :c:func:`proj_degree_input()` and :c:func:`proj_degree_output()` (`#2144 <https://github.com/OSGeo/PROJ/issues/2144>`_) + + * Moved :c:func:`proj_context_get_url_endpoint()` & :c:func:`proj_context_get_user_writable_directory()` + from ``proj_experimental.h`` to ``proj.h`` (`#2162 <https://github.com/OSGeo/PROJ/issues/2162>`_) + + * :c:func:`createFromUserInput()`: allow compound CRS with the 2 parts given by names, + e.g. 'WGS 84 + EGM96 height' (`#2126 <https://github.com/OSGeo/PROJ/issues/2126>`_) + + * :c:func:`createOperations()`: when converting CompoundCRS<-->Geographic3DCrs, do not + use discard change of ellipsoidal height if a Helmert transformation is + involved (`#2227 <https://github.com/OSGeo/PROJ/issues/2227>`_) + ++ **Optimizations** + + * ``tmerc/utm``: add a +algo=auto/evenden_snyder/poder_engsager parameter (`#2030 <https://github.com/OSGeo/PROJ/issues/2030>`_) + + * Extended ``tmerc`` (Poder/Engsager): speed optimizations (`#2036 <https://github.com/OSGeo/PROJ/issues/2036>`_) + + * Approximate ``tmerc`` (Snyder): speed optimizations (`#2039 <https://github.com/OSGeo/PROJ/issues/2039>`_) + + * :c:func:`pj_phi2()`: speed-up computation (and thus inverse ellipsoidal Mercator and LCC) (`#2052 <https://github.com/OSGeo/PROJ/issues/2052>`_) + + * Inverse ``cart``: speed-up computation by 33% (`#2145 <https://github.com/OSGeo/PROJ/issues/2145>`_) + + * Extended ``tmerc``: speed-up forward path by ~5% (`#2147 <https://github.com/OSGeo/PROJ/issues/2147>`_) + ++ **Various** + + * Follow PDAL's CMake RPATH strategy (`#2009 <https://github.com/OSGeo/PROJ/issues/2009>`_) + + * WKT import/export: add support for WKT1_ESRI VERTCS syntax (`#2024 <https://github.com/OSGeo/PROJ/issues/2024>`_) + + * :program:`projinfo`: add a ``--hide-ballpark`` option (`#2127 <https://github.com/OSGeo/PROJ/issues/2127>`_) + + * :program:`gie`: implement a strict mode with ``<gie-strict> </gie-strict>`` (`#2168 <https://github.com/OSGeo/PROJ/issues/2168>`_) + + * Allow importing WKT1 COMPD_CS with a VERT_DATUM[Ellipsoid,2002] (`#2229 <https://github.com/OSGeo/PROJ/issues/2229>`_) + + * Add runtime checking that sqlite3 is >= 3.11 (`#2235 <https://github.com/OSGeo/PROJ/issues/2235>`_) + + +Bug fixes +--------- + +* :cpp:func:`createOperations()`: do not remove ballpark transformation if there are only grid + based operations, even if they cover the whole area of use (`#2155 <https://github.com/OSGeo/PROJ/issues/2155>`_) + +* :cpp:func:`createFromProjString()`: handle default parameters of '+krovak +type=crs', and + handle ``+czech`` correctly (`#2200 <https://github.com/OSGeo/PROJ/issues/2200>`_) + +* :cpp:func:`ProjectedCRS::identify()`: fix identification of EPSG:3059 (`#2215 <https://github.com/OSGeo/PROJ/issues/2215>`_) + +* Database: add a 'WGS84' alias for the EPSG:4326 CRS (`#2218 <https://github.com/OSGeo/PROJ/issues/2218>`_) + +* Fixes related to CompoundCRS and BoundCRS (`#2222 <https://github.com/OSGeo/PROJ/issues/2222>`_) + +* Avoid 2 warnings about missing database indices (`#2223 <https://github.com/OSGeo/PROJ/issues/2223>`_) + +* Make ``projinfo --3d --boundcrs-to-wgs84`` work better (`#2224 <https://github.com/OSGeo/PROJ/issues/2224>`_) + +* Many fixes regarding BoundCRS, CompoundCRS, Geographic3D CRS with + non-metre units (`#2234 <https://github.com/OSGeo/PROJ/issues/2234>`_) + +* Fix identification of (one of the) ESRI WKT formulations of EPSG:3035 (`#2240 <https://github.com/OSGeo/PROJ/issues/2240>`_) + +* Avoid using deprecated and removed Windows API function with Mingw32 (`#2246 <https://github.com/OSGeo/PROJ/issues/2246>`_) + +* :cpp:func:`normalizeForVisualization()`: make it switch axis for EPSG:5482 + (RSRGD2000 / RSPS2000) (`#2256 <https://github.com/OSGeo/PROJ/issues/2256>`_) + +* Fix access violation in :c:func:`proj_context_get_database_metadata()` (`#2260 <https://github.com/OSGeo/PROJ/issues/2260>`_) + + +7.0.1 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*May 1st 2020* + +Updates +------- + +* Database: update to EPSG v9.8.9 (`#2141 <https://github.com/OSGeo/PROJ/issues/2141>`_) + +Bug fixes +--------- + +* Make tests independent of proj-datumgrid (`#1995 <https://github.com/OSGeo/PROJ/issues/1995>`_) + +* Add missing projection property tables (`#1996 <https://github.com/OSGeo/PROJ/issues/1996>`_) + +* Avoid crash when running against SQLite3 binary built with + ``-DSQLITE_OMIT_AUTOINIT`` (`#1999 <https://github.com/OSGeo/PROJ/issues/1999>`_) + +* :c:func:`createOperations`: fix wrong pipeline generation with CRS that has ``+nadgrids=`` + and ``+pm=`` (`#2002 <https://github.com/OSGeo/PROJ/issues/2002>`_) + +* Fix bad copy&replace pattern on HEALPix and rHEALPix projection names (`#2007 <https://github.com/OSGeo/PROJ/issues/2007>`_) + +* :c:func:`createUnitOfMeasure`: use full double resolution for the conversion + factor (`#2014 <https://github.com/OSGeo/PROJ/issues/2014>`_) + +* Update README with info on PROJ-data (`#2015 <https://github.com/OSGeo/PROJ/issues/2015>`_) + +* ``utm/ups``: make sure to set errno to ``PJD_ERR_ELLIPSOID_USE_REQUIRED`` if + ``+es==0`` (`#2045 <https://github.com/OSGeo/PROJ/issues/2045>`_) + +* ``data/Makefile.am``: remove bashism (`#2048 <https://github.com/OSGeo/PROJ/issues/2048>`_) + +* :cpp:func:`ProjectedCRS::identify`: tune it to better work with ESRI WKT + representation of EPSG:2193 (`#2059 <https://github.com/OSGeo/PROJ/issues/2059>`_) + +* Fix build with gcc 4.8.5 (`#2066 <https://github.com/OSGeo/PROJ/issues/2066>`_) + +* Autotools/pkg-conf: Define datarootdir (`#2069 <https://github.com/OSGeo/PROJ/issues/2069>`_) + +* :program:`cs2cs`: don't require ``+to`` for '{source_crs} {target_crs} filename...' + syntax (`#2081 <https://github.com/OSGeo/PROJ/issues/2081>`_) + +* CMake: fix bug with ``find_package(PROJ)`` with macOS (`#2082 <https://github.com/OSGeo/PROJ/issues/2082>`_) + +* ESRI WKT import / identification: special case for + NAD_1983_HARN_StatePlane_Colorado_North_FIPS_0501 with Foot_US unit (`#2088 <https://github.com/OSGeo/PROJ/issues/2088>`_) + +* ESRI WKT import / identification: special case for + NAD_1983_HARN_StatePlane_Colorado_North_FIPS_0501 with Foot_US unit (`#2089 <https://github.com/OSGeo/PROJ/issues/2089>`_) + +* EngineeringCRS: when exporting to WKT1_GDAL, output unit and axis (`#2092 <https://github.com/OSGeo/PROJ/issues/2092>`_) + +* Use jtsk03-jtsk horizontal grid from CDN (`#2098 <https://github.com/OSGeo/PROJ/issues/2098>`_) + +* CMake: prefer to use use PROJ_SOURCE_DIR and PROJ_BINARY_DIR (`#2100 <https://github.com/OSGeo/PROJ/issues/2100>`_) + +* Fix wrong grids file name in esri.sql (`#2104 <https://github.com/OSGeo/PROJ/issues/2104>`_) + +* Fix identification of projected CRS whose name is close but not strictly + equal to a ESRI alias (`#2106 <https://github.com/OSGeo/PROJ/issues/2106>`_) + +* Fix working of Helmert transform between the horizontal part of + 2 compoundCRS (`#2111 <https://github.com/OSGeo/PROJ/issues/2111>`_) + +* Database: fix registration of custom entries of grid_transformation_custom.sql + for geoid grids (`#2114 <https://github.com/OSGeo/PROJ/issues/2114>`_) + +* ESRI_WKT ingestion: make sure to identify to non-deprecated EPSG entry when + possible (`#2119 <https://github.com/OSGeo/PROJ/issues/2119>`_) + +* Make sure that importing a Projected 3D CRS from WKT:2019 keeps the base + geographic CRS as 3D (`#2125 <https://github.com/OSGeo/PROJ/issues/2125>`_) + +* :c:func:`createOperations`: improve results of compoundCRS to compoundCRS case (`#2131 <https://github.com/OSGeo/PROJ/issues/2131>`_) + +* hgridshift/vgridshift: defer grid opening when grid has already + been opened (`#2132 <https://github.com/OSGeo/PROJ/issues/2132>`_) + +* Resolve a few shadowed declaration warnings (`#2142 <https://github.com/OSGeo/PROJ/issues/2142>`_) + +* ProjectedCRS identification: deal with switched 1st/2nd std parallels for + LCC_2SP(`#2153 <https://github.com/OSGeo/PROJ/issues/2153>`_) + +* Fix Robinson inverse projection (`#2154 <https://github.com/OSGeo/PROJ/issues/2154>`_) + +* :c:func:`createOperations()`: do not remove ballpark transformation if there are only + grid based operations, even if they cover the whole area of use (`#2156 <https://github.com/OSGeo/PROJ/issues/2156>`_) + +* :c:func:`createFromCoordinateReferenceSystemCodes`: 'optimization' to avoid using + C++ exceptions (`#2161 <https://github.com/OSGeo/PROJ/issues/2161>`_) + +* Ingestion of WKT1_GDAL: correctly map 'Cylindrical_Equal_Area' (`#2167 <https://github.com/OSGeo/PROJ/issues/2167>`_) + +* Add limited support for non-conformant WKT1 LAS COMPD_CS[] (`#2172 <https://github.com/OSGeo/PROJ/issues/2172>`_) + +* PROJ4 string import: take into correctly non-metre unit when the string + looks like the one for WGS 84 / Pseudo Mercator (`#2177 <https://github.com/OSGeo/PROJ/issues/2177>`_) + +* ``io.hpp``: avoid dependency to ``proj_json_streaming_writer.hpp`` (`#2184 <https://github.com/OSGeo/PROJ/issues/2184>`_) + +* Fix support of WKT1_GDAL with netCDF rotated pole formulation (`#2186 <https://github.com/OSGeo/PROJ/issues/2186>`_) + + + +6.3.2 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*May 1st 2020* + + +Bug fixes +--------- + +* :c:func:`validateParameters`: fix false-positive warning on + Equidistant Cylindrical (`#1947 <https://github.com/OSGeo/PROJ/issues/1947>`_) + +* :c:func:`proj_create_crs_to_cr`: avoid potential reprojection failures when + reprojecting area of use to source and target CRS (`#1993 <https://github.com/OSGeo/PROJ/issues/1993>`_) + +* :c:func:`createOperations`: fix wrong pipeline generation with CRS that has ``+nadgrids=`` + and ``+pm=`` (`#2003 <https://github.com/OSGeo/PROJ/issues/2003>`_) + +* Fix bad copy&replace pattern on HEALPix and rHEALPix projection names (`#2006 <https://github.com/OSGeo/PROJ/issues/2006>`_) + +* :c:func:`createUnitOfMeasure`: use full double resolution for the conversion + factor (`#2013 <https://github.com/OSGeo/PROJ/issues/2013>`_) + +* ``data/Makefile.am``: remove bashism (`#2047 <https://github.com/OSGeo/PROJ/issues/2047>`_) + +* :cpp:func:``ProjectedCRS::identify``: tune it to better work with ESRI WKT representation + of EPSG:2193 (`#2058 <https://github.com/OSGeo/PROJ/issues/2058>`_) + +* EngineeringCRS: when exporting to WKT1_GDAL, output unit and axis (`#2091 <https://github.com/OSGeo/PROJ/issues/2091>`_) + +* Add missing entries in grid_alternatives for Portugal grids coming from + ESRI entries (`#2103 <https://github.com/OSGeo/PROJ/issues/2103>`_) + +* Fix working of Helmert transform between the horizontal part of 2 + compoundCRS (`#2110 <https://github.com/OSGeo/PROJ/issues/2110>`_) + +* ESRI_WKT ingestion: make sure to identify to non-deprecated EPSG entry when + possible (`#2118 <https://github.com/OSGeo/PROJ/issues/2118>`_) + +* Make sure that importing a Projected 3D CRS from WKT:2019 keeps the base + geographic CRS as 3D (`#2124 <https://github.com/OSGeo/PROJ/issues/2124>`_) + +* :c:func:`createOperations`: improve results of compoundCRS to compoundCRS case (`#2130 <https://github.com/OSGeo/PROJ/issues/2130>`_) + +* PROJ4 string import: take into correctly non-metre unit when the string looks + like the one for WGS 84 / Pseudo Mercator (`#2178 <https://github.com/OSGeo/PROJ/issues/2178>`_) + +* Fix support of WKT1_GDAL with netCDF rotated pole formulation (`#2187 <https://github.com/OSGeo/PROJ/issues/2187>`_) + +* ``io.hpp``: avoid dependency to ``proj_json_streaming_writer.hpp`` (`#2188 <https://github.com/OSGeo/PROJ/issues/2188>`_) + + +7.0.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*March 1st 2020* + +The major feature in PROJ 7 is significantly improved handling of gridded +models. This was implemented in :ref:`RFC4`. +The main features of the RFC4 work is that PROJ now implements a new grid format, +Geodetic TIFF grids, for exchanging gridded transformation models. In addition +to the new grid format, PROJ can now also access grids online using a data +store in the cloud. + +The grids that was previously available via the proj-datumgrid packages are now +available in two places: + + 1. As a single combined data archive including all available resource files + 2. From the cloud via https://cdn.proj.org + +In Addition, provided with PROJ is a utility called :program:`projsync` that can be used +download grids from the data store in the cloud. + +The use of the new grid format and the data from the cloud requires that +PROJ is build against ``libtiff`` and ``libcurl``. Both are optional dependencies +to PROJ but it is highly encouraged that the software is build against both. + + +.. warning:: + + PROJ 7 will be last major release version that includes the ``proj_api.h`` + header. The functionality in ``proj_api.h`` is deprecated and only supported in + maintenance mode. It is inferior to the functionality provided by functions + in the ``proj.h`` header and all projects still relying on ``proj_api.h`` are encouraged + to migrate to the new API in ``proj.h``. See :ref:`API_migration`. + for more info on how to migrate from the old to the new API. + + +Updates +------- + +* Added new file access API to ``proj.h`` (`#866 <https://github.com/OSGeo/PROJ/issues/866>`_) + +* Updated the name of the most recent version of the WKT2 standard from + WKT2_2018 to WKT2_2019 to reflect the proper name of the standard (`#1585 <https://github.com/OSGeo/PROJ/issues/1585>`_) + +* Improvements in transformations from/to WGS 84 (Gxxxx) realizations and + vertical <--> geog transormations (`#1608 <https://github.com/OSGeo/PROJ/issues/1608>`_) + +* Update to version 1.50 of the geodesic library (`#1629 <https://github.com/OSGeo/PROJ/issues/1629>`_) + +* Promote :c:func:`proj_assign_context` to ``proj.h`` from ``proj_experimental.h`` (`#1630 <https://github.com/OSGeo/PROJ/issues/1630>`_) + +* Add rotation support to the HEALPix projection (`#1638 <https://github.com/OSGeo/PROJ/issues/1638>`_) + +* Add C function :c:func:`proj_crs_create_bound_vertical_crs` (`#1689 <https://github.com/OSGeo/PROJ/issues/1689>`_) + +* Use Win32 Unicode APIs and expect all strings to be UTF-8 (`#1765 <https://github.com/OSGeo/PROJ/issues/1765>`_) + +* Improved name aliases lookup (`#1827 <https://github.com/OSGeo/PROJ/issues/1827>`_) + +* CMake: Employ better use of CTest with the ``BUILD_TESTING`` option (`#1870 <https://github.com/OSGeo/PROJ/issues/1870>`_) + +* Grid correction: fix handling grids spanning antimeridian (`#1882 <https://github.com/OSGeo/PROJ/issues/1882>`_) + +* Remove legacy CMake target name ``proj`` (`#1883 <https://github.com/OSGeo/PROJ/issues/1883>`_) + +* :program:`projinfo` add ``--searchpaths`` switch (`#1892 <https://github.com/OSGeo/PROJ/issues/1892>`_) + +* Add :ref:`+proj=set operation<set>` to set component(s) of a coordinate to a fixed + value (`#1896 <https://github.com/OSGeo/PROJ/issues/1896>`_) + +* Add EPSG records for 'Geocentric translation by Grid Interpolation (IGN)' + (``gr3df97a.txt``) and map them to new :ref:`+proj=xyzgridshift<xyzgridshift>` (`#1897 <https://github.com/OSGeo/PROJ/issues/1897>`_) + +* Remove ``null`` grid file as it is now a special hardcoded case in grid + code (`#1898 <https://github.com/OSGeo/PROJ/issues/1898>`_) + +* Add :program:`projsync` utility (`#1903 <https://github.com/OSGeo/PROJ/issues/1903>`_) + +* Make ``PROJ`` the CMake project name (`#1910 <https://github.com/OSGeo/PROJ/issues/1910>`_) + +* Use relative directory to locate PROJ resource files (`#1921 <https://github.com/OSGeo/PROJ/issues/1921>`_) + + +Bug fixes +--------- + +* Horizontal grid shift: fix failures on points slightly outside a + subgrid (`#209 <https://github.com/OSGeo/PROJ/issues/209>`_) + +* Fix ASAN issue with SQLite3VFS class (`#1902 <https://github.com/OSGeo/PROJ/issues/1902>`_) + +* tests: force use of bash for ``proj_add_test_script_sh`` (`#1905 <https://github.com/OSGeo/PROJ/issues/1905>`_) + + +Breaking changes +---------------- + +* Reject NTV2 files where ``GS_TYPE != SECONDS`` (`#1294 <https://github.com/OSGeo/PROJ/issues/1294>`_) + +* On Windows the name of the library is now fixed to ``proj.lib`` instead + of encoding the version number in the library name (`#1581 <https://github.com/OSGeo/PROJ/issues/1581>`_) + +* Require C99 compiler (`#1624 <https://github.com/OSGeo/PROJ/issues/1624>`_) + +* Remove deprecated JNI bindings (`#1825 <https://github.com/OSGeo/PROJ/issues/1825>`_) + +* Remove -ld option from :program:`proj` and :program:`cs2cs` (`#1844 <https://github.com/OSGeo/PROJ/issues/1844>`_) + +* Increase CMake minimum version from 3.5 to 3.9 (`#1907 <https://github.com/OSGeo/PROJ/issues/1907>`_) + + + + + +6.3.1 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*February 11th 2020* + +Updates +------- + +* Update the EPSG database to version 9.8.6 + +* Database: add mapping for gg10_smv2.mnt and gg10_sbv2.mnt French grids + +* Database: add mapping for TOR27CSv1.GSB + +Bug fixes +--------- + +* Fix wrong use of derivingConversionRef() that caused issues with use of + +init=epsg:XXXX by GDAL (affecting R spatial libraries) or in MapServer + +* fix exporting CoordinateSystem to PROJ JSON with ID + +* projinfo: use No. abbreviation instead of UTF-8 character + (`#1828 <https://github.com/OSGeo/PROJ/issues/1828>`_) + +* CompoundCRS::identify(): avoid exception when horiz/vertical part is a + BoundCRS + +* createOperations(): fix dealing with projected 3D CRS whose Z units != metre + +* WKT1_GDAL export: limit datum name massaging to names matching EPSG + (`#1835 <https://github.com/OSGeo/PROJ/issues/1835>`_) + +* unitconvert with mjd time format: avoid potential integer overflow + (ossfuzz 20072) + +* ProjectedCRS::identify(): fix wrong identification of some ESRI WKT linked + to units + +* Database: add a geoid_like value for proj_method column of grid_alternatives, + fix related entries and simplify/robustify logic to deal with EPSG + 'Geographic3D to GravityRelatedHeight' methods + +* Fix ingestion of +proj=cea with +k_0 (`#1881 <https://github.com/OSGeo/PROJ/issues/1881>`_) + +* Fix performance issue, affecting PROJ.4 string generation of EPSG:7842 + (`#1913 <https://github.com/OSGeo/PROJ/issues/1913>`_) + +* Fix identification of ESRI-style datum names starting with D\_ but without + alias (`#1911 <https://github.com/OSGeo/PROJ/issues/1911>`_) + +* cart: Avoid discontinuity at poles in the inverse case + (`#1906 <https://github.com/OSGeo/PROJ/issues/1906>`_) + +* Various updates to make regression test suite pass with gcc on i386 + (`#1906 <https://github.com/OSGeo/PROJ/issues/1906>`_) + + +6.3.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*January 1st 2020* + +Updates +------- + +* Database: tune accuracy of Canadian NTv1 file w.r.t NTv2 (`#1812 <https://github.com/OSGeo/PROJ/issues/1812>`_) + +* Modify verbosity level of some debug/trace messages (`#1811 <https://github.com/OSGeo/PROJ/issues/1811>`_) + +* :program:`projinfo`: no longer call createBoundCRSToWGS84IfPossible() for WKT1:GDAL + (`#1810 <https://github.com/OSGeo/PROJ/issues/1810>`_) + +* :c:func:`proj_trans`: add retry logic to select other transformation if the best one + fails. (`#1809 <https://github.com/OSGeo/PROJ/issues/1809>`_) + +* `BoundCRS::identify()`: improvements to discard CRS that aren't relevant + (`#1802 <https://github.com/OSGeo/PROJ/issues/1802>`_) + +* Database: update to IGNF v3.1.0 (`#1785 <https://github.com/OSGeo/PROJ/issues/1785>`_) + +* Build: Only export symbols if building DLL (`#1773 <https://github.com/OSGeo/PROJ/issues/1773>`_) + +* Database: update ESRI entries with ArcGIS Desktop version 10.8.0 database + (`#1762 <https://github.com/OSGeo/PROJ/issues/1762>`_) + +* :c:func:`createOperations()`: chain operations whose middle CRSs are not identical but + have the same datum (`#1734 <https://github.com/OSGeo/PROJ/issues/1734>`_) + +* import/export PROJJSON: support a interpolation_crs key to geoid_model + (`#1732 <https://github.com/OSGeo/PROJ/issues/1732>`_) + +* Database: update to EPSG v9.8.4 (`#1725 <https://github.com/OSGeo/PROJ/issues/1725>`_) + +* Build: require SQLite 3.11 (`#1721 <https://github.com/OSGeo/PROJ/issues/1721>`_) + +* Add support for GEOIDMODEL (`#1710 <https://github.com/OSGeo/PROJ/issues/1710>`_) + +* Better filtering based on extent and performance improvements (`#1709 <https://github.com/OSGeo/PROJ/issues/1709>`_) + +Bug fixes +--------- + +* Horizontal grid shift: fix issue on iterative inverse computation when + switching between (sub)grids (`#1797 <https://github.com/OSGeo/PROJ/issues/1797>`_) + +* :c:func:`createOperations()`: make filtering out of 'uninteresting' operations less + aggressive (`#1788 <https://github.com/OSGeo/PROJ/issues/1788>`_) + +* Make EPSG:102100 resolve to ESRI:102100 (`#1786 <https://github.com/OSGeo/PROJ/issues/1786>`_) + +* ``ob_tran``: restore traditional handling of ``+to_meter`` with :c:func:`pj_transform()` and + :program:`proj` utility (`#1783 <https://github.com/OSGeo/PROJ/issues/1783>`_) + +* CRS identification: use case insensitive comparison for authority name + (`#1780 <https://github.com/OSGeo/PROJ/issues/1780>`_) + +* :c:func:`normalizeForVisualization()` and other methods applying on a ProjectedCRS: do + not mess the derivingConversion object of the original object (`#1746 <https://github.com/OSGeo/PROJ/issues/1746>`_) + +* :c:func:`createOperations()`: fix transformation computation from/to a CRS with + ``+geoidgrids`` and ``+vunits`` != m (`#1731 <https://github.com/OSGeo/PROJ/issues/1731>`_) + +* Fix :c:func:`proj_assign_context()`/:c:func:`pj_set_ctx()` with pipelines and alternative coord + operations (`#1726 <https://github.com/OSGeo/PROJ/issues/1726>`_) + +* Database: add an auxiliary concatenated_operation_step table to allow + arbitrary number of steps (`#1696 <https://github.com/OSGeo/PROJ/issues/1696>`_) + +* Fix errors running gie-based tests in Debug mode on Window (`#1688 <https://github.com/OSGeo/PROJ/issues/1688>`_) + +6.2.1 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*November 1st 2019* + +Updates +------- + +* Update the EPSG database to version 9.8.2 + +Bug fixes +---------- + +* Fixed erroneous spelling of "Potsdam" (`#1573 <https://github.com/OSGeo/PROJ/issues/1573>`_) + +* Calculate y-coordinate correctly in :ref:`bertin1953` in all cases (`#1579 <https://github.com/OSGeo/PROJ/issues/1579>`_) + +* :c:func:`proj_create_crs_to_crs_from_pj()`: make the PJ* arguments const PJ* (`#1583 <https://github.com/OSGeo/PROJ/issues/1583>`_) + +* `PROJStringParser::createFromPROJString()`: avoid potential infinite + recursion (`#1574 <https://github.com/OSGeo/PROJ/issues/1574>`_) + +* Avoid core dump when setting ``ctx==NULL`` in functions + :c:func:`proj_coordoperation_is_instantiable` and + :c:func:`proj_coordoperation_has_ballpark_transformation` (`#1590 <https://github.com/OSGeo/PROJ/issues/1590>`_) + +* :c:func:`createOperations()`: fix conversion from/to PROJ.4 CRS strings with + non-ISO-kosher options and ``+towgs84``/``+nadgrids`` (`#1602 <https://github.com/OSGeo/PROJ/issues/1602>`_) + +* :c:func:`proj_trans_generic()`: properly set coordinate time to ``HUGE_VAL`` + when no value is passed to the function (`#1604 <https://github.com/OSGeo/PROJ/issues/1604>`_) + +* Fix support for ``+proj=ob_tran +o_proj=lonlat/latlong/latlon`` instead of only + only allowing ``+o_proj=longlat`` (`#1601 <https://github.com/OSGeo/PROJ/issues/1601>`_) + +* Improve backwards compatibility of vertical transforms (`#1613 <https://github.com/OSGeo/PROJ/issues/1613>`_) + +* Improve emulation of deprecated ``+init`` style initialization (`#1614 <https://github.com/OSGeo/PROJ/issues/1614>`_) + +* :program:`cs2cs`: autopromote CRS to 3D when there's a mix of 2D and 3D (`#1563 <https://github.com/OSGeo/PROJ/issues/1563>`_) + +* Avoid divisions by zero in odd situations (`#1620 <https://github.com/OSGeo/PROJ/issues/1620>`_) + +* Avoid compile error on Solaris (`#1639 <https://github.com/OSGeo/PROJ/issues/1639>`_) + +* :c:func:`proj_create_crs_to_crs()`: fix when there are only transformations with + ballpark steps (`#1643 <https://github.com/OSGeo/PROJ/issues/1643>`_) + +* PROJ string CRS ingester: recognize more unit-less parameters, and general + handling of ``+key=string_value`` parameters (`#1645 <https://github.com/OSGeo/PROJ/issues/1645>`_) + +* Only call pkg-config in configure when necessary (`#1652 <https://github.com/OSGeo/PROJ/issues/1652>`_) + +* :ref:`aeqd`: for spherical forward path, go to higher precision ellipsoidal + case when the point coordinates are super close to the origin (`#1654 <https://github.com/OSGeo/PROJ/issues/1654>`_) + +* :c:func:`proj_create_crs_to_crs()`: remove elimination of Ballpark operations + that caused transformation failures in some cases (`#1665 <https://github.com/OSGeo/PROJ/issues/1665>`_) + +* :c:func:`createOperations()`: allow transforming from a compoundCRS of a bound + verticalCRS to a 2D CRS (`#1667 <https://github.com/OSGeo/PROJ/issues/1667>`_) + +* Avoid segfaults in case of out-of-memory situations (`#1679 <https://github.com/OSGeo/PROJ/issues/1679>`_) + +* :c:func:`createOperations()`: fix double vertical unit conversion from CompoundCRS + to other CRS when the horizontal part of the projected CRS uses non-metre + unit (#1683)(`#1683 <https://github.com/OSGeo/PROJ/issues/1683>`_) + +* :c:func:`importFromWkt()`: fix axis orientation for non-standard ESRI WKT (`#1690 <https://github.com/OSGeo/PROJ/issues/1690>`_) + + + +6.2.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*September 1st 2019* + +Updates +------- + + * Introduced :ref:`PROJJSON`, a JSON encoding of WKT2 (`#1547 <https://github.com/OSGeo/PROJ/issues/1547>`_) + * Support CRS instantiation of OGC URN's (`#1505 <https://github.com/OSGeo/PROJ/issues/1505>`_) + + * Expose scope and remarks of database objects (`#1537 <https://github.com/OSGeo/PROJ/issues/1537>`_) + + * EPSG Database updated to version 9.7.0 (`#1558 <https://github.com/OSGeo/PROJ/issues/1558>`_) + + * Added C API function proj_grid_get_info_from_database() (`#1494 <https://github.com/OSGeo/PROJ/issues/1494>`_) + + * Added C API function + proj_operation_factory_context_set_discard_superseded() (`#1534 <https://github.com/OSGeo/PROJ/issues/1534>`_) + + * Added C API function proj_context_set_autoclose_database() (`#1566 <https://github.com/OSGeo/PROJ/issues/1566>`_) + + * Added C API function proj_create_crs_to_crs_from_pj() (`#1567 <https://github.com/OSGeo/PROJ/issues/1567>`_) + + * Added C API function proj_cleanup() (`#1569 <https://github.com/OSGeo/PROJ/issues/1569>`_) + + + +Bug Fixes +--------- + + * Fixed build failure on Solaris systems (`#1554 <https://github.com/OSGeo/PROJ/issues/1554>`_) + + +6.1.1 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*July 1st 2019* + +Updates +------- + +* Update EPSG registry to version 9.6.3 (`#1485 <https://github.com/OSGeo/PROJ/issues/1485>`_) + +Bug Fixes +--------- + +* Take the passed authority into account when identifying + objects (`#1466 <https://github.com/OSGeo/PROJ/issues/1466>`_) + +* Avoid exception when transforming from NAD83 to projected + CRS using NAD83(2011) (`#1477 <https://github.com/OSGeo/PROJ/issues/1477>`_) + +* Avoid off-by-one reading of name argument if name of resource + file has length 1 (`#11489 <https://github.com/OSGeo/PROJ/issues/1489>`_) + +* Do not include :envvar:`PROJ_LIB` in ``proj_info().searchpath`` when context + search path is set (`#1498 <https://github.com/OSGeo/PROJ/issues/1498>`_) + +* Use correct delimiter for the current platform when parsing + PROJ_LIB (`#1497 <https://github.com/OSGeo/PROJ/issues/1497>`_) + +* Do not confuse 'ID74' CRS with WKT2 ID[] node (`#1506 <https://github.com/OSGeo/PROJ/issues/1506>`_) + +* WKT1 importer: do case insensitive comparison for axis + direction (`#1509 <https://github.com/OSGeo/PROJ/issues/1509>`_) + +* Avoid compile errors on GCC 4.9.3 (`#1512 <https://github.com/OSGeo/PROJ/issues/1512>`_) + +* Make sure that pipelines including ``+proj=ob_tran`` can be + created (`#1526 <https://github.com/OSGeo/PROJ/issues/1526>`_) + + +6.1.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*May 15th 2019* + +Updates +------- + +* Include custom ellipsoid definitions from QGIS (`#1137 <https://github.com/OSGeo/proj.4/issues/1337>`_) + +* Add ``-k ellipsoid`` option to projinfo (`#1338 <https://github.com/OSGeo/proj.4/issues/1338>`_) + +* Make cs2cs support 4D coordinates (`#1355 <https://github.com/OSGeo/proj.4/issues/1355>`_) + +* WKT2 parser: update to OGC 18-010r6 (`#1360 <https://github.com/OSGeo/proj.4/issues/1360>`_ `#1366 <https://github.com/OSGeo/proj.4/issues/1366>`_)) + +* Update internal version of googletest to v1.8.1 (`#1361 <https://github.com/OSGeo/proj.4/issues/1361>`_) + +* Database update: EPSG v9.6.2 (`#1462 <https://github.com/OSGeo/proj.4/issues/1462>`_), IGNF v3.0.3, ESRI 10.7.0 + and add operation_version column (`#1368 <https://github.com/OSGeo/proj.4/issues/1368>`_) + +* Add :c:func:`proj_normalize_for_visualization` that attempts to apply axis + ordering as used by most GIS applications and PROJ <6 (`#1387 <https://github.com/OSGeo/proj.4/issues/1387>`_) + +* Added noop operation (`#1391 <https://github.com/OSGeo/proj.4/issues/1391>`_) + +* Paths set by user take priority over :envvar:`PROJ_LIB` for search paths (`#1398 <https://github.com/OSGeo/proj.4/issues/1398>`_) + +* Reduced database size (`#1438 <https://github.com/OSGeo/proj.4/issues/1438>`_) + +* add support for compoundCRS and concatenatedOperation named from + their components (`#1441 <https://github.com/OSGeo/proj.4/issues/1441>`_) + +Bug fixes +--------- + +* Have :program:`gie` return non-zero code when file can't be opened (`#1312 <https://github.com/OSGeo/proj.4/issues/1312>`_) + +* CMake cross-compilation fix (`#1316 <https://github.com/OSGeo/proj.4/issues/1316>`_) + +* Use 1st eccentricity instead of 2nd eccentricity in Molodensky (`#1324 <https://github.com/OSGeo/proj.4/issues/1324>`_) + +* Make sure to include grids when doing Geocentric to CompoundCRS with + nadgrids+geoidgrids transformations (`#1326 <https://github.com/OSGeo/proj.4/issues/1326>`_) + +* Handle coordinates outside of bbox better (`#1333 <https://github.com/OSGeo/proj.4/issues/1333>`_) + +* Enable system error messages in command line automatically in builds (`#1336 <https://github.com/OSGeo/proj.4/issues/1336>`_) + +* Make sure to install projinfo man page with CMake (`#1347 <https://github.com/OSGeo/proj.4/issues/1347>`_) + +* Add data dir to pkg-config file proj.pc (`#1348 <https://github.com/OSGeo/proj.4/issues/1348>`_) + +* Fix GCC 9 warning about useless ``std::move()`` (`#1352 <https://github.com/OSGeo/proj.4/issues/1352>`_) + +* Grid related fixes (`#1369 <https://github.com/OSGeo/proj.4/issues/1369>`_) + +* Make sure that ISO19111 C++ code sets pj_errno on errors (`#1405 <https://github.com/OSGeo/proj.4/issues/1405>`_) + +* vgridshift: handle longitude wrap-around for grids with 360deg + longitude extent (`#1429 <https://github.com/OSGeo/proj.4/issues/1429>`_) + +* :program:`proj`/:program:`cs2cs`: validate value of ``-f`` parameter to avoid potential crashes (`#1434 <https://github.com/OSGeo/proj.4/issues/1434>`_) + +* Many division by zero and similar bug fixes found by OSS Fuzz. + + +6.0.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*March 1st 2019* + + +PROJ 6 has undergone extensive changes to increase its functional scope from a +cartographic projection engine with so-called "early-binding" geodetic datum +transformation capabilities to a more complete library supporting coordinate +transformations and coordinate reference systems. + +As a foundation for other enhancements, PROJ now includes a C++ implementation +of the modelisation propopsed by the ISO-19111:2019 standard / OGC Abstract +Specification Topic 2: "Referencing By Coordinates", for geodetic reference +frames (datums), coordinate reference systems and coordinate operations. +Construction and query of those geodetic objects is available through a new C++ +API, and also accessible for the most part from bindings in the C API. + +Those geodetic objects can be imported and exported from and into the OGC +Well-Known Text format (WKT) in its different variants: ESRI WKT, GDAL WKT 1, +WKT2:2015 (ISO 19162:2015) and WKT2:2018 (ISO 19162:2018). Import and export of +CRS objects from and into PROJ strings is also supported. This functionality +was previously available in the GDAL software library (except WKT2 support +which is a new feature), and is now an integral part of PROJ. + +A unified database of geodetic objects, coordinate reference systems and their +metadata, and coordinate operations between those CRS is now available in a +SQLite3 database file, proj.db. This includes definitions imported from the +IOGP EPSG dataset (v9.6.0 release), the IGNF (French national mapping agency) +geodetic registry and the ESRI projection engine database. PROJ is now the +reference software in the "OSGeo C stack" for this CRS and coordinate operation +database, whereas previously this functionality was spread over PROJ, GDAL and +libgeotiff, and used CSV or other adhoc text-based formats. + +Late-binding coordinate operation capabilities, that takes metadata such as +area of use and accuracy into account, has been added. This can avoid in a +number of situations the past requirement of using WGS84 as a pivot system, +which could cause unneeded accuracy loss, or was not doable at all sometimes +when transformation to WGS84 was not available. Those late-binding capabilities +are now used by the proj_create_crs_to_crs() function and the cs2cs utility. + +A new command line utility, projinfo, has been added to query information about +a geodetic object of the database, import and export geodetic objects from/into +WKT and PROJ strings, and display coordinate operations available between two +CRSs. + +UPDATES +------- + +* Removed projects.h as a public interface (`#835 <https://github.com/OSGeo/proj.4/issues/835>`_) + +* Deprecated the proj_api.h interface. The header file is still available + but will be removed with the next major version release of PROJ. It is + now required to define :c:macro:`ACCEPT_USE_OF_DEPRECATED_PROJ_API_H` + before the interface can be used (`#836 <https://github.com/OSGeo/proj.4/issues/836>`_) + +* Removed support for the nmake build system (`#838 <https://github.com/OSGeo/proj.4/issues/838>`_) + +* Removed support for the ``proj_def.dat`` defaults file (`#201 <https://github.com/OSGeo/proj.4/issues/201>`_) + +* C++11 required for building PROJ (`#1203 <https://github.com/OSGeo/proj.4/issues/1203>`_) + +* Added build dependency on SQLite 3.7 (`#1175 <https://github.com/OSGeo/proj.4/issues/1175>`_) + +* Added :program:`projinfo` command line application (`#1189 <https://github.com/OSGeo/proj.4/issues/1189>`_) + +* Added many functions to ``proj.h`` for handling ISO19111 functionality (`#1175 <https://github.com/OSGeo/proj.4/issues/1175>`_) + +* Added C++ API exposing ISO19111 functionality (`#1175 <https://github.com/OSGeo/proj.4/issues/1175>`_) + +* Updated :program:`cs2cs` to use late-binding features (`#1182 <https://github.com/OSGeo/proj.4/issues/1182>`_) + +* Removed the ``nad2bin`` application. Now available in the + `proj-datumgrid <https://github.com/OSGeo/proj-datumgrid>`_ + git repository (`#1236 <https://github.com/OSGeo/proj.4/issues/1236>`_) + +* Removed support for Chebyshev polynomials in :program:`proj` + (`#1226 <https://github.com/OSGeo/proj.4/issues/1226>`_) + +* Removed :c:func:`proj_geocentric_latitude` from `proj.h` API + (`#1170 <https://github.com/OSGeo/proj.4/issues/1170>`_) + +* Changed behavior of :program:`proj`: Now only allow initialization of + projections (`#1162 <https://github.com/OSGeo/proj.4/issues/1162>`_) + +* Changed behavior of :ref:`tmerc <tmerc>`: Now defaults to the Extended + Transverse Mercator algorithm (``etmerc``). Old implementation available + by adding ``+approx`` + (`#404 <https://github.com/OSGeo/proj.4/issues/404>`_) + +* Changed behavior: Default ellipsoid now set to GRS80 (was WGS84) (`#1210 <https://github.com/OSGeo/proj.4/issues/1210>`_) + +* Allow multiple directories in :envvar:`PROJ_LIB` environment variable (`#1281 <https://github.com/OSGeo/proj.4/issues/1281>`_) + +* Added :ref:`Lambert Conic Conformal (2SP Michigan) <lcc>` projection (`#1142 <https://github.com/OSGeo/proj.4/issues/1142>`_) + +* Added :ref:`Bertin1953 <bertin1953>` projection (`#1133 <https://github.com/OSGeo/proj.4/issues/1133>`_) + +* Added :ref:`Tobler-Mercator <tobmerc>` projection (`#1153 <https://github.com/OSGeo/proj.4/issues/1153>`_) + +* Added :ref:`Molodensky-Badekas <molobadekas>` transform (`#1160 <https://github.com/OSGeo/proj.4/issues/1160>`_) + +* Added :ref:`push <push>` and :ref:`pop <pop>` coordinate operations (`#1250 <https://github.com/OSGeo/proj.4/issues/1250>`_) + +* Removed ``+t_obs`` parameter from helmert and deformation (`#1264 <https://github.com/OSGeo/proj.4/issues/1264>`_) + +* Added :option:`+dt` parameter to deformation as replacement for + removed ``+t_obs`` (`#1264 <https://github.com/OSGeo/proj.4/issues/1264>`_) + +BUG FIXES +--------- + +* Read :option:`+towgs84` values correctly on locales not using dot as comma separator (`#1136 <https://github.com/OSGeo/proj.4/issues/1136>`_) + +* Fixed file offset for reading of shift values in NTv1 files (`#1144 <https://github.com/OSGeo/proj.4/issues/1144>`_) + +* Avoid problems with :c:macro:`PTHREAD_MUTEX_RECURSIVE` when using CMake (`#1158 <https://github.com/OSGeo/proj.4/issues/1158>`_) + +* Avoid raising errors when setting ellipsoid flattening to zero (`#1191 <https://github.com/OSGeo/proj.4/issues/1191>`_) + +* Fixed lower square calculations in :ref:`rHealpix <rhealpix>` projection (`#1206 <https://github.com/OSGeo/proj.4/issues/1206>`_) + +* Allow :ref:`Molodensky <molodensky>` transform parameters to be zero (`#1194 <https://github.com/OSGeo/proj.4/issues/1194>`_) + +* Fixed wrong parameter in ``ITRF2000`` init file (`#1240 <https://github.com/OSGeo/proj.4/issues/1240>`_) + +* Fixed use of grid paths including spaces (`#1152 <https://github.com/OSGeo/proj.4/issues/1152>`_) + +* :ref:`Robinson <robin>`: fix wrong values for forward path for latitudes >= 87.5, + and fix inaccurate inverse method (`#1172 <https://github.com/OSGeo/proj.4/issues/1172>`_) + + +PROJ 5.2.0 +++++++++++++++++++++++++++++++++++++++++ +*September 15th 2018* + +UPDATES +------- + +* Added support for deg, rad and grad in unitconvert (`#1054 <https://github.com/OSGeo/proj.4/issues/1054>`_) + +* Assume :option:`+t_epoch` as time input when not otherwise specified (`#1065 <https://github.com/OSGeo/proj.4/issues/1065>`_) + +* Added inverse Lagrange projection (`#1058 <https://github.com/OSGeo/proj.4/issues/1058>`_) + +* Added :option:`+multiplier` option to vgridshift (`#1072 <https://github.com/OSGeo/proj.4/issues/1072>`_) + +* Added Equal Earth projection (`#1085 <https://github.com/OSGeo/proj.4/issues/1085>`_) + +* Added "require_grid" option to gie (`#1088 <https://github.com/OSGeo/proj.4/issues/1088>`_) + +* Replace :option:`+transpose` option of Helmert transform with :option:`+convention`. + From now on the convention used should be explicitly written. An + error will be returned when using the +transpose option (`#1091 <https://github.com/OSGeo/proj.4/issues/1091>`_) + +* Improved numerical precision of inverse spherical Mercator + projection (`#1105 <https://github.com/OSGeo/proj.4/issues/1105>`_) + +* :program:`cct` will now forward text after coordinate input to output + stream (`#1111 <https://github.com/OSGeo/proj.4/issues/1111>`_) + + +BUG FIXES +------------ + +* Do not pivot over WGS84 when doing cs2cs-emulation with geocent (`#1026 <https://github.com/OSGeo/proj.4/issues/1026>`_) + +* Do not scan past the end of the read data in :c:func:`pj_ctx_fgets` (`#1042 <https://github.com/OSGeo/proj.4/issues/1042>`_) + +* Make sure :c:func:`proj_errno_string()` is available in DLL (`#1050 <https://github.com/OSGeo/proj.4/issues/1050>`_) + +* Respect `+to_meter` setting when doing cs2cs-emulation (`#1053 <https://github.com/OSGeo/proj.4/issues/1053>`_) + +* Fixed unit conversion factors for :program:`geod` (`#1075 <https://github.com/OSGeo/proj.4/issues/1075>`_) + +* Fixed test failures related to GCC 8 (`#1084 <https://github.com/OSGeo/proj.4/issues/1084>`_) + +* Improved handling of `+geoc` flag (`#1093 <https://github.com/OSGeo/proj.4/issues/1093>`_) + +* Calculate correct projection factors for Webmercator (`#1095 <https://github.com/OSGeo/proj.4/issues/1095>`_) + +* :program:`cs2cs` now always outputs degrees when transformed coordinates are + in angular units (`#1112 <https://github.com/OSGeo/proj.4/issues/1112>`_) + + +PROJ 5.1.0 +++++++++++++++++++++++++++++++++++++++++ +*June 1st 2018* + + +UPDATES +------- + +* Function :c:func:`proj_errno_string()` added to ``proj.h`` API (`#847 <https://github.com/OSGeo/proj.4/issues/847>`_) + +* Validate units between pipeline steps and ensure transformation + sanity (`#906 <https://github.com/OSGeo/proj.4/issues/906>`_) + +* Print help when calling :program:`cct` and :program:`gie` without arguments (`#907 <https://github.com/OSGeo/proj.4/issues/907>`_) + +* `CITATION` file added to source distribution (`#914 <https://github.com/OSGeo/proj.4/issues/914>`_) + +* Webmercator operation added (`#925 <https://github.com/OSGeo/proj.4/issues/925>`_) + +* Enhanced numerical precision of forward spherical Mercator near + the Equator (`#928 <https://github.com/OSGeo/proj.4/issues/928>`_) + +* Added ``--skip-lines`` option to :program:`cct` (`#923 <https://github.com/OSGeo/proj.4/issues/923>`_) + +* Consistently return ``NaN`` values on ``NaN`` input (`#949 <https://github.com/OSGeo/proj.4/issues/949>`_) + +* Removed unused ``src/org_proj4_Projections.h`` file (`#956 <https://github.com/OSGeo/proj.4/issues/956>`_) + +* Java Native Interface bindings updated (`#957 <https://github.com/OSGeo/proj.4/issues/957>`_, `#969 <https://github.com/OSGeo/proj.4/issues/969>`_) + +* Horizontal and vertical gridshift operations extended to + the temporal domain (`#1015 <https://github.com/OSGeo/proj.4/issues/1015>`_) + + +BUG FIXES +------------ + +* Handle ``NaN`` float cast overflow in ``PJ_robin.c`` and ``nad_intr.c`` (`#887 <https://github.com/OSGeo/proj.4/issues/887>`_) + +* Avoid overflow when Horner order is unreasonably large (`#893 <https://github.com/OSGeo/proj.4/issues/893>`_) + +* Avoid unwanted NaN conversions in etmerc (`#899 <https://github.com/OSGeo/proj.4/issues/899>`_) + +* Avoid memory failure in :program:`gie` when not specifying x,y,z in gie files (`#902 <https://github.com/OSGeo/proj.4/issues/902>`_) + +* Avoid memory failure when :option:`+sweep` is initialized incorrectly in geos (`#908 <https://github.com/OSGeo/proj.4/issues/908>`_) + +* Return ``HUGE_VAL`` on erroneous input in ortho (`#912 <https://github.com/OSGeo/proj.4/issues/912>`_) + +* Handle commented lines correctly in cct (`#933 <https://github.com/OSGeo/proj.4/issues/933>`_) + +* Avoid segmentation fault when transformation coordinates outside grid + area in deformation (`#934 <https://github.com/OSGeo/proj.4/issues/934>`_) + +* Avoid doing false easting/northing adjustments on cartesian + coordinates (`#936 <https://github.com/OSGeo/proj.4/issues/936>`_) + +* Thread-safe creation of proj mutex (`#954 <https://github.com/OSGeo/proj.4/issues/954>`_) + +* Avoid errors when setting up geos with +lat_0!=0 (`#986 <https://github.com/OSGeo/proj.4/issues/986>`_) + +* Reset errno when running :program:`proj` in verbose mode (`#988 <https://github.com/OSGeo/proj.4/issues/988>`_) + +* Do not interpolate node values at nodata value in vertical + grid shifts (`#1004 <https://github.com/OSGeo/proj.4/issues/1004>`_) + +* Restrict Horner degrees to positive integer values to avoid + memory allocation issues (`#1005 <https://github.com/OSGeo/proj.4/issues/1005>`_) + + + +PROJ 5.0.1 +++++++++++++++++++++++++++++++++++++++++ +*March 1st 2018* + +Bug fixes +--------- + +* Handle ellipsoid change correctly in pipelines when ``+towgs84=0,0,0`` is set (`#881 <https://github.com/OSGeo/proj.4/issues/881>`_) + + +* Handle the case where nad_ctable2_init returns NULL (`#883 <https://github.com/OSGeo/proj.4/issues/883>`_) + + +* Avoid shadowed declaration errors with old gcc (`#880 <https://github.com/OSGeo/proj.4/issues/880>`_) + + +* Expand ``+datum`` properly in pipelines (`#872 <https://github.com/OSGeo/proj.4/issues/872>`_) + + +* Fail gracefully when incorrect headers are encountered in grid files (`#875 <https://github.com/OSGeo/proj.4/issues/875>`_) + + +* Improve roundtrip stability in pipelines using ``+towgs84`` (`#871 <https://github.com/OSGeo/proj.4/issues/871>`_) + + +* Fixed typo in gie error codes (`#861 <https://github.com/OSGeo/proj.4/issues/861>`_) + + +* Numerical stability fixes to the geodesic package (`#826 <https://github.com/OSGeo/proj.4/issues/826>`_ & `#843 <https://github.com/OSGeo/proj.4/issues/843>`_) + + +* Make sure that transient errors are returned correctly (`#857 <https://github.com/OSGeo/proj.4/issues/857>`_) + + +* Make sure that locally installed header files are not used when building PROJ (`#849 <https://github.com/OSGeo/proj.4/issues/849>`_) + + +* Fix inconsistent parameter names in ``proj.h``/``proj_4D_api.c`` (`#842 <https://github.com/OSGeo/proj.4/issues/842>`_) + + +* Make sure ``+vunits`` is applied (`#833 <https://github.com/OSGeo/proj.4/issues/833>`_) + + +* Fix incorrect Web Mercator transformations (`#834 <https://github.com/OSGeo/proj.4/issues/834>`_) + + + +PROJ 5.0.0 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +*February 1st 2018* + +This version of PROJ introduces some significant extensions and +improvements to (primarily) the geodetic functionality of the system. + +The main driver for introducing the new features is the emergence of +dynamic reference frames, the increasing use of high accuracy GNSS, +and the related growing demand for accurate coordinate +transformations. While older versions of PROJ included some geodetic +functionality, the new framework lays the foundation for turning PROJ +into a generic geospatial coordinate transformation engine. + +The core of the library is still the well established projection code. +The new functionality is primarily exposed in a new programming +interface and a new command line utility, :ref:`cct<cct>` +(for "Coordinate Conversion and Transformation"). The old programming interface is +still available and can - to some extent - use the new geodetic +transformation features. + +The internal architecture has also seen many changes and much +improvement. So far, these improvements respect the existing +programming interface. But the process has revealed a need to simplify +and reduce the code base, in order to support sustained active +development. + + +**Therefore we have scheduled regular releases over the coming years** +**which will gradually remove the old programming interface.** + +**This will cause breaking changes with the next two major version** +**releases, which will affect all projects that depend on PROJ** +**(cf. section "deprecations" below).** + +The decision to break the existing API has not been easy, but has +ultimately been deemed necessary to ensure the long term survival of +the project. Not only by improving the maintainability immensely, but +also by extending the potential user (and hence developer) community. + +The end goal is to deliver a generic coordinate transformation +software package with a clean and concise code base appealing to +both users and developers. + + +Versioning and naming +--------------------- + +For the first time in more than 25 years the major version number of +the software is changed. The decision to do this is based on the many +new features and new API. While backwards compatibility remains - +except in a few rare corner cases - the addition of a new and improved +programming interface warrants a new major release. + +The new major version number unfortunately leaves the project in a bit +of a conundrum regarding the name. For the majority of the life-time +of the product it has been known as PROJ.4, but since we have now +reached version 5 the name is no longer aligned with the version +number. + +Hence we have decided to decouple the name from the version number and +from this version and onwards the product will simply be called PROJ. + +In recognition of the history of the software we are keeping PROJ.4 as +the *name of the organizing project*. The same project team also +produces the datum-grid package. + +In summary: + +* The PROJ.4 project provides the product PROJ, which is now at + version 5.0.0. + +* The foundational component of PROJ is the library libproj. + +* Other PROJ components include the application proj, which provides + a command line interface to libproj. + +* The PROJ.4 project also distributes the datum-grid package, + which at the time of writing is at version 1.6.0. + +Updates +------- + +* Introduced new API in ``proj.h``. + + - The new API is orthogonal to the existing ``proj_api.h`` API and the internally used ``projects.h`` API. + + - The new API adds the ability to transform spatiotemporal (4D) coordinates. + + - Functions in the new API use the ``proj_`` namespace. + + - Data types in the new API use the ``PJ_`` namespace. + +* Introduced the concept of "transformation pipelines" that makes possible to do complex geodetic transformations of coordinates by daisy chaining simple coordinate operations. + +* Introduced :ref:`cct`, the Coordinate Conversion and Transformation application. + +* Introduced :ref:`gie`, the Geospatial Integrity Investigation Environment. + + - Selftest invoked by ``-C`` flag in :ref:`proj` has been removed + - Ported approx. 1300 built-in selftests to :ref:`gie` format + - Ported approx. 1000 tests from the gigs test framework + - Added approx. 200 new tests + +* Adopted terminology from the OGC/ISO-19100 geospatial standards series. Key definitions are: + + - At the most generic level, a *coordinate operation* is a change of coordinates, based on a one-to-one relationship, from one coordinate reference system to another. + + - A *transformation* is a coordinate operation in which the two coordinate reference systems are based on different datums, e.g. a change from a global reference frame to a regional frame. + + - A *conversion* is a coordinate operation in which both coordinate reference systems are based on the same datum, e.g. change of units of coordinates. + + - A *projection* is a coordinate conversion from an ellipsoidal coordinate system to a plane. Although projections are simply conversions according to the standard, they are treated as separate entities in PROJ as they make up the vast majority of operations in the library. + +* New operations + + - :ref:`The pipeline operator<pipeline>` (``pipeline``) + + - Transformations + + :ref:`Helmert transform<helmert>` (``helmert``) + + Horner real and complex polynomial evaluation (``horner``) + + :ref:`Horizontal gridshift<hgridshift>` (``hgridshift``) + + :ref:`Vertical gridshift<vgridshift>` (``vgridshift``) + + :ref:`Molodensky transform<molodensky>` (``molodensky``) + + :ref:`Kinematic gridshift with deformation model<deformation>` (``deformation``) + + - Conversions + + :ref:`Unit conversion<unitconvert>` (``unitconvert``) + + :ref:`Axis swap<axisswap>` (``axisswap``) + + - Projections + + :ref:`Central Conic projection<ccon>` (``ccon``) + +* Significant documentation updates, including + + - Overhaul of the structure of the documentation + - A better introduction to the use of PROJ + - :ref:`A complete reference to the new API<reference>` + - a complete rewrite of the section on geodesic calculations + - Figures for all projections + +* New "free format" option for operation definitions, which permits separating tokens by whitespace when specifying key/value- pairs, e.g. ``proj = merc lat_0 = 45``. + +* Added metadata to init-files that can be read with the :c:func:`proj_init_info` function in the new ``proj.h`` API. + +* Added ITRF2000, ITRF2008 and ITRF2014 init-files with ITRF transformation parameters, including plate motion model parameters. + +* Added ellipsoid parameters for GSK2011, PZ90 and "danish". The latter is similar to the already supported andrae ellipsoid, but has a slightly different semimajor axis. + +* Added Copenhagen prime meridian. + +* Updated EPSG database to version 9.2.0. + +* Geodesic library updated to version 1.49.2-c. + +* Support for analytical partial derivatives has been removed. + +* Improved performance in Winkel Tripel and Aitoff. + +* Introduced ``pj_has_inverse()`` function to ``proj_api.h``. Checks if an operation has an inverse. Use this instead of checking whether ``P->inv`` exists, since that can no longer be relied on. + +* ABI version number updated to 13:0:0. + +* Removed support for Windows CE. + +* Removed the VB6 COM interface. + +Bug fixes +--------- + +* Fixed incorrect convergence calculation in Lambert Conformal Conic. (`#16 <https://github.com/OSGeo/proj.4/issues/16>`_) + + +* Handle ellipsoid parameters correctly when using ``+nadgrids=@null``. (`#22 <https://github.com/OSGeo/proj.4/issues/22>`_) + + +* Return correct latitude when using negative northings in Transverse Mercator. (`#138 <https://github.com/OSGeo/proj.4/issues/138>`_) + + +* Return correct result at origin in inverse Mod. Stereographic of Alaska. (`#161 <https://github.com/OSGeo/proj.4/issues/161>`_) + + +* Return correct result at origin in inverse Mod. Stereographic of 48 U.S. (`#162 <https://github.com/OSGeo/proj.4/issues/162>`_) + + +* Return correct result at origin in inverse Mod. Stereographic of 50 U.S. (`#163 <https://github.com/OSGeo/proj.4/issues/163>`_) + + +* Return correct result at origin in inverse Lee Oblated Stereographic. (`#164 <https://github.com/OSGeo/proj.4/issues/164>`_) + + +* Return correct result at origin in inverse Miller Oblated Stereographic. (`#165 <https://github.com/OSGeo/proj.4/issues/165>`_) + + +* Fixed scaling and wrap-around issues in Oblique Cylindrical Equal Area. (`#166 <https://github.com/OSGeo/proj.4/issues/166>`_) + + +* Corrected a coefficient error in inverse Transverse Mercator. (`#174 <https://github.com/OSGeo/proj.4/issues/174>`_) + +* Respect ``-r`` flag when calling :program:`proj` with ``-V``. (`#184 <https://github.com/OSGeo/proj.4/issues/184>`_) + +* Remove multiplication by 2 at the equator error in Stereographic projection. (`#194 <https://github.com/OSGeo/proj.4/issues/194>`_) + +* Allow +alpha=0 and +gamma=0 when using Oblique Mercator. (`#195 <https://github.com/OSGeo/proj.4/issues/195>`_) + +* Return correct result of inverse Oblique Mercator when alpha is between 90 and 270. (`#331 <https://github.com/OSGeo/proj.4/issues/331>`_) + +* Avoid segmentation fault when accessing point outside grid. (`#396 <https://github.com/OSGeo/proj.4/issues/396>`_) + +* Avoid segmentation fault on NaN input in Robin inverse. (`#463 <https://github.com/OSGeo/proj.4/issues/463>`_) + +* Very verbose use of :program:`proj` (``-V``) on Windows is fixed. (`#484 <https://github.com/OSGeo/proj.4/issues/484>`_) + +* Fixed memory leak in General Oblique Transformation. (`#497 <https://github.com/OSGeo/proj.4/issues/497>`_) + +* Equations for meridian convergence and partial derivatives have + been corrected for non-conformal projections. (`#526 <https://github.com/OSGeo/proj.4/issues/526>`_) + +* Fixed scaling of cartesian coordinates in ``pj_transform()``. (`#726 <https://github.com/OSGeo/proj.4/issues/726>`_) + +* Additional bug fixes courtesy of `Google's OSS-Fuzz program <https://bugs.chromium.org/p/oss-fuzz/issues/list?can=1&q=proj4>`_ diff --git a/_sources/operations/conversions/axisswap.rst.txt b/_sources/operations/conversions/axisswap.rst.txt new file mode 100644 index 00000000..b8d606ff --- /dev/null +++ b/_sources/operations/conversions/axisswap.rst.txt @@ -0,0 +1,56 @@ +.. _axisswap: + +================================================================================ +Axis swap +================================================================================ + +.. versionadded:: 5.0.0 + +Change the order and sign of 2,3 or 4 axes. + ++---------------------+--------------------------------------------------------+ +| **Alias** | axisswap | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D, 3D or 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + + +Each of the possible four axes are numbered with 1--4, such that the first input axis +is 1, the second is 2 and so on. The output ordering is controlled by a list of the +input axes re-ordered to the new mapping. + +Usage +################################################################################ + +Reversing the order of the axes:: + + +proj=axisswap +order=4,3,2,1 + +Swapping the first two axes (x and y):: + + +proj=axisswap +order=2,1,3,4 + +The direction, or sign, of an axis can be changed by adding a minus in +front of the axis-number:: + + +proj=axisswap +order=1,-2,3,4 + +It is only necessary to specify the axes that are affected by the swap +operation:: + + +proj=axisswap +order=2,1 + +Parameters +################################################################################ + +.. option:: +order=<list> + + Ordered comma-separated list of axis, e.g. *+order=2,1,3,4*. + Adding a minus in front of an axis number results in a change of direction + for that axis, e.g. southward instead of northward. + + *Required.* diff --git a/_sources/operations/conversions/cart.rst.txt b/_sources/operations/conversions/cart.rst.txt new file mode 100644 index 00000000..239b1772 --- /dev/null +++ b/_sources/operations/conversions/cart.rst.txt @@ -0,0 +1,38 @@ +.. _cart: + +================================================================================ +Geodetic to cartesian conversion +================================================================================ + +.. versionadded:: 5.0.0 + +Convert geodetic coordinates to cartesian coordinates (in the forward path). + ++---------------------+--------------------------------------------------------+ +| **Alias** | cart | ++---------------------+--------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Geocentric cartesian coordinates | ++---------------------+--------------------------------------------------------+ + +This conversion converts geodetic coordinate values (longitude, latitude, +elevation above ellipsoid) to their geocentric (X, Y, Z) representation, where +the first axis (X) points from the Earth centre to the point of longitude=0, +latitude=0, the second axis (Y) points from the Earth centre to the point of +longitude=90, latitude=0 and the third axis (Z) points to the North pole. + +Usage +################################################################################ + +Convert geodetic coordinates to GRS80 cartesian coordinates:: + + echo 17.7562015132 45.3935192042 133.12 2017.8 | cct +proj=cart +ellps=GRS80 + 4272922.1553 1368283.0597 4518261.3501 2017.8000 + +Parameters +################################################################################ + +.. include:: ../options/ellps.rst diff --git a/_sources/operations/conversions/geoc.rst.txt b/_sources/operations/conversions/geoc.rst.txt new file mode 100644 index 00000000..6ee32ea6 --- /dev/null +++ b/_sources/operations/conversions/geoc.rst.txt @@ -0,0 +1,75 @@ +.. _geoc: + +================================================================================ +Geocentric Latitude +================================================================================ + +.. versionadded:: 5.0.0 + +Convert from Geodetic Latitude to Geocentric Latitude (in the forward path). + ++---------------------+--------------------------------------------------------+ +| **Alias** | geoc | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Geocentric angular coordinates | ++---------------------+--------------------------------------------------------+ + +The geodetic (or geographic) latitude (also called planetographic latitude +in the context of non-Earth bodies) is the angle between the equatorial plane +and the normal (vertical) to the ellipsoid surface at the considered point. +The geodetic latitude is what is normally used everywhere in PROJ when angular +coordinates are expected or produced. + +The geocentric latitude (also called planetocentric latitude in the context of +non-Earth bodies) is the angle between the equatorial plane and a line joining +the body centre to the considered point. + +.. image:: ./images/geocentric_latitude.png + :align: center + :scale: 100% + :alt: Geocentric latitude + + +.. note:: + + This conversion must be distinguished from the :ref:`cart` + which converts geodetic coordinates to geocentric coordinates in the cartesian + domain. + +Mathematical definition +####################### + +The formulas describing the conversion are taken from :cite:`Snyder1987` +(equation 3-28) + +Let :math:`\phi'` to be the geocentric latitude and :math:`\phi` the +geodetic latitude, then + +.. math:: + + \phi' = \arctan \left[ (1 - e^2) \tan \left( \phi \right) \right] + +The geocentric latitude is consequently lesser (in absolute value) than the geodetic +latitude, except at the equator and the poles where they are equal. + +On a sphere, they are always equal. + +Usage +################################################################################ + +Converting from geodetic latitude to geocentric latitude:: + + +proj=geoc +ellps=GRS80 + +Converting from geocentric latitude to geodetic latitude:: + + +proj=pipeline +step +proj=geoc +inv +ellps=GRS80 + +Parameters +################################################################################ + +.. include:: ../options/ellps.rst diff --git a/_sources/operations/conversions/index.rst.txt b/_sources/operations/conversions/index.rst.txt new file mode 100644 index 00000000..b335c2ac --- /dev/null +++ b/_sources/operations/conversions/index.rst.txt @@ -0,0 +1,23 @@ +.. _conversions_list: + +================================================================================ +Conversions +================================================================================ + +Conversions are coordinate operations in which both coordinate reference systems +are based on the same datum. In PROJ projections are differentiated from +conversions. + +.. toctree:: + :maxdepth: 1 + + axisswap + cart + geoc + latlon + noop + pop + push + set + topocentric + unitconvert diff --git a/_sources/operations/conversions/latlon.rst.txt b/_sources/operations/conversions/latlon.rst.txt new file mode 100644 index 00000000..25e2a143 --- /dev/null +++ b/_sources/operations/conversions/latlon.rst.txt @@ -0,0 +1,46 @@ +.. _latlon: + +******************************************************************************** +Lat/long (Geodetic alias) +******************************************************************************** + +Passes geodetic coordinates through unchanged. + ++---------------------+--------------------------------------------------------+ +| **Aliases** | latlon, latlong, lonlat, longlat | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ + +.. note:: Can not be used with the :program:`proj` application. + + +Parameters +################################################################################ + +No parameters will affect the output of the operation if used on it's own. +However, the parameters below can be used in a declarative manner when used with +:program:`cs2cs` or in a :ref:`transformation pipeline <pipeline>` . + +.. include:: ../options/ellps.rst + +.. option:: +datum=<value> + + Declare the datum used with the coordinates. Available options are: + ``WGS84``, ``GGRS87``, ``NAD38``, ``NAD27``, ``potsdam``, ``carthage``, + ``hermannskogel``, ``ire65``, ``nzgd49``, ``OSGB336``. + + .. note:: + + The ``+datum`` option is primarily available to support the legacy + use of PROJ.4 strings as CRS descriptors and should in most cases + be avoided. + +.. option:: +towgs84=<list> + + A list of three or seven :ref:`Helmert <helmert>` parameters that maps + the input coordinates to the WGS84 datum. diff --git a/_sources/operations/conversions/noop.rst.txt b/_sources/operations/conversions/noop.rst.txt new file mode 100644 index 00000000..a35b2b58 --- /dev/null +++ b/_sources/operations/conversions/noop.rst.txt @@ -0,0 +1,28 @@ +.. _noop: + +================================================================================ +No operation +================================================================================ + +.. versionadded:: 6.1.0 + +Pass a coordinate through unchanged. + ++---------------------+--------------------------------------------------------+ +| **Alias** | noop | ++---------------------+--------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +The no operation is a dummy operation that returns whatever is passed to it +as seen in this example:: + + $ echo 12 34 56 78 | cct +proj=noop + 12.0000 34.0000 56.0000 78.0000 + +The operation has no options and default options will not affect the output. + diff --git a/_sources/operations/conversions/pop.rst.txt b/_sources/operations/conversions/pop.rst.txt new file mode 100644 index 00000000..2c6d264a --- /dev/null +++ b/_sources/operations/conversions/pop.rst.txt @@ -0,0 +1,94 @@ +.. _pop: + +================================================================================ +Pop coordinate value to pipeline stack +================================================================================ + +.. versionadded:: 6.0.0 + +Retrieve components of a coordinate that was saved in a previous pipeline step. + ++---------------------+--------------------------------------------------------+ +| **Alias** | pop | ++---------------------+--------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +This operations makes it possible to retrieve coordinate components that was +saved in previous pipeline steps. A retrieved coordinate component is loaded, +or *popped*, from a memory stack that is part of a :ref:`pipeline<pipeline>`. +The pipeline coordinate stack is inspired by the stack data structure that is +commonly used in computer science. There's four stacks available: One four each +coordinate dimension. The dimensions, or coordinate components, are numbered +1--4. It is only possible to move data to and from the stack within the same +coordinate component number. Values can be saved to the stack by using the +:ref:`push operation<push>`. + +If the pop operation is used by itself, e.g. not in a pipeline, it will +function as a no-operation that passes the coordinate through unchanged. +Similarly, if no coordinate component is available on the stack to be popped +the operation does nothing. + +Examples +################################################################################ + +A common use of the :ref:`push<push>` and pop operations is in 3D +:ref:`Helmert<helmert>` transformations where only the horizontal components +are needed. This is often the case when combining heights from a legacy +vertical reference with a modern geocentric reference. Below is a an example of +such a transformation, where the horizontal part is transformed with a Helmert +operation but the vertical part is kept exactly as the input was. + +:: + + $ echo 12 56 12.3 2020 | cct +proj=pipeline \ + +step +proj=push +v_3 \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=3000 +y=1000 +z=2000 \ + +step +proj=cart +ellps=GRS80 +inv \ + +step +proj=pop +v_3 \ + + 12.0056753463 55.9866540552 12.3000 2000.0000 + +Note that the third coordinate component in the output is the same as the input. + +The same transformation without the push and pop operations would look like this:: + + $ echo 12 56 12.3 2020 | cct +proj=pipeline \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=3000 +y=1000 +z=2000 \ + +step +proj=cart +ellps=GRS80 +inv \ + + 12.0057 55.9867 3427.7404 2000.0000 + +Here the vertical component is adjusted significantly. + +Parameters +################################################################################ + +.. option:: +v_1 + + Retrieves the first coordinate component from the pipeline stack + +.. option:: +v_2 + + Retrieves the second coordinate component from the pipeline stack + +.. option:: +v_3 + + Retrieves the third coordinate component from the pipeline stack + +.. option:: +v_4 + + Retrieves the fourth coordinate component from the pipeline stack + + +Further reading +################################################################################ + +#. `Stack data structure on Wikipedia <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>`_ + diff --git a/_sources/operations/conversions/push.rst.txt b/_sources/operations/conversions/push.rst.txt new file mode 100644 index 00000000..a1f4423a --- /dev/null +++ b/_sources/operations/conversions/push.rst.txt @@ -0,0 +1,93 @@ +.. _push: + +================================================================================ +Push coordinate value to pipeline stack +================================================================================ + +.. versionadded:: 6.0.0 + +Save components of a coordinate from one step of a pipeline and make it +available for retrieving in another pipeline step. + ++---------------------+--------------------------------------------------------+ +| **Alias** | push | ++---------------------+--------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +This operations allows for components of coordinates to be saved for +application in a later step. A saved coordinate component is moved, or +*pushed*, to a memory stack that is part of a :ref:`pipeline<pipeline>`. The +pipeline coordinate stack is inspired by the stack data structure that is +commonly used in computer science. There's four stacks available: One four each +coordinate dimension. The dimensions, or coordinate components, are numbered +1--4. It is only possible to move data to and from the stack within the same +coordinate component number. Values can be moved off the stack again by using +the :ref:`pop operation<pop>`. + +If the push operation is used by itself, e.g. not in a pipeline, it will +function as a no-operation that passes the coordinate through unchanged. + +Examples +################################################################################ + +A common use of the push and :ref:`pop<pop>` operations is in 3D +:ref:`Helmert<helmert>` transformations where only the horizontal components +are needed. This is often the case when combining heights from a legacy +vertical reference with a modern geocentric reference. Below is a an example of +such a transformation, where the horizontal part is transformed with a Helmert +operation but the vertical part is kept exactly as the input was. + +:: + + $ echo 12 56 12.3 2020 | cct +proj=pipeline \ + +step +proj=push +v_3 \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=3000 +y=1000 +z=2000 \ + +step +proj=cart +ellps=GRS80 +inv \ + +step +proj=pop +v_3 \ + + 12.0056753463 55.9866540552 12.3000 2000.0000 + +Note that the third coordinate component in the output is the same as the input. + +The same transformation without the push and pop operations would look like this:: + + $ echo 12 56 12.3 2020 | cct +proj=pipeline \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=3000 +y=1000 +z=2000 \ + +step +proj=cart +ellps=GRS80 +inv \ + + 12.0057 55.9867 3427.7404 2000.0000 + +Here the vertical component is adjusted significantly. + +Parameters +################################################################################ + +.. option:: +v_1 + + Stores the first coordinate component on the pipeline stack + +.. option:: +v_2 + + Stores the second coordinate component on the pipeline stack + +.. option:: +v_3 + + Stores the third coordinate component on the pipeline stack + +.. option:: +v_4 + + Stores the fourth coordinate component on the pipeline stack + + +Further reading +################################################################################ + +#. `Stack data structure on Wikipedia <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>`_ + diff --git a/_sources/operations/conversions/set.rst.txt b/_sources/operations/conversions/set.rst.txt new file mode 100644 index 00000000..635d08d3 --- /dev/null +++ b/_sources/operations/conversions/set.rst.txt @@ -0,0 +1,76 @@ +.. _set: + +================================================================================ +Set coordinate value +================================================================================ + +.. versionadded:: 7.0.0 + +Set component(s) of a coordinate to a fixed value. + ++---------------------+--------------------------------------------------------+ +| **Alias** | set | ++---------------------+--------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +This operations allows for components of coordinates to be set to a fixed value. +This may be useful in :ref:`pipeline<pipeline>` when a step requires some +component, typically an elevation or a date, to be set to a fixed value. + +Example +################################################################################ + +In the ETRS89 to Dutch RD with NAP height transformation, the used ellipsoidal +height for the Helmert transformation is not the NAP height, but the height is +set to 0 m. This is an unconventional trick to get the same results as when the +effect of the Helmert transformation is included in the horizontal NTv2 grid. +For the forward transformation from ETRS89 to RD with NAP height, we need to set +the ellipsoidal ETRS89 height for the Helmert transformation to the equivalent +of 0 m NAP. This is 43 m for the centre of the Netherlands and this value can +be used as an approximation elsewhere (the effect of this approximation is +below 1 mm for the horizontal coordinates, in an area up to hundreds of km +outside the Netherlands). + +The ``+proj=set +v_3=0`` close to the end of the pipeline is to make it usable in +the reverse direction. + +:: + + $ cct -t 0 -d 4 +proj=pipeline \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=axisswap +order=2,1 \ + +step +proj=vgridshift +grids=nlgeo2018.gtx \ + +step +proj=push +v_3 \ + +step +proj=set +v_3=43 \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=-565.7346 +y=-50.4058 +z=-465.2895 +rx=-0.395023 +ry=0.330776 +rz=-1.876073 +s=-4.07242 +convention=coordinate_frame +exact \ + +step +proj=cart +inv +ellps=bessel \ + +step +proj=hgridshift +inv +grids=rdcorr2018.gsb,null \ + +step +proj=sterea +lat_0=52.156160556 +lon_0=5.387638889 +k=0.9999079 +x_0=155000 +y_0=463000 +ellps=bessel \ + +step +proj=set +v_3=0 \ + +step +proj=pop +v_3 + +Parameters +################################################################################ + +.. option:: +v_1=value + + Set the first coordinate component to the specified value + +.. option:: +v_2=value + + Set the second coordinate component to the specified value + +.. option:: +v_3=value + + Set the third coordinate component to the specified value + +.. option:: +v_4=value + + Set the fourth coordinate component to the specified value + diff --git a/_sources/operations/conversions/topocentric.rst.txt b/_sources/operations/conversions/topocentric.rst.txt new file mode 100644 index 00000000..14019965 --- /dev/null +++ b/_sources/operations/conversions/topocentric.rst.txt @@ -0,0 +1,117 @@ +.. _topocentric: + +================================================================================ +Geocentric to topocentric conversion +================================================================================ + +.. versionadded:: 8.0.0 + +Convert geocentric coordinates to topocentric coordinates (in the forward path). + ++---------------------+--------------------------------------------------------+ +| **Alias** | topocentric | ++---------------------+--------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geocentric cartesian coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Topocentric cartesian coordinates | ++---------------------+--------------------------------------------------------+ + +This operation converts geocentric coordinate values (X, Y, Z) to topocentric +(E/East, N/North, U/Up) values. This is also sometimes known as the ECEF (Earth +Centered Earth Fixed) to ENU conversion. + +Topocentric coordinates are expressed in a frame whose East and North axis form +a local tangent plane to the Earth's ellipsoidal surface fixed to a specific +location (the topocentric origin), and the Up axis points upwards along the +normal to that plane. + +.. image:: ./images/ECEF_ENU_Longitude_Latitude_relationships.png + :align: center + :scale: 100% + :alt: ENU coordinate frame + +.. + Source : https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates#/media/File:ECEF_ENU_Longitude_Latitude_relationships.svg + Public domain +.. + +The topocentric origin is a required parameter of the conversion, and can be +expressed either as geocentric coordinates (``X_0``, ``Y_0`` and ``Z_0``) or +as geographic coordinates (``lat_0``, ``lon_0``, ``h_0``). + +When conversion between geographic and topocentric coordinates is desired, the +topocentric conversion must be preceded by the :ref:`cart` conversion to +perform the initial geographic to geocentric coordinates conversion. + +The formulas used come from the "Geocentric/topocentric conversions" paragraph +of :cite:`IOGP2018`. ``+proj=topocentric`` alone corresponds to the ``EPSG:9836`` +conversion method, ``+proj=cart`` followed by ``+proj=topocentric`` corresponds +to ``EPSG:9837``. + +Usage +################################################################################ + +Convert geocentric coordinates to topocentric coordinates, with the topocentric +origin specified in geocentric coordinates:: + + echo 3771793.968 140253.342 5124304.349 2020 | \ + cct -d 3 +proj=topocentric +ellps=WGS84 +X_0=3652755.3058 +Y_0=319574.6799 +Z_0=5201547.3536 + + -189013.869 -128642.040 -4220.171 2020.0000 + +Convert geographic coordinates to topocentric coordinates, with the topocentric +origin specified in geographic coordinates:: + + echo 2.12955 53.80939444 73 2020 | cct -d 3 +proj=pipeline \ + +step +proj=cart +ellps=WGS84 \ + +step +proj=topocentric +ellps=WGS84 +lon_0=5 +lat_0=55 +h_0=200 + + -189013.869 -128642.040 -4220.171 2020.0000 + + +Parameters +################################################################################ + +.. include:: ../options/ellps.rst + +Topocentric origin described as geocentric coordinates +------------------------------------------------------ + +.. note:: + + The below options are mutually exclusive with the ones to express the origin as geographic coordinates. + +.. option:: +X_0=<value> + + Geocentric X value of the topocentric origin (in metre) + +.. option:: +Y_0=<value> + + Geocentric Y value of the topocentric origin (in metre) + +.. option:: +Z_0=<value> + + Geocentric Z value of the topocentric origin (in metre) + +Topocentric origin described as geographic coordinates +------------------------------------------------------ + +.. note:: + + The below options are mutually exclusive with the ones to express the origin as geocentric coordinates. + +.. option:: +lat_0=<value> + + Latitude of topocentric origin (in degree) + +.. option:: +lon_0=<value> + + Longitude of topocentric origin (in degree) + +.. option:: +h_0=<value> + + Ellipsoidal height of topocentric origin (in metre) + + *Defaults to 0.0.* diff --git a/_sources/operations/conversions/unitconvert.rst.txt b/_sources/operations/conversions/unitconvert.rst.txt new file mode 100644 index 00000000..13ca9228 --- /dev/null +++ b/_sources/operations/conversions/unitconvert.rst.txt @@ -0,0 +1,182 @@ +.. _unitconvert: + +================================================================================ +Unit conversion +================================================================================ + +.. versionadded:: 5.0.0 + +Convert between various distance, angular and time units. + ++---------------------+--------------------------------------------------------+ +| **Alias** | unitconvert | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D, 3D or 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +There are many examples of coordinate reference systems that are expressed in +other units than the meter. There are also many cases where temporal data +has to be translated to different units. The `unitconvert` operation takes care +of that. + +Many North American systems are defined with coordinates in feet. For example +in Vermont:: + + +proj=pipeline + +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k_0=0.999964286 +x_0=500000.00001016 +y_0=0 + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +Often when working with GNSS data the timestamps are presented in GPS-weeks, +but when the data transformed with the `helmert` operation timestamps are +expected to be in units of decimalyears. This can be fixed with `unitconvert`:: + + +proj=pipeline + +step +proj=unitconvert +t_in=gps_week +t_out=decimalyear + +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ... + +Parameters +################################################################################ + +.. option:: +xy_in=<unit> or <conversion_factor> + + Horizontal input units. See :ref:`distance_units` and :ref:`angular_units` + for a list of available units. `<conversion_factor>` is the conversion factor + from the input unit to metre for linear units, or to radian for angular + units. + +.. option:: +xy_out=<unit> or <conversion_factor> + + Horizontal output units. See :ref:`distance_units` and :ref:`angular_units` + for a list of available units. `<conversion_factor>` is the conversion factor + from the output unit to metre for linear units, or to radian for angular + units. + +.. option:: +z_in=<unit> or <conversion_factor> + + Vertical output units. See :ref:`distance_units` and :ref:`angular_units` + for a list of available units. `<conversion_factor>` is the conversion factor + from the input unit to metre for linear units, or to radian for angular + units. + +.. option:: +z_out=<unit> or <conversion_factor> + + Vertical output units. See :ref:`distance_units` and :ref:`angular_units` + for a list of available units. `<conversion_factor>` is the conversion factor + from the output unit to metre for linear units, or to radian for angular + units. + +.. option:: +t_in=<unit> + + Temporal input units. See :ref:`time_units` for a list of available units. + +.. option:: +t_out=<unit> + + Temporal output units. See :ref:`time_units` for a list of available units. + +.. _distance_units: + +Distance units +############################################################################### + +In the table below all distance units supported by PROJ are listed. +The same list can also be produced on the command line with :program:`proj` or +:program:`cs2cs`, by adding the `-lu` flag when calling the utility. + ++----------+---------------------------------+ +| Label | Name | ++==========+=================================+ +| km | Kilometer | ++----------+---------------------------------+ +| m | Meter | ++----------+---------------------------------+ +| dm | Decimeter | ++----------+---------------------------------+ +| cm | Centimeter | ++----------+---------------------------------+ +| mm | Millimeter | ++----------+---------------------------------+ +| kmi | International Nautical Mile | ++----------+---------------------------------+ +| in | International Inch | ++----------+---------------------------------+ +| ft | International Foot | ++----------+---------------------------------+ +| yd | International Yard | ++----------+---------------------------------+ +| mi | International Statute Mile | ++----------+---------------------------------+ +| fath | International Fathom | ++----------+---------------------------------+ +| ch | International Chain | ++----------+---------------------------------+ +| link | International Link | ++----------+---------------------------------+ +| us-in | U.S. Surveyor's Inch | ++----------+---------------------------------+ +| us-ft | U.S. Surveyor's Foot | ++----------+---------------------------------+ +| us-yd | U.S. Surveyor's Yard | ++----------+---------------------------------+ +| us-ch | U.S. Surveyor's Chain | ++----------+---------------------------------+ +| us-mi | U.S. Surveyor's Statute Mile | ++----------+---------------------------------+ +| ind-yd | Indian Yard | ++----------+---------------------------------+ +| ind-ft | Indian Foot | ++----------+---------------------------------+ +| ind-ch | Indian Chain | ++----------+---------------------------------+ + +.. _angular_units: + +Angular units +############################################################################### + +.. versionadded:: 5.2.0 + +In the table below all angular units supported by PROJ `unitconvert` are listed. + ++----------+---------------------------------+ +| Label | Name | ++==========+=================================+ +| deg | Degree | ++----------+---------------------------------+ +| grad | Grad | ++----------+---------------------------------+ +| rad | Radian | ++----------+---------------------------------+ + +.. _time_units: + +Time units +############################################################################### + +In the table below all time units supported by PROJ are listed. + + .. note:: + + When converting time units from a date-only format (`yyyymmdd`), PROJ + assumes a time value of 00:00 midnight. When converting time units + to a date-only format, PROJ rounds to the *nearest* date at 00:00 + midnight. That is, any time values less than 12:00 noon will round to + 00:00 on the same day. Time values greater than or equal to 12:00 noon + will round to 00:00 on the following day. + + ++--------------+-----------------------------+ +| Label | Name | ++==============+=============================+ +| mjd | Modified Julian date | ++--------------+-----------------------------+ +| decimalyear | Decimal year | ++--------------+-----------------------------+ +| gps_week | GPS Week | ++--------------+-----------------------------+ +| yyyymmdd | Date in yyyymmdd format | ++--------------+-----------------------------+ + diff --git a/_sources/operations/index.rst.txt b/_sources/operations/index.rst.txt new file mode 100644 index 00000000..d4582049 --- /dev/null +++ b/_sources/operations/index.rst.txt @@ -0,0 +1,22 @@ +.. _operations: + +================================================================================ +Coordinate operations +================================================================================ + +Coordinate operations in PROJ are divided into three groups: +Projections, conversions and transformations. +Projections are purely cartographic mappings of the sphere onto the plane. +Technically projections are conversions (according to ISO standards), though in +PROJ projections are distinguished from conversions. Conversions are coordinate +operations that do not exert a change in reference frame. Operations that do +exert a change in reference frame are called transformations. + +.. toctree:: + :maxdepth: 1 + + projections/index + conversions/index + transformations/index + pipeline + operations_computation diff --git a/_sources/operations/operations_computation.rst.txt b/_sources/operations/operations_computation.rst.txt new file mode 100644 index 00000000..5c2596e6 --- /dev/null +++ b/_sources/operations/operations_computation.rst.txt @@ -0,0 +1,785 @@ +.. _operations_computation: + +================================================================================ +Computation of coordinate operations between two CRS +================================================================================ + +:Author: Even Rouault +:Last Updated: 2021-02-10 + +Introduction +------------ + +When using :command:`projinfo -s {crs_def} -t {crs_def}`, +:command:`cs2cs {crs_def} {crs_def}` or the underlying +:c:func:`proj_create_crs_to_crs` or :cpp:func:`proj_create_operations` functions, +PROJ applies an algorithm to compute one or several candidate coordinate operations, +that can be expressed as a PROJ :ref:`pipeline <pipeline>` to transform between the source +and the target CRS. This document is about the description of this algorithm that +finds the actual operations to apply to be able later to perform transform coordinates. +So this is mostly about metadata management around coordinate operation methods, +and not about the actual mathematics used to implement those methods. +As a matter of fact with PROJ 6, there are about 60 000 +lines of code dealing with "metadata" management (including conversions between PROJ +strings, all CRS WKT variants), to be compared to 30 000 for the purely computation part. + +This document is meant as a plain text explanation of the code for developers, +but also as a in-depth examination of what happens under the hood for curious PROJ +users. It is important to keep in mind that it is not meant to be the ultimate +source of truth of how coordinate operations should be computed. There are clearly +implementation choices and compromises that can be questioned. + +Let us start with an example to research operations between the NAD27 and NAD83 +geographic CRS: + +.. code-block:: shell + + $ projinfo -s NAD27 -t NAD83 --summary --spatial-test intersects --grid-check none + + Candidate operations found: 10 + DERIVED_FROM(EPSG):1312, NAD27 to NAD83 (3), 1.0 m, Canada + DERIVED_FROM(EPSG):1313, NAD27 to NAD83 (4), 1.5 m, Canada - NAD27, at least one grid missing + DERIVED_FROM(EPSG):1241, NAD27 to NAD83 (1), 0.15 m, USA - CONUS including EEZ + DERIVED_FROM(EPSG):1243, NAD27 to NAD83 (2), 0.5 m, USA - Alaska including EEZ + DERIVED_FROM(EPSG):1573, NAD27 to NAD83 (6), 1.5 m, Canada - Quebec, at least one grid missing + EPSG:1462, NAD27 to NAD83 (5), 1.0 m, Canada - Quebec, at least one grid missing + EPSG:9111, NAD27 to NAD83 (9), 1.5 m, Canada - Saskatchewan, at least one grid missing + unknown id, Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, World, has ballpark transformation + EPSG:8555, NAD27 to NAD83 (7), 0.15 m, USA - CONUS and GoM, at least one grid missing + EPSG:8549, NAD27 to NAD83 (8), 0.5 m, USA - Alaska, at least one grid missing + +The algorithm involves many cases, so we will progress in the explanation from +the most simple case to more complex ones. We document here the working of this +algorithm as implemented in PROJ 8.0.0. +The results of some examples might also be quite sensitive to the content of the +PROJ database and the PROJ version used. + +From a code point of view, the entry point of the algorithm is the C++ +:cpp:func:`osgeo::proj::operation::CoordinateOperation::createOperations` method. + +It combines several strategies: + + - look up in the PROJ database for available operations + - consider the pair (source CRS, target CRS) to synthetize operations depending + on the nature of the source and target CRS. + +Geographic CRS to Geographic CRS, with known identifiers +-------------------------------------------------------- + +With the above example of two geographic CRS, that have an identified identifier, +(:program:`projinfo` internally resolves NAD27 to EPSG:4267 and NAD83 to EPSG:4269) +the algorithm will first search +in the coordinate operation related tables of the :file:`proj.db` if there are records +that list direct transformations between the source and the target CRS. The +transformations typically involve :ref:`Helmert <helmert>`-style operations or datum shift based on +grids (more esoteric operations are possible). + +A request similar to the following will be emitted: + +.. code-block:: shell + + $ sqlite3 proj.db "SELECT auth_name, code, name, method_name, accuracy FROM \ + coordinate_operation_view WHERE \ + source_crs_auth_name = 'EPSG' AND \ + source_crs_code = '4267' AND \ + target_crs_auth_name = 'EPSG' AND \ + target_crs_code = '4269'" + + EPSG|1241|NAD27 to NAD83 (1)|NADCON|0.15 + EPSG|1243|NAD27 to NAD83 (2)|NADCON|0.5 + EPSG|1312|NAD27 to NAD83 (3)|NTv1|1.0 + EPSG|1313|NAD27 to NAD83 (4)|NTv2|1.5 + EPSG|1462|NAD27 to NAD83 (5)|NTv1|1.0 + EPSG|1573|NAD27 to NAD83 (6)|NTv2|1.5 + EPSG|8549|NAD27 to NAD83 (8)|NADCON5 (2D)|0.5 + EPSG|8555|NAD27 to NAD83 (7)|NADCON5 (2D)|0.15 + EPSG|9111|NAD27 to NAD83 (9)|NTv2|1.5 + ESRI|108003|NAD_1927_To_NAD_1983_PR_VI|NTv2|0.05 + +As we have found direct transformations, we will not attempt any more complicated +research. +One can note in the above result set that a ESRI:108003 operation was found, +but as the source and target CRS are in the EPSG registry, and there are +operations between those CRS in the EPSG registry itself, transformations from +other authorities will be ignored (except if they are in the PROJ authority, +which can be used as an override). + +As those results all involve operations that does not have a perfect accuracy and that +does not cover the area of use of the 2 CRSs, a +'Ballpark geographic offset from NAD27 to NAD83' operation is synthetized by PROJ +(see :term:`Ballpark transformation`) + +Filtering and sorting of coordinate operations +---------------------------------------------- + +The last step is to filter and sort results in order of relevance. + +The filtering takes into account the following criteria to decide which operations +must be retained or discarded: + +* a minimum accuracy that the user might have expressed, +* an area of use on which the coordinate operation(s) must apply +* if the absence of grids needed by an operation must result in discarding it. + +The sorting algorithm determines the order of relevance of the operations we got. +A comparison function compares pair of operations to determine which of the +two is the most relevant. This is implemented by the :cpp:func:`operator ()` +method of the SortFunction structure. +When comparing two operations, the following criteria are used. The tests are +performed in the order they are listed below: + +1. consider as more relevant an operation that can be expressed as a PROJ operation string + (the database might list operations whose method is not (yet) implemented by PROJ) +2. if both operations evaluate identically with respect to the above criterion, + consider as more relevant an operation that does not include a synthetic + ballpark vertical transformation (occurs when there is a geoid model). +3. if both operations evaluate identically with respect to the above criterion, + consider as more relevant an operation that does not include a synthetic + ballpark horizontal transformation. +4. consider as more relevant an operation that refers to shift grids that are locally available. +5. consider as more relevant an operation that refers to grids that are available + in one of the proj-datumgrid packages, but not necessarily locally available +6. consider as more relevant an operation that has a known accuracy. +7. if two operations have unknown accuracy, consider as more relevant an operation + that uses grid(s) if the other one does not (grid based operations are assumed + to be more precise than operations relying on a few parameters) +8. consider as more relevant an operation whose area of use is larger + (note: the computation of the are of use is approximate, based on a bounding box) +9. consider as more relevant an operation that has a better accuracy. +10. in case of same accuracy, consider as more relevant an operation that does + not use grids (operations that use only parameters will be faster) +11. consider as more relevant an operation that involves less transformation steps + (transformation steps considered are the ones listed in the WKT output, not PROJ pipeline steps) +12. and for completeness, if two operations are comparable given all the above criteria, + consider as more relevant the one which has the shorter name, and if they + have the same length, consider as more relevant the one whose name comes last in + lexicographic order (e.g. "FOO to BAR (3)" will have higher precedence than + "FOO to BAR (2)") + +.. note:: + + :c:func:`proj_trans`, on the results returned by :c:func:`proj_create_crs_to_crs`, + will not necessarily use the operation that + is listed in first position due to the above algorithm. :c:func:`proj_trans` + has more context, since it has the coordinate to transform, so it can compare + this coordinate to the area of use of operations. Typically, the above criteria + will favor an operation that has a larger area of use over another one with a + smaller area, due to it being more generally applicable. But once coordinates are known, + :c:func:`proj_trans` can select an operation with a smaller + area of use that applies to the coordinate to transform. + +Geodetic/geographic CRS to Geodetic/geographic CRS, without known identifiers +----------------------------------------------------------------------------- + +In a number of situations, the source and/or target CRS do not have an identifier +(WKT without identifier, PROJ string, ..) +The first step is to try to find in the :file:`proj.db` a CRS of the same nature of +the CRS to identify and whose name exactly matches the one provided to the +:c:func:`createOperations` method. If there is exactly one match and that the CRS are +"computationally" equivalent, then use the code of the CRS for further computations. + +If this search did not succeed, or if the previous case with known CRS identifiers +did not result in matches in the database, the search will be based on the +datums. That is, a list of geographic CRS whose datum matches the datum of the +source and target CRS is searched for in the database (by querying the `geodetic_crs` +database table). If the datum has a known +identifier, we will use it, otherwise we will look for an equivalent datum in the +database based on the datum name. + +Let's consider the case where the datum of the source CRS is EPSG:6171 "Reseau +Geodesique Francais 1993" and the datum of the target CRS is EPSG:6258 "European +Terrestrial Reference System 1989". +For EPSG:6171, there are 10 matching (non-deprecated) geodetic CRSs: + +- EPSG:4171, RGF93, geographic 2D +- EPSG:4964, RGF93, geocentric +- EPSG:4965, RGF93, geographic 3D +- EPSG:7042, RGF93 (lon-lat), geographic 3D +- EPSG:7084, RGF93 (lon-lat), geographic 2D +- IGNF:RGF93, RGF93 cartesiennes geocentriques, geocentric +- IGNF:RGF93GDD, RGF93 geographiques (dd),geographic 2D +- IGNF:RGF93GEODD, RGF93 geographiques (dd), geographic 3D +- IGNF:RGF93G, RGF93 geographiques (dms), geographic 2D +- IGNF:RGF93GEO, RGF93 geographiques (dms), geographic 3D + +The first three entries from the EPSG dataset are typical: for each datum, +one can define a geographic 2D CRS (latitude, longitude), a geographic 3D crs +(latitude, longitude, ellipsoidal height) and a geocentric one. For that particular +case, the EPSG dataset has also included two extra definitions corresponding to a +longitude, latitude, [ellipsoidal height] coordinate system, as found in the official +French IGNF registry. This IGNF registry has also definitions for a geographic 2D +CRS (with an extra subtlety with an entry using decimal degree as unit and another +one degree-minute-second), geographic 3D and geocentric. + +For EPSG:6258, there are 7 matching (non-deprecated) geodetic CRSs: + +- EPSG:4258, ETRS89, geographic 2D +- EPSG:4936, ETRS89, geocentric +- EPSG:4937, ETRS89, geographic 3D +- IGNF:ETRS89, ETRS89 cartesiennes geocentriques, geocentric +- IGNF:ETRS89G, ETRS89 geographiques (dms), geographic 2D +- IGNF:ETRS89GEO, ETRS89 geographiques (dms), geographic 3D +- ESRI:104129, GCS_EUREF_FIN, geographic 2D + +So the 3 typical EPSG entries, 3 equivalent (with long, lat ordering for the +geographic CRS) and one from the ESRI registry; + +PROJ can now test 10 x 7 different combinations of source x target CRSs, using +the database searching method explained in the previous section. As soon as +one of this combination returns at least one non-ballpark combination, the result +set coming from that combination is used. PROJ will then add before that +transformation a conversion between the source CRS and the first intermediate CRS, +and will add at the end a conversion between the second intermediate CRS and the +target CRS. Those conversions are conversion between geographic 2D and geographic 3D +CRS or geographic 2D/3D and geocentric CRS. + +This is done by the :c:func:`createOperationsWithDatumPivot()` method. + +So if transforming between EPSG:7042, RGF93 (lon-lat), geographic 3D and +EPSG:4936, ETRS89, geocentric, one get the following concatenated operation, +chaining an axis order change, the null geocentric translation between +RGF93 and ETRS89 (EPSG:1591), and a conversion between geographic and geocentric +coordinates. This concatenated operation is assumed to have a perfect accuracy +as both the initial and final operations are conversions, and the middle transformation +accounts for the fact that the RGF93 datum is one realization of ETRS89, so they +are equivalent for most purposes. + +.. code-block:: shell + + $ projinfo -s EPSG:7042 -t EPSG:4936 + + Candidate operations found: 1 + ------------------------------------- + Operation No. 1: + + unknown id, axis order change (geographic3D horizontal) + RGF93 to ETRS89 (1) + Conversion from ETRS89 (geog2D) to ETRS89 (geocentric), 0 m, France + + PROJ string: + +proj=pipeline +step +proj=unitconvert +xy_in=deg +xy_out=rad +step +proj=cart +ellps=GRS80 + + WKT2:2019 string: + CONCATENATEDOPERATION["axis order change (geographic3D horizontal) + RGF93 to ETRS89 (1) + Conversion from ETRS89 (geog2D) to ETRS89 (geocentric)", + SOURCECRS[ + GEOGCRS["RGF93 (lon-lat)", + [...] + ID["EPSG",7042]]], + TARGETCRS[ + GEODCRS["ETRS89", + [...] + ID["EPSG",4936]]], + STEP[ + CONVERSION["axis order change (geographic3D horizontal)", + METHOD["Axis Order Reversal (Geographic3D horizontal)", + ID["EPSG",9844]], + ID["EPSG",15499]]], + STEP[ + COORDINATEOPERATION["RGF93 to ETRS89 (1)", + [...] + METHOD["Geocentric translations (geog2D domain)", + ID["EPSG",9603]], + PARAMETER["X-axis translation",0, + LENGTHUNIT["metre",1], + ID["EPSG",8605]], + PARAMETER["Y-axis translation",0, + LENGTHUNIT["metre",1], + ID["EPSG",8606]], + PARAMETER["Z-axis translation",0, + LENGTHUNIT["metre",1], + ID["EPSG",8607]], + OPERATIONACCURACY[0.0], + ID["EPSG",1591], + REMARK["May be taken as approximate transformation RGF93 to WGS 84 - see code 1671."]]], + STEP[ + CONVERSION["Conversion from ETRS89 (geog2D) to ETRS89 (geocentric)", + METHOD["Geographic/geocentric conversions", + ID["EPSG",9602]]]], + USAGE[ + SCOPE["unknown"], + AREA["France"], + BBOX[41.15,-9.86,51.56,10.38]]] + +Geodetic/geographic CRS to Geodetic/geographic CRS, without direct transformation +--------------------------------------------------------------------------------- + +Still considering transformations between geodetic/geographic CRS, but let's +consider that the lookup in the database for a transformation between +the source and target CRS (possibly going through the "equivalent" CRS based on +the same datum as detailed in the previous section) leads to an empty set. + +Of course, as most operations are invertible, one first tries to do a lookup switching +the source and target CRS, and inverting the resulting operation(s): + +.. code-block:: shell + + $ projinfo -s NAD83 -t NAD27 --spatial-test intersects --summary + + Candidate operations found: 10 + INVERSE(DERIVED_FROM(EPSG)):1312, Inverse of NAD27 to NAD83 (3), 2.0 m, Canada + INVERSE(DERIVED_FROM(EPSG)):1313, Inverse of NAD27 to NAD83 (4), 1.5 m, Canada - NAD27 + INVERSE(DERIVED_FROM(EPSG)):1241, Inverse of NAD27 to NAD83 (1), 0.15 m, USA - CONUS including EEZ + INVERSE(DERIVED_FROM(EPSG)):1243, Inverse of NAD27 to NAD83 (2), 0.5 m, USA - Alaska including EEZ + INVERSE(DERIVED_FROM(EPSG)):1573, Inverse of NAD27 to NAD83 (6), 1.5 m, Canada - Quebec, at least one grid missing + INVERSE(EPSG):1462, Inverse of NAD27 to NAD83 (5), 2.0 m, Canada - Quebec, at least one grid missing + INVERSE(EPSG):9111, Inverse of NAD27 to NAD83 (9), 1.5 m, Canada - Saskatchewan, at least one grid missing + unknown id, Ballpark geographic offset from NAD83 to NAD27, unknown accuracy, World, has ballpark transformation + INVERSE(EPSG):8555, Inverse of NAD27 to NAD83 (7), 0.15 m, USA - CONUS and GoM, at least one grid missing + INVERSE(EPSG):8549, Inverse of NAD27 to NAD83 (8), 0.5 m, USA - Alaska, at least one grid missing + +That was an easy case. Now let's consider the transformation between the Australian +CRS AGD84 and GDA2020. There is no direct transformation from AGD84 to GDA2020, or +in the reverse direction, even when considering alternative geodetic CRS based on +the underlying datums. PROJ will then do a cross-join in the coordinate_operation_view +table to find the tuples (op1, op2) of coordinate operations such that: + +- SOURCE_CRS = op1.source_crs AND op1.target_crs = op2.source_crs AND op2.target_crs = TARGET_CRS or +- SOURCE_CRS = op1.source_crs AND op1.target_crs = op2.target_crs AND op2.source_crs = TARGET_CRS or +- SOURCE_CRS = op1.target_crs AND op1.source_crs = op2.source_crs AND op2.target_crs = TARGET_CRS or +- SOURCE_CRS = op1.target_crs AND op1.source_crs = op2.target_crs AND op2.source_crs = TARGET_CRS + +Depending on which case is selected, op1 and op2 should be reversed, before +being concatenated. + +This logic is implement by the ``findsOpsInRegistryWithIntermediate()`` method. + +Assuming that the proj-datumgrid-oceania package is installed, we get the +following results for the AGD84 to GDA2020 coordinate operations lookup: + +.. code-block:: shell + + $ projinfo -s AGD84 -t GDA2020 --spatial-test intersects -o PROJ + + Candidate operations found: 4 + ------------------------------------- + Operation No. 1: + + unknown id, AGD84 to GDA94 (5) + GDA94 to GDA2020 (1), 0.11 m, Australia - AGD84 + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=hgridshift +grids=National_84_02_07_01.gsb \ + +step +proj=push +v_3 \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=0.06155 +y=-0.01087 +z=-0.04019 \ + +rx=-0.0394924 +ry=-0.0327221 +rz=-0.0328979 \ + +s=-0.009994 +convention=coordinate_frame \ + +step +inv +proj=cart +ellps=GRS80 \ + +step +proj=pop +v_3 \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + + ------------------------------------- + Operation No. 2: + + unknown id, AGD84 to GDA94 (2) + GDA94 to GDA2020 (1), 1.01 m, Australia - AGD84 + + 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=aust_SA \ + +step +proj=helmert +x=-117.763 +y=-51.51 +z=139.061 \ + +rx=-0.292 +ry=-0.443 +rz=-0.277 +s=-0.191 \ + +convention=coordinate_frame \ + +step +proj=helmert +x=0.06155 +y=-0.01087 +z=-0.04019 \ + +rx=-0.0394924 +ry=-0.0327221 +rz=-0.0328979 \ + +s=-0.009994 +convention=coordinate_frame \ + +step +inv +proj=cart +ellps=GRS80 \ + +step +proj=pop +v_3 \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + + ------------------------------------- + Operation No. 3: + + unknown id, AGD84 to GDA94 (5) + GDA94 to GDA2020 (2), 0.15 m, unknown domain of validity + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=hgridshift +grids=National_84_02_07_01.gsb \ + +step +proj=hgridshift +grids=GDA94_GDA2020_conformal_and_distortion.gsb \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + + ------------------------------------- + Operation No. 4: + + unknown id, AGD84 to GDA94 (5) + GDA94 to GDA2020 (3), 0.15 m, unknown domain of validity + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=hgridshift +grids=National_84_02_07_01.gsb \ + +step +proj=hgridshift +grids=GDA94_GDA2020_conformal.gsb \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + +One can see that the selected intermediate CRS that has been used is GDA94. +This is a completely novel behavior of PROJ 6 as opposed to the logic of PROJ.4 +where datum transformations implied using EPSG:4326 / WGS 84 has the mandatory +datum hub. PROJ 6 no longer hardcodes it as the mandatory datum hub, and relies +on the database to find the appropriate hub(s). +Actually, WGS 84 has been considered during the above lookup, because there are +transformations between AGD84 and WGS 84 and WGS 84 and GDA2020. However those +have been discarded in a step which we did not mention previously: just after +the initial filtering of results and their sorting, there is a final filtering +that is done. In the list of sorted results, given two operations A and B that +have the same area of use, if B has an accuracy lower than A, and A does not use +grids, or all the needed grids are available, then B is discarded. + +If one forces the datum hub to be considered to be EPSG:4326, ones gets: + +.. code-block:: shell + + $ projinfo -s AGD84 -t GDA2020 --spatial-test intersects --pivot-crs EPSG:4326 -o PROJ + + Candidate operations found: 2 + ------------------------------------- + Operation No. 1: + + unknown id, AGD84 to WGS 84 (7) + Inverse of GDA2020 to WGS 84 (2), 4 m, Australia - AGD84 + + 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=aust_SA \ + +step +proj=helmert +x=-117.763 +y=-51.51 +z=139.061 \ + +rx=-0.292 +ry=-0.443 +rz=-0.277 \ + +s=-0.191 +convention=coordinate_frame \ + +step +inv +proj=cart +ellps=GRS80 \ + +step +proj=pop +v_3 \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + + ------------------------------------- + Operation No. 2: + + unknown id, AGD84 to WGS 84 (9) + Inverse of GDA2020 to WGS 84 (2), 4 m, Australia - AGD84 + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=hgridshift +grids=National_84_02_07_01.gsb \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + +Those operations are less accurate, since WGS 84 is assumed to be equivalent to +GDA2020 with an accuracy of 4 metre. This is an instance demonstrating that using +WGS 84 as a hub systematically can be sub-optimal. + +There are still situations where the attempt to find a hub CRS does not work, +because there is no such hub. This can occur for example when transforming from +GDA94 to the latest realization at time of writing of WGS 84, WGS 84 (G1762). +There are transformations between WGS 84 (G1762). Using the above described +techniques, we would only find one non-ballpark operation taking the route: +1. Conversion from GDA94 (geog2D) to GDA94 (geocentric): synthetized by PROJ +2. Inverse of ITRF2008 to GDA94 (1): from EPSG +3. Inverse of WGS 84 (G1762) to ITRF2008 (1): from EPSG +4. Conversion from WGS 84 (G1762) (geocentric) to WGS 84 (G1762): synthetized by PROJ + +This is not bad, but the global validity area of use is "Australia - onshore and EEZ", +whereas GDA94 has a larger area of use. +There is another road that can be taken by going through GDA2020 instead of ITRF2008. +The GDA94 to GDA2020 transformations operate on the respective geographic CRS, +whereas GDA2020 to WGS 84 (G1762) operate on the geocentric CRS. Consequently, +GDA2020 cannot be identifier as a hub by a "simple" self-join SQL request on +the coordinate operation table. This requires to do the join based on the datum +referenced by the source and target CRS of each operation rather than the +source and target CRS themselves. When there is a match, PROJ inserts the required +conversions between geographic and geocentric CRS to have a consistent concatenated +operation, like the following: +1. GDA94 to GDA2020 (1): from EPSG +2. Conversion from GDA2020 (geog2D) to GDA2020 (geocentric): synthetized by PROJ +3. GDA2020 to WGS 84 (G1762) (1): from EPSG +4. Conversion from WGS 84 (G1762) (geocentric) to WGS 84 (G1762) (geog2D): synthetized by PROJ + +Projected CRS to any target CRS +--------------------------------------------------------------------------------- + +This actually extends to any Derived CRS, whose Projected CRS is a well-known +particular case. Such transformations are done in 2 steps: + +1. Use the inverse conversion of the derived CRS to its base CRS, typically an + inverse map projection. +2. Find transformations from this base CRS to the target CRS. If the base CRS + is the target CRS, this step can be skipped. + +.. code-block:: shell + + $ projinfo -s EPSG:32631 -t RGF93 + + Candidate operations found: 1 + ------------------------------------- + Operation No. 1: + + unknown id, Inverse of UTM zone 31N + Inverse of RGF93 to WGS 84 (1), 1 m, France + + PROJ string: + +proj=pipeline +step +inv +proj=utm +zone=31 +ellps=WGS84 +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1 + +This is implemented by the ``createOperationsDerivedTo`` method + +For the symmetric case, source CRS to a derived CRS, the above algorithm is applied +by switching the source and target CRS, and then inverting the resulting operation(s). +This is mostly a matter of avoiding to write very similar code twice. This logic +is also applied to all below cases when considering the transformation between 2 different +types of objects. + +.. _verttogeog: + +Vertical CRS to a Geographic CRS +--------------------------------------------------------------------------------- + +Such transformation is normally not meant as being used as standalone by PROJ +users, but as an internal computation step of a Compound CRS to a target CRS. + +In cases where we are lucky, the PROJ database will have a transformation registered +between those: + +.. code-block:: shell + + $ projinfo -s "NAVD88 height" -t "NAD83(2011)" -o PROJ --spatial-test intersects + Candidate operations found: 11 + ------------------------------------- + Operation No. 1: + + INVERSE(DERIVED_FROM(EPSG)):9229, Inverse of NAD83(2011) to NAVD88 height (3), 0.015 m, USA - CONUS - onshore + + PROJ string: + +proj=vgridshift +grids=g2018u0.gtx +multiplier=1 + + +But in cases where there is no match, the ``createOperationsVertToGeog`` method +will be used to synthetize a ballpark vertical transformation, just taking care +of unit changes, and axis reversal in case the vertical CRS was a depth rather than +a height. Of course the results of such an operation are questionable, hence the +ballpark qualifier and a unknown accuracy advertized for such an operation. + +Vertical CRS to a Vertical CRS +--------------------------------------------------------------------------------- + +Overall logic is similar to the above case. There might be direct operations in +the PROJ database, involving grid transformations or simple offsets. The fallback +case is to synthetize a ballpark transformation. + +This is implemented by the ``createOperationsVertToVert`` method + +.. code-block:: shell + + $ projinfo -s "NGVD29 depth (ftUS)" -t "NAVD88 height" --spatial-test intersects -o PROJ + + Candidate operations found: 3 + ------------------------------------- + Operation No. 1: + + unknown id, Inverse of NGVD29 height (ftUS) to NGVD29 depth (ftUS) + NGVD29 height (ftUS) to NGVD29 height (m) + NGVD29 height (m) to NAVD88 height (3), 0.02 m, USA - CONUS east of 89°W - onshore + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=1,2,-3 +step +proj=unitconvert +z_in=us-ft +z_out=m +step +proj=vgridshift +grids=vertcone.gtx +multiplier=0.001 + + ------------------------------------- + Operation No. 2: + + unknown id, Inverse of NGVD29 height (ftUS) to NGVD29 depth (ftUS) + NGVD29 height (ftUS) to NGVD29 height (m) + NGVD29 height (m) to NAVD88 height (2), 0.02 m, USA - CONUS 89°W-107°W - onshore + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=1,2,-3 +step +proj=unitconvert +z_in=us-ft +z_out=m +step +proj=vgridshift +grids=vertconc.gtx +multiplier=0.001 + + ------------------------------------- + Operation No. 3: + + unknown id, Inverse of NGVD29 height (ftUS) to NGVD29 depth (ftUS) + NGVD29 height (ftUS) to NGVD29 height (m) + NGVD29 height (m) to NAVD88 height (1), 0.02 m, USA - CONUS west of 107°W - onshore + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=1,2,-3 +step +proj=unitconvert +z_in=us-ft +z_out=m +step +proj=vgridshift +grids=vertconw.gtx +multiplier=0.001 + + +Compound CRS to a Geographic CRS +--------------------------------------------------------------------------------- + +A typical example of a Compound CRS is a CRS made of a geographic or projected CRS +as the horizontal component, and a vertical CRS. E.g. "NAD83 + NAVD88 height" + +When the horizontal component of the compound source CRS is a projected CRS, we +first look for the operation from this source CRS to another compound CRS made +of the geographic CRS base of the projected CRS, +like "NAD83 / California zone 1 (ftUS) + NAVD88 height" to "NAD83 + NAVD88 height", +which ultimately goes to one of the above described case. Then we can consider +the transformation from a compound CRS made of a geographic CRS to another geographic CRS. + +It first starts by the vertical transformations from the vertical CRS of the +source compound CRS to the target geographic CRS, using the strategy detailed +in :ref:`Vertical CRS to a Geographic CRS <verttogeog>` + +What we did not mention is that when there is not a transformation registered +between the vertical CRS and the target geographic CRS, PROJ attempts to find +transformations between that vertical CRS and any other geographic CRS. This is +clearly an approximation. +If the research of the vertical CRS to the target geographic CRS resulted in +operations that use grids that are not available, as another approximation, we +research operations from the vertical CRS to the source geographic CRS for the +vertical component. + +Once we got those more or less accurate vertical transformations, we must consider +the horizontal transformation(s). The algorithm iterates over all found vertical +transformations and look for their target geographic CRS. This will be used as +the interpolation CRS for horizontal transformations. PROJ will then look for +available transformations from the source geographic CRS to the interpolation CRS +and from the interpolation CRS to the target geographic CRS. There is then a +3-level loop to create the final set of operations chaining together: + +- the horizontal transformation from the source geographic CRS to the interpolation CRS +- the vertical transformation from the source vertical CRS to the interpolation CRS +- the horizontal transformation from the interpolation CRS to the target geographic CRS. + +This is implemented by the ``createOperationsCompoundToGeog`` method + +Example: + +.. code-block:: shell + + $ projinfo -s "NAD83(NSRS2007) + NAVD88 height" -t "WGS 84 (G1762)" --spatial-test intersects --summary + + Candidate operations found: 21 + unknown id, Inverse of NAD83(NSRS2007) to NAVD88 height (1) + NAD83(NSRS2007) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.05 m, USA - CONUS - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (7) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, 95°W to 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (7) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, 95°W to 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (6) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, 112°W to 95°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (6) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, 112°W to 95°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (2) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, 112°W to 95°W + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (2) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, 112°W to 95°W + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (3) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, 95°W to 78°W + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (3) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, 95°W to 78°W + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (5) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, west of 112°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (5) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, west of 112°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (1) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, west of 112°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (1) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, west of 112°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (4) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, east of 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (4) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, east of 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (8) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, east of 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (8) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, east of 78°W - onshore + unknown id, Ballpark geographic offset from NAD83(NSRS2007) to NAD83(FBN) + Inverse of NAD83(FBN) to NAVD88 height (1) + Ballpark geographic offset from NAD83(FBN) to WGS 84 (G1762), unknown accuracy, USA - CONUS - onshore, has ballpark transformation + unknown id, Ballpark geographic offset from NAD83(NSRS2007) to NAD83(2011) + Inverse of NAD83(2011) to NAVD88 height (3) + Ballpark geographic offset from NAD83(2011) to WGS 84 (G1762), unknown accuracy, USA - CONUS - onshore, has ballpark transformation + unknown id, Ballpark geographic offset from NAD83(NSRS2007) to NAD83(2011) + Inverse of NAD83(2011) to NAVD88 height (3) + Conversion from NAD83(2011) (geog2D) to NAD83(2011) (geocentric) + Inverse of ITRF2008 to NAD83(2011) (1) + Inverse of WGS 84 (G1762) to ITRF2008 (1) + Conversion from WGS 84 (G1762) (geocentric) to WGS 84 (G1762) (geog2D), unknown accuracy, USA - CONUS - onshore, has ballpark transformation + unknown id, NAD83(NSRS2007) to WGS 84 (1) + WGS 84 to WGS 84 (G1762) + Transformation from NAVD88 height to WGS 84 (G1762) (ballpark vertical transformation, without ellipsoid height to vertical height correction), unknown accuracy, USA - CONUS and Alaska; PRVI, has ballpark transformation + + +CompoundCRS to CompoundCRS +--------------------------------------------------------------------------------- + +There is some similarity with the previous paragraph. We first research the +vertical transformations between the two vertical CRS. + +1. If there is such a transformation, be it direct, or if both vertical CRS + relate to a common intermediate CRS. + If it has a registered interpolation geographic CRS, then it is used. + Otherwise we fallback to the geographic CRS of the source CRS. + + Finally, a 3-level loop to create the final set of operations chaining together: + + - the horizontal transformation from the source CRS to the interpolation CRS + - the vertical transformation + - the horizontal transformation from the interpolation CRS to the target CRS. + + Example: + + .. code-block:: shell + + $ projinfo -s "NAD27 + NGVD29 height (ftUS)" -t "NAD83 + NAVD88 height" --spatial-test intersects --summary + + Candidate operations found: 20 + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + NAD27 to NAD83 (1), 0.17 m, USA - CONUS east of 89°W - onshore + unknown id, NGVD29 height (ftUS) to NAVD88 height (2) + NAD27 to NAD83 (1), 0.17 m, USA - CONUS 89°W-107°W - onshore + unknown id, NGVD29 height (ftUS) to NAVD88 height (1) + NAD27 to NAD83 (1), 0.17 m, USA - CONUS west of 107°W - onshore + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + NAD27 to NAD83 (3), 1.02 m, unknown domain of validity + unknown id, NGVD29 height (ftUS) to NAVD88 height (2) + NAD27 to NAD83 (3), 1.02 m, unknown domain of validity + unknown id, NGVD29 height (ftUS) to NAVD88 height (1) + NAD27 to NAD83 (3), 1.02 m, unknown domain of validity + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + NAD27 to NAD83 (5), 1.02 m, unknown domain of validity, at least one grid missing + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + NAD27 to NAD83 (6), 1.52 m, unknown domain of validity, at least one grid missing + unknown id, NGVD29 height (ftUS) to NAVD88 height (2) + NAD27 to NAD83 (9), 1.52 m, unknown domain of validity, at least one grid missing + unknown id, NGVD29 height (ftUS) to NAVD88 height (1) + NAD27 to NAD83 (9), 1.52 m, unknown domain of validity, at least one grid missing + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, USA - CONUS east of 89°W - onshore, has ballpark transformation + unknown id, NGVD29 height (ftUS) to NAVD88 height (2) + Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, USA - CONUS 89°W-107°W - onshore, has ballpark transformation + unknown id, NGVD29 height (ftUS) to NAVD88 height (1) + Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, USA - CONUS west of 107°W - onshore, has ballpark transformation + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (1), unknown accuracy, USA - CONUS including EEZ, has ballpark transformation + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (3), unknown accuracy, Canada, has ballpark transformation + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (4), unknown accuracy, Canada - NAD27, has ballpark transformation + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (5), unknown accuracy, Canada - Quebec, has ballpark transformation, at least one grid missing + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (6), unknown accuracy, Canada - Quebec, has ballpark transformation, at least one grid missing + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (9), unknown accuracy, Canada - Saskatchewan, has ballpark transformation, at least one grid missing + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, World, has ballpark transformation + + +2. Otherwise, when there is no such transformation, we decompose into 3 steps: + + - transform from the source CRS to the geographic 3D CRS corresponding to it + - transform from the geographic 3D CRS corresponding to the source CRS to the + geographic 3D CRS corresponding to the target CRS + - transform from the geographic 3D CRS corresponding to the target CRS to the + target CRS. + + Example: + + .. code-block:: shell + + $ projinfo -s "WGS 84 + EGM96 height" -t "ETRS89 + Belfast height" --spatial-test intersects --summary + + Candidate operations found: 7 + unknown id, Inverse of WGS 84 to EGM96 height (1) + Inverse of ETRS89 to WGS 84 (1) + ETRS89 to Belfast height (2), 2.014 m, UK - Northern Ireland - onshore + unknown id, Inverse of WGS 84 to EGM96 height (1) + Inverse of ETRS89 to WGS 84 (1) + ETRS89 to Belfast height (1), 2.03 m, UK - Northern Ireland - onshore, at least one grid missing + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of OSGB 1936 to WGS 84 (4) + OSGB 1936 to ETRS89 (2) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (2), 19.044 m, unknown domain of validity + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of OSGB 1936 to WGS 84 (2) + OSGB 1936 to ETRS89 (2) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (2), 11.044 m, unknown domain of validity + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of TM75 to WGS 84 (2) + TM75 to ETRS89 (3) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (2), 2.424 m, UK - Northern Ireland - onshore, at least one grid missing + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of TM75 to WGS 84 (2) + TM75 to ETRS89 (3) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (1), 2.44 m, UK - Northern Ireland - onshore, at least one grid missing + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of OSGB 1936 to WGS 84 (4) + OSGB 1936 to ETRS89 (2) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (1), 19.06 m, unknown domain of validity, at least one grid missing + + +This is implemented by the ``createOperationsCompoundToCompound`` method + +When the source or target CRS is a BoundCRS +--------------------------------------------------------------------------------- + +The BoundCRS concept is an hybrid concept where a CRS is linked to a transformation +from it to a hub CRS, typically WGS 84. This is a long-time practice in PROJ.4 +strings with the ``+towgs84``, ``+nadgrids`` and ``+geoidgrids`` keywords, or the +``TOWGS84[]`` node of WKT 1. When encountering those attributes when parsing +a CRS string, PROJ will create a BoundCRS object capturing this transformation. +A BoundCRS object can also be provided with a WKT2 string, and in that case with +a hub CRS being potentially different from WGS 84. + +Let's consider the case of a transformation between a BoundCRS +("+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 ++ellps=airy +towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489 +units=m" +which used to be the PROJ.4 definition of "OSGB 1936 / British National Grid") +and a target Geographic CRS, ETRS89. + +We apply the following steps: + +- transform from the base of the source CRS (that is the CRS wrapped by BoundCRS, + here a ProjectedCRS) to the geographic CRS of this base CRS +- apply the transformation of the BoundCRS to go from the geographic CRS of this base CRS + to the hub CRS of the BoundCRS, in that instance WGS 84. +- apply a transformation from the hub CRS to the target CRS. + +This is implemented by the ``createOperationsBoundToGeog`` method + +Example: + +.. code-block:: shell + + $ projinfo -s "+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489 +units=m +type=crs" -t ETRS89 -o PROJ + + Candidate operations found: 1 + ------------------------------------- + Operation No. 1: + + unknown id, Inverse of unknown + Transformation from unknown to WGS84 + Inverse of ETRS89 to WGS 84 (1), unknown accuracy, Europe - ETRS89 + + PROJ string: + +proj=pipeline +step +inv +proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +step +proj=push +v_3 +step +proj=cart +ellps=airy +step +proj=helmert +x=446.448 +y=-125.157 +z=542.06 +rx=0.15 +ry=0.247 +rz=0.842 +s=-20.489 +convention=position_vector +step +inv +proj=cart +ellps=GRS80 +step +proj=pop +v_3 +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1 + +There are other situations with BoundCRS, involving vertical transformations, +or transforming to other objects than a geographic CRS, but the curious reader +will have to inspect the code for the actual gory details. diff --git a/_sources/operations/pipeline.rst.txt b/_sources/operations/pipeline.rst.txt new file mode 100644 index 00000000..97b58e3e --- /dev/null +++ b/_sources/operations/pipeline.rst.txt @@ -0,0 +1,161 @@ +.. _pipeline: + +================================================================================ +The pipeline operator +================================================================================ + +.. versionadded:: 5.0.0 + +Construct complex operations by daisy-chaining operations in a sequential pipeline. + ++-----------------+--------------------------------------------------------------------+ +| **Alias** | pipeline | ++-----------------+--------------------------------------------------------------------+ +| **Domain** | 2D, 3D and 4D | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Any | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Any | ++-----------------+--------------------------------------------------------------------+ + +.. note:: See the section on :ref:`transformation` for a more thorough introduction + to the concept of transformation pipelines in PROJ. + + +With the pipeline operation it is possible to perform several operations after each +other on the same input data. This feature makes it possible to create transformations +that are made up of more than one operation, e.g. performing a datum shift and then +applying a suitable map projection. Theoretically any transformation between two +coordinate reference systems is possible to perform using the pipeline operation, +provided that the necessary coordinate operations in each step is available in PROJ. + +A pipeline is made up of a number of steps, with each step being a coordinate operation +in itself. By connecting these individual steps sequentially we end up with a concatenated +coordinate operation. An example of this is a transformation from geodetic coordinates +on the GRS80 ellipsoid to a projected system where the east-west and north-east axes has +been swapped: + +:: + + +proj=pipeline +ellps=GRS80 +step +proj=merc +step +proj=axisswap +order=2,1 + +Here the first step is applying the :ref:`merc` projection and the second step is +applying the :ref:`axisswap` conversion. Note that the `+ellps=GRS80` is specified +before the first occurrence of `+step`. This means that the GRS80 ellipsoid is used +in both steps, since any parameter stated before the first occurrence of `+step` is +treated as a global parameter and is transferred to each individual steps. + + +Rules for pipelines +------------------------------------------------------------------------------- + +**1. Pipelines must consist of at least one step.** + +:: + + +proj=pipeline + +Will result in an error. + +**2. Pipelines can only be nested if the nested pipeline is defined in an init file.** + +:: + + +proj=pipeline + +step +proj=pipeline +step +proj=merc +step +proj=axisswap +order=2,1 + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +Results in an error, while + +:: + + +proj=pipeline + +step +init=predefined_pipelines:projectandswap + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +does not. + +**3. Pipelines without a forward path can't be constructed.** + +:: + + +proj=pipeline +step +inv +proj=urm5 + +Will result in an error since :ref:`urm5` does not have an inverse operation defined. + +.. _global-pipeline-parameter: + +**4. Parameters added before the first `+step` are global and will be applied to all steps.** + +In the following the GRS80 ellipsoid will be applied to all steps. + +:: + + +proj=pipeline +ellps=GRS80 + +step +proj=cart + +step +proj=helmert +x=10 +y=3 +z=1 + +step +proj=cart +inv + +step +proj=merc + +**5. Units of operations must match between steps.** + +.. versionadded:: 5.1.0 + +The output units of step *n* must match the expected input unit of step *n+1*. E.g., you can't +pass an operation that outputs projected coordinates to an operation that expects angular units +(degrees). An example of such a unit mismatch is displayed below. + +:: + + +proj=pipeline + +step +proj=merc # Mercator outputs projected coordinates + +step +proj=robin # The Robinson projection expects angular input + +Parameters +------------------------------------------------------------------------------- + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +step + + Separate each step in a pipeline. + + +Optional ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +inv + + Invert a step in a pipeline. + +.. option:: +omit_fwd + + .. versionadded:: 6.3.0 + + Skip a step of the pipeline when it is followed in the forward path. + + The following example shows a combined use of :ref:`push <push>` and :ref:`pop <pop>` operators, + with ``omit_fwd`` and ``omit_inv`` options, to implement a vertical adjustment that must + be done in a interpolation CRS that is different from the horizontal CRS + used in input and output. +omit_fwd in the forward path avoid a useless + inverse horizontal transformation and relies on the pop operator to restore + initial horizontal coordinates. +omit_inv serves the similar purpose when + the pipeline is executed in the reverse direction + + :: + + +proj=pipeline + +step +proj=unitconvert +xy_in=deg +xy_out=rad + +step +proj=push +v_1 +v_2 + +step +proj=hgridshift +grids=nvhpgn.gsb +omit_inv + +step +proj=vgridshift +grids=g1999u05.gtx +multiplier=1 + +step +inv +proj=hgridshift +grids=nvhpgn.gsb +omit_fwd + +step +proj=pop +v_1 +v_2 + +step +proj=unitconvert +xy_in=rad +xy_out=deg + +.. option:: +omit_inv + + .. versionadded:: 6.3.0 + + Skip a step of the pipeline when it is followed in the reverse path. diff --git a/_sources/operations/projections/adams_hemi.rst.txt b/_sources/operations/projections/adams_hemi.rst.txt new file mode 100644 index 00000000..96fe78f1 --- /dev/null +++ b/_sources/operations/projections/adams_hemi.rst.txt @@ -0,0 +1,42 @@ +.. _adams_hemi: + +******************************************************************************** +Adams Hemisphere in a Square +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | adams_hemi | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/adams_hemi.png + :width: 500 px + :align: center + :alt: Adams Hemisphere in a Square + + proj-string: ``+proj=adams_hemi`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/adams_ws1.rst.txt b/_sources/operations/projections/adams_ws1.rst.txt new file mode 100644 index 00000000..3283ff57 --- /dev/null +++ b/_sources/operations/projections/adams_ws1.rst.txt @@ -0,0 +1,42 @@ +.. _adams_ws1: + +******************************************************************************** +Adams World in a Square I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | adams_ws1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/adams_ws1.png + :width: 500 px + :align: center + :alt: Adams World in a Square I + + proj-string: ``+proj=adams_ws1`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/adams_ws2.rst.txt b/_sources/operations/projections/adams_ws2.rst.txt new file mode 100644 index 00000000..60630286 --- /dev/null +++ b/_sources/operations/projections/adams_ws2.rst.txt @@ -0,0 +1,42 @@ +.. _adams_ws2: + +******************************************************************************** +Adams World in a Square II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | adams_ws2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/adams_ws2.png + :width: 500 px + :align: center + :alt: Adams World in a Square II + + proj-string: ``+proj=adams_ws2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/aea.rst.txt b/_sources/operations/projections/aea.rst.txt new file mode 100644 index 00000000..47a24251 --- /dev/null +++ b/_sources/operations/projections/aea.rst.txt @@ -0,0 +1,52 @@ +.. _aea: + +******************************************************************************** +Albers Equal Area +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | aea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/aea.png + :width: 500 px + :align: center + :alt: Albers Equal Area + + proj-string: ``+proj=aea +lat_1=29.5 +lat_2=42.5`` + +Options +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/aeqd.rst.txt b/_sources/operations/projections/aeqd.rst.txt new file mode 100644 index 00000000..3c5566ec --- /dev/null +++ b/_sources/operations/projections/aeqd.rst.txt @@ -0,0 +1,49 @@ +.. _aeqd: + +******************************************************************************** +Azimuthal Equidistant +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Alias** | aeqd | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/aeqd.png + :width: 500 px + :align: center + :alt: Azimuthal Equidistant + + proj-string: ``+proj=aeqd`` + + +Options +################################################################################ + +.. note:: All options are optional for the Azimuthal Equidistant projection. + +.. option:: +guam + + Use Guam ellipsoidal formulas. Only accurate near the Island of Guam + (:math:`\lambda\approx 144.5^{\circ}`, :math:`\phi\approx 13.5^{\circ}`) + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst diff --git a/_sources/operations/projections/airy.rst.txt b/_sources/operations/projections/airy.rst.txt new file mode 100644 index 00000000..04af065e --- /dev/null +++ b/_sources/operations/projections/airy.rst.txt @@ -0,0 +1,58 @@ +.. _airy: + +******************************************************************************** +Airy +******************************************************************************** + +The Airy projection is an azimuthal minimum error projection for the region +within the small or great circle defined by an angular distance, +:math:`\phi_b`, from the tangency point of the plane :math:`( \lambda_0, \phi_0 )`. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | airy | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. figure:: ./images/airy.png + :width: 500 px + :align: center + :alt: Airy + + proj-string: ``+proj=airy`` + +Options +################################################################################ + +.. option:: +lat_b + + Angular distance from tangency point of the plane :math:`( \lambda_0, \phi_0 )` + where the error is kept at minimum. + + *Defaults to 90° (suitable for hemispherical maps).* + +.. option:: +no_cut + + Do not cut at hemisphere limit + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/R.rst diff --git a/_sources/operations/projections/aitoff.rst.txt b/_sources/operations/projections/aitoff.rst.txt new file mode 100644 index 00000000..7508445d --- /dev/null +++ b/_sources/operations/projections/aitoff.rst.txt @@ -0,0 +1,40 @@ +.. _aitoff: + +******************************************************************************** +Aitoff +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | aitoff | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/aitoff.png + :width: 500 px + :align: center + :alt: Aitoff + + proj-string: ``+proj=aitoff`` + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/alsk.rst.txt b/_sources/operations/projections/alsk.rst.txt new file mode 100644 index 00000000..5c2b416f --- /dev/null +++ b/_sources/operations/projections/alsk.rst.txt @@ -0,0 +1,39 @@ +.. _alsk: + +******************************************************************************** +Modified Stereographic of Alaska +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Modified azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Alaska | ++---------------------+----------------------------------------------------------+ +| **Alsk** | alsk | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/alsk.png + :width: 500 px + :align: center + :alt: Modified Stereographic of Alaska + + proj-string: ``+proj=alsk`` + +Options +################################################################################ + +.. note:: All options are optional for the projection. + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst diff --git a/_sources/operations/projections/apian.rst.txt b/_sources/operations/projections/apian.rst.txt new file mode 100644 index 00000000..870dc0ce --- /dev/null +++ b/_sources/operations/projections/apian.rst.txt @@ -0,0 +1,44 @@ +.. _apian: + +******************************************************************************** +Apian Globular I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | apian | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/apian.png + :width: 500 px + :align: center + :alt: Apian Globular I + + proj-string: ``+proj=apian`` + +Options +################################################################################ + +.. note:: All options are optional for the Apian Globular projection. + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/august.rst.txt b/_sources/operations/projections/august.rst.txt new file mode 100644 index 00000000..ae5c95dc --- /dev/null +++ b/_sources/operations/projections/august.rst.txt @@ -0,0 +1,42 @@ +.. _august: + +******************************************************************************** +August Epicycloidal +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | august | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/august.png + :width: 500 px + :align: center + :alt: August Epicycloidal + + proj-string: ``+proj=august`` + +Parameters +################################################################################ + +.. note:: All options are optional for the August Epicycloidal projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/bacon.rst.txt b/_sources/operations/projections/bacon.rst.txt new file mode 100644 index 00000000..8e2fda9e --- /dev/null +++ b/_sources/operations/projections/bacon.rst.txt @@ -0,0 +1,42 @@ +.. _bacon: + +******************************************************************************** +Bacon Globular +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | bacon | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/bacon.png + :width: 500 px + :align: center + :alt: Bacon Globular + + proj-string: ``+proj=bacon`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Bacon Globular projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/bertin1953.rst.txt b/_sources/operations/projections/bertin1953.rst.txt new file mode 100644 index 00000000..65afcf62 --- /dev/null +++ b/_sources/operations/projections/bertin1953.rst.txt @@ -0,0 +1,64 @@ +.. _bertin1953: + +******************************************************************************** +Bertin 1953 +******************************************************************************** + +.. versionadded:: 6.0.0 + ++---------------------+-------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+-------------------------------+ +| **Available forms** | Forward, spherical projection | ++---------------------+-------------------------------+ +| **Defined area** | Global | ++---------------------+-------------------------------+ +| **Alias** | bertin1953 | ++---------------------+-------------------------------+ +| **Domain** | 2D | ++---------------------+-------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+-------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+-------------------------------+ + + + +.. figure:: ./images/bertin1953.png + :width: 500 px + :align: center + :alt: Bertin 1953 + + proj-string: ``+proj=bertin1953`` + + +The Bertin 1953 projection is intended for making world maps. Created by Jacques Bertin +in 1953, this projection was the go-to choice of the French cartographic school when they +wished to represent phenomena on a global scale. The projection was formulated in 2017 +by Philippe Rivière for visionscarto.net. + + +Usage +############################################################################### + +The Bertin 1953 projection has no special options. Its rotation parameters +are fixed. Here is an example of a forward projection with scale 1:: + + $ echo 122 47 | src/proj +proj=bertin1953 +R=1 + 0.72 0.73 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. Philippe Rivière (2017). `Bertin Projection (1953) <https://visionscarto.net/bertin-projection-1953>`, Visionscarto.net. diff --git a/_sources/operations/projections/bipc.rst.txt b/_sources/operations/projections/bipc.rst.txt new file mode 100644 index 00000000..9ac73750 --- /dev/null +++ b/_sources/operations/projections/bipc.rst.txt @@ -0,0 +1,46 @@ +.. _bipc: + +******************************************************************************** +Bipolar conic of western hemisphere +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | bipc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/bipc.png + :width: 500 px + :align: center + :alt: Bipolar conic of western hemisphere + + proj-string: ``+proj=bipc +ns`` + +Parameters +################################################################################ + +.. note:: All options are optional for the Bipolar Conic projection. + +.. option:: +ns + + Return non-skewed cartesian coordinates. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/boggs.rst.txt b/_sources/operations/projections/boggs.rst.txt new file mode 100644 index 00000000..82f43733 --- /dev/null +++ b/_sources/operations/projections/boggs.rst.txt @@ -0,0 +1,42 @@ +.. _boggs: + +******************************************************************************** +Boggs Eumorphic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | boggs | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/boggs.png + :width: 500 px + :align: center + :alt: Boggs Eumorphic + + proj-string: ``+proj=boggs`` + +Parameters +################################################################################ + +.. note:: All options are optional for the Boggs Eumorphic projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/bonne.rst.txt b/_sources/operations/projections/bonne.rst.txt new file mode 100644 index 00000000..1b81237b --- /dev/null +++ b/_sources/operations/projections/bonne.rst.txt @@ -0,0 +1,50 @@ +.. _bonne: + +******************************************************************************** +Bonne (Werner lat_1=90) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | bonne | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/bonne.png + :width: 500 px + :align: center + :alt: Bonne (Werner lat_1=90) + + proj-string: ``+proj=bonne +lat_1=10`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/calcofi.rst.txt b/_sources/operations/projections/calcofi.rst.txt new file mode 100644 index 00000000..829c5060 --- /dev/null +++ b/_sources/operations/projections/calcofi.rst.txt @@ -0,0 +1,107 @@ +.. _calcofi: + +******************************************************************************** +Cal Coop Ocean Fish Invest Lines/Stations +******************************************************************************** + +The CalCOFI pseudo-projection is the line and station coordinate system of the +California Cooperative Oceanic Fisheries Investigations program, known as CalCOFI, for sampling offshore of the west coast of the U.S. and Mexico. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Only valid for the west coast of USA and Mexico | ++---------------------+----------------------------------------------------------+ +| **Alias** | calcofi | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. image:: ../../../images/calcofi.png + :width: 500 px + :align: center + :alt: Cal Coop Ocean Fish Invest Lines/Stations + +The coordinate system is based on the Mercator projection with units rotated -30 +degrees from the meridian so that they are oriented with the coastline of the Southern California Bight and Baja California. +Lines increase from Northwest to Southeast. +A unit of line is 12 nautical miles. Stations increase from inshore to offshore. +A unit of station is equal to 4 nautical miles. +The rotation point is located at line 80, station 60, or 34.15 degrees N, -121.15 degrees W, and is depicted by the red dot in the figure. +By convention, the ellipsoid of Clarke 1866 is used to calculate CalCOFI coordinates. + +The CalCOFI program is a joint research effort by the U.S. National Oceanic and +Atmospheric Administration, University of California Scripps Oceanographic Institute, and California Department of Fish and Game. +Surveys have been conducted for the CalCOFI program since 1951, creating one of the oldest and most scientifically valuable joint oceanographic and fisheries data sets in the world. +The CalCOFI line and station coordinate system is now used by several other programs including the Investigaciones Mexicanas de la Corriente de California (IMECOCAL) program offshore of Baja California. +The figure depicts some commonly sampled locations from line 40 to line 156.7 and offshore to station 120. Blue numbers indicate line (bottom) or station (left) numbers along the grid. Note that lines spaced at approximate 3-1/3 intervals are commonly sampled, e.g., lines 43.3 and 46.7. + +Usage +############################################################################### + +A typical forward CalCOFI projection would be from lon/lat coordinates on the +Clark 1866 ellipsoid. +For example:: + + proj +proj=calcofi +ellps=clrk66 -E <<EOF + -121.15 34.15 + EOF + +Output of the above command:: + + -121.15 34.15 80.00 60.00 + +The reverse projection from line/station coordinates to lon/lat would be entered +as:: + + proj +proj=calcofi +ellps=clrk66 -I -E -f "%.2f" <<EOF + 80.0 60.0 + EOF + +Output of the above command:: + + 80.0 60.0 -121.15 34.15 + +Options +################################################################################ + +.. note:: All options are optional for the CalCOFI projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +Mathematical definition +################################################################################ + +The algorithm used to make conversions is described in :cite:`EberHewitt1979` with +a few corrections reported in :cite:`WeberMoore2013`. + + +Further reading +################################################################################ + +#. `General information about the CalCOFI program <http://www.calcofi.org>`_ +#. `The Investigaciones Mexicanas de la Corriente de California <http://imecocal.cicese.mx>`_ + + + + + + + + + + + + + + diff --git a/_sources/operations/projections/cass.rst.txt b/_sources/operations/projections/cass.rst.txt new file mode 100644 index 00000000..073fe6cc --- /dev/null +++ b/_sources/operations/projections/cass.rst.txt @@ -0,0 +1,172 @@ +.. _cass: + +******************************************************************************** +Cassini (Cassini-Soldner) +******************************************************************************** + +Although the Cassini projection has been largely replaced by the Transverse Mercator, it is still in limited use outside the United States and was one of the major topographic mapping projections until the early 20th century. + ++---------------------+-------------------------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+-------------------------------------------------------------------------+ +| **Available forms** | Forward and inverse, Spherical and ellipsoidal | ++---------------------+-------------------------------------------------------------------------+ +| **Defined area** | Global, but best used near the central meridian with long, narrow areas | ++---------------------+-------------------------------------------------------------------------+ +| **Alias** | cass | ++---------------------+-------------------------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+-------------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+-------------------------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+-------------------------------------------------------------------------+ + + +.. figure:: ./images/cass.png + :width: 500 px + :align: center + :alt: Cassini + + proj-string: ``+proj=cass`` + +Usage +##### + +There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini-Soldner version was adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century :cite:`Steers1970`. +Many of these maps were prepared at a scale of 1:2,500. +The Cassini-Soldner was also used for the detailed mapping of many German states during the same period. + + +Example using EPSG 30200 (Trinidad 1903, units in clarke's links):: + + $ echo 0.17453293 -1.08210414 | proj +proj=cass +lat_0=10.44166666666667 +lon_0=-61.33333333333334 +x_0=86501.46392051999 +y_0=65379.0134283 +a=6378293.645208759 +b=6356617.987679838 +to_meter=0.201166195164 + 66644.94 82536.22 + +Example using EPSG 3068 (Soldner Berlin):: + + $ echo 13.5 52.4 | proj +proj=cass +lat_0=52.41864827777778 +lon_0=13.62720366666667 +x_0=40000 +y_0=10000 +ellps=bessel +units=m + 31343.05 7932.76 + +Options +################################################################################ + +.. note:: All options are optional for the Cassini projection. + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. option:: +hyperbolic + + Use modified form of the standard Cassini-Soldner projection known as the Hyperbolic Cassini-Soldner. + This is used in particular for the "Vanua Levu Grid" of the island of Vanua Levu, Fiji (EPSG:3139) + + +Mathematical definition +####################### + +The formulas describing the Cassini projection are taken from :cite:`Snyder1987`. + +:math:`\phi_0` is the latitude of origin that match the center of the map (default to 0). It can be set with ``+lat_0``. + + +Spherical form +============== + +Forward projection +------------------ + +.. math:: + + x = \arcsin(\cos(\phi) \sin(\lambda)) + +.. math:: + + y = \arctan2(\tan(\phi), \cos(\lambda)) - \phi_0 + +Inverse projection +------------------ + +.. math:: + + \phi = \arcsin(\sin(y+\phi_0) \cos(x)) + +.. math:: + + \lambda = \arctan2(\tan(x), \cos(y+\phi_0)) + +Ellipsoidal form +================ + +Forward projection +------------------ + +.. math:: + + N = (1 - e^2 \sin^2(\phi))^{-1/2} + +.. math:: + + T = \tan^2(\phi) + +.. math:: + + A = \lambda \cos(\phi) + +.. math:: + + C = \frac{e^2}{1-e^2} cos^2(\phi) + +.. math:: + + x = N ( A - T \frac{A^3}{6} - (8-T+8C)T\frac{A^5}{120}) + +.. math:: + + y = M(\phi) - M(\phi_0) + N \tan(\phi)(\frac{A^2}{2} + (5-T+6C)\frac{A^4}{24}) + +and M() is the meridional distance function. + +Inverse projection +------------------ + +.. math:: + + \phi' = M^{-1}(M(\phi_0)+y) + +if :math:`\phi' = \frac{\pi}{2}` then :math:`\phi=\phi'` and :math:`\lambda=0` + +otherwise evaluate T and N above using :math:`\phi'` and + +.. math:: + + R = (1 - e^2)(1 - e^2 sin^2 \phi')^{-3/2} + +.. math:: + + D = x/N + +.. math:: + + \phi = \phi' - \tan \phi' \frac{N}{R}(\frac{D^2}{2}-(1+3T)\frac{D^4}{24}) + +.. math:: + + \lambda = \frac{(D - T\frac{D^3}{3} + (1+3T)T\frac{D^5}{15})}{\cos \phi'} + +.. _further-reading: + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Equirectangular_projection>`_ +#. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas <http://www.ihsenergy.com/epsg/guid7.pdf>`_ diff --git a/_sources/operations/projections/cc.rst.txt b/_sources/operations/projections/cc.rst.txt new file mode 100644 index 00000000..c6f3927a --- /dev/null +++ b/_sources/operations/projections/cc.rst.txt @@ -0,0 +1,42 @@ +.. _cc: + +******************************************************************************** +Central Cylindrical +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | cc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/cc.png + :width: 500 px + :align: center + :alt: Central Cylindrical + + proj-string: ``+proj=cc`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Central Cylindrical projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/ccon.rst.txt b/_sources/operations/projections/ccon.rst.txt new file mode 100644 index 00000000..949da8b5 --- /dev/null +++ b/_sources/operations/projections/ccon.rst.txt @@ -0,0 +1,159 @@ +.. _ccon: + +******************************************************************************** +Central Conic +******************************************************************************** + +.. versionadded:: 5.0.0 + +This is central (centrographic) projection on cone tangent at :option:``lat_1`` +latitude, identical with ``conic()`` projection from ``mapproj`` R package. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the standard parallel | ++---------------------+----------------------------------------------------------+ +| **Alias** | ccon | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/ccon.png + :width: 500 px + :align: center + :alt: Central Conic + + proj-string: ``+proj=ccon +lat_1=52 +lon_0=19`` + +Usage +######## + +This simple projection is rarely used, as it is not equidistant, equal-area, nor +conformal. + +An example of usage (and the main reason to implement this projection in proj4) +is the ATPOL geobotanical grid of Poland, developed in Institute of Botany, +Jagiellonian University, Krakow, Poland in 1970s :cite:`Zajac1978`. The grid was +originally handwritten on paper maps and further copied by hand. The projection +(together with strange Earth radius) was chosen by its creators as the compromise +fit to existing maps during first software development in DOS era. Many years later +it is still de facto standard grid in Polish geobotanical research. + +The ATPOL coordinates can be achieved with with the following parameters: + +:: + + +proj=ccon +lat_1=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000 + +For more information see :cite:`Komsta2016` and :cite:`Verey2017`. + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. option:: +lat_1=<value> + + Standard parallel of projection. + +Optional +------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + + +Mathematical definition +################################################################################ + + +Forward projection +------------------------------------------------------------------------------- + +.. math:: + + r = \cot \phi_0 - \tan (\phi - \phi_0) + +.. math:: + + x = r \sin (\lambda\sin\phi_0) + +.. math:: + + y = \cot \phi_0 - r \cos (\lambda\sin\phi_0) + + +Inverse projection +------------------------------------------------------------------------------- + +.. math:: + + y = \cot \phi_0 - y + +.. math:: + + \phi = \phi_0 - \tan^{-1} ( \sqrt{x^2+y^2} - \cot \phi_0 ) + +.. math:: + + \lambda = \frac{\tan^{-1} \sqrt{x^2+y^2}}{\sin \phi_0} + +Reference values +################################################################################ + +For ATPOL to WGS84 test, run the following script: + +:: + + #!/bin/bash + cat << EOF | src/cs2cs -v -f "%E" +proj=ccon +lat_1=52 +lat_0=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000 +to +proj=longlat + 0 0 + 0 700000 + 700000 0 + 700000 700000 + 330000 350000 + EOF + +It should result with + +:: + + 1.384023E+01 5.503040E+01 0.000000E+00 + 1.451445E+01 4.877385E+01 0.000000E+00 + 2.478271E+01 5.500352E+01 0.000000E+00 + 2.402761E+01 4.875048E+01 0.000000E+00 + 1.900000E+01 5.200000E+01 0.000000E+00 + +Analogous script can be run for reverse test: + +:: + + cat << EOF | src/cs2cs -v -f "%E" +proj=longlat +to +proj=ccon +lat_1=52 +lat_0=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000 + 24 55 + 15 49 + 24 49 + 19 52 + EOF + +and it should give the following results: + +:: + + 6.500315E+05 4.106162E+03 0.000000E+00 + 3.707419E+04 6.768262E+05 0.000000E+00 + 6.960534E+05 6.722946E+05 0.000000E+00 + 3.300000E+05 3.500000E+05 0.000000E+00 diff --git a/_sources/operations/projections/cea.rst.txt b/_sources/operations/projections/cea.rst.txt new file mode 100644 index 00000000..3f8af65f --- /dev/null +++ b/_sources/operations/projections/cea.rst.txt @@ -0,0 +1,79 @@ +.. _cea: + +******************************************************************************** +Equal Area Cylindrical +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | cea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/cea.png + :width: 500 px + :align: center + :alt: Equal Area Cylindrical + + proj-string: ``+proj=cea`` + +Named specializations +################################################################################ + +The Equal Area Cylindrical projection is sometimes known under other names when +it is instanciated with particular values of the ``lat_ts`` parameter: + ++----------------------------------+------------+ +| **Name** | **lat_ts** | ++----------------------------------+------------+ +| Lambert cylindrical equal-area | 0 | ++----------------------------------+------------+ +| Behrmann | 30 | ++----------------------------------+------------+ +| Gall-Peters | 45 | ++----------------------------------+------------+ + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Equal Area Cylindrical projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. note:: + + ``lat_ts`` and ``k_0`` are mutually exclusive. If ``lat_ts`` + is specified, it is equivalent to setting ``k_0`` to + :math:`\frac{\cos \phi_{ts}}{\sqrt{1 - e^2 \sin^2 \phi_{ts}}}` + +Further reading +############### + +#. `Wikipedia: Lambert cylindrical equal-area <https://en.wikipedia.org/wiki/Lambert_cylindrical_equal-area_projection>`_ + +#. `Wikipedia: Gall-Peters <https://en.wikipedia.org/wiki/Gall%E2%80%93Peters_projection>`_ + +#. `Wikipedia: Behrmann <https://en.wikipedia.org/wiki/Behrmann_projection>`_ diff --git a/_sources/operations/projections/chamb.rst.txt b/_sources/operations/projections/chamb.rst.txt new file mode 100644 index 00000000..c33017a5 --- /dev/null +++ b/_sources/operations/projections/chamb.rst.txt @@ -0,0 +1,72 @@ +.. _chamb: + +******************************************************************************** +Chamberlin Trimetric +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | chamb | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/chamb.png + :width: 500 px + :align: center + :alt: Chamberlin Trimetric + + proj-string: ``+proj=chamb +lat_1=10 +lon_1=30 +lon_2=40`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. note:: Control points should be oriented clockwise. + +.. option:: +lat_1=<value> + + Latitude of the first control point. + +.. option:: +lon_1=<value> + + Longitude of the first control point. + +.. option:: +lat_2=<value> + + Latitude of the second control point. + +.. option:: +lon_2=<value> + + Longitude of the second control point. + +.. option:: +lat_3=<value> + + Latitude of the third control point. + +.. option:: +lon_3=<value> + + Longitude of the third control point. + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/col_urban.rst.txt b/_sources/operations/projections/col_urban.rst.txt new file mode 100644 index 00000000..df2873dd --- /dev/null +++ b/_sources/operations/projections/col_urban.rst.txt @@ -0,0 +1,49 @@ +.. _col_urban: + +******************************************************************************** +Colombia Urban +******************************************************************************** + +.. versionadded:: 7.2 + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse ellipsoidal projection | ++---------------------+----------------------------------------------------------+ +| **Alias** | col_urban | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +From :cite:`IOGP2018`: + + The capital cites of each department in Colombia use an urban projection for large + scale topographic mapping of the urban areas. It is based on a plane through + the origin at an average height for the area, eliminating the need for corrections + to engineering survey observations. + + proj-string: ``+proj=col_urban`` + +Parameters +################################################################################ + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. option:: +h_0=<value> + + Projection plane origin height (in metre) + + *Defaults to 0.0.* diff --git a/_sources/operations/projections/collg.rst.txt b/_sources/operations/projections/collg.rst.txt new file mode 100644 index 00000000..f0ed215f --- /dev/null +++ b/_sources/operations/projections/collg.rst.txt @@ -0,0 +1,43 @@ +.. _collg: + +******************************************************************************** +Collignon +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | collg | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/collg.png + :width: 500 px + :align: center + :alt: Collignon + + proj-string: ``+proj=collg`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Collignon projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/comill.rst.txt b/_sources/operations/projections/comill.rst.txt new file mode 100644 index 00000000..fa04ec18 --- /dev/null +++ b/_sources/operations/projections/comill.rst.txt @@ -0,0 +1,46 @@ +.. _comill: + +******************************************************************************** +Compact Miller +******************************************************************************** + +The Compact Miller projection is a cylindrical map projection with a +height-to-width ratio of 0.6:1. + +See :cite:`Jenny2015` + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | comill | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/comill.png + :width: 500 px + :align: center + :alt: Compact Miller + + proj-string: ``+proj=comill`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/crast.rst.txt b/_sources/operations/projections/crast.rst.txt new file mode 100644 index 00000000..406c300a --- /dev/null +++ b/_sources/operations/projections/crast.rst.txt @@ -0,0 +1,43 @@ +.. _crast: + +******************************************************************************** +Craster Parabolic (Putnins P4) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | crast | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/crast.png + :width: 500 px + :align: center + :alt: Craster Parabolic (Putnins P4) + + proj-string: ``+proj=crast`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Craster Parabolic projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/denoy.rst.txt b/_sources/operations/projections/denoy.rst.txt new file mode 100644 index 00000000..b2913379 --- /dev/null +++ b/_sources/operations/projections/denoy.rst.txt @@ -0,0 +1,42 @@ +.. _denoy: + +******************************************************************************** +Denoyer Semi-Elliptical +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | denoy | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/denoy.png + :width: 500 px + :align: center + :alt: Denoyer Semi-Elliptical + + proj-string: ``+proj=denoy`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Denoyer Semi-Elliptical projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck1.rst.txt b/_sources/operations/projections/eck1.rst.txt new file mode 100644 index 00000000..28359977 --- /dev/null +++ b/_sources/operations/projections/eck1.rst.txt @@ -0,0 +1,49 @@ +.. _eck1: + +******************************************************************************** +Eckert I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck1.png + :width: 500 px + :align: center + :alt: Eckert I + + proj-string: ``+proj=eck1`` + + +.. math:: + + x &= 2 \sqrt{2/3\pi} \lambda (1- |\phi|/\pi) + + y &= 2 \sqrt{2/3\pi}\phi + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert I projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck2.rst.txt b/_sources/operations/projections/eck2.rst.txt new file mode 100644 index 00000000..aaa1ccd5 --- /dev/null +++ b/_sources/operations/projections/eck2.rst.txt @@ -0,0 +1,42 @@ +.. _eck2: + +******************************************************************************** +Eckert II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck2.png + :width: 500 px + :align: center + :alt: Eckert II + + proj-string: ``+proj=eck2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert II projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck3.rst.txt b/_sources/operations/projections/eck3.rst.txt new file mode 100644 index 00000000..94ef3a33 --- /dev/null +++ b/_sources/operations/projections/eck3.rst.txt @@ -0,0 +1,42 @@ +.. _eck3: + +******************************************************************************** +Eckert III +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck3.png + :width: 500 px + :align: center + :alt: Eckert III + + proj-string: ``+proj=eck3`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert III projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck4.rst.txt b/_sources/operations/projections/eck4.rst.txt new file mode 100644 index 00000000..e62a4fd8 --- /dev/null +++ b/_sources/operations/projections/eck4.rst.txt @@ -0,0 +1,49 @@ +.. _eck4: + +******************************************************************************** +Eckert IV +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck4 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck4.png + :width: 500 px + :align: center + :alt: Eckert IV + + proj-string: ``+proj=eck4`` + +.. math:: + + x = \lambda(1+cos\phi) / \sqrt{ 2 + \pi } + +.. math:: + y = 2 \phi / \sqrt { 2 + \pi } + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert IV projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck5.rst.txt b/_sources/operations/projections/eck5.rst.txt new file mode 100644 index 00000000..cfc888ff --- /dev/null +++ b/_sources/operations/projections/eck5.rst.txt @@ -0,0 +1,42 @@ +.. _eck5: + +******************************************************************************** +Eckert V +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck5 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck5.png + :width: 500 px + :align: center + :alt: Eckert V + + proj-string: ``+proj=eck5`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert V projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck6.rst.txt b/_sources/operations/projections/eck6.rst.txt new file mode 100644 index 00000000..1026b555 --- /dev/null +++ b/_sources/operations/projections/eck6.rst.txt @@ -0,0 +1,42 @@ +.. _eck6: + +******************************************************************************** +Eckert VI +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck6 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck6.png + :width: 500 px + :align: center + :alt: Eckert VI + + proj-string: ``+proj=eck6`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert VI projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eqc.rst.txt b/_sources/operations/projections/eqc.rst.txt new file mode 100644 index 00000000..964a5f16 --- /dev/null +++ b/_sources/operations/projections/eqc.rst.txt @@ -0,0 +1,131 @@ +.. _eqc: + +******************************************************************************** +Equidistant Cylindrical (Plate Carrée) +******************************************************************************** + +The simplest of all projections. Standard parallels (0° when omitted) may be specified that determine latitude of true scale (k=h=1). + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+----------------------------------------------------------+ +| **Alias** | eqc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eqc.png + :width: 500 px + :align: center + :alt: Equidistant Cylindrical (Plate Carrée) + + proj-string: ``+proj=eqc`` + +Usage +######## + +Because of the distortions introduced by this projection, it has little use in navigation or cadastral mapping and finds its main use in thematic mapping. +In particular, the plate carrée has become a standard for global raster datasets, such as Celestia and NASA World Wind, because of the particularly simple relationship between the position of an image pixel on the map and its corresponding geographic location on Earth. + +The following table gives special cases of the cylindrical equidistant projection. + ++---------------------------------------------------------+--------------------------+ +| Projection Name | (lat ts=) :math:`\phi_0` | ++=========================================================+==========================+ +| Plain/Plane Chart | 0° | ++---------------------------------------------------------+--------------------------+ +| Simple Cylindrical | 0° | ++---------------------------------------------------------+--------------------------+ +| Plate Carrée | 0° | ++---------------------------------------------------------+--------------------------+ +| Ronald Miller—minimum overall scale distortion | 37°30′ | ++---------------------------------------------------------+--------------------------+ +| E.Grafarend and A.Niermann | 42° | ++---------------------------------------------------------+--------------------------+ +| Ronald Miller—minimum continental scale distortion | 43°30′ | ++---------------------------------------------------------+--------------------------+ +| Gall Isographic | 45° | ++---------------------------------------------------------+--------------------------+ +| Ronald Miller Equirectangular | 50°30′ | ++---------------------------------------------------------+--------------------------+ +| E.Grafarend and A.Niermann minimum linear distortion | 61°7′ | ++---------------------------------------------------------+--------------------------+ + + +Example using EPSG 32662 (WGS84 Plate Carrée):: + + $ echo 2 47 | proj +proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +units=m + 222638.98 5232016.07 + +Example using Plate Carrée projection with true scale at latitude 30° and central meridian 90°W:: + + $ echo -88 30 | proj +proj=eqc +lat_ts=30 +lon_0=90w + 192811.01 3339584.72 + +Parameters +################################################################################ + + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +Mathematical definition +####################### + +The formulas describing the Equidistant Cylindrical projection are all taken from :cite:`Snyder1987`. + +:math:`\phi_{ts}` is the latitude of true scale, that mean the standard parallels where the scale of the projection is true. It can be set with ``+lat_ts``. + +:math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``. + + +Forward projection +================== + +.. math:: + + x = \lambda \cos \phi_{ts} + +.. math:: + + y = \phi - \phi_0 + +Inverse projection +================== + +.. math:: + + \lambda = x / cos \phi_{ts} + +.. math:: + + \phi = y + \phi_0 + + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Equirectangular_projection>`_ +#. `Wolfram Mathworld <http://mathworld.wolfram.com/CylindricalEquidistantProjection.html>`_ + + diff --git a/_sources/operations/projections/eqdc.rst.txt b/_sources/operations/projections/eqdc.rst.txt new file mode 100644 index 00000000..881a9282 --- /dev/null +++ b/_sources/operations/projections/eqdc.rst.txt @@ -0,0 +1,52 @@ +.. _eqdc: + +******************************************************************************** +Equidistant Conic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eqdc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eqdc.png + :width: 500 px + :align: center + :alt: Equidistant Conic + + proj-string: ``+proj=eqdc +lat_1=55 +lat_2=60`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eqearth.rst.txt b/_sources/operations/projections/eqearth.rst.txt new file mode 100644 index 00000000..bb6d22ce --- /dev/null +++ b/_sources/operations/projections/eqearth.rst.txt @@ -0,0 +1,68 @@ +.. _eqearth: + +******************************************************************************** +Equal Earth +******************************************************************************** + +.. versionadded:: 5.2.0 + ++---------------------+-----------------------------------------------------------+ +| **Classification** | Pseudo cylindrical | ++---------------------+-----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal projection | ++---------------------+-----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+-----------------------------------------------------------+ +| **Alias** | eqearth | ++---------------------+-----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+-----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+-----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+-----------------------------------------------------------+ + + + +.. figure:: ./images/eqearth.png + :width: 500 px + :align: center + :alt: Equal Earth + + proj-string: ``+proj=eqearth`` + + +The Equal Earth projection is intended for making world maps. Equal Earth is a +projection inspired by the Robinson projection, but unlike +the Robinson projection retains the relative size of areas. The projection +was designed in 2018 by Bojan Savric, Tom Patterson and Bernhard Jenny :cite:`Savric2018`. + + +Usage +############################################################################### + +The Equal Earth projection has no special options. Here is +an example of an forward projection on a sphere with a radius of 1 m:: + + $ echo 122 47 | src/proj +proj=eqearth +R=1 + 1.55 0.89 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. Bojan Savric, Tom Patterson & Bernhard Jenny (2018). `The Equal Earth map projection <https://www.researchgate.net/profile/Bojan_Savric2/publication/326879978_The_Equal_Earth_map_projection/links/5b69d0ae299bf14c6d951b77/The-Equal-Earth-map-projection.pdf>`_, International Journal of Geographical Information Science diff --git a/_sources/operations/projections/euler.rst.txt b/_sources/operations/projections/euler.rst.txt new file mode 100644 index 00000000..bac89855 --- /dev/null +++ b/_sources/operations/projections/euler.rst.txt @@ -0,0 +1,51 @@ +.. _euler: + +******************************************************************************** +Euler +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | euler | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/euler.png + :width: 500 px + :align: center + :alt: Euler + + proj-string: ``+proj=euler +lat_1=67 +lat_2=75`` + + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/fahey.rst.txt b/_sources/operations/projections/fahey.rst.txt new file mode 100644 index 00000000..39a7b1be --- /dev/null +++ b/_sources/operations/projections/fahey.rst.txt @@ -0,0 +1,42 @@ +.. _fahey: + +******************************************************************************** +Fahey +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | fahey | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/fahey.png + :width: 500 px + :align: center + :alt: Fahey + + proj-string: ``+proj=fahey`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Fahey projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/fouc.rst.txt b/_sources/operations/projections/fouc.rst.txt new file mode 100644 index 00000000..3bcb3e7d --- /dev/null +++ b/_sources/operations/projections/fouc.rst.txt @@ -0,0 +1,42 @@ +.. _fouc: + +******************************************************************************** +Foucaut +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | fouc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/fouc.png + :width: 500 px + :align: center + :alt: Foucaut + + proj-string: ``+proj=fouc`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Foucaut projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/fouc_s.rst.txt b/_sources/operations/projections/fouc_s.rst.txt new file mode 100644 index 00000000..1938b637 --- /dev/null +++ b/_sources/operations/projections/fouc_s.rst.txt @@ -0,0 +1,63 @@ +.. _fouc_s: + +******************************************************************************** +Foucaut Sinusoidal +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | fouc_s | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/fouc_s.png + :width: 500 px + :align: center + :alt: Foucaut Sinusoidal + + proj-string: ``+proj=fouc_s`` + + +The `y`-axis is based upon a weighted mean of the cylindrical equal-area and +the sinusoidal projections. Parameter :math:`n=n` is the weighting factor where +:math:`0 <= n <= 1`. + +.. math:: + + x &= \lambda \cos \phi / (n + (1 - n) \ cos \phi) + + y &= n \phi + (1 - n) \sin \phi + +For the inverse, the Newton-Raphson method can be used to determine +:math:`\phi` from the equation for :math:`y` above. As :math:`n \rightarrow 0` and +:math:`\phi \rightarrow \pi/2`, convergence is slow but for :math:`n = 0`, :math:`\phi = +\sin^1y` + + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Foucaut Sinusoidal projection. + +.. option:: +n=<value> + + Weighting factor. Value should be in the interval 0-1. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gall.rst.txt b/_sources/operations/projections/gall.rst.txt new file mode 100644 index 00000000..ba83d450 --- /dev/null +++ b/_sources/operations/projections/gall.rst.txt @@ -0,0 +1,111 @@ +.. _gall: + +******************************************************************************** +Gall (Gall Stereographic) +******************************************************************************** + +The Gall stereographic projection, presented by James Gall in 1855, is a cylindrical projection. +It is neither equal-area nor conformal but instead tries to balance the distortion inherent in any projection. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, Spherical | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gall | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gall.png + :width: 500 px + :align: center + :alt: Gall (Gall Stereographic) + + proj-string: ``+proj=gall`` + +Usage +##### + +The need for a world map which avoids some of the scale exaggeration of the Mercator projection has led to some commonly used cylindrical modifications, as well as to other modifications which are not cylindrical. +The earliest common cylindrical example was developed by James Gall of Edinburgh about 1855 (Gall, 1885, p. 119-123). +His meridians are equally spaced, but the parallels are spaced at increasing intervals away from the Equator. +The parallels of latitude are actually projected onto a cylinder wrapped about the sphere, but cutting it at lats. 45° N. and S., the point of perspective being a point on the Equator opposite the meridian being projected. +It is used in several British atlases, but seldom in the United States. +The Gall projection is neither conformal nor equal-area, but has a blend of various features. +Unlike the Mercator, the Gall shows the poles as lines running across the top and bottom of the map. + +.. note:: + + The Gall projection must not be confused with the Gall-Peters one, the later + being a specialization of :ref:`cea`. + +Example using Gall Stereographic :: + + $ echo 9 51 | proj +proj=gall +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +units=m + 708432.90 5193386.36 + +Example using Gall Stereographic (Central meridian 90°W) :: + + $ echo 9 51 | proj +proj=gall +lon_0=90w +x_0=0 +y_0=0 +ellps=WGS84 +units=m + 7792761.91 5193386.36 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + + +Mathematical definition +####################### + +The formulas describing the Gall Stereographic are all taken from :cite:`Snyder1993`. + +Spherical form +************** + +Forward projection +================== + +.. math:: + + x = \frac{\lambda}{\sqrt{2}} + +.. math:: + + y = (1+\frac{\sqrt{2}}{2}) \tan(\phi/2) + +Inverse projection +================== + +.. math:: + + \phi = 2 \arctan( \frac{y}{1+\frac{\sqrt{2}}{2}} ) + +.. math:: + + \lambda = \sqrt{2} x + + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Gall_stereographic_projection>`_ +#. `Cartographic Projection Procedures for the UNIX Environment-A User's Manual <http://sites.lsa.umich.edu/zhukov/wp-content/uploads/sites/140/2014/08/projection-procedures.pdf>`_ diff --git a/_sources/operations/projections/geos.rst.txt b/_sources/operations/projections/geos.rst.txt new file mode 100644 index 00000000..9b8bf21b --- /dev/null +++ b/_sources/operations/projections/geos.rst.txt @@ -0,0 +1,103 @@ +.. _geos: + +******************************************************************************** +Geostationary Satellite View +******************************************************************************** + +The geos projection pictures how a geostationary satellite scans the earth at regular +scanning angle intervals. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | geos | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/geos.png + :width: 500 px + :align: center + :alt: Geostationary Satellite View + + proj-string: ``+proj=geos +h=35785831.0 +lon_0=-60 +sweep=y`` + +Usage +############################################################################### + +In order to project using the geos projection you can do the following:: + + proj +proj=geos +h=35785831.0 + +The required argument ``h`` is the viewing point (satellite position) height above +the earth. + +The projection coordinate relate to the scanning angle by the following simple +relation:: + + scanning_angle (radians) = projection_coordinate / h + + +Note on sweep angle +------------------------------------------------------------------------------- + +The viewing instrument on-board geostationary satellites described by this +projection have a two-axis gimbal viewing geometry. This means that the different +scanning positions are obtained by rotating the gimbal along a N/S axis (or ``y``) +and a E/W axis (or ``x``). + +.. image:: ../../..//images/geos_sweep.png + :width: 500 px + :align: center + :alt: Gimbal geometry + +In the image above, the outer-gimbal axis, or sweep-angle axis, is the N/S axis (``y``) +while the inner-gimbal axis, or fixed-angle axis, is the E/W axis (``x``). + +This example represents the scanning geometry of the Meteosat series satellite. +However, the GOES satellite series use the opposite scanning geometry, with the +E/W axis (``x``) as the sweep-angle axis, and the N/S (``y``) as the fixed-angle axis. + +The sweep argument is used to tell PROJ which on which axis the outer-gimbal +is rotating. The possible values are x or y, y being the default. Thus, the +scanning geometry of the Meteosat series satellite should take sweep as y, and +GOES should take sweep as x. + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. include:: ../options/h.rst + + +Optional +------------------------------------------------------------------------------- + +.. option:: +sweep=<axis> + + Sweep angle axis of the viewing instrument. Valid options are *"x"* and *"y*". + + *Defaults to "y".* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + + diff --git a/_sources/operations/projections/gins8.rst.txt b/_sources/operations/projections/gins8.rst.txt new file mode 100644 index 00000000..07c26912 --- /dev/null +++ b/_sources/operations/projections/gins8.rst.txt @@ -0,0 +1,42 @@ +.. _gins8: + +******************************************************************************** +Ginsburg VIII (TsNIIGAiK) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gins8 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gins8.png + :width: 500 px + :align: center + :alt: Ginsburg VIII (TsNIIGAiK) + + proj-string: ``+proj=gins8`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Ginsburg VIII projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gn_sinu.rst.txt b/_sources/operations/projections/gn_sinu.rst.txt new file mode 100644 index 00000000..a42e1d14 --- /dev/null +++ b/_sources/operations/projections/gn_sinu.rst.txt @@ -0,0 +1,43 @@ +.. _gn_sinu: + +******************************************************************************** +General Sinusoidal Series +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gn_sinu | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gn_sinu.png + :width: 500 px + :align: center + :alt: General Sinusoidal Series + + proj-string: ``+proj=gn_sinu +m=2 +n=3`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the General Sinusoidal Series + projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gnom.rst.txt b/_sources/operations/projections/gnom.rst.txt new file mode 100644 index 00000000..1bbb5034 --- /dev/null +++ b/_sources/operations/projections/gnom.rst.txt @@ -0,0 +1,44 @@ +.. _gnom: + +******************************************************************************** +Gnomonic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gnom | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gnom.png + :width: 500 px + :align: center + :alt: Gnomonic + + proj-string: ``+proj=gnom +lat_0=90 +lon_0=-50`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Gnomonic projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/goode.rst.txt b/_sources/operations/projections/goode.rst.txt new file mode 100644 index 00000000..55f0f370 --- /dev/null +++ b/_sources/operations/projections/goode.rst.txt @@ -0,0 +1,42 @@ +.. _goode: + +******************************************************************************** +Goode Homolosine +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | goode | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/goode.png + :width: 500 px + :align: center + :alt: Goode Homolosine + + proj-string: ``+proj=goode`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Goode Homolosine projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gs48.rst.txt b/_sources/operations/projections/gs48.rst.txt new file mode 100644 index 00000000..b8088fb4 --- /dev/null +++ b/_sources/operations/projections/gs48.rst.txt @@ -0,0 +1,40 @@ +.. _gs48: + +******************************************************************************** +Modified Stereographic of 48 U.S. +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | The lower 48 states of the U.S. | ++---------------------+----------------------------------------------------------+ +| **Alias** | gs48 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gs48.png + :width: 500 px + :align: center + :alt: Modified Stereographic of 48 U.S. + + proj-string: ``+proj=gs48`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gs50.rst.txt b/_sources/operations/projections/gs50.rst.txt new file mode 100644 index 00000000..a5694f94 --- /dev/null +++ b/_sources/operations/projections/gs50.rst.txt @@ -0,0 +1,40 @@ +.. _gs50: + +******************************************************************************** +Modified Stereographic of 50 U.S. +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | All 50 states of the U.S. | ++---------------------+----------------------------------------------------------+ +| **Alias** | gs50 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gs50.png + :width: 500 px + :align: center + :alt: Modified Stereographic of 50 U.S. + + proj-string: ``+proj=gs50`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gstmerc.rst.txt b/_sources/operations/projections/gstmerc.rst.txt new file mode 100644 index 00000000..33c68eff --- /dev/null +++ b/_sources/operations/projections/gstmerc.rst.txt @@ -0,0 +1,48 @@ +.. _gstmerc: + +******************************************************************************** +Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gstmerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gstmerc.png + :width: 500 px + :align: center + :alt: Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) + + proj-string: ``+proj=gstmerc`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/guyou.rst.txt b/_sources/operations/projections/guyou.rst.txt new file mode 100644 index 00000000..89d455be --- /dev/null +++ b/_sources/operations/projections/guyou.rst.txt @@ -0,0 +1,42 @@ +.. _guyou: + +******************************************************************************** +Guyou +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | guyou | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/guyou.png + :width: 500 px + :align: center + :alt: Guyou + + proj-string: ``+proj=guyou`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/hammer.rst.txt b/_sources/operations/projections/hammer.rst.txt new file mode 100644 index 00000000..c3551d0c --- /dev/null +++ b/_sources/operations/projections/hammer.rst.txt @@ -0,0 +1,55 @@ +.. _hammer: + +******************************************************************************** +Hammer & Eckert-Greifendorff +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | hammer | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/hammer.png + :width: 500 px + :align: center + :alt: Hammer & Eckert-Greifendorff + + proj-string: ``+proj=hammer`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +W=<value> + + Set to 0.5 for the Hammer projection and 0.25 for the Eckert-Greifendorff + projection. :option:`+W` has to be larger than zero. + + *Defaults to 0.5.* + +.. option:: +M=<value> + + :option:`+M` has to be larger than zero. + + *Defaults to 1.0.* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/hatano.rst.txt b/_sources/operations/projections/hatano.rst.txt new file mode 100644 index 00000000..35bc32c3 --- /dev/null +++ b/_sources/operations/projections/hatano.rst.txt @@ -0,0 +1,84 @@ +.. _hatano: + +******************************************************************************** +Hatano Asymmetrical Equal Area +******************************************************************************** + + + + ++---------------------+----------------------------------------------------------+ +| **Classification** | :term:`Pseudocylindrical Projection` | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | hatano | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. figure:: ./images/hatano.png + :width: 500 px + :align: center + :alt: Hatano Asymmetrical Equal Area + + proj-string: ``+proj=hatano`` + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + + +Mathematical Definition +-------------------------------------------------------------------------------- + +Forward +................................................................................ + +.. math:: + + x &= 0.85\lambda \cos \theta + + y &= C_y \sin \theta + + P(\theta) &= 2\theta + \sin 2\theta - C_p \sin \phi + + P'(\theta) &= 2(1 + \cos 2\theta) + + \theta_0 &= 2\phi + + +==================================== ================== =================== +Condition :math:`C_y` :math:`C_p` +==================================== ================== =================== +For :math:`\phi > 0` 1.75859 2.67595 +For :math:`\phi < 0` 1.93052 2.43763 +==================================== ================== =================== + +For :math:`\phi = 0`, :math:`y \leftarrow 0`, and :math:`x \leftarrow 0.85\lambda`. + +Further reading +-------------------------------------------------------------------------------- + +#. `Compare Map Projections <http://map-projections.net/single-view/hatano>`__ +#. `Mathworks <http://www.mathworks.com/help/map/hatano.html>`__ + + + diff --git a/_sources/operations/projections/healpix.rst.txt b/_sources/operations/projections/healpix.rst.txt new file mode 100644 index 00000000..41bc10db --- /dev/null +++ b/_sources/operations/projections/healpix.rst.txt @@ -0,0 +1,77 @@ +.. _healpix: + +******************************************************************************** +HEALPix +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | healpix | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. image:: ../../../images/healpix.png + :scale: 75% + :alt: HEALPix + +The HEALPix projection is area preserving and can be used with a spherical and +ellipsoidal model. It was initially developed for mapping cosmic background +microwave radiation. The image below is the graphical representation of the +mapping and consists of eight isomorphic triangular interrupted map graticules. +The north and south contains four in which straight meridians converge polewards +to a point and unequally spaced horizontal parallels. HEALPix provides a mapping +in which points of equal latitude and equally spaced longitude are mapped to points +of equal latitude and equally spaced longitude with the module of the polar +interruptions. + + +Usage +############################################################################### + +To run a forward HEALPix projection on a unit sphere model, use the following command:: + + proj +proj=healpix +lon_0=0 +a=1 -E <<EOF + 0 0 + EOF + # output + 0 0 0.00 0.00 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. option:: +rot_xy + + .. versionadded:: 6.3.0 + + Rotation of the HEALPix map in degrees. A positive value results in a clockwise + rotation around (x_0, y_0) in the cartesian / projected coordinate space. + + *Defaults to 0.0.* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +Further reading +################################################################################ + +#. `NASA <http://healpix.jpl.nasa.gov/>`_ +#. `Wikipedia <https://en.wikipedia.org/wiki/HEALPix>`_ diff --git a/_sources/operations/projections/igh.rst.txt b/_sources/operations/projections/igh.rst.txt new file mode 100644 index 00000000..5e7df9a9 --- /dev/null +++ b/_sources/operations/projections/igh.rst.txt @@ -0,0 +1,42 @@ +.. _igh: + +******************************************************************************** +Interrupted Goode Homolosine +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | igh | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/igh.png + :width: 500 px + :align: center + :alt: Interrupted Goode Homolosine + + proj-string: ``+proj=igh`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/igh_o.rst.txt b/_sources/operations/projections/igh_o.rst.txt new file mode 100644 index 00000000..2df7223a --- /dev/null +++ b/_sources/operations/projections/igh_o.rst.txt @@ -0,0 +1,42 @@ +.. _igh_o: + +******************************************************************************** +Interrupted Goode Homolosine (Oceanic View) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | igh_o | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/igh_o.png + :width: 500 px + :align: center + :alt: Interrupted Goode Homolosine + + proj-string: ``+proj=igh_o +lon_0=-160`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. A value of +lon_0=-160 is recommended. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/imw_p.rst.txt b/_sources/operations/projections/imw_p.rst.txt new file mode 100644 index 00000000..1dad270e --- /dev/null +++ b/_sources/operations/projections/imw_p.rst.txt @@ -0,0 +1,50 @@ +.. _imw_p: + +******************************************************************************** +International Map of the World Polyconic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoconical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | imw_p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/imw_p.png + :width: 500 px + :align: center + :alt: International Map of the World Polyconic + + proj-string: ``+proj=imw_p +lat_1=30 +lat_2=-40`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/index.rst.txt b/_sources/operations/projections/index.rst.txt new file mode 100644 index 00000000..4f76dab2 --- /dev/null +++ b/_sources/operations/projections/index.rst.txt @@ -0,0 +1,164 @@ +.. _projections: + +================================================================================ +Projections +================================================================================ + +Projections are coordinate operations that are technically conversions but since +projections are so fundamental to PROJ we differentiate them from conversions. + +Projections map the spherical 3D space to a flat 2D space. + +.. toctree:: + :maxdepth: 1 + + adams_hemi + adams_ws1 + adams_ws2 + aea + aeqd + airy + aitoff + alsk + apian + august + bacon + bertin1953 + bipc + boggs + bonne + calcofi + cass + cc + ccon + cea + chamb + collg + col_urban + comill + crast + denoy + eck1 + eck2 + eck3 + eck4 + eck5 + eck6 + eqc + eqdc + eqearth + euler + fahey + fouc + fouc_s + gall + geos + gins8 + gn_sinu + gnom + goode + gs48 + gs50 + guyou + hammer + hatano + healpix + rhealpix + igh + igh_o + imw_p + isea + kav5 + kav7 + krovak + labrd + laea + lagrng + larr + lask + lcc + lcca + leac + lee_os + loxim + lsat + mbt_s + mbt_fps + mbtfpp + mbtfpq + mbtfps + merc + mil_os + mill + misrsom + moll + murd1 + murd2 + murd3 + natearth + natearth2 + nell + nell_h + nicol + nsper + nzmg + ob_tran + ocea + oea + omerc + ortel + ortho + patterson + pconic + peirce_q + poly + putp1 + putp2 + putp3 + putp3p + putp4p + putp5 + putp5p + putp6 + putp6p + qua_aut + qsc + robin + rouss + rpoly + s2 + sch + sinu + somerc + stere + sterea + gstmerc + tcc + tcea + times + tissot + tmerc + tobmerc + tpeqd + tpers + ups + urm5 + urmfps + utm + vandg + vandg2 + vandg3 + vandg4 + vitk1 + wag1 + wag2 + wag3 + wag4 + wag5 + wag6 + wag7 + webmerc + weren + wink1 + wink2 + wintri diff --git a/_sources/operations/projections/isea.rst.txt b/_sources/operations/projections/isea.rst.txt new file mode 100644 index 00000000..73f0af7a --- /dev/null +++ b/_sources/operations/projections/isea.rst.txt @@ -0,0 +1,78 @@ +.. _isea: + +******************************************************************************** +Icosahedral Snyder Equal Area +******************************************************************************** + +Snyder's Icosahedral Equal Area map projections on polyhedral globes for the +dodecahedron and truncated icosahedron offer relatively low scale and +angular distortion. The equations involved are relatively straight-forward, +and for certain instructional tools and databases, the projections are useful +for world maps. The interruptions remain a disadvantage, as with any low-error +projection system applied to the entire globe :cite:`Snyder1992`. + + ++---------------------+----------------------------------------------------------+ +| **Classification** | Polyhedral, equal area | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward, spherical | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | isea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/isea.png + :width: 500 px + :align: center + :alt: Icosahedral Snyder Equal Area + + proj-string: ``+proj=isea`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +orient=<string> + + Can be set to either ``isea`` or ``pole``. See Snyder's Figure 12 for pole orientation :cite:`Snyder1992`. + + *Defaults to isea* + +.. option:: +azi=<value> + + Azimuth. + + *Defaults to 0.0* + +.. option:: +aperture=<value> + + *Defaults to 3.0* + +.. option:: +resolution=<value> + + *Defaults to 4.0* + +.. option:: +mode=<string> + + Can be either ``plane``, ``di``, ``dd`` or ``hex``. + + *Defaults to plane* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/kav5.rst.txt b/_sources/operations/projections/kav5.rst.txt new file mode 100644 index 00000000..0025260b --- /dev/null +++ b/_sources/operations/projections/kav5.rst.txt @@ -0,0 +1,46 @@ +.. _kav5: + +******************************************************************************** +Kavrayskiy V +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | kav5 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/kav5.png + :width: 500 px + :align: center + :alt: Kavrayskiy V + + proj-string: ``+proj=kav5`` + +.. note:: This projection name may also be transliterated as Kavraisky V. + +Created by Soviet cartographer Vladimir V. Kavrayskiy in 1933 :cite:`Snyder1993`. + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Kavrayskiy V projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/kav7.rst.txt b/_sources/operations/projections/kav7.rst.txt new file mode 100644 index 00000000..1808f4ca --- /dev/null +++ b/_sources/operations/projections/kav7.rst.txt @@ -0,0 +1,46 @@ +.. _kav7: + +******************************************************************************** +Kavrayskiy VII +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | kav7 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/kav7.png + :width: 500 px + :align: center + :alt: Kavrayskiy VII + + proj-string: ``+proj=kav7`` + +.. note:: This projection name may also be transliterated as Kavraisky VII. + +Created by Soviet cartographer Vladimir V. Kavrayskiy in 1939 :cite:`Snyder1993`. + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Kavrayskiy VII projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/krovak.rst.txt b/_sources/operations/projections/krovak.rst.txt new file mode 100644 index 00000000..59f66b04 --- /dev/null +++ b/_sources/operations/projections/krovak.rst.txt @@ -0,0 +1,64 @@ +.. _krovak: + +******************************************************************************** +Krovak +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but more accurate around Czechoslovakia | ++---------------------+----------------------------------------------------------+ +| **Alias** | krovak | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/krovak.png + :width: 500 px + :align: center + :alt: Krovak + + proj-string: ``+proj=krovak`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Krovak projection. + + The latitude of pseudo standard parallel is hardcoded to 78.5° and + the ellipsoid to Bessel. + +.. option:: +czech + + Reverse the sign of the output coordinates, as is tradition in the + Czech Republic. + +.. option:: +lon_0=<value> + + Longitude of projection center. + + *Defaults to 24°50' (24.8333333333333)* + +.. option:: +lat_0=<value> + + Latitude of projection center. + + *Defaults to 49.5* + +.. option:: +k_0=<value> + + Scale factor. Determines scale factor used in the projection. + + *Defaults to 0.9999* + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/labrd.rst.txt b/_sources/operations/projections/labrd.rst.txt new file mode 100644 index 00000000..c91e38b7 --- /dev/null +++ b/_sources/operations/projections/labrd.rst.txt @@ -0,0 +1,57 @@ +.. _labrd: + +******************************************************************************** +Laborde +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but more accurate around Madagascar | ++---------------------+----------------------------------------------------------+ +| **Alias** | labrd | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/labrd.png + :width: 500 px + :align: center + :alt: Laborde + + proj-string: ``+proj=labrd +lon_0=40 +lat_0=-10`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +lat_0=<value> + + Latitude of projection center. Must not be zero. + + +Optional +-------------------------------------------------------------------------------- + +.. option:: +azi=<value> + + Azimuth of the central line. + + *Defaults to 0.0* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/laea.rst.txt b/_sources/operations/projections/laea.rst.txt new file mode 100644 index 00000000..5434564c --- /dev/null +++ b/_sources/operations/projections/laea.rst.txt @@ -0,0 +1,46 @@ +.. _laea: + +******************************************************************************** +Lambert Azimuthal Equal Area +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | laea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/laea.png + :width: 500 px + :align: center + :alt: Lambert Azimuthal Equal Area + + proj-string: ``+proj=laea`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/lagrng.rst.txt b/_sources/operations/projections/lagrng.rst.txt new file mode 100644 index 00000000..b96fcd32 --- /dev/null +++ b/_sources/operations/projections/lagrng.rst.txt @@ -0,0 +1,54 @@ +.. _lagrng: + +******************************************************************************** +Lagrange +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lagrng | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lagrng.png + :width: 500 px + :align: center + :alt: Lagrange + + proj-string: ``+proj=lagrng`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +W=<value> + + The factor :option:`+W` is the ratio of the difference in longitude from the + central meridian to the a circular meridian to 90. :option:`+W` must be a + positive value. + + *Defaults to 2.0* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_1.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/larr.rst.txt b/_sources/operations/projections/larr.rst.txt new file mode 100644 index 00000000..edcf146b --- /dev/null +++ b/_sources/operations/projections/larr.rst.txt @@ -0,0 +1,42 @@ +.. _larr: + +******************************************************************************** +Larrivee +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | larr | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/larr.png + :width: 500 px + :align: center + :alt: Larrivee + + proj-string: ``+proj=larr`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Larrivee projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/lask.rst.txt b/_sources/operations/projections/lask.rst.txt new file mode 100644 index 00000000..a4f9a5db --- /dev/null +++ b/_sources/operations/projections/lask.rst.txt @@ -0,0 +1,42 @@ +.. _lask: + +******************************************************************************** +Laskowski +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lask | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lask.png + :width: 500 px + :align: center + :alt: Laskowski + + proj-string: ``+proj=lask`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/lcc.rst.txt b/_sources/operations/projections/lcc.rst.txt new file mode 100644 index 00000000..bf15d76a --- /dev/null +++ b/_sources/operations/projections/lcc.rst.txt @@ -0,0 +1,88 @@ +.. _lcc: + +******************************************************************************** +Lambert Conformal Conic +******************************************************************************** + +A Lambert Conformal Conic projection (LCC) is a conic map projection +used for aeronautical charts, portions of the State Plane Coordinate +System, and many national and regional mapping systems. It is one of +seven projections introduced by Johann Heinrich Lambert in 1772. + +It has several different forms: with one and two standard parallels +(referred to as 1SP and 2SP in EPSG guidance notes). Additionally we +provide "2SP Michigan" form which is very similar to normal 2SP, but +with a scaling factor on the ellipsoid (given as `k_0` parameter). +It is implemented as per EPSG Guidance Note 7-2 (version 54, August +2018, page 25). It is used in a few systems in the EPSG database which +justifies adding this otherwise non-standard projection. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal .| +| | One or two standard parallels (1SP and 2SP). | +| | "LCC 2SP Michigan" form can be used by setting | +| | ``+k_0`` parameter to specify ellipsoid scale. | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Best for regions predominantly east–west in extent and | +| | located in the middle north or south latitudes. | ++---------------------+----------------------------------------------------------+ +| **Alias** | lcc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/lcc.png + :width: 500 px + :align: center + :alt: Lambert Conformal Conic + + proj-string: ``+proj=lcc +lon_0=-90 +lat_1=33 +lat_2=45`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lat_2.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. option:: +k_0=<value> + + This parameter can represent two different values depending on the + form of the projection. In LCC 1SP it determines the scale factor + at natural origin. In LCC 2SP Michigan it determines the ellipsoid + scale factor. + + *Defaults to 1.0.* + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Lambert_conformal_conic_projection>`_ +#. `Wolfram Mathworld <http://mathworld.wolfram.com/LambertConformalConicProjection.html>`_ +#. `John P. Snyder "Map projections: A working manual" (pp. 104-110) <https://pubs.er.usgs.gov/publication/pp1395>`_ +#. `ArcGIS documentation on "Lambert Conformal Conic" <http://desktop.arcgis.com/en/arcmap/10.3/guide-books/map-projections/lambert-conformal-conic.htm>`_ +#. `EPSG Guidance Note 7-2 (version 54, August 2018, page 25) <http://www.epsg.org/Guidancenotes.aspx>`_ diff --git a/_sources/operations/projections/lcca.rst.txt b/_sources/operations/projections/lcca.rst.txt new file mode 100644 index 00000000..f97c81b4 --- /dev/null +++ b/_sources/operations/projections/lcca.rst.txt @@ -0,0 +1,46 @@ +.. _lcca: + +******************************************************************************** +Lambert Conformal Conic Alternative +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lcca | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lcca.png + :width: 500 px + :align: center + :alt: Lambert Conformal Conic Alternative + + proj-string: ``+proj=lcca +lat_0=35`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/leac.rst.txt b/_sources/operations/projections/leac.rst.txt new file mode 100644 index 00000000..7cc0f2d2 --- /dev/null +++ b/_sources/operations/projections/leac.rst.txt @@ -0,0 +1,53 @@ +.. _leac: + +******************************************************************************** +Lambert Equal Area Conic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | leac | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/leac.png + :width: 500 px + :align: center + :alt: Lambert Equal Area Conic + + proj-string: ``+proj=leac`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Lambert Equal Area Conic + projection. + +.. include:: ../options/lat_1.rst + +.. option:: +south + + Sets the second standard parallel to 90°S. When the flag is off the second + standard parallel is set to 90°N. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/lee_os.rst.txt b/_sources/operations/projections/lee_os.rst.txt new file mode 100644 index 00000000..3f9248ac --- /dev/null +++ b/_sources/operations/projections/lee_os.rst.txt @@ -0,0 +1,40 @@ +.. _lee_os: + +******************************************************************************** +Lee Oblated Stereographic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lee_os | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lee_os.png + :width: 500 px + :align: center + :alt: Lee Oblated Stereographic + + proj-string: ``+proj=lee_os`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/loxim.rst.txt b/_sources/operations/projections/loxim.rst.txt new file mode 100644 index 00000000..9813b6e6 --- /dev/null +++ b/_sources/operations/projections/loxim.rst.txt @@ -0,0 +1,44 @@ +.. _loxim: + +******************************************************************************** +Loximuthal +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | loxim | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/loxim.png + :width: 500 px + :align: center + :alt: Loximuthal + + proj-string: ``+proj=loxim`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Loximuthal projection. + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/lsat.rst.txt b/_sources/operations/projections/lsat.rst.txt new file mode 100644 index 00000000..d7b545a8 --- /dev/null +++ b/_sources/operations/projections/lsat.rst.txt @@ -0,0 +1,58 @@ +.. _lsat: + +******************************************************************************** +Space oblique for LANDSAT +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lsat | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lsat.png + :width: 500 px + :align: center + :alt: Space oblique for LANDSAT + + proj-string: ``+proj=lsat +ellps=GRS80 +lat_1=-60 +lat_2=60 +lsat=2 +path=2`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +lsat=<value> + + Landsat satellite used for the projection. Value between 1 and 5. + +.. option:: +path=<value> + + Selected path of satellite. Value between 1 and 253 when :option:`+lsat` is + set to 1,2 or 3, otherwise valid input is between 1 and 233. + + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbt_fps.rst.txt b/_sources/operations/projections/mbt_fps.rst.txt new file mode 100644 index 00000000..614c514a --- /dev/null +++ b/_sources/operations/projections/mbt_fps.rst.txt @@ -0,0 +1,42 @@ +.. _mbt_fps: + +******************************************************************************** +McBryde-Thomas Flat-Pole Sine (No. 2) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbt_fps | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbt_fps.png + :width: 500 px + :align: center + :alt: McBryde-Thomas Flat-Pole Sine (No. 2) + + proj-string: ``+proj=mbt_fps`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbt_s.rst.txt b/_sources/operations/projections/mbt_s.rst.txt new file mode 100644 index 00000000..300c2749 --- /dev/null +++ b/_sources/operations/projections/mbt_s.rst.txt @@ -0,0 +1,43 @@ +.. _mbt_s: + +******************************************************************************** +McBryde-Thomas Flat-Polar Sine (No. 1) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbt_s | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbt_s.png + :width: 500 px + :align: center + :alt: McBryde-Thomas Flat-Polar Sine (No. 1) + + proj-string: ``+proj=mbt_s`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the McBryde-Thomas Flat-Polar Sine + projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbtfpp.rst.txt b/_sources/operations/projections/mbtfpp.rst.txt new file mode 100644 index 00000000..ec83d5f5 --- /dev/null +++ b/_sources/operations/projections/mbtfpp.rst.txt @@ -0,0 +1,42 @@ +.. _mbtfpp: + +******************************************************************************** +McBride-Thomas Flat-Polar Parabolic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbtfpp | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbtfpp.png + :width: 500 px + :align: center + :alt: McBride-Thomas Flat-Polar Parabolic + + proj-string: ``+proj=mbtfpp`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbtfpq.rst.txt b/_sources/operations/projections/mbtfpq.rst.txt new file mode 100644 index 00000000..4ed23e28 --- /dev/null +++ b/_sources/operations/projections/mbtfpq.rst.txt @@ -0,0 +1,42 @@ +.. _mbtfpq: + +******************************************************************************** +McBryde-Thomas Flat-Polar Quartic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbtfpq | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbtfpq.png + :width: 500 px + :align: center + :alt: McBryde-Thomas Flat-Polar Quartic + + proj-string: ``+proj=mbtfpq`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbtfps.rst.txt b/_sources/operations/projections/mbtfps.rst.txt new file mode 100644 index 00000000..34217e71 --- /dev/null +++ b/_sources/operations/projections/mbtfps.rst.txt @@ -0,0 +1,43 @@ +.. _mbtfps: + +******************************************************************************** +McBryde-Thomas Flat-Polar Sinusoidal +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbtfps | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbtfps.png + :width: 500 px + :align: center + :alt: McBryde-Thomas Flat-Polar Sinusoidal + + proj-string: ``+proj=mbtfps`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the McBryde-Thomas Flat-Polar + Sinusoidal projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/merc.rst.txt b/_sources/operations/projections/merc.rst.txt new file mode 100644 index 00000000..6eae9d36 --- /dev/null +++ b/_sources/operations/projections/merc.rst.txt @@ -0,0 +1,197 @@ +.. _merc: + +******************************************************************************** +Mercator +******************************************************************************** + +The Mercator projection is a cylindrical map projection that origins +from the 16th century. It is widely recognized as the first regularly +used map projection. It is a conformal projection in which the equator +projects to a straight line at constant scale. The projection has the +property that a rhumb line, a course of constant heading, projects to a +straight line. This makes it suitable for navigational purposes. + + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+----------------------------------------------------------+ +| **Alias** | merc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/merc.png + :width: 500 px + :align: center + :alt: Mercator + + proj-string: ``+proj=merc`` + +Usage +######## + +Applications should be limited to equatorial regions, but is frequently +used for navigational charts with latitude of true scale (:option:`+lat_ts`) specified within +or near chart's boundaries. +It is considered to be inappropriate for world maps because of the gross +distortions in area; for example the projected area of Greenland is +larger than that of South America, despite the fact that Greenland's +area is :math:`\frac18` that of South America :cite:`Snyder1987`. + + +Example using latitude of true scale:: + + $ echo 56.35 12.32 | proj +proj=merc +lat_ts=56.5 + 3470306.37 759599.90 + +Example using scaling factor:: + + echo 56.35 12.32 | proj +proj=merc +k_0=2 + 12545706.61 2746073.80 + + +Note that :option:`+lat_ts` and :option:`+k_0` are mutually exclusive. +If used together, :option:`+lat_ts` takes precedence over :option:`+k_0`. + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +Mathematical definition +####################### + +Spherical form +************** +For the spherical form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = \cos \phi_{ts} + +Forward projection +================== + +.. math:: + + x = k_0R \lambda; \qquad y = k_0R \psi + +.. math:: + + \psi &= \ln \tan \biggl(\frac{\pi}{4} + \frac{\phi}{2} \biggr)\\ + &= \sinh^{-1}\tan\phi + +The quantity :math:`\psi` is the isometric latitude. + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0R}; \qquad \psi = \frac{y}{k_0R} + +.. math:: + + \phi &= \frac{\pi}{2} - 2 \tan^{-1} \exp(-\psi)\\ + &= \tan^{-1}\sinh\psi + + +Ellipsoidal form +**************** + +For the ellipsoidal form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = m( \phi_{ts} ) + +where + +.. math:: + + m(\phi) = \frac{\cos\phi}{\sqrt{1 - e^2\sin^2\phi}} + +:math:`a\,m(\phi)` is the radius of the circle of latitude :math:`\phi`. + +Forward projection +================== +.. math:: + + x = k_0 a \lambda; \qquad y = k_0 a \psi + +.. math:: + + \psi &= \ln\tan\biggl(\frac\pi4 + \frac{\phi}2\biggr) + -\frac12 e + \ln \biggl(\frac{1 + e \sin\phi}{1 - e \sin\phi}\biggr)\\ + &= \sinh^{-1}\tan\phi - e \tanh^{-1}(e \sin\phi) + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0 a}; \quad \psi = \frac{y}{k_0 a} + +The latitude :math:`\phi` is found by inverting the equation for +:math:`\psi`. This follows the method given by :cite:`Karney2011tm`. +Start by introducing the conformal latitude + +.. math:: + \chi = \tan^{-1}\sinh\psi + +The tangents of the latitudes :math:`\tau = \tan\phi` and :math:`\tau' = +\tan\chi = \sinh\psi` are related by + +.. math:: + \tau' = \tau \sqrt{1 + \sigma^2} - \sigma \sqrt{1 + \tau^2} + +where + +.. math:: + \sigma = \sinh\bigl(e \tanh^{-1}(e \tau/\sqrt{1 + \tau^2}) \bigr) + +This is obtained by taking the :math:`\sinh` of the equation for +:math:`\psi` and using the multiple argument formula. The equation for +:math:`\tau'` can be solved to give :math:`\tau` using Newton's method +using :math:`\tau = \tau'/(1 - e^2)` as an initial guess and with the +needed derivative given by + +.. math:: + \frac{d\tau'}{d\tau} = \frac{1 - e^2}{1 + (1 - e^2)\tau^2} + \sqrt{1 + \tau'^2} \sqrt{1 + \tau^2} + +This converges after no more than 2 iterations. Finally set +:math:`\phi=\tan^{-1}\tau`. + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Mercator_projection>`_ +#. `Wolfram Mathworld <http://mathworld.wolfram.com/MercatorProjection.html>`_ + + diff --git a/_sources/operations/projections/mil_os.rst.txt b/_sources/operations/projections/mil_os.rst.txt new file mode 100644 index 00000000..dbf8488f --- /dev/null +++ b/_sources/operations/projections/mil_os.rst.txt @@ -0,0 +1,40 @@ +.. _mil_os: + +******************************************************************************** +Miller Oblated Stereographic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mil_os | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mil_os.png + :width: 500 px + :align: center + :alt: Miller Oblated Stereographic + + proj-string: ``+proj=mil_os`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mill.rst.txt b/_sources/operations/projections/mill.rst.txt new file mode 100644 index 00000000..83447ad5 --- /dev/null +++ b/_sources/operations/projections/mill.rst.txt @@ -0,0 +1,91 @@ +.. _mill: + +******************************************************************************** +Miller Cylindrical +******************************************************************************** + +The Miller cylindrical projection is a modified Mercator projection, proposed by Osborn Maitland Miller in 1942. +The latitude is scaled by a factor of :math:`\frac{4}{5}`, projected according to Mercator, and then the result is multiplied by :math:`\frac{5}{4}` to retain scale along the equator. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Neither conformal nor equal area cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse spherical | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+----------------------------------------------------------+ +| **Alias** | mill | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mill.png + :width: 500 px + :align: center + :alt: Miller Cylindrical + + proj-string: ``+proj=mill`` + +Usage +######## + +The Miller Cylindrical projection is used for world maps and in several atlases, +including the National Atlas of the United States (USGS, 1970, p. 330-331) :cite:`Snyder1987`. + +Example using Central meridian 90°W:: + + $ echo -100 35 | proj +proj=mill +lon_0=90w + -1113194.91 4061217.24 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Mathematical definition +####################### + +The formulas describing the Miller projection are all taken from :cite:`Snyder1987`. + + +Forward projection +================== + +.. math:: + + x = \lambda + +.. math:: + + y = 1.25 * \ln \left[ \tan \left(\frac{\pi}{4} + 0.4 * \phi \right) \right] + + +Inverse projection +================== + +.. math:: + + \lambda = x + +.. math:: + + \phi = 2.5 * ( \arctan \left[ e^{0.8 * y} \right] - \frac{\pi}{4} ) + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Miller_cylindrical_projection>`_ + diff --git a/_sources/operations/projections/misrsom.rst.txt b/_sources/operations/projections/misrsom.rst.txt new file mode 100644 index 00000000..f04af6b3 --- /dev/null +++ b/_sources/operations/projections/misrsom.rst.txt @@ -0,0 +1,53 @@ +.. _misrsom: + +******************************************************************************** +Space oblique for MISR +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | misrsom | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/misrsom.png + :width: 500 px + :align: center + :alt: Space oblique for MISR + + proj-string: ``+proj=misrsom +path=1`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +path=<value> + + Selected path of satellite. Value between 1 and 233. + + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/moll.rst.txt b/_sources/operations/projections/moll.rst.txt new file mode 100644 index 00000000..e38131d4 --- /dev/null +++ b/_sources/operations/projections/moll.rst.txt @@ -0,0 +1,42 @@ +.. _moll: + +******************************************************************************** +Mollweide +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | moll | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/moll.png + :width: 500 px + :align: center + :alt: Mollweide + + proj-string: ``+proj=moll`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/murd1.rst.txt b/_sources/operations/projections/murd1.rst.txt new file mode 100644 index 00000000..c52de4ce --- /dev/null +++ b/_sources/operations/projections/murd1.rst.txt @@ -0,0 +1,50 @@ +.. _murd1: + +******************************************************************************** +Murdoch I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | murd1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/murd1.png + :width: 500 px + :align: center + :alt: Murdoch I + + proj-string: ``+proj=murd1 +lat_1=30 +lat_2=50`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/murd2.rst.txt b/_sources/operations/projections/murd2.rst.txt new file mode 100644 index 00000000..e9dbb1a6 --- /dev/null +++ b/_sources/operations/projections/murd2.rst.txt @@ -0,0 +1,50 @@ +.. _murd2: + +******************************************************************************** +Murdoch II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | murd2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/murd2.png + :width: 500 px + :align: center + :alt: Murdoch II + + proj-string: ``+proj=murd2 +lat_1=30 +lat_2=50`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/murd3.rst.txt b/_sources/operations/projections/murd3.rst.txt new file mode 100644 index 00000000..194ea31f --- /dev/null +++ b/_sources/operations/projections/murd3.rst.txt @@ -0,0 +1,50 @@ +.. _murd3: + +******************************************************************************** +Murdoch III +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | murd3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/murd3.png + :width: 500 px + :align: center + :alt: Murdoch III + + proj-string: ``+proj=murd3 +lat_1=30 +lat_2=50`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/natearth.rst.txt b/_sources/operations/projections/natearth.rst.txt new file mode 100644 index 00000000..4ed5b638 --- /dev/null +++ b/_sources/operations/projections/natearth.rst.txt @@ -0,0 +1,65 @@ +.. _natearth: + +******************************************************************************** +Natural Earth +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Pseudo cylindrical | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Alias** | natearth | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + + + +.. figure:: ./images/natearth.png + :width: 500 px + :align: center + :alt: Natural Earth + + proj-string: ``+proj=natearth`` + +The Natural Earth projection is intended for making world maps. A distinguishing trait +is its slightly rounded corners fashioned to emulate the spherical shape of Earth. +The meridians (except for the central meridian) bend acutely inward as they approach +the pole lines, giving the projection a hint of three-dimensionality. This bending +also suggests that the meridians converge at the poles instead of truncating at the +top and bottom edges. The distortion characteristics of the Natural Earth projection +compare favorably to other world map projections. + + +Usage +############################################################################### + +The Natural Earth projection has no special options so usage is simple. Here is +an example of an inverse projection on a sphere with a radius of 7500 m:: + + $ echo 3500 -8000 | proj -I +proj=natearth +a=7500 + 37d54'6.091"E 61d23'4.582"S + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. `Wikipedia <https://en.wikipedia.org/wiki/Natural_Earth_projection>`_ diff --git a/_sources/operations/projections/natearth2.rst.txt b/_sources/operations/projections/natearth2.rst.txt new file mode 100644 index 00000000..a5128ea9 --- /dev/null +++ b/_sources/operations/projections/natearth2.rst.txt @@ -0,0 +1,49 @@ +.. _natearth2: + +******************************************************************************** +Natural Earth II +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Pseudo cylindrical | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Alias** | natearth2 | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + + + +.. figure:: ./images/natearth2.png + :width: 500 px + :align: center + :alt: Natural Earth II + + proj-string: ``+proj=natearth2`` + +The Natural Earth II projection is intended for making world maps. At high +latitudes, meridians bend steeply toward short pole lines resulting in a map +with highly rounded corners that resembles an elongated globe. + +See :cite:`Savric2015` + + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nell.rst.txt b/_sources/operations/projections/nell.rst.txt new file mode 100644 index 00000000..2619d0b3 --- /dev/null +++ b/_sources/operations/projections/nell.rst.txt @@ -0,0 +1,42 @@ +.. _nell: + +******************************************************************************** +Nell +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | nell | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/nell.png + :width: 500 px + :align: center + :alt: Nell + + proj-string: ``+proj=nell`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nell_h.rst.txt b/_sources/operations/projections/nell_h.rst.txt new file mode 100644 index 00000000..5b4a45df --- /dev/null +++ b/_sources/operations/projections/nell_h.rst.txt @@ -0,0 +1,42 @@ +.. _nell_h: + +******************************************************************************** +Nell-Hammer +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | nell_h | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/nell_h.png + :width: 500 px + :align: center + :alt: Nell-Hammer + + proj-string: ``+proj=nell_h`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nicol.rst.txt b/_sources/operations/projections/nicol.rst.txt new file mode 100644 index 00000000..0b7f0251 --- /dev/null +++ b/_sources/operations/projections/nicol.rst.txt @@ -0,0 +1,42 @@ +.. _nicol: + +******************************************************************************** +Nicolosi Globular +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoconical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | nicol | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/nicol.png + :width: 500 px + :align: center + :alt: Nicolosi Globular + + proj-string: ``+proj=nicol`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nsper.rst.txt b/_sources/operations/projections/nsper.rst.txt new file mode 100644 index 00000000..d99c7932 --- /dev/null +++ b/_sources/operations/projections/nsper.rst.txt @@ -0,0 +1,53 @@ +.. _nsper: + +******************************************************************************** +Near-sided perspective +******************************************************************************** + +The near-sided perspective projection simulates a view from a height +:math:`h` similar to how a satellite in orbit would see it. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal. Neither conformal nor equal area. | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, although for one hemisphere at a time. | ++---------------------+----------------------------------------------------------+ +| **Alias** | nsper | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/nsper.png + :width: 500 px + :align: center + :alt: Near-sided perspective + + proj-string: ``+proj=nsper +h=3000000 +lat_0=-20 +lon_0=145`` + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. include:: ../options/h.rst + +Optional +------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nzmg.rst.txt b/_sources/operations/projections/nzmg.rst.txt new file mode 100644 index 00000000..2e367fdf --- /dev/null +++ b/_sources/operations/projections/nzmg.rst.txt @@ -0,0 +1,17 @@ +.. _nzmg: + +******************************************************************************** +New Zealand Map Grid +******************************************************************************** + +.. figure:: ./images/nzmg.png + :width: 500 px + :align: center + :alt: New Zealand Map Grid + + proj-string: ``+proj=nzmg`` + +Parameters +################################################################################ + +.. note:: All standard projection parameters are hard-coded for this projection diff --git a/_sources/operations/projections/ob_tran.rst.txt b/_sources/operations/projections/ob_tran.rst.txt new file mode 100644 index 00000000..2ede2dd6 --- /dev/null +++ b/_sources/operations/projections/ob_tran.rst.txt @@ -0,0 +1,120 @@ +.. _ob_tran: + +******************************************************************************** +General Oblique Transformation +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | ob_tran | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/ob_tran.png + :width: 500 px + :align: center + :alt: General Oblique Transformation + + proj-string: ``+proj=ob_tran +o_proj=mill +o_lon_p=40 +o_lat_p=50 +lon_0=60`` + +Usage +################################################################################ + +All of the projections of spherical library can be used as an +oblique projection by means of the General Oblique Transformation. The user +performs the oblique transformation by selecting the oblique projection +``+proj=ob_tran``, specifying the translation factors, :option:`+o_lat_p`, and +:option:`+o_lon_p`, and the projection to be used, :option:`+o_proj`. In the +example of the Fairgrieve projection, the latitude and longitude of the North pole +of the unrotated geographic CRS, :math:`\alpha` and :math:`\beta` respectively, +expressed in the rotated geographic CRS, are to be placed +at 45°N and 90°W and the :ref:`moll` projection is used. Because the central meridian +of the translated coordinates will follow the :math:`\beta` meridian it is +necessary to translate the translated system so that the Greenwich meridian +will pass through the center of the projection by offsetting the central meridian. + +The final control for this projection is:: + + +proj=ob_tran +o_proj=moll +o_lat_p=45 +o_lon_p=-90 +lon_0=-90 + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +o_proj=<projection> + + Oblique projection. + +In addition to specifying an oblique projection, *how* to rotate the projection +should be specified. This is done in one of three ways: Define a new pole, +rotate the projection about a given point or define a new "equator" spanned by +two points on the sphere. See the details below. + +New pole +................................................................................ + +.. option:: +o_lat_p=<latitude> + + Latitude of the North pole of the unrotated source CRS, expressed in the rotated geographic CRS. + +.. option:: +o_lon_p=<longitude> + + Longitude of the North pole of the unrotated source CRS, expressed in the rotated geographic CRS. + +Rotate about point +................................................................................ + +.. option:: +o_alpha=<value> + + Angle to rotate the projection with. + +.. option:: +o_lon_c=<value> + + Longitude of the point the projection will be rotated about. + +.. option:: +o_lat_c=<value> + + Latitude of the point the projection will be rotated about. + +New "equator" points +................................................................................ + +.. option:: +o_lon_1=<value> + + Longitude of first point. + +.. option:: +o_lat_1=<value> + + Latitude of first point. + +.. option:: +o_lon_2=<value> + + Longitude of second point. + +.. option:: +o_lat_2=<value> + + Latitude of second point. + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/ocea.rst.txt b/_sources/operations/projections/ocea.rst.txt new file mode 100644 index 00000000..480dfd53 --- /dev/null +++ b/_sources/operations/projections/ocea.rst.txt @@ -0,0 +1,82 @@ +.. _ocea: + +******************************************************************************** +Oblique Cylindrical Equal Area +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | ocea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/ocea.png + :width: 500 px + :align: center + :alt: Oblique Cylindrical Equal Area + + proj-string: ``+proj=ocea`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +For the Oblique Cylindrical Equal Area projection a pole of rotation is needed. +The pole can be defined in two ways: By a point and azimuth or by providing to +points that make up the pole. + +Point & azimuth +................................................................................ + +.. option:: +lonc=<value> + + Longitude of rotational pole point. + +.. option:: +alpha=<value> + + Angle of rotational pole. + +Two points +................................................................................ + +.. option:: +lon_1=<value> + + Longitude of first point. + +.. option:: +lat_1=<value> + + Latitude of first point. + +.. option:: +lon_2=<value> + + Longitude of second point. + +.. option:: +lat_2=<value> + + Latitude of second point. + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/oea.rst.txt b/_sources/operations/projections/oea.rst.txt new file mode 100644 index 00000000..a3db1722 --- /dev/null +++ b/_sources/operations/projections/oea.rst.txt @@ -0,0 +1,54 @@ +.. _oea: + +******************************************************************************** +Oblated Equal Area +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | oea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/oea.png + :width: 500 px + :align: center + :alt: Oblated Equal Area + + proj-string: ``+proj=oea +m=1 +n=2`` + +Described in :cite:`Snyder1988`. + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +m=<value> + +.. option:: +n=<value> + +Optional +-------------------------------------------------------------------------------- + +.. option:: +theta=<value> + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/omerc.rst.txt b/_sources/operations/projections/omerc.rst.txt new file mode 100644 index 00000000..cf9a1af1 --- /dev/null +++ b/_sources/operations/projections/omerc.rst.txt @@ -0,0 +1,173 @@ +.. _omerc: + +******************************************************************************** +Oblique Mercator +******************************************************************************** + +The Oblique Mercator projection is a cylindrical map projection that closes the +gap between the Mercator and the Transverse Mercator projections. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but reasonably accurate only within 15 degrees | +| | of the oblique central line | ++---------------------+----------------------------------------------------------+ +| **Alias** | omerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/omerc.png + :width: 500 px + :align: center + :alt: Oblique Mercator + + proj-string: ``+proj=omerc +lat_1=45 +lat_2=55`` + + +Figuratively, the cylinder used for developing the Mercator projection touches +the planet along the Equator, while that of the Transverse Mercator touches the +planet along a meridian, i.e. along a line perpendicular to the Equator. + +The cylinder for the Oblique Mercator, however, touches the planet along a line +at an arbitrary angle with the Equator. Hence, the Oblique Mercator projection +is useful for mapping areas having their greatest extent along a direction that +is neither north-south, nor east-west. + +The Mercator and the Transverse Mercator projections are both limiting forms of +the Oblique Mercator: The Mercator projection is equivalent to an Oblique Mercator +with central line along the Equator, while the Transverse Mercator is equivalent +to an Oblique Mercator with central line along a meridian. + +For the sphere, the construction of the Oblique Mercator projection can be +imagined as "tilting the cylinder of a plain Mercator projection", +so the cylinder, instead of touching the equator, touches an arbitrary great circle +on the sphere. The great circle is defined by the tilt angle of the central line, +hence putting land masses along that great circle near the centre of the map, +where the Equator would go in the plain Mercator case. + +The ellipsoidal case, developed by Hotine, and refined by Snyder :cite:`Snyder1987` +is more complex, involving initial steps projecting from the ellipsoid to another +curved surface, the "aposphere", then projection from the aposphere to the skew +uv-plane, before finally rectifying the skew uv-plane onto the map XY plane. + + +Usage +######## + +The tilt angle (azimuth) of the central line can be given in two different ways. +In the first case, the azimuth is given directly, using the option :option:`+alpha` +and defining the centre of projection using the options :option:`+lonc` and +:option:`+lat_0`. +In the second case, the azimuth is given indirectly by specifying two points on +the central line, using the options +:option:`+lat_1`, :option:`+lon_1`, :option:`+lat_2`, and :option:`+lon_2`. + +Example: Verify that the Mercator projection is a limiting form of the Oblique +Mercator + +:: + + $ echo 12 55 | proj +proj=merc +ellps=GRS80 + 1335833.89 7326837.71 + + $ echo 12 55 | proj +proj=omerc +lonc=0 +alpha=90 +ellps=GRS80 + 1335833.89 7326837.71 + +Example: Second case - indirectly given azimuth + +:: + + $ echo 12 55 | proj +proj=omerc +lon_1=-1 +lat_1=1 +lon_2=0 +lat_2=0 +ellps=GRS80 + 349567.57 6839490.50 + + +Example: An approximation of the Danish "System 34" from :cite:`Rittri2012` + +:: + + $ echo 10.536498003 56.229892362 | proj +proj=omerc +axis=wnu +lonc=9.46 +lat_0=56.13333333 +x_0=-266906.229 +y_0=189617.957 +k=0.9999537 +alpha=-0.76324 +gamma=0 +ellps=GRS80 + 200000.13 199999.89 + +The input coordinate represents the System 34 datum point "Agri Bavnehoj", with coordinates +(200000, 200000) by definition. So at the datum point, the approximation is off by about 17 cm. +This use case represents a datum shift from a cylinder projection on an old, slightly +misaligned datum, to a similar projection on a modern datum. + + +Parameters +################################################################################ + + +Central point and azimuth method +-------------------------------------------------------------------------------- + +.. option:: +alpha=<value> + + Azimuth of centerline clockwise from north at the center point of the line. + If :option:`+gamma` is not given then :option:`+alpha` determines the value of + :option:`+gamma`. + +.. option:: +gamma=<value> + + Azimuth of centerline clockwise from north of the rectified + bearing of centre line. If :option:`+alpha` is not given, then + :option:`+gamma` is used to determine :option:`+alpha`. + +.. option:: +lonc=<value> + + Longitude of the central point. + +.. option:: +lat_0=<value> + + Latitude of the central point. + +Two point method +-------------------------------------------------------------------------------- + +.. option:: +lon_1=<value> + + Longitude of first point. + +.. option:: +lat_1=<value> + + Latitude of first point. + +.. option:: +lon_2=<value> + + Longitude of second point. + +.. option:: +lat_2=<value> + + Latitude of second point. + +Optional +-------------------------------------------------------------------------------- + +.. option:: +no_rot + + No rectification (not "no rotation" as one may well assume). + Do not take the last step from the skew uv-plane to the map + XY plane. + + .. note:: This option is probably only marginally useful, but remains for (mostly) historical reasons. + +.. option:: +no_off + + Do not offset origin to center of projection. + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/ortel.rst.txt b/_sources/operations/projections/ortel.rst.txt new file mode 100644 index 00000000..f6fa5f3c --- /dev/null +++ b/_sources/operations/projections/ortel.rst.txt @@ -0,0 +1,42 @@ +.. _ortel: + +******************************************************************************** +Ortelius Oval +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | ortel | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/ortel.png + :width: 500 px + :align: center + :alt: Ortelius Oval + + proj-string: ``+proj=ortel`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/ortho.rst.txt b/_sources/operations/projections/ortho.rst.txt new file mode 100644 index 00000000..09107c9d --- /dev/null +++ b/_sources/operations/projections/ortho.rst.txt @@ -0,0 +1,57 @@ +.. _ortho: + +******************************************************************************** +Orthographic +******************************************************************************** + +The orthographic projection is a perspective azimuthal projection centered +around a given latitude and longitude. + ++---------------------+--------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global, although only one hemisphere can be seen at a | +| | time | ++---------------------+--------------------------------------------------------+ +| **Alias** | ortho | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + +.. figure:: ./images/ortho.png + :width: 500 px + :align: center + :alt: Orthographic + + proj-string: ``+proj=ortho`` + + +.. note:: Before PROJ 7.2, only the spherical formulation was implemented. If + wanting to replicate PROJ < 7.2 results with newer versions, the + ellipsoid must be forced to a sphere, for example by adding a ``+f=0`` + parameter. + +This projection method corresponds to ``EPSG:9840``. + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/patterson.rst.txt b/_sources/operations/projections/patterson.rst.txt new file mode 100644 index 00000000..b68a14d0 --- /dev/null +++ b/_sources/operations/projections/patterson.rst.txt @@ -0,0 +1,46 @@ +.. _patterson: + +******************************************************************************** +Patterson +******************************************************************************** + +The Patterson projection is a cylindrical map projection designed for +general-purpose mapmaking. + +See :cite:`Patterson2014` + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | patterson | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/patterson.png + :width: 500 px + :align: center + :alt: Patterson + + proj-string: ``+proj=patterson`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/pconic.rst.txt b/_sources/operations/projections/pconic.rst.txt new file mode 100644 index 00000000..8c486151 --- /dev/null +++ b/_sources/operations/projections/pconic.rst.txt @@ -0,0 +1,50 @@ +.. _pconic: + +******************************************************************************** +Perspective Conic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | pconic | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/pconic.png + :width: 500 px + :align: center + :alt: Perspective Conic + + proj-string: ``+proj=pconic +lat_1=25 +lat_2=75`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/peirce_q.rst.txt b/_sources/operations/projections/peirce_q.rst.txt new file mode 100644 index 00000000..57504032 --- /dev/null +++ b/_sources/operations/projections/peirce_q.rst.txt @@ -0,0 +1,119 @@ +.. _peirce_q: + +******************************************************************************** +Peirce Quincuncial +******************************************************************************** + +The Peirce Quincuncial projection is a conformal map projection +that transforms the circle of the northern hemisphere into a square, +and the southern hemisphere split into four triangles arranged +around the square to form a quincunx. The resulting projection +is a regular diamond shape or can be rotated to form a square. +The resulting tile can be infinitely tessellated. Though this implementation +defaults to a central meridian of 0, it is more common to use a central +meridian of around 25 to optimise the distortions. Peirce's original +published map from 1879 used a central meridian of approx -70. +The diamond and square versions can be produced using the +``+shape=diamond`` and ``+shape=square`` options respectively. +This implementation includes an alternative lateral projection +which places hemispheres side-by-side (``+shape=horizontal`` or +``+shape=vertical``). Combined with a general oblique transformation, +this can be used to produced a Grieger Triptychial projection +(see example below). + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | peirce_q | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/peirce_q_square.png + :width: 500 px + :align: center + :alt: Peirce Quincuncial (Square) + + proj-string: ``+proj=peirce_q +lon_0=25 +shape=square`` + +.. figure:: ./images/peirce_q_diamond.png + :width: 500 px + :align: center + :alt: Peirce Quincuncial (Diamond) + + proj-string: ``+proj=peirce_q +lon_0=25 +shape=diamond`` + +.. figure:: ./images/peirce_q_horizontal.png + :width: 500 px + :align: center + :alt: Peirce Quincuncial (Horizontal) + + proj-string: ``+proj=peirce_q +lon_0=25 +shape=horizontal`` + +.. figure:: ./images/grieger_triptychial.png + :width: 500 px + :align: center + :alt: Grieger Triptychial + + proj-string: ``+proj=pipeline +step +proj=ob_tran +o_proj=peirce_q +o_lat_p=-45 +o_lon_p=45 +o_type=horizontal +o_scrollx=-0.25 +step +proj=affine +s11=-1 +s12=0 +s21=0 +s22=-1`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. option:: +shape=square/diamond/horizontal/vertical/nhemisphere/shemisphere + + .. versionadded:: 9.0 + + *Defaults to diamond.* + + .. warning:: This option was wrongly introduced introduced in 8.2.1 with the + ``type`` name, which was inappropriate as it conflicted with + the ``+type=crs`` general hint. + + Indicates the shape of transformation applied to the southern hemisphere: + ``square`` and ``diamond`` represent the traditional quincuncial form suggested + by Peirce with the southern hemisphere divided into 4 triangles and reflected + outward from the northern hemisphere. The ``square`` shape is rotated by 45 + degrees to produce the conventional square presentation. The origin lies at + the centre of the square or diamond. + + By contrast, the ``horizontal`` and ``vertical`` forms reflect the southern + hemisphere laterally across the x or y axis respectively to produce a rectangular + form. The origin lies at the centre of the rectangle. + + The other two types, ``nhemisphere`` and ``shemisphere``, discard latitudes of less + than 0 or more than 0, respectively, to allow single hemispheres to be selected. + The origin lies at the centre of the square or diamond. + +.. option:: +scrollx=<value> + + For ``horizontal`` shape allows a scalar circular scroll of resulting x coordinates + to shift sections of the projection to the other horizontal side of the map. + + *Defaults to 0.0. Must be a scale between -1.0 and 1.0.* + +.. option:: +scrolly=<value> + + For ``vertical`` shape allows a scalar circular scroll of resulting y coordinates + to shift sections of the projection to the other vertical side of the map. + + *Defaults to 0.0. Must be a scale between -1.0 and 1.0.* + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/poly.rst.txt b/_sources/operations/projections/poly.rst.txt new file mode 100644 index 00000000..67815cca --- /dev/null +++ b/_sources/operations/projections/poly.rst.txt @@ -0,0 +1,44 @@ +.. _poly: + +******************************************************************************** +Polyconic (American) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoconical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | poly | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/poly.png + :width: 500 px + :align: center + :alt: Polyconic (American) + + proj-string: ``+proj=poly`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp1.rst.txt b/_sources/operations/projections/putp1.rst.txt new file mode 100644 index 00000000..e621a3c7 --- /dev/null +++ b/_sources/operations/projections/putp1.rst.txt @@ -0,0 +1,42 @@ +.. _putp1: + +******************************************************************************** +Putnins P1 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp1.png + :width: 500 px + :align: center + :alt: Putnins P1 + + proj-string: ``+proj=putp1`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Putnins P1 projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp2.rst.txt b/_sources/operations/projections/putp2.rst.txt new file mode 100644 index 00000000..c0f0648e --- /dev/null +++ b/_sources/operations/projections/putp2.rst.txt @@ -0,0 +1,42 @@ +.. _putp2: + +******************************************************************************** +Putnins P2 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp2.png + :width: 500 px + :align: center + :alt: Putnins P2 + + proj-string: ``+proj=putp2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp3.rst.txt b/_sources/operations/projections/putp3.rst.txt new file mode 100644 index 00000000..17fd4012 --- /dev/null +++ b/_sources/operations/projections/putp3.rst.txt @@ -0,0 +1,42 @@ +.. _putp3: + +******************************************************************************** +Putnins P3 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp3.png + :width: 500 px + :align: center + :alt: Putnins P3 + + proj-string: ``+proj=putp3`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp3p.rst.txt b/_sources/operations/projections/putp3p.rst.txt new file mode 100644 index 00000000..0e3aed3c --- /dev/null +++ b/_sources/operations/projections/putp3p.rst.txt @@ -0,0 +1,42 @@ +.. _putp3p: + +******************************************************************************** +Putnins P3' +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp3p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp3p.png + :width: 500 px + :align: center + :alt: Putnins P3' + + proj-string: ``+proj=putp3p`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp4p.rst.txt b/_sources/operations/projections/putp4p.rst.txt new file mode 100644 index 00000000..895c55e3 --- /dev/null +++ b/_sources/operations/projections/putp4p.rst.txt @@ -0,0 +1,41 @@ +.. _putp4p: + +******************************************************************************** +Putnins P4' +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp4p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/putp4p.png + :width: 500 px + :align: center + :alt: Putnins P4' + + proj-string: ``+proj=putp4p`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp5.rst.txt b/_sources/operations/projections/putp5.rst.txt new file mode 100644 index 00000000..511b570d --- /dev/null +++ b/_sources/operations/projections/putp5.rst.txt @@ -0,0 +1,42 @@ +.. _putp5: + +******************************************************************************** +Putnins P5 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp5 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp5.png + :width: 500 px + :align: center + :alt: Putnins P5 + + proj-string: ``+proj=putp5`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp5p.rst.txt b/_sources/operations/projections/putp5p.rst.txt new file mode 100644 index 00000000..2150057d --- /dev/null +++ b/_sources/operations/projections/putp5p.rst.txt @@ -0,0 +1,42 @@ +.. _putp5p: + +******************************************************************************** +Putnins P5' +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp5p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp5p.png + :width: 500 px + :align: center + :alt: Putnins P5' + + proj-string: ``+proj=putp5p`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp6.rst.txt b/_sources/operations/projections/putp6.rst.txt new file mode 100644 index 00000000..1ef7718f --- /dev/null +++ b/_sources/operations/projections/putp6.rst.txt @@ -0,0 +1,42 @@ +.. _putp6: + +******************************************************************************** +Putnins P6 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp6 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp6.png + :width: 500 px + :align: center + :alt: Putnins P6 + + proj-string: ``+proj=putp6`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp6p.rst.txt b/_sources/operations/projections/putp6p.rst.txt new file mode 100644 index 00000000..1976bfd0 --- /dev/null +++ b/_sources/operations/projections/putp6p.rst.txt @@ -0,0 +1,42 @@ +.. _putp6p: + +******************************************************************************** +Putnins P6' +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp6p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp6p.png + :width: 500 px + :align: center + :alt: Putnins P6' + + proj-string: ``+proj=putp6p`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/qsc.rst.txt b/_sources/operations/projections/qsc.rst.txt new file mode 100644 index 00000000..d7171fb4 --- /dev/null +++ b/_sources/operations/projections/qsc.rst.txt @@ -0,0 +1,174 @@ +.. _qsc: + +******************************************************************************** +Quadrilateralized Spherical Cube +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | qsc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +The purpose of the Quadrilateralized Spherical Cube (QSC) projection is to project +a sphere surface onto the six sides of a cube: + +.. image:: ../../../images/qsc_concept.jpg + :width: 500 px + :align: center + :alt: Quadrilateralized Spherical Cube + +For this purpose, other alternatives can be used, notably :ref:`gnom` or +:ref:`healpix`. However, QSC projection has the following favorable properties: + +It is an equal-area projection, and at the same time introduces only limited angular +distortions. It treats all cube sides equally, i.e. it does not use different +projections for polar areas and equatorial areas. These properties make QSC +projection a good choice for planetary-scale terrain rendering. Map data can be +organized in quadtree structures for each cube side. See :cite:`LambersKolb2012` for an example. + +The QSC projection was introduced by :cite:`ONeilLaubscher1976`, +building on previous work by :cite:`ChanONeil1975`. For clarity: The +earlier QSC variant described in :cite:`ChanONeil1975` became known as the COBE QSC since it +was used by the NASA Cosmic Background Explorer (COBE) project; it is an approximately +equal-area projection and is not the same as the QSC projection. + +See also :cite:`CalabrettaGreisen2002` Sec. 5.6.2 and 5.6.3 for a description of both and +some analysis. + +In this implementation, the QSC projection projects onto one side of a circumscribed +cube. The cube side is selected by choosing one of the following six projection centers: + ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=0`` | front cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=90`` | right cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=180`` | back cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=-90`` | left cube side | ++-------------------------+--------------------+ +| ``+lat_0=90`` | top cube side | ++-------------------------+--------------------+ +| ``+lat_0=-90`` | bottom cube side | ++-------------------------+--------------------+ + +Furthermore, this implementation allows the projection to be applied to ellipsoids. +A preceding shift to a sphere is performed automatically; see :cite:`LambersKolb2012` for details. + + +Usage +############################################################################### + +The following example uses QSC projection via GDAL to create the six cube side +maps from a world map for the WGS84 ellipsoid:: + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=0" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff frontside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=90" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff rightside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=180" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff backside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=-90" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff leftside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=90 +lon_0=0" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff topside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=-90 +lon_0=0" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff bottomside.tiff + + +Explanation: + +* QSC projection is selected with ``+wktext +proj=qsc``. +* The WGS84 ellipsoid is specified with ``+ellps=WGS84``. +* The cube side is selected with ``+lat_0=... +lon_0=...``. +* The ``-wo`` options are necessary for GDAL to avoid holes in the output maps. +* The ``-te`` option limits the extends of the output map to the major axis diameter + (from -radius to +radius in both x and y direction). These are the dimensions of one side + of the circumscribing cube. + + +The resulting images can be laid out in a grid like below. + + +.. |topside| image:: ../../../images/qsc_topside.jpg + :scale: 50 % + :align: middle + :alt: Top side + +.. |leftside| image:: ../../../images/qsc_leftside.jpg + :scale: 50% + :align: middle + :alt: Left side + +.. |frontside| image:: ../../../images/qsc_frontside.jpg + :scale: 50% + :align: middle + :alt: Front side + +.. |rightside| image:: ../../../images/qsc_rightside.jpg + :scale: 50% + :align: middle + :alt: Right side + +.. |backside| image:: ../../../images/qsc_backside.jpg + :scale: 50% + :align: middle + :alt: Back side + +.. |bottomside| image:: ../../../images/qsc_bottomside.jpg + :scale: 50% + :align: middle + :alt: Bottom side + + ++------------+--------------+-------------+------------+ +| | |topside| | | | ++------------+--------------+-------------+------------+ +| |leftside| | |frontside| | |rightside| | |backside| | ++------------+--------------+-------------+------------+ +| | |bottomside| | | | ++------------+--------------+-------------+------------+ + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. `Wikipedia <https://en.wikipedia.org/wiki/Quadrilateralized_spherical_cube>`_ +#. `NASA <https://lambda.gsfc.nasa.gov/product/cobe/skymap_info_new.cfm>`_ diff --git a/_sources/operations/projections/qua_aut.rst.txt b/_sources/operations/projections/qua_aut.rst.txt new file mode 100644 index 00000000..67a5e5bf --- /dev/null +++ b/_sources/operations/projections/qua_aut.rst.txt @@ -0,0 +1,42 @@ +.. _qua_aut: + +******************************************************************************** +Quartic Authalic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | qua_aut | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/qua_aut.png + :width: 500 px + :align: center + :alt: Quartic Authalic + + proj-string: ``+proj=qua_aut`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Quartic Authalic projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/rhealpix.rst.txt b/_sources/operations/projections/rhealpix.rst.txt new file mode 100644 index 00000000..5a9b99b5 --- /dev/null +++ b/_sources/operations/projections/rhealpix.rst.txt @@ -0,0 +1,75 @@ +.. _rhealpix: + +******************************************************************************** +rHEALPix +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | rhealpix | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. image:: ../../../images/rhealpix.png + :scale: 75% + :alt: rHEALPix + +rHEALPix is a projection based on the HEALPix projection. The implementation of +rHEALPix uses the HEALPix projection. The rHEALPix combines the peaks of the +HEALPix into a square. The square's position can be translated and rotated across +the x-axis which is a novel approach for the rHEALPix projection. The initial +intention of using rHEALPix in the Spatial Computation Engine Science Collaboration +Environment (SCENZGrid). + +Usage +############################################################################### + +To run a rHEALPix projection on a WGS84 ellipsoidal model, use the following +command:: + + proj +proj=rhealpix -f '%.2f' +ellps=WGS84 +south_square=0 +north_square=2 -E << EOF + > 55 12 + > EOF + 55 12 6115727.86 1553840.13 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. option:: +north_square + + Position of the north polar square. Valid inputs are 0--3. + + *Defaults to 0.0.* + +.. option:: +south_square + + Position of the south polar square. Valid inputs are 0--3. + + *Defaults to 0.0.* + + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. `NASA <http://healpix.jpl.nasa.gov/>`_ +#. `Wikipedia <https://en.wikipedia.org/wiki/HEALPix>`_ diff --git a/_sources/operations/projections/robin.rst.txt b/_sources/operations/projections/robin.rst.txt new file mode 100644 index 00000000..5ebdf5e5 --- /dev/null +++ b/_sources/operations/projections/robin.rst.txt @@ -0,0 +1,42 @@ +.. _robin: + +******************************************************************************** +Robinson +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | robin | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/robin.png + :width: 500 px + :align: center + :alt: Robinson + + proj-string: ``+proj=robin`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/rouss.rst.txt b/_sources/operations/projections/rouss.rst.txt new file mode 100644 index 00000000..08fc6e36 --- /dev/null +++ b/_sources/operations/projections/rouss.rst.txt @@ -0,0 +1,44 @@ +.. _rouss: + +******************************************************************************** +Roussilhe Stereographic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | rouss | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/rouss.png + :width: 500 px + :align: center + :alt: Roussilhe Stereographic + + proj-string: ``+proj=rouss`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/rpoly.rst.txt b/_sources/operations/projections/rpoly.rst.txt new file mode 100644 index 00000000..eee66c5e --- /dev/null +++ b/_sources/operations/projections/rpoly.rst.txt @@ -0,0 +1,44 @@ +.. _rpoly: + +******************************************************************************** +Rectangular Polyconic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoconical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | rpoly | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/rpoly.png + :width: 500 px + :align: center + :alt: Rectangular Polyconic + + proj-string: ``+proj=rpoly`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/s2.rst.txt b/_sources/operations/projections/s2.rst.txt new file mode 100644 index 00000000..46ae715e --- /dev/null +++ b/_sources/operations/projections/s2.rst.txt @@ -0,0 +1,120 @@ +.. _s2: + +******************************************************************************** +S2 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | s2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. versionadded:: 8.2 + +The S2 projection, like the Quadrilateralized Spherical Cube (QSC) projection, projects +a sphere surface onto the six sides of a cube: + +.. image:: ../../../images/qsc_concept.jpg + :width: 500 px + :align: center + :alt: Quadrilateralized Spherical Cube + +S2 was created by Google to represent geographic data on the whole earth. The documentation can be found +at `S2 Geometry <https://s2geometry.io/>`_ It works by first +projecting a point on the sphere to a face of the cube. These are called u,v-coordinates, and they are in [-1,1] x [-1,1]. +This step is followed by a non-linear transformation to normalize the area of rectangles on the sphere. There are three +different choices available for this transformation, meaning that S2 is a family of projections. The final output is in +s,t-coordinates, which are in [0,1] x [0,1]. +See the comments in `S2 Code <https://github.com/google/s2geometry/blob/0c4c460bdfe696da303641771f9def900b3e440f/src/s2/s2coords.h#L226>`_ +for an explanation of the tradeoff between speed and area-preservation. Note that the projection is azimuthal when "none" or +"linear" is selected for the area-normalization, but it is not azimuthal when "quadratic" or "tangent" is chosen. See +S2's `Earthcube page <https://s2geometry.io/resources/earthcube>`_ +to visualize the unfolded cube and the orientation of each face. + +In this implementation, the cube side is selected by choosing one of the following six projection centers: + ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=0`` | front cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=90`` | right cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=180`` | back cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=-90`` | left cube side | ++-------------------------+--------------------+ +| ``+lat_0=90`` | top cube side | ++-------------------------+--------------------+ +| ``+lat_0=-90`` | bottom cube side | ++-------------------------+--------------------+ + +The specific transformation can be chosen with the UVtoST parameter: + ++-------------------------+-----------------------------+ +| ``+UVtoST=linear`` | fastest, no normalization | ++-------------------------+-----------------------------+ +| ``+UVtoST=quadratic`` | fast, good normalization | ++-------------------------+-----------------------------+ +| ``+UVtoST=tangent`` | slowest, best normalization | ++-------------------------+-----------------------------+ +| ``+UVtoST=none`` | returns u,v-coordinates | ++-------------------------+-----------------------------+ + +Furthermore, this implementation allows the projection to be applied to ellipsoids. +A preceding shift to a sphere is performed automatically; see :cite:`LambersKolb2012` for details. +The output of the projection is in s,t-coordinates ([0,1] x [0,1]), so only the +eccentricity of the ellipse is taken into account: the absolute value of the axes does +not affect the output. + + +Usage +############################################################################### + +The following example uses S2 on the right face:: + + echo 90 0 | ../bin/proj +proj=s2 +lat_0=0 +lon_0=90 +ellps=WGS84 +UVtoST=linear + + 0.5 0.5 + +Explanation: + +* S2 projection is selected with ``+proj=s2``. +* The WGS84 ellipsoid is specified with ``+ellps=WGS84``. +* The cube side is selected with ``+lat_0=... +lon_0=...``. +* The normalization transformation is selected with ``+UVtoST=...``. + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. option:: +UVtoST=<value> + + The area-normalization transformation. Choose from {linear, quadratic, tangent, none} + + *Defaults to "quadratic".* + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. `S2's Website <https://s2geometry.io/>`_ diff --git a/_sources/operations/projections/sch.rst.txt b/_sources/operations/projections/sch.rst.txt new file mode 100644 index 00000000..f987d75d --- /dev/null +++ b/_sources/operations/projections/sch.rst.txt @@ -0,0 +1,65 @@ +.. _sch: + +******************************************************************************** +Spherical Cross-track Height +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse. | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Alias** | sch | ++---------------------+--------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+--------------------------------------------------------+ +| **Input type** | 3D coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + + proj-string: ``+proj=sch +plat_0=XX +plon_0=XX +phdg_0=XX`` + +The SCH coordinate system is a sensor aligned coordinate system developed at +JPL (Jet Propulsion Laboratory) for radar mapping missions. + +See :cite:`Hensley2002` + + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. option:: +plat_0=<value> + + Peg latitude (in degree) + +.. option:: +plon_0=<value> + + Peg longitude (in degree) + +.. option:: +phdg_0=<value> + + Peg heading (in degree) + +Optional +------------------------------------------------------------------------------- + +.. option:: +h_0=<value> + + Average height (in metre) + + *Defaults to 0.0.* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst diff --git a/_sources/operations/projections/sinu.rst.txt b/_sources/operations/projections/sinu.rst.txt new file mode 100644 index 00000000..6bd059fb --- /dev/null +++ b/_sources/operations/projections/sinu.rst.txt @@ -0,0 +1,56 @@ +.. _sinu: + +******************************************************************************** +Sinusoidal (Sanson-Flamsteed) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | sinu | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/sinu.png + :width: 500 px + :align: center + :alt: Sinusoidal (Sanson-Flamsteed) + + proj-string: ``+proj=sinu`` + +MacBryde and Thomas developed generalized formulas for several of the +pseudocylindricals with sinusoidal meridians: + +.. math:: + + x = C\lambda(m+cos\theta) / ( m + 1) + +.. math:: + y = C\theta + +.. math:: + + C = \sqrt { (m + 1 ) / n } + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Sinusoidal projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/somerc.rst.txt b/_sources/operations/projections/somerc.rst.txt new file mode 100644 index 00000000..f8530d70 --- /dev/null +++ b/_sources/operations/projections/somerc.rst.txt @@ -0,0 +1,30 @@ +.. _somerc: + +******************************************************************************** +Swiss Oblique Mercator +******************************************************************************** + +.. figure:: ./images/somerc.png + :width: 500 px + :align: center + :alt: Swiss Oblique Mercator + + proj-string: ``+proj=somerc`` + + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/stere.rst.txt b/_sources/operations/projections/stere.rst.txt new file mode 100644 index 00000000..06d77f94 --- /dev/null +++ b/_sources/operations/projections/stere.rst.txt @@ -0,0 +1,56 @@ +.. _stere: + +******************************************************************************** +Stereographic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | stere | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/stere.png + :width: 500 px + :align: center + :alt: Stereographic + + proj-string: ``+proj=stere +lat_0=90 +lat_ts=75`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_0.rst + +.. option:: +lat_ts=<value> + + Defines the latitude where scale is not distorted. It is only taken into + account for Polar Stereographic formulations (``+lat_0`` = +/- 90 ), and + then defaults to the ``+lat_0`` value. + If set to a value different from +/- 90, it takes precedence over ``+k_0`` + if both options are used together. + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/sterea.rst.txt b/_sources/operations/projections/sterea.rst.txt new file mode 100644 index 00000000..80666d06 --- /dev/null +++ b/_sources/operations/projections/sterea.rst.txt @@ -0,0 +1,46 @@ +.. _sterea: + +******************************************************************************** +Oblique Stereographic Alternative +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | sterea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/sterea.png + :width: 500 px + :align: center + :alt: Oblique Stereographic Alternative + + proj-string: ``+proj=sterea +lat_0=90`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tcc.rst.txt b/_sources/operations/projections/tcc.rst.txt new file mode 100644 index 00000000..3c5fe8eb --- /dev/null +++ b/_sources/operations/projections/tcc.rst.txt @@ -0,0 +1,42 @@ +.. _tcc: + +******************************************************************************** +Transverse Central Cylindrical +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | tcc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/tcc.png + :width: 500 px + :align: center + :alt: Transverse Central Cylindrical + + proj-string: ``+proj=tcc`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tcea.rst.txt b/_sources/operations/projections/tcea.rst.txt new file mode 100644 index 00000000..028e5c32 --- /dev/null +++ b/_sources/operations/projections/tcea.rst.txt @@ -0,0 +1,44 @@ +.. _tcea: + +******************************************************************************** +Transverse Cylindrical Equal Area +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | tcea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/tcea.png + :width: 500 px + :align: center + :alt: Transverse Cylindrical Equal Area + + proj-string: ``+proj=tcea`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/times.rst.txt b/_sources/operations/projections/times.rst.txt new file mode 100644 index 00000000..33e12148 --- /dev/null +++ b/_sources/operations/projections/times.rst.txt @@ -0,0 +1,43 @@ +.. _times: + +******************************************************************************** +Times +******************************************************************************** + +See :cite:`Snyder1993`, p.213-214. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | times | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/times.png + :width: 500 px + :align: center + :alt: Times + + proj-string: ``+proj=times`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tissot.rst.txt b/_sources/operations/projections/tissot.rst.txt new file mode 100644 index 00000000..814fa637 --- /dev/null +++ b/_sources/operations/projections/tissot.rst.txt @@ -0,0 +1,33 @@ +.. _tissot: + +******************************************************************************** +Tissot +******************************************************************************** + +.. figure:: ./images/tissot.png + :width: 500 px + :align: center + :alt: Tissot + + proj-string: ``+proj=tissot +lat_1=60 +lat_2=65`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tmerc.rst.txt b/_sources/operations/projections/tmerc.rst.txt new file mode 100644 index 00000000..576ad327 --- /dev/null +++ b/_sources/operations/projections/tmerc.rst.txt @@ -0,0 +1,412 @@ +.. _tmerc: + +******************************************************************************** +Transverse Mercator +******************************************************************************** + +The transverse Mercator projection in its various forms is the most widely used projected coordinate system for world topographical and offshore mapping. +It is a conformal projection in which a chosen meridian projects to a +straight line at constant scale. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, with full accuracy within 3900 km | +| | of the central meridian | ++---------------------+----------------------------------------------------------+ +| **Alias** | tmerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. figure:: ./images/tmerc.png + :width: 500 px + :align: center + :alt: Transverse Mercator + + proj-string: ``+proj=tmerc`` + +Usage +##### + + +Prior to the development of the Universal Transverse Mercator coordinate system, several European nations demonstrated the utility of grid-based conformal maps by mapping their territory during the interwar period. +Calculating the distance between two points on these maps could be performed more easily in the field (using the Pythagorean theorem) than was possible using the trigonometric formulas required under the graticule-based system of latitude and longitude. +In the post-war years, these concepts were extended into the Universal Transverse Mercator/Universal Polar Stereographic (UTM/UPS) coordinate system, which is a global (or universal) system of grid-based maps. + +The following table gives special cases of the Transverse Mercator projection. + ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| Projection Name | Areas | Central meridian | Zone width | Scale Factor | ++=====================================+=====================================================+================================+===========================================+==============+ +| Transverse Mercator | World wide | Various | less than 1000 km | Various | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| Transverse Mercator south oriented | Southern Africa | 2° intervals E of 11°E | 2° | 1.000 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| UTM North hemisphere | World wide equator to 84°N | 6° intervals E & W of 3° E & W | Usually 6°, wider for Norway and Svalbard | 0.9996 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| UTM South hemisphere | World wide north of 80°S to equator | 6° intervals E & W of 3° E & W | Always 6° | 0.9996 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| Gauss-Kruger | Former USSR, Yugoslavia, Germany, S. America, China | Various, according to area | Usually less than 6°, often less than 4° | 1.0000 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| Gauss Boaga | Italy | Various, according to area | 6° | 0.9996 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ + + + +Example using Gauss-Kruger on Germany area (aka EPSG:31467) :: + + $ echo 9 51 | proj +proj=tmerc +lat_0=0 +lon_0=9 +k_0=1 +x_0=3500000 +y_0=0 +ellps=bessel +units=m + 3500000.00 5651505.56 + +Example using Gauss Boaga on Italy area (EPSG:3004) :: + + $ echo 15 42 | proj +proj=tmerc +lat_0=0 +lon_0=15 +k_0=0.9996 +x_0=2520000 +y_0=0 +ellps=intl +units=m + 2520000.00 4649858.60 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. option:: +approx + + .. versionadded:: 6.0.0 + + Use the Evenden-Snyder algorithm described below under "Legacy + ellipsoidal form". It is faster than the default algorithm, but is + less accurate and diverges beyond 3° from the central meridian. + +.. option:: +algo=auto/evenden_snyder/poder_engsager + + .. versionadded:: 7.1 + + Selects the algorithm to use. The hardcoded value and the one defined in + :ref:`proj-ini` default to ``poder_engsager``; that is the most precise + one. + + When using auto, a heuristics based on the input coordinate to transform + is used to determine if the faster Evenden-Snyder method can be used, for + faster computation, without causing an error greater than 0.1 mm (for an + ellipsoid of the size of Earth) + + Note that :option:`+approx` and :option:`+algo` are mutually exclusive. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Mathematical definition +####################### + +The formulation given here for the Transverse Mercator projection is due +to Krüger :cite:`Krueger1912` who gave the series expansions accurate to +:math:`n^4`, where :math:`n = (a-b)/(a+b)` is the third flattening. +These series were extended to sixth order by Engsager and Poder in +:cite:`Poder1998` and :cite:`Engsager2007`. This gives full +double-precision accuracy within 3900 km of the central meridian (about +57% of the surface of the earth) :cite:`Karney2011tm`. The error is +less than 0.1 mm within 7000 km of the central meridian (about 89% of +the surface of the earth). + +This formulation consists of three steps: a conformal projection from +the ellipsoid to a sphere, the spherical transverse Mercator +projection, rectifying this projection to give constant scale on the +central meridian. + +The scale on the central meridian is :math:`k_0` and is set by ``+k_0``. + +Option :option:`+lon_0` sets the central meridian; in the formulation +below :math:`\lambda` is the longitude relative to the central meridian. + +Options :option:`+lat_0`, :option:`+x_0`, and :option:`+y_0` serve to +translate the projected coordinates so that at :math:`(\phi, \lambda) = +(\phi_0, \lambda_0)`, the projected coordinates are :math:`(x,y) = +(x_0,y_0)`. To simplify the formulas below, these options are set to +zero (their default values). + +Because the projection is conformal, the formulation is most +conveniently given in terms of complex numbers. In particular, the +unscaled projected coordinates :math:`\eta` (proportional to the +easting, :math:`x`) and :math:`\xi` (proportional to the northing, +:math:`y`) are combined into the single complex quantity :math:`\zeta = +\xi + i\eta`, where :math:`i=\sqrt{-1}`. Then any analytic function +:math:`f(\zeta)` defines a conformal mapping (this follows from the +Cauchy-Riemann conditions). + +Spherical form +************** + +Because the full (ellipsoidal) projection includes the spherical +projection as one of the components, we present the spherical form first +with the coordinates tagged with primes, :math:`\phi'`, +:math:`\lambda'`, :math:`\zeta' = \xi' + i\eta'`, :math:`x'`, +:math:`y'`, so that they can be distinguished from the corresponding +ellipsoidal coordinates (without the primes). The projected coordinates +for the sphere are given by + +.. math:: + + x' = k_0 R \eta';\qquad y' = k_0 R \xi' + +Forward projection +================== + +.. math:: + + \xi' = \tan^{-1}\biggl(\frac{\tan\phi'}{\cos\lambda'}\biggr) + +.. math:: + + \eta' = \sinh^{-1}\biggl(\frac{\sin\lambda'} + {\sqrt{\tan^2\phi' + \cos^2\lambda'}}\biggr) + + +Inverse projection +================== + +.. math:: + + \phi' = \tan^{-1}\biggl(\frac{\sin\xi'} + {\sqrt{\sinh^2\eta' + \cos^2\xi'}}\biggr) + +.. math:: + + \lambda' = \tan^{-1}\biggl(\frac{\sinh\eta'}{\cos\xi'}\biggr) + + +Ellipsoidal form +**************** + +The projected coordinates are given by + +.. math:: + + \zeta = \xi + i\eta;\qquad x = k_0 A \eta;\qquad y = k_0 A \xi + +.. math:: + + A = \frac a{1+n}\biggl(1 + \frac14 n^2 + \frac1{64} n^4 + + \frac1{256}n^6\biggr) + +The series for conversion between ellipsoidal and spherical geographic +coordinates and ellipsoidal and spherical projected coordinates are +given in matrix notation where :math:`\mathbf S(\theta)` and +:math:`\mathbf N` are the row and column vectors of length 6 + +.. math:: + + \mathbf S(\theta) = \begin{pmatrix} + \sin 2\theta & + \sin 4\theta & + \sin 6\theta & + \sin 8\theta & + \sin 10\theta & + \sin 12\theta + \end{pmatrix} + +.. math:: + + \mathbf N = \begin{pmatrix} + n \\ n^2 \\ n^3\\ n^4 \\ n^5 \\ n^6 + \end{pmatrix} + +and :math:`\mathsf C_{\alpha,\beta}` are upper triangular +:math:`6\times6` matrices. + +Relation between geographic coordinates +======================================= + +.. math:: + + \lambda' = \lambda + +.. math:: + + \phi' = \tan^{-1}\sinh\bigl(\sinh^{-1}\tan\phi + - e \tanh^{-1}(e\sin\phi)\bigr) + +Instead of using this analytical formula for :math:`\phi'`, the +conversions between :math:`\phi` and :math:`\phi'` use the series +approximations: + +.. math:: + + \phi' = \phi + \mathbf S(\phi) \cdot \mathsf C_{\chi,\phi} \cdot \mathbf N + +.. math:: + + \phi = \phi' + \mathbf S(\phi') \cdot \mathsf C_{\phi,\chi} \cdot \mathbf N + +.. math:: + + \mathsf C_{\chi,\phi} = \begin{pmatrix} + -2& \frac{2}{3}& \frac{4}{3}& -\frac{82}{45}& \frac{32}{45}& \frac{4642}{4725} \\ + & \frac{5}{3}& -\frac{16}{15}& -\frac{13}{9}& \frac{904}{315}& -\frac{1522}{945} \\ + & & -\frac{26}{15}& \frac{34}{21}& \frac{8}{5}& -\frac{12686}{2835} \\ + & & & \frac{1237}{630}& -\frac{12}{5}& -\frac{24832}{14175} \\ + & & & & -\frac{734}{315}& \frac{109598}{31185} \\ + & & & & & \frac{444337}{155925} \\ + \end{pmatrix} + +.. math:: + + \mathsf C_{\phi,\chi} = \begin{pmatrix} + 2& -\frac{2}{3}& -2& \frac{116}{45}& \frac{26}{45}& -\frac{2854}{675} \\ + & \frac{7}{3}& -\frac{8}{5}& -\frac{227}{45}& \frac{2704}{315}& \frac{2323}{945} \\ + & & \frac{56}{15}& -\frac{136}{35}& -\frac{1262}{105}& \frac{73814}{2835} \\ + & & & \frac{4279}{630}& -\frac{332}{35}& -\frac{399572}{14175} \\ + & & & & \frac{4174}{315}& -\frac{144838}{6237} \\ + & & & & & \frac{601676}{22275} \\ + \end{pmatrix} + +Here :math:`\phi'` is the conformal latitude (sometimes denoted by +:math:`\chi`) and :math:`\mathsf C_{\chi,\phi}` and :math:`\mathsf +C_{\phi,\chi}` are the coefficients in the trigonometric series for +converting between :math:`\phi` and :math:`\chi`. + +Relation between projected coordinates +====================================== + +.. math:: + + \zeta = \zeta' + \mathbf S(\zeta') \cdot \mathsf C_{\mu,\chi} \cdot \mathbf N + +.. math:: + + \zeta' = \zeta + \mathbf S(\zeta) \cdot \mathsf C_{\chi,\mu} \cdot \mathbf N + +.. math:: + + \mathsf C_{\mu,\chi} = \begin{pmatrix} + \frac{1}{2}& -\frac{2}{3}& \frac{5}{16}& \frac{41}{180}& -\frac{127}{288}& \frac{7891}{37800} \\ + & \frac{13}{48}& -\frac{3}{5}& \frac{557}{1440}& \frac{281}{630}& -\frac{1983433}{1935360} \\ + & & \frac{61}{240}& -\frac{103}{140}& \frac{15061}{26880}& \frac{167603}{181440} \\ + & & & \frac{49561}{161280}& -\frac{179}{168}& \frac{6601661}{7257600} \\ + & & & & \frac{34729}{80640}& -\frac{3418889}{1995840} \\ + & & & & & \frac{212378941}{319334400} \\ + \end{pmatrix} + +.. math:: + + \mathsf C_{\chi,\mu} = \begin{pmatrix} + -\frac{1}{2}& \frac{2}{3}& -\frac{37}{96}& \frac{1}{360}& \frac{81}{512}& -\frac{96199}{604800} \\ + & -\frac{1}{48}& -\frac{1}{15}& \frac{437}{1440}& -\frac{46}{105}& \frac{1118711}{3870720} \\ + & & -\frac{17}{480}& \frac{37}{840}& \frac{209}{4480}& -\frac{5569}{90720} \\ + & & & -\frac{4397}{161280}& \frac{11}{504}& \frac{830251}{7257600} \\ + & & & & -\frac{4583}{161280}& \frac{108847}{3991680} \\ + & & & & & -\frac{20648693}{638668800} \\ + \end{pmatrix} + +On the central meridian (:math:`\lambda = \lambda' = 0`), :math:`\zeta' += \phi'` is the conformal latitude :math:`\chi` and :math:`\zeta` plays +the role of the rectifying latitude (sometimes denoted by :math:`\mu`). +:math:`\mathsf C_{\mu,\chi}` and :math:`\mathsf C_{\chi,\mu}` are the +coefficients in the trigonometric series for converting between +:math:`\chi` and :math:`\mu`. + +Legacy ellipsoidal form +*********************** + +The formulas below describe the algorithm used when giving the +:option:`+approx` option. They are originally from :cite:`Snyder1987`, +but here quoted from :cite:`Evenden1995` and :cite:`Evenden2005`. These +are less accurate that the formulation above and are only valid within +about 5 degrees of the central meridian. Here :math:`M(\phi)` is the +meridional distance. + + +Forward projection +================== + +.. math:: + + N = \frac{k_0}{(1 - e^2 \sin^2\phi)^{1/2}} + +.. math:: + + R = \frac{k_0(1-e^2)}{(1-e^2 \sin^2\phi)^{3/2}} + +.. math:: + + t = \tan\phi + +.. math:: + + \eta = \frac{e^2}{1-e^2} \cos^2\phi + +.. math:: + + x &= k_0 \lambda \cos \phi \\ + &+ \frac{k_0 \lambda^3 \cos^3\phi}{3!}(1-t^2+\eta^2) \\ + &+ \frac{k_0 \lambda^5 \cos^5\phi}{5!}(5-18t^2+t^4+14\eta^2-58t^2\eta^2) \\ + &+\frac{k_0 \lambda^7 \cos^7\phi}{7!}(61-479t^2+179t^4-t^6) + +.. math:: + + y &= M(\phi) \\ + &+ \frac{k_0 \lambda^2 \sin\phi \cos \phi}{2!} \\ + &+ \frac{k_0 \lambda^4 \sin\phi \cos^3\phi}{4!}(5-t^2+9\eta^2+4\eta^4) \\ + &+ \frac{k_0 \lambda^6 \sin\phi \cos^5\phi}{6!}(61-58t^2+t^4+270\eta^2-330t^2\eta^2) \\ + &+ \frac{k_0 \lambda^8 \sin\phi \cos^7\phi}{8!}(1385-3111t^2+543t^4-t^6) + +Inverse projection +================== + +.. math:: + + \phi_1 = M^{-1}(y) + +.. math:: + + N_1 = \frac{k_0}{1 - e^2 \sin^2\phi_1)^{1/2}} + +.. math:: + + R_1 = \frac{k_0(1-e^2)}{(1-e^2 \sin^2\phi_1)^{3/2}} + +.. math:: + + t_1 = \tan(\phi_1) + +.. math:: + + \eta_1 = \frac{e^2}{1-e^2} \cos^2\phi_1 + +.. math:: + + \phi &= \phi_1 \\ + &- \frac{t_1 x^2}{2! R_1 N_1} \\ + &+ \frac{t_1 x^4}{4! R_1 N_1^3}(5+3t_1^2+\eta_1^2-4\eta_1^4-9\eta_1^2t_1^2) \\ + &- \frac{t_1 x^6}{6! R_1 N_1^5}(61+90t_1^2+46\eta_1^2+45t_1^4-252t_1^2\eta_1^2) \\ + &+ \frac{t_1 x^8}{8! R_1 N_1^7}(1385+3633t_1^2+4095t_1^4+1575t_1^6) + +.. math:: + + \lambda &= \frac{x}{\cos \phi N_1} \\ + &- \frac{x^3}{3! \cos \phi N_1^3}(1+2t_1^2+\eta_1^2) \\ + &+ \frac{x^5}{5! \cos \phi N_1^5}(5+6\eta_1^2+28t_1^2-3\eta_1^2+8t_1^2\eta_1^2) \\ + &- \frac{x^7}{7! \cos \phi N_1^7}(61+662t_1^2+1320t_1^4+720t_1^6) + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Transverse_Mercator_projection>`_ diff --git a/_sources/operations/projections/tobmerc.rst.txt b/_sources/operations/projections/tobmerc.rst.txt new file mode 100644 index 00000000..7bc5cb95 --- /dev/null +++ b/_sources/operations/projections/tobmerc.rst.txt @@ -0,0 +1,100 @@ +.. _tobmerc: + +******************************************************************************** +Tobler-Mercator +******************************************************************************** + +.. versionadded:: 6.0.0 + +Equal area cylindrical projection with the same latitudinal spacing as +Mercator projection. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical equal area | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical only | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, conventionally truncated at about 80 degrees | +| | north and south | ++---------------------+----------------------------------------------------------+ +| **Alias** | tobmerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/tobmerc.png + :width: 500 px + :align: center + :alt: Tobler-Mercator + + proj-string: ``+proj=tobmerc`` + +Usage +##### + +The inappropriate use of the Mercator projection has declined but still +occasionally occurs. One method of contrasting the Mercator projection is to +present an alternative in the form of an equal area projection. The map +projection derived here is thus not simply a pretty Christmas tree ornament: +it is instead a complement to Mercator's conformal navigation anamorphosis +and can be displayed as an alternative. The equations for the new map +projection preserve the latitudinal stretching of the Mercator while +adjusting the longitudinal spacing. This allows placement of the new map +adjacent to that of Mercator. The surface area, while drastically warped, +maintains the correct magnitude. + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/R.rst + +Mathematical definition +####################### + +The formulas describing the Tobler-Mercator are taken from Waldo Tobler's +article :cite:`Tobler2018` + +Spherical form +************** +For the spherical form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = \cos^2 \phi_{ts} + +Forward projection +================== + +.. math:: + + x = k_0 \lambda + +.. math:: + + y = k_0 \ln \left[ \tan \left(\frac{\pi}{4} + \frac{\phi}{2} \right) \right] + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0} + +.. math:: + + \phi = \frac{\pi}{2} - 2 \arctan \left[ e^{-y/k_0} \right] diff --git a/_sources/operations/projections/tpeqd.rst.txt b/_sources/operations/projections/tpeqd.rst.txt new file mode 100644 index 00000000..fb75a7b1 --- /dev/null +++ b/_sources/operations/projections/tpeqd.rst.txt @@ -0,0 +1,56 @@ +.. _tpeqd: + +******************************************************************************** +Two Point Equidistant +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | tpeqd | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/tpeqd.png + :width: 500 px + :align: center + :alt: Two Point Equidistant + + proj-string: ``+proj=tpeqd +lat_1=60 +lat_2=65`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +lon_1=<value> + + Longitude of first point. + +.. option:: +lat_1=<value> + + Latitude of first point. + +.. option:: +lon_2=<value> + + Longitude of second point. + +.. option:: +lat_2=<value> + + Latitude of second point. + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tpers.rst.txt b/_sources/operations/projections/tpers.rst.txt new file mode 100644 index 00000000..9dd73805 --- /dev/null +++ b/_sources/operations/projections/tpers.rst.txt @@ -0,0 +1,70 @@ +.. _tpers: + +******************************************************************************** +Tilted perspective +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | tpers | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. figure:: ./images/tpers.png + :width: 500 px + :align: center + :alt: Tilted perspective + + proj-string: ``+proj=tpers +h=5500000 +lat_0=40`` + +Tilted Perspective is similar to :ref:`nsper` (``nsper``) in that it simulates a +perspective view from a height. Where ``nsper`` projects onto a plane tangent to +the surface, Tilted Perspective orients the plane towards the direction of the +view. Thus, extra parameters specifying azimuth and tilt are required beyond +`nsper``'s ``h``. As with ``nsper``, ``lat_0`` & ``lon_0`` are +also required for satellite position. + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. include:: ../options/h.rst + +Optional +------------------------------------------------------------------------------- + +.. option:: +azi=<value> + + Bearing in degrees away from north. + + *Defaults to 0.0.* + +.. option:: +tilt=<value> + + Angle in degrees away from nadir. + + *Defaults to 0.0.* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/ups.rst.txt b/_sources/operations/projections/ups.rst.txt new file mode 100644 index 00000000..b652b563 --- /dev/null +++ b/_sources/operations/projections/ups.rst.txt @@ -0,0 +1,31 @@ +.. _ups: + +******************************************************************************** +Universal Polar Stereographic +******************************************************************************** + +.. figure:: ./images/ups.png + :width: 500 px + :align: center + :alt: Universal Polar Stereographic + + proj-string: ``+proj=ups`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +south + + South polar aspect. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/urm5.rst.txt b/_sources/operations/projections/urm5.rst.txt new file mode 100644 index 00000000..4d2dd557 --- /dev/null +++ b/_sources/operations/projections/urm5.rst.txt @@ -0,0 +1,41 @@ +.. _urm5: + +******************************************************************************** +Urmaev V +******************************************************************************** + +.. figure:: ./images/urm5.png + :width: 500 px + :align: center + :alt: Urmaev V + + proj-string: ``+proj=urm5 +n=0.9 +alpha=2 +q=4`` + +Parameters +################################################################################ + +Required parameters +-------------------------------------------------------------------------------- +.. option:: +n=<value> + + Set the :math:`n` constant. Value between 0 and 1. + +Optional parameters +-------------------------------------------------------------------------------- +.. option:: +q=<value> + + Set the :math:`q` constant. + +.. option:: +alpha=<value> + + Set the :math:`\alpha` constant. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/urmfps.rst.txt b/_sources/operations/projections/urmfps.rst.txt new file mode 100644 index 00000000..b1f39b28 --- /dev/null +++ b/_sources/operations/projections/urmfps.rst.txt @@ -0,0 +1,29 @@ +.. _urmfps: + +******************************************************************************** +Urmaev Flat-Polar Sinusoidal +******************************************************************************** + +.. figure:: ./images/urmfps.png + :width: 500 px + :align: center + :alt: Urmaev Flat-Polar Sinusoidal + + proj-string: ``+proj=urmfps +n=0.5`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +n=<value> + + Set the :math:`n` constant. Value between 0 and 1. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/utm.rst.txt b/_sources/operations/projections/utm.rst.txt new file mode 100644 index 00000000..2367cbad --- /dev/null +++ b/_sources/operations/projections/utm.rst.txt @@ -0,0 +1,99 @@ +.. _utm: + +******************************************************************************** +Universal Transverse Mercator (UTM) +******************************************************************************** + +The Universal Transverse Mercator is a system of map projections divided into +sixty zones across the globe, with each zone corresponding to 6 degrees of +longitude. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Transverse cylindrical, conformal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, ellipsoidal only | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Within the used zone, but transformations of coordinates | +| | in adjacent zones can be expected to be accurate as well | ++---------------------+----------------------------------------------------------+ +| **Alias** | utm | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ../../../images/utm_zones.png + :alt: Universal Transverse Mercator (UTM) zones + :figwidth: 100% + :align: center + + UTM zones. + +UTM projections are really the :ref:`Transverse Mercator<tmerc>` +to which specific parameters, such as central meridians, have been applied. +The Earth is divided into 60 zones each generally 6° wide in longitude. +Bounding meridians are evenly divisible by 6°, and zones are +numbered from 1 to 60 proceeding east from the 180th meridian from Greenwich +with minor exceptions :cite:`Snyder1987`. + +Usage +##### + +Convert geodetic coordinate to UTM Zone 32 on the northern hemisphere:: + + $ echo 12 56 | proj +proj=utm +zone=32 + 687071.44 6210141.33 + +Convert geodetic coordinate to UTM Zone 59 on the southern hemisphere:: + + $ echo 174 -44 | proj +proj=utm +zone=59 +south + 740526.32 5123750.87 + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. option:: +zone=<value> + + Select which UTM zone to use. Can be a value between 1-60. + + +Optional +------------------------------------------------------------------------------- + +.. option:: +south + + Add this flag when using the UTM on the southern hemisphere. + +.. option:: +approx + + .. versionadded:: 6.0.0 + + Use faster, less accurate algorithm for the Transverse Mercator. + +.. option:: +algo=auto/evenden_snyder/poder_engsager + + .. versionadded:: 7.1 + + Selects the algorithm to use. The hardcoded value and the one defined in + :ref:`proj-ini` default to ``poder_engsager``, that is the most precise + one. + + When using auto, a heuristics based on the input coordinate to transform + is used to determine if the faster Evenden-Snyder method can be used, for + faster computation, without causing an error greater than 0.1 mm (for an + ellipsoid of the size of Earth) + + Note that :option:`+approx` and :option:`+algo` are mutually exclusive. + +.. include:: ../options/ellps.rst + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>`_ diff --git a/_sources/operations/projections/vandg.rst.txt b/_sources/operations/projections/vandg.rst.txt new file mode 100644 index 00000000..32366534 --- /dev/null +++ b/_sources/operations/projections/vandg.rst.txt @@ -0,0 +1,42 @@ +.. _vandg: + +******************************************************************************** +van der Grinten (I) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vandg | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vandg.png + :width: 500 px + :align: center + :alt: van der Grinten (I) + + proj-string: ``+proj=vandg`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/vandg2.rst.txt b/_sources/operations/projections/vandg2.rst.txt new file mode 100644 index 00000000..dee18774 --- /dev/null +++ b/_sources/operations/projections/vandg2.rst.txt @@ -0,0 +1,42 @@ +.. _vandg2: + +******************************************************************************** +van der Grinten II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vandg2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vandg2.png + :width: 500 px + :align: center + :alt: van der Grinten II + + proj-string: ``+proj=vandg2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/vandg3.rst.txt b/_sources/operations/projections/vandg3.rst.txt new file mode 100644 index 00000000..9f57f320 --- /dev/null +++ b/_sources/operations/projections/vandg3.rst.txt @@ -0,0 +1,42 @@ +.. _vandg3: + +******************************************************************************** +van der Grinten III +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vandg3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vandg3.png + :width: 500 px + :align: center + :alt: van der Grinten III + + proj-string: ``+proj=vandg3`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/vandg4.rst.txt b/_sources/operations/projections/vandg4.rst.txt new file mode 100644 index 00000000..e2215c91 --- /dev/null +++ b/_sources/operations/projections/vandg4.rst.txt @@ -0,0 +1,42 @@ +.. _vandg4: + +******************************************************************************** +van der Grinten IV +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vandg4 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vandg4.png + :width: 500 px + :align: center + :alt: van der Grinten IV + + proj-string: ``+proj=vandg4`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/vitk1.rst.txt b/_sources/operations/projections/vitk1.rst.txt new file mode 100644 index 00000000..c2baf2bf --- /dev/null +++ b/_sources/operations/projections/vitk1.rst.txt @@ -0,0 +1,50 @@ +.. _vitk1: + +******************************************************************************** +Vitkovsky I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vitk1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vitk1.png + :width: 500 px + :align: center + :alt: Vitkovsky I + + proj-string: ``+proj=vitk1 +lat_1=45 +lat_2=55`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag1.rst.txt b/_sources/operations/projections/wag1.rst.txt new file mode 100644 index 00000000..72c65ab2 --- /dev/null +++ b/_sources/operations/projections/wag1.rst.txt @@ -0,0 +1,44 @@ +.. _wag1: + +******************************************************************************** +Wagner I (Kavrayskiy VI) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag1.png + :width: 500 px + :align: center + :alt: Wagner I (Kavrayskiy VI) + + proj-string: ``+proj=wag1`` + +.. note:: This projection name may also be transliterated as Kavraisky VI. + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag2.rst.txt b/_sources/operations/projections/wag2.rst.txt new file mode 100644 index 00000000..60fa7789 --- /dev/null +++ b/_sources/operations/projections/wag2.rst.txt @@ -0,0 +1,50 @@ +.. _wag2: + +******************************************************************************** +Wagner II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag2.png + :width: 500 px + :align: center + :alt: Wagner II + + proj-string: ``+proj=wag2`` + +.. math:: + + x &= 0.92483 \lambda \cos \theta + + y &= 1.38725\theta + + \sin \theta &= 0.88022 \sin(0.8855\phi) + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag3.rst.txt b/_sources/operations/projections/wag3.rst.txt new file mode 100644 index 00000000..6f3dcbb6 --- /dev/null +++ b/_sources/operations/projections/wag3.rst.txt @@ -0,0 +1,50 @@ +.. _wag3: + +******************************************************************************** +Wagner III +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag3.png + :width: 500 px + :align: center + :alt: Wagner III + + proj-string: ``+proj=wag3`` + +.. math:: + + x &= [\cos\phi_{ts} / \cos ( 2\phi_{ts} / 3)] \lambda \cos (2\phi /3) + + y = \phi + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag4.rst.txt b/_sources/operations/projections/wag4.rst.txt new file mode 100644 index 00000000..a709acfa --- /dev/null +++ b/_sources/operations/projections/wag4.rst.txt @@ -0,0 +1,42 @@ +.. _wag4: + +******************************************************************************** +Wagner IV +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag4 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag4.png + :width: 500 px + :align: center + :alt: Wagner IV + + proj-string: ``+proj=wag4`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag5.rst.txt b/_sources/operations/projections/wag5.rst.txt new file mode 100644 index 00000000..083b5ec6 --- /dev/null +++ b/_sources/operations/projections/wag5.rst.txt @@ -0,0 +1,42 @@ +.. _wag5: + +******************************************************************************** +Wagner V +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag5 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag5.png + :width: 500 px + :align: center + :alt: Wagner V + + proj-string: ``+proj=wag5`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag6.rst.txt b/_sources/operations/projections/wag6.rst.txt new file mode 100644 index 00000000..db7c7421 --- /dev/null +++ b/_sources/operations/projections/wag6.rst.txt @@ -0,0 +1,42 @@ +.. _wag6: + +******************************************************************************** +Wagner VI +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag6 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag6.png + :width: 500 px + :align: center + :alt: Wagner VI + + proj-string: ``+proj=wag6`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Wagner VI projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag7.rst.txt b/_sources/operations/projections/wag7.rst.txt new file mode 100644 index 00000000..bf99d85b --- /dev/null +++ b/_sources/operations/projections/wag7.rst.txt @@ -0,0 +1,29 @@ +.. _wag7: + +******************************************************************************** +Wagner VII +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag7 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag7.png + :width: 500 px + :align: center + :alt: Wagner VII + + proj-string: ``+proj=wag7`` diff --git a/_sources/operations/projections/webmerc.rst.txt b/_sources/operations/projections/webmerc.rst.txt new file mode 100644 index 00000000..55199b24 --- /dev/null +++ b/_sources/operations/projections/webmerc.rst.txt @@ -0,0 +1,100 @@ +.. _webmerc: + +******************************************************************************** +Web Mercator / Pseudo Mercator +******************************************************************************** + +.. versionadded:: 5.1.0 + +The Web Mercator / Pseudo Mercator projection is a cylindrical map projection. +This is a variant of the regular :ref:`merc` projection, except that the computation +is done on a sphere, using the semi-major axis of the ellipsoid. + +From `Wikipedia <https://en.wikipedia.org/wiki/Web_Mercator>`_: + + This projection is widely used by the Web Mercator, Google Web Mercator, + Spherical Mercator, WGS 84 Web Mercator[1] or WGS 84/Pseudo-Mercator is a + variant of the Mercator projection and is the de facto standard for Web + mapping applications. [...] + It is used by virtually all major online map providers [...] + Its official EPSG identifier is EPSG:3857, although others have been used + historically. + + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical (non conformant if used with ellipsoid) | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | webmerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +Usage +######## + +Example:: + + $ echo 2 49 | proj +proj=webmerc +datum=WGS84 + 222638.98 6274861.39 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional, except the ellipsoid + definition, which is WGS84 for the typical use case of EPSG:3857. + In which case, the other parameters are set to their default 0 value. + +.. include:: ../options/ellps.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Mathematical definition +####################### + +The formulas describing the Mercator projection are all taken from G. Evenden's libproj manuals :cite:`Evenden2005`. + +Forward projection +================== + +.. math:: + + x = \lambda + +.. math:: + + y = \ln \left[ \tan \left(\frac{\pi}{4} + \frac{\phi}{2} \right) \right] + + +Inverse projection +================== + +.. math:: + + \lambda = {x} + +.. math:: + + \phi = \frac{\pi}{2} - 2 \arctan \left[ e^{-y} \right] + + + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Web_Mercator>`_ + + + diff --git a/_sources/operations/projections/weren.rst.txt b/_sources/operations/projections/weren.rst.txt new file mode 100644 index 00000000..6c7afdad --- /dev/null +++ b/_sources/operations/projections/weren.rst.txt @@ -0,0 +1,42 @@ +.. _weren: + +******************************************************************************** +Werenskiold I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | weren | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/weren.png + :width: 500 px + :align: center + :alt: Werenskiold I + + proj-string: ``+proj=weren`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wink1.rst.txt b/_sources/operations/projections/wink1.rst.txt new file mode 100644 index 00000000..801bfad2 --- /dev/null +++ b/_sources/operations/projections/wink1.rst.txt @@ -0,0 +1,44 @@ +.. _wink1: + +******************************************************************************** +Winkel I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wink1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wink1.png + :width: 500 px + :align: center + :alt: Winkel I + + proj-string: ``+proj=wink1`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wink2.rst.txt b/_sources/operations/projections/wink2.rst.txt new file mode 100644 index 00000000..059a7efa --- /dev/null +++ b/_sources/operations/projections/wink2.rst.txt @@ -0,0 +1,44 @@ +.. _wink2: + +******************************************************************************** +Winkel II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wink2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wink2.png + :width: 500 px + :align: center + :alt: Winkel II + + proj-string: ``+proj=wink2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wintri.rst.txt b/_sources/operations/projections/wintri.rst.txt new file mode 100644 index 00000000..8534c92c --- /dev/null +++ b/_sources/operations/projections/wintri.rst.txt @@ -0,0 +1,44 @@ +.. _wintri: + +******************************************************************************** +Winkel Tripel +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoazimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wintri | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wintri.png + :width: 500 px + :align: center + :alt: Winkel Tripel + + proj-string: ``+proj=wintri`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/transformations/affine.rst.txt b/_sources/operations/transformations/affine.rst.txt new file mode 100644 index 00000000..d2a4e26b --- /dev/null +++ b/_sources/operations/transformations/affine.rst.txt @@ -0,0 +1,123 @@ +.. _affine: + +================================================================================ +Affine transformation +================================================================================ + +.. versionadded:: 6.0.0 + +The affine transformation applies translation and scaling/rotation terms on the +x,y,z coordinates, and translation and scaling on the temporal coordinate. + ++---------------------+----------------------------------------------------------+ +| **Alias** | affine | ++---------------------+----------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+----------------------------------------------------------+ +| **Input type** | XYZT | ++---------------------+----------------------------------------------------------+ +| **output type** | XYZT | ++---------------------+----------------------------------------------------------+ + +By default, the parameters are set for an identity transforms. The transformation +is reversible unless the determinant of the sji matrix is 0, or `tscale` is 0 + + +Parameters +################################################################################ + +Optional +------------------------------------------------------------------------------- + +.. option:: +xoff=<value> + + Offset in X. Default value: 0 + +.. option:: +yoff=<value> + + Offset in Y. Default value: 0 + +.. option:: +zoff=<value> + + Offset in Z. Default value: 0 + +.. option:: +toff=<value> + + Offset in T. Default value: 0 + +.. option:: +s11=<value> + + Rotation/scaling term. Default value: 1 + +.. option:: +s12=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s13=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s21=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s22=<value> + + Rotation/scaling term. Default value: 1 + +.. option:: +s23=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s31=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s32=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s33=<value> + + Rotation/scaling term. Default value: 1 + +.. option:: +tscale=<value> + + Time scaling term. Default value: 1 + + + +Mathematical description ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. math:: + :label: formula + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + T \\ + \end{bmatrix}^{dest} = + \begin{bmatrix} + xoff \\ + yoff \\ + zoff \\ + toff \\ + \end{bmatrix} + + \begin{bmatrix} + s11 & s12 & s13 & 0 \\ + s21 & s22 & s23 & 0 \\ + s31 & s32 & s33 & 0 \\ + 0 & 0 & 0 & tscale \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + T \\ + \end{bmatrix}^{source} + \end{align} + + diff --git a/_sources/operations/transformations/defmodel.rst.txt b/_sources/operations/transformations/defmodel.rst.txt new file mode 100644 index 00000000..77906924 --- /dev/null +++ b/_sources/operations/transformations/defmodel.rst.txt @@ -0,0 +1,63 @@ +.. _defmodel: + +================================================================================ +Multi-component time-based deformation model +================================================================================ + +.. versionadded:: 7.1.0 + ++---------------------+--------------------------------------------------------------------+ +| **Alias** | defmodel | ++---------------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic or projected coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++---------------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic or projected coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++---------------------+--------------------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------------------+ +| **Available forms** | Forward and inverse | ++---------------------+--------------------------------------------------------------------+ + +The defmodel transformation can be used to represent most deformation models +currently in use, in particular for areas subject to complex deformation, including +large scale secular crustal deformation near plate boundaries and vertical deformation +due to Glacial Isostatic Adjustment (GIA). These can often be represented by a constant +velocity model. Additionally, many areas suffer episodic deformation events such as +earthquakes and aseismic slow slip event. + +The transformation relies on a "master" JSON file, describing general metadata on +the deformation model, its spatial and temporal extent, and listing spatial +components whose values are stored in :ref:`Geodetic TIFF grids (GTG) <geodetictiffgrids>`. +The valuation of each component is modulated by a time function (constant, step, +reverse step, velocity, piecewise, exponential). + +All details on the content of this JSON file are given in the `Proposal for encoding +of a Deformation Model <https://github.com/linz/deformation-model-format/blob/master/doc/JsonGeotiffDeformationModelFormat_20200501.pdf>`__ + +If input coordinates are given in the geographic domain (resp. projected domain), +the output will also be in the geographic domain (resp. projected domain). +The domain should be the corresponding to the source_crs metadata of the model. + +This transformation is a generalization of the :ref:`Kinematic datum shifting utilizing a deformation model <deformation>` transformation. + +Parameters +------------------------------------------------------------------------------- + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +model=<filename> + + Filename to the JSON master file for the deformation model. + + +Example +------------------------------------------------------------------------------- + +Transforming a point with the LINZ NZGD2000 deformation model: + +:: + + echo 166.7133850980 -44.5105886020 293.3700 2007.689 | cct +proj=defmodel +model=nzgd2000-20180701.json diff --git a/_sources/operations/transformations/deformation.rst.txt b/_sources/operations/transformations/deformation.rst.txt new file mode 100644 index 00000000..84b87949 --- /dev/null +++ b/_sources/operations/transformations/deformation.rst.txt @@ -0,0 +1,229 @@ +.. _deformation: + +================================================================================ +Kinematic datum shifting utilizing a deformation model +================================================================================ + +.. versionadded:: 5.0.0 + +Perform datum shifts means of a deformation/velocity model. + ++-----------------+--------------------------------------------------------------------+ +| **Alias** | deformation | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+--------------------------------------------------------------------+ +| **Domain** | 4D | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates | ++-----------------+--------------------------------------------------------------------+ + + +The deformation operation is used to adjust coordinates for intraplate deformations. +Usually the transformation parameters for regional plate-fixed reference frames such as +the ETRS89 does not take intraplate deformation into account. It is assumed that +tectonic plate of the region is rigid. Often times this is true, but near the plate +boundary and in areas with post-glacial uplift the assumption breaks. Intraplate +deformations can be modelled and then applied to the coordinates so that +they represent the physical world better. In PROJ this is done with the deformation +operation. + +The horizontal grid is stored in CTable2 format and the vertical grid is stored in the +GTX format. Both grids are expected to contain grid-values in units of +mm/year. GDAL both reads and writes both file formats. Using GDAL for +construction of new grids is recommended. + +Starting with PROJ 7.0, use of a GeoTIFF format is recommended to store both +the horizontal and vertical velocities. + +More complex deformations can be done with the :ref:`Multi-component time-based deformation model <defmodel>` transformation. + +Example +------------------------------------------------------------------------------- + +In :cite:`Hakli2016` coordinate transformation including a deformation model is described. +The paper describes how coordinates from the global ITRFxx frames are transformed to the +local Nordic realisations of ETRS89. Scandinavia is an area with significant post-glacial +rebound. The deformations from the post-glacial uplift is not accounted for in the +official ETRS89 transformations so in order to get accurate transformations in the Nordic +countries it is necessary to apply the deformation model. The transformation from ITRF2008 +to the Danish realisation of ETRS89 is in PROJ described as:: + + + proj = pipeline ellps = GRS80 + # ITRF2008@t_obs -> ITRF2000@t_obs + step init = ITRF2008:ITRF2000 + # ITRF2000@t_obs -> ETRF2000@t_obs + step proj=helmert t_epoch = 2000.0 convention=position_vector + x = 0.054 rx = 0.000891 drx = 8.1e-05 + y = 0.051 ry = 0.00539 dry = 0.00049 + z = -0.048 rz = -0.008712 drz = -0.000792 + # ETRF2000@t_obs -> NKG_ETRF00@2000.0 + step proj = deformation t_epoch = 2000.0 + grids = ./eur_nkg_nkgrf03vel_realigned.tif + inv + # NKG_ETRF@2000.0 -> ETRF92@2000.0 + step proj=helmert convention=position_vector s = -0.009420e + x = 0.03863 rx = 0.00617753 + y = 0.147 ry = 5.064e-05 + z = 0.02776 rz = 4.729e-05 + # ETRF92@2000.0 -> ETRF92@1994.704 + step proj = deformation dt = -5.296 + grids = ./eur_nkg_nkgrf03vel_realigned.tif + +From this we can see that the transformation from ITRF2008 to the Danish realisation of +ETRS89 is a combination of Helmert transformations and adjustments with a deformation +model. The first use of the deformation operation is:: + + proj = deformation t_epoch = 2000.0 grids = ./eur_nkg_nkgrf03vel_realigned.tif + +Here we set the central epoch of the transformation, 2000.0. The observation epoch +is expected as part of the input coordinate tuple. The deformation model is +described by two grids, specified with :option:`+xy_grids` and :option:`+z_grids`. +The first is the horizontal part of the model and the second is the vertical +component. + +Parameters +------------------------------------------------------------------------------- + +.. option:: +xy_grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an ``@`` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids for the horizontal component of a deformation model is expected to be + in CTable2 format. + + .. note:: :option:`+xy_grids` is mutually exclusive with :option:`+grids` + +.. option:: +z_grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an `@` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids for the vertical component of a deformation model is expected to be + in either GTX format. + + .. note:: :option:`+z_grids` is mutually exclusive with :option:`+grids` + +.. option:: +grids=<list> + + .. versionadded:: 7.0.0 + + Comma-separated list of grids to load. If a grid is prefixed by an `@` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids should be in GeoTIFF format with the first 3 components being + respectively the easting, northing and up velocities in mm/year. + Setting the Description and Unit Type GDAL band metadata items is strongly + recommended, so that gdalinfo reports: + + :: + + Band 1 Block=... Type=Float32, ColorInterp=Gray + Description = east_velocity + Unit Type: mm/year + Band 2 Block=... Type=Float32, ColorInterp=Undefined + Description = north_velocity + Unit Type: mm/year + Band 3 Block=... Type=Float32, ColorInterp=Undefined + Description = up_velocity + Unit Type: mm/year + + .. note:: :option:`+grids` is mutually exclusive with :option:`+xy_grids` + and :option:`+z_grids` + +.. option:: +t_epoch=<value> + + Central epoch of transformation given in decimalyears. Will be used in + conjunction with the observation time from the input coordinate to + determine :math:`dt` as used in eq. :eq:`apply_velocity` below. + + .. note:: :option:`+t_epoch` is mutually exclusive with :option:`+dt` + +.. option:: +dt=<value> + + .. versionadded:: 6.0.0 + + :math:`dt` as used in eq. :eq:`apply_velocity` below. Is useful when + no observation time is available in the input coordinate or when + a deformation for a specific timespan needs to be applied in a + transformation. :math:`dt` is given in units of decimalyears. + + .. note:: :option:`+dt` is mutually exclusive with :option:`+t_epoch` + +Mathematical description +------------------------------------------------------------------------------- + +Mathematically speaking, application of a deformation model is simple. The deformation model is +represented as a grid of velocities in three dimensions. Coordinate corrections are +applied in cartesian space. For a given coordinate, :math:`(X, Y, Z)`, velocities +:math:`(V_X, V_Y, V_Z)` can be interpolated from the gridded model. The time span +between :math:`t_{obs}` and :math:`t_c` determine the magnitude of the coordinate +correction as seen in eq. :eq:`apply_velocity` below. + +.. math:: + :label: apply_velocity + + \begin{align} + \begin{pmatrix} + X \\ + Y \\ + Z \\ + \end{pmatrix}_B = + \begin{pmatrix} + X \\ + Y \\ + Z \\ + \end{pmatrix}_A + + (t_{obs} - t_c) + \begin{pmatrix} + V_X \\ + V_Y \\ + V_Z \\ + \end{pmatrix} + \end{align} + +Corrections are done in cartesian space. + +Coordinates of the gridded model are in ENU (east, north, up) space because it +would otherwise require an enormous 3 dimensional grid to handle the corrections +in cartesian space. Keeping the correction in lat/long space reduces the +complexity of the grid significantly. Consequently though, the input coordinates +needs to be converted to lat/long space when searching for corrections in the +grid. This is done with the :ref:`cart<cart>` operation. The converted grid +corrections can then be applied to the input coordinates in cartesian space. The +conversion from ENU space to cartesian space is done in the following way: + +.. math:: + :label: enu2xyz + + \begin{align} + \begin{pmatrix} + X \\ + Y \\ + Z \\ + \end{pmatrix} = + \begin{pmatrix} + -\sin\phi \cos\lambda N - \sin\lambda E + \cos\phi \cos\lambda U \\ + -\sin\phi \sin\lambda N + \sin\lambda E + \cos\phi \sin\lambda U \\ + \cos\phi N + \sin\phi U \\ + \end{pmatrix} + \end{align} + +where :math:`\phi` and :math:`\lambda` are the latitude and longitude of the coordinate +that is searched for in the grid. :math:`(E, N, U)` are the grid values in ENU-space and +:math:`(X, Y, Z)` are the corrections converted to cartesian space. + + +See also +----------------------------------------------------------------------------- + +#. :ref:`Behavioural changes from version 5 to 6<differences_deformation>` diff --git a/_sources/operations/transformations/geogoffset.rst.txt b/_sources/operations/transformations/geogoffset.rst.txt new file mode 100644 index 00000000..6ca4f64c --- /dev/null +++ b/_sources/operations/transformations/geogoffset.rst.txt @@ -0,0 +1,70 @@ +.. _geogoffset: + +================================================================================ +Geographic offsets +================================================================================ + +.. versionadded:: 6.0.0 + +The Geographic offsets transformation adds an offset to the geographic longitude, +latitude coordinates, and an offset to the ellipsoidal height. + ++---------------------+----------------------------------------------------------+ +| **Alias** | geogoffset | ++---------------------+----------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical) | ++---------------------+----------------------------------------------------------+ +| **output type** | Geodetic coordinates (horizontal), meters (vertical) | ++---------------------+----------------------------------------------------------+ + +This method is normally only used when low accuracy is tolerated. It is documented +as coordinate operation method code 9619 (for geographic 2D) and 9660 (for +geographic 3D) in the EPSG dataset (:cite:`IOGP2018`) + +It can also be used to implement the method Geographic2D with Height Offsets +(code 9618) by noting that the input vertical component is a gravity-related +height and the output vertical component is the ellipsoid height (dh being +the geoid undulation). + +It can also be used to implement the method Vertical offset (code 9616) + +The reverse transformation simply consists in subtracting the offsets. + +This method is a conveniency wrapper for the more general :ref:`affine`. + +Examples +############################################################################### + +Geographic offset from the old Greek geographic 2D CRS to the newer GGRS87 CRS:: + + proj=geogoffset dlon=0.28 dlat=-5.86 + +Conversion from Tokyo + JSLD69 height to WGS 84:: + + proj=geogoffset dlon=-13.97 dlat=7.94 dh=26.9 + +Conversion from Baltic 1977 height to Black Sea height:: + + proj=geogoffset dh=0.4 + + +Parameters +################################################################################ + +Optional +------------------------------------------------------------------------------- + +.. option:: +dlon=<value> + + Offset in longitude, expressed in arc-second, to add. + +.. option:: +dlat=<value> + + Offset in latitude, expressed in arc-second, to add. + +.. option:: +dh=<value> + + Offset in height, expressed in meter, to add. + diff --git a/_sources/operations/transformations/helmert.rst.txt b/_sources/operations/transformations/helmert.rst.txt new file mode 100644 index 00000000..c0f6934f --- /dev/null +++ b/_sources/operations/transformations/helmert.rst.txt @@ -0,0 +1,482 @@ +.. _helmert: + +================================================================================ +Helmert transform +================================================================================ + +.. versionadded:: 5.0.0 + +The Helmert transformation changes coordinates from one reference frame to +another by means of 3-, 4-and 7-parameter shifts, or one of their 6-, 8- and +14-parameter kinematic counterparts. + + ++-----------------+-------------------------------------------------------------------+ +| **Alias** | helmert | ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 2D, 3D and 4D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ + +The Helmert transform, in all its various incarnations, is used to perform reference +frame shifts. The transformation operates in cartesian space. It can be used to transform +planar coordinates from one datum to another, transform 3D cartesian +coordinates from one static reference frame to another or it can be used to do fully +kinematic transformations from global reference frames to local static frames. + +All of the parameters described in the table above are marked as optional. This is true +as long as at least one parameter is defined in the setup of the transformation. +The behavior of the transformation depends on which parameters are used in the setup. +For instance, if a rate of change parameter is specified a kinematic version of the +transformation is used. + +The kinematic transformations require an observation time of the coordinate, as well +as a central epoch for the transformation. The latter is usually documented +alongside the rest of the transformation parameters for a given transformation. +The central epoch is controlled with the parameter `t_epoch`. The observation +time is given as part of the coordinate when using PROJ's 4D-functionality. + +Examples ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert: + +:: + + proj=helmert convention=coordinate_frame x=-9597.3572 y=.6112 s=0.304794780637 theta=-1.244048 + +Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters: + +:: + + proj=helmert convention=coordinate_frame x=0.67678 y=0.65495 z=-0.52827 + rx=-0.022742 ry=0.012667 rz=0.022704 s=-0.01070 + +Transformation from `ITRF2000` to `ITRF93` using 15 parameters: + +:: + + proj=helmert convention=position_vector + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + rx=-0.00039 ry=0.00080 rz=-0.00114 + drx=-0.00011 dry=-0.00019 drz=0.00007 + t_epoch=1988.0 + +Parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. note:: + + All parameters are optional but at least one should be used, otherwise the + operation will return the coordinates unchanged. + +.. option:: +convention=coordinate_frame/position_vector + + .. versionadded:: 5.2.0 + + Indicates the convention to express the rotational terms when a 3D-Helmert / + 7-parameter more transform is involved. As soon as a rotational parameter + is specified (one of ``rx``, ``ry``, ``rz``, ``drx``, ``dry``, ``drz``), + ``convention`` is required. + + The two conventions are equally popular and a frequent source of confusion. + The coordinate frame convention is also described as an clockwise + rotation of the coordinate frame. It corresponds to EPSG method code + 1032 (in the geocentric domain) or 9607 (in the geographic domain) + The position vector convention is also described as an anticlockwise + (counter-clockwise) rotation of the coordinate frame. + It corresponds to as EPSG method code 1033 (in the geocentric domain) or + 9606 (in the geographic domain). + + This parameter is ignored when only a 3-parameter + (translation terms only: ``x``, ``y``, ``z``) , 4-parameter (3-parameter + and ``theta``) or 6-parameter (3-parameter and their derivative terms) + is used. + + The result obtained with parameters specified in a given convention + can be obtained in the other convention by negating the rotational parameters + (``rx``, ``ry``, ``rz``, ``drx``, ``dry``, ``drz``) + + .. note:: This parameter obsoletes ``transpose`` which was present in + PROJ 5.0 and 5.1, and is forbidden starting with PROJ 5.2 + +.. option:: +x=<value> + + Translation of the x-axis given in meters. + +.. option:: +y=<value> + + Translation of the y-axis given in meters. + +.. option:: +z=<value> + + Translation of the z-axis given in meters. + +.. option:: +s=<value> + + Scale factor given in ppm. + +.. option:: +rx=<value> + + X-axis rotation in the 3D Helmert given arc seconds. + + +.. option:: +ry=<value> + + Y-axis rotation in the 3D Helmert given in arc seconds. + +.. option:: +rz=<value> + + Z-axis rotation in the 3D Helmert given in arc seconds. + + +.. option:: +theta=<value> + + Rotation angle in the 2D Helmert given in arc seconds. + +.. option:: +dx=<value> + + Translation rate of the x-axis given in m/year. + +.. option:: +dy=<value> + + Translation rate of the y-axis given in m/year. + +.. option:: +dz=<value> + + Translation rate of the z-axis given in m/year. + +.. option:: +ds=<value> + + Scale rate factor given in ppm/year. + +.. option:: +drx=<value> + + Rotation rate of the x-axis given in arc seconds/year. + +.. option:: +dry=<value> + + Rotation rate of the y-axis given in arc seconds/year. + +.. option:: +drz=<value> + + Rotation rate of the y-axis given in arc seconds/year. + +.. option:: +t_epoch=<value> + + Central epoch of transformation given in decimalyear. Only used + spatiotemporal transformations. + +.. option:: +exact + + Use exact transformation equations. + + See :eq:`rot_exact` + +.. option:: +transpose + + .. deprecated:: 5.2.0 (removed) + + Transpose rotation matrix and follow the **Position Vector** rotation + convention. If :option:`+transpose` is not added the **Coordinate Frame** + rotation convention is used. + + + +Mathematical description ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In the notation used below, :math:`\hat{P}` is the rate of change of a given transformation +parameter :math:`P`. :math:`\dot{P}` is the kinematically adjusted version of :math:`P`, +described by + +.. math:: + :label: propagation + + \dot{P}= P + \hat{P}\left(t - t_{central}\right) + +where :math:`t` is the observation time of the coordinate and :math:`t_{central}` is +the central epoch of the transformation. Equation :eq:`propagation` can be used to +propagate all transformation parameters in time. + +Superscripts of vectors denote the reference frame the coordinates in the vector belong to. + + +2D Helmert +------------------------------------------------------------------------------- + +The simplest version of the Helmert transform is the 2D case. In the 2-dimensional +case only the horizontal coordinates are changed. The coordinates can be +translated, rotated and scale. Translation is controlled with the `x` and `y` +parameters. The rotation is determined by `theta` and the scale is controlled with +the `s` parameters. + +.. note:: + + The scaling parameter `s` is unitless for the 2D Helmert, as opposed to the + 3D version where the scaling parameter is given in units of ppm. + +Mathematically the 2D Helmert is described as: + +.. math:: + :label: 4param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + \end{bmatrix} + + s + \begin{bmatrix} + \hphantom{-}\cos \theta & \sin \theta \\ + -\sin \theta & \cos \theta \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + + +:eq:`4param` can be extended to a time-varying kinematic version by +adjusting the parameters with :eq:`propagation` to :eq:`4param`, which yields +the kinematic 2D Helmert transform: + +.. math:: + :label: 8param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \end{bmatrix} + + s(t) + \begin{bmatrix} + \hphantom{-}\cos \dot{\theta} & \sin \dot{\theta} \\ + -\sin\ \dot{\theta} & \cos \dot{\theta} \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + +All parameters in :eq:`8param` are determined by the use of :eq:`propagation`, +which applies the rate of change to each individual parameter for a given +timespan between :math:`t` and :math:`t_{central}`. + + +3D Helmert +------------------------------------------------------------------------------- + +The general form of the 3D Helmert is + +.. math:: + :label: general-helmert + + + \begin{align} + V^B = T + \left(1 + s \times 10^{-6}\right) \mathbf{R} V^A + \end{align} + +Where :math:`T` is a vector consisting of the three translation parameters, :math:`s` +is the scaling factor and :math:`\mathbf{R}` is a rotation matrix. :math:`V^A` and +:math:`V^B` are coordinate vectors, with :math:`V^A` being the input coordinate and +:math:`V^B` is the output coordinate. + +In the *Position Vector* convention, we define :math:`R_x = radians \left( rx \right)`, +:math:`R_z = radians \left( ry \right)` and :math:`R_z = radians \left( rz \right)` + +In the *Coordinate Frame* convention, :math:`R_x = - radians \left( rx \right)`, +:math:`R_z = - radians \left( ry \right)` and :math:`R_z = - radians \left( rz \right)` + +The rotation matrix is composed of three rotation matrices, one for each axis. + +.. math:: + + \begin{align} + \mathbf{R}_X &= \begin{bmatrix} 1 & 0 & 0\\ 0 & \cos R_x & -\sin R_x \\ 0 & \sin R_x & \cos R_x \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Y &= \begin{bmatrix} \cos R_y & 0 & \sin R_y\\ 0 & 1 & 0\\ -\sin R_y & 0 & \cos R_y \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Z &= \begin{bmatrix} \cos R_z & -\sin R_z & 0\\ \sin R_z & \cos R_z & 0\\ 0 & 0 & 1 \end{bmatrix} + \end{align} + +The three rotation matrices can be combined in one: + +.. math:: + + \begin{align} + \mathbf{R} = \mathbf{R_X} \mathbf{R_Y} \mathbf{R_Y} + \end{align} + + +For :math:`\mathbf{R}`, this yields: + +.. math:: + :label: rot_exact + + \begin{bmatrix} + \cos R_y \cos R_z & -\cos R_x \sin R_z + & \sin R_x \sin R_z + \\ + & \sin R_x \sin R_y \cos R_z & \cos R_x \sin R_y \cos R_z \\ + \cos R_y\sin R_z & \cos R_x \cos R_z + & - \sin R_x \cos R_z + \\ + & \sin R_x \sin R_y \sin R_z & \cos R_x \sin R_y \sin R_z \\ + -\sin R_y & \sin R_x \cos R_y & \cos R_x \cos R_y \\ + \end{bmatrix} + + +Using the small angle approximation the rotation matrix can be simplified to + +.. math:: + :label: rot_approx + + \begin{align} \mathbf{R} = + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \end{align} + +Which allow us to express the most common version of the Helmert transform, +using the approximated rotation matrix: + + +.. math:: + :label: 7param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \left(1 + s \times 10^{-6}\right) + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +If the rotation matrix is transposed, or the sign of the rotation terms negated, +the rotational part of the transformation is effectively reversed. +This is what happens when switching between the 2 conventions ``position_vector`` +and ``coordinate_frame`` + +Applying :eq:`propagation` we get the kinematic version of the approximated +3D Helmert: + +.. math:: + :label: 14param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \left(1 + \dot{s} \times 10^{-6}\right) + \begin{bmatrix} + 1 & -\dot{R_z} & \dot{R_y} \\ + \dot{R_z} & 1 & -\dot{R_x} \\ + -\dot{R_y} & \dot{R_x} & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + + + + +The Helmert transformation can be applied without using the rotation parameters, +in which case it becomes a simple translation of the origin of the coordinate +system. When using the Helmert in this version equation :eq:`general-helmert` +simplifies to: + +.. math:: + :label: 3param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +That after application of :eq:`propagation` has the following kinematic +counterpart: + +.. math:: + :label: 6param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} diff --git a/_sources/operations/transformations/hgridshift.rst.txt b/_sources/operations/transformations/hgridshift.rst.txt new file mode 100644 index 00000000..d27059e9 --- /dev/null +++ b/_sources/operations/transformations/hgridshift.rst.txt @@ -0,0 +1,118 @@ +.. _hgridshift: + +================================================================================ +Horizontal grid shift +================================================================================ + +.. versionadded:: 5.0.0 + +Change of horizontal datum by grid shift. + ++-----------------+--------------------------------------------------------------------+ +| **Alias** | hgridshift | ++-----------------+--------------------------------------------------------------------+ +| **Domain** | 2D, 3D and 4D | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++-----------------+--------------------------------------------------------------------+ + +The horizontal grid shift is done by offsetting the planar input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid:: + + +proj=hgridshift +grids=nzgr2kgrid0005.gsb + + +More than one grid can be loaded at the same time, for instance in case the +dataset needs to be transformed spans several countries. In this example grids +of the continental US, Alaska and Canada is loaded at the same time:: + + +proj=hgridshift +grids=@conus,@alaska,@ntv2_0.gsb,@ntv_can.dat + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ search path. The list of grids is prioritized so that +grids in the start of the list takes precedence over the grids in the back of the +list. + +PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections. Details +about all three formats can be found in the GDAL documentation and/or driver source +code. GDAL reads and writes all three formats. Using GDAL for construction of +new grids is recommended. + + +Temporal gridshifting +################################################################################ +.. versionadded:: 5.1.0 + +By initializing the horizontal gridshift operation with a central epoch, it can be +used as a step function applying the grid offsets only if a coordinate is +transformed from an epoch before grids central epoch to an epoch after. This is +handy in transformations where it is necessary to handle deformations caused by +seismic activity. + +The central epoch of the grid is controlled with :option:`+t_epoch` and the final +epoch of the coordinate is set with :option:`+t_final`. The observation epoch of +the coordinate is part of the coordinate tuple. + +Suppose we want to model the deformation of the 2008 earthquake in Iceland in +a transformation of data from 2005 to 2009:: + + echo 63.992 -21.014 10.0 2005.0 | cct +proj=hgridshift +grids=iceland2008.gsb +t_epoch=2008.4071 +t_final=2009.0 + 63.9920021 -21.0140013 10.0 2005.0 + +.. note:: + The timestamp of the resulting coordinate is still 2005.0. The observation + time is always kept unchanged as it would otherwise be impossible to do the + inverse transformation. + +Temporal gridshifting is especially powerful in transformation pipelines where +several gridshifts can be chained together, effectively acting as a series of +step functions that can be applied to a coordinate that is propagated through +time. In the following example we establish a pipeline that allows transformation +of coordinates from any given epoch up until the current date, applying only +those gridshifts that have central epochs between the observation epoch and +the final epoch:: + + +proj=pipeline +t_final=now + +step +proj=hgridshift +grids=earthquake_1.gsb +t_epoch=2010.421 + +step +proj=hgridshift +grids=earthquake_2.gsb +t_epoch=2013.853 + +step +proj=hgridshift +grids=earthquake_3.gsb +t_epoch=2017.713 + +.. note:: + The special epoch *now* is used when specifying the final epoch with + :option:`+t_final`. This results in coordinates being transformed to the + current date. Additionally, :option:`+t_final` is used as a + :ref:`global pipeline parameter<global-pipeline-parameter>`, which means + that it is applied to all the steps in the pipeline. + +In the above transformation, a coordinate with observation epoch 2009.32 would +be subject to all three gridshift steps in the pipeline. A coordinate with +observation epoch 2014.12 would only by offset by the last step in the pipeline. + + +Parameters +################################################################################ + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an `@` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids are expected to be in CTable2, NTv1 or NTv2 format. + +Optional ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. include:: ../options/t_epoch.rst +.. versionadded:: 5.1.0 +.. include:: ../options/t_final.rst +.. versionadded:: 5.1.0 + diff --git a/_sources/operations/transformations/horner.rst.txt b/_sources/operations/transformations/horner.rst.txt new file mode 100644 index 00000000..ad09e8ab --- /dev/null +++ b/_sources/operations/transformations/horner.rst.txt @@ -0,0 +1,213 @@ +.. _horner: + +================================================================================ +Horner polynomial evaluation +================================================================================ + +.. versionadded:: 5.0.0 + ++-----------------+-------------------------------------------------------------------+ +| **Alias** | horner | ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 2D and 3D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Geodetic and projected coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Geodetic and projected coordinates | ++-----------------+-------------------------------------------------------------------+ + +The Horner polynomial evaluation scheme is used for transformations between reference +frames where one or both are inhomogeneous or internally distorted. This will typically +be reference frames created before the introduction of space geodetic techniques such +as GPS. + +Horner polynomials, or Multiple Regression Equations as they are also known as, have +their strength in being able to create complicated mappings between coordinate +reference frames while still being lightweight in both computational cost and disk +space used. + +PROJ implements two versions of the Horner evaluation scheme: Real and complex +polynomial evaluation. Below both are briefly described. For more details consult +:cite:`Ruffhead2016` and :cite:`IOGP2018`. + +The polynomial evaluation in real number space is defined by the following equations: + +.. math:: + :label: real_poly + + \Delta X = \sum_{i,j} u_{i,j} U^i V^j + + \Delta Y = \sum_{i,j} v_{i,j} U^i V^j + +where + +.. math:: + :label: UV + + U = X_{in} - X_{origin} + + V = Y_{in} - Y_{origin} + +and :math:`u_{i,j}` and :math:`v_{i,j}` are coefficients that make up +the polynomial. + +The final coordinates are determined as + +.. math:: + :label: xy_out + + X_{out} = X_{in} + \Delta X + + Y_{out} = Y_{in} + \Delta Y + +The inverse transform is the same as the above but requires a different set of +coefficients. + +Evaluation of the complex polynomials are defined by the following equations: + +.. math:: + :label: complex_poly + + \Delta X + i \Delta Y = \sum_{j=1}^n (c_{2j-1} + i c_{2j}) (U + i V)^j + +Where :math:`n` is the degree of the polynomial. :math:`U` and :math:`V` are +defined as in :eq:`UV` and the resulting coordinates are again determined +by :eq:`xy_out`. + +Examples +################################################################################ + +Mapping between Danish TC32 and ETRS89/UTM zone 32 using polynomials in real +number space:: + + +proj=horner + +ellps=intl + +range=500000 + +fwd_origin=877605.269066,6125810.306769 + +inv_origin=877605.760036,6125811.281773 + +deg=4 + +fwd_v=6.1258112678e+06,9.9999971567e-01,1.5372750011e-10,5.9300860915e-15,2.2609497633e-19,4.3188227445e-05,2.8225130416e-10,7.8740007114e-16,-1.7453997279e-19,1.6877465415e-10,-1.1234649773e-14,-1.7042333358e-18,-7.9303467953e-15,-5.2906832535e-19,3.9984284847e-19 + +fwd_u=8.7760574982e+05,9.9999752475e-01,2.8817299305e-10,5.5641310680e-15,-1.5544700949e-18,-4.1357045890e-05,4.2106213519e-11,2.8525551629e-14,-1.9107771273e-18,3.3615590093e-10,2.4380247154e-14,-2.0241230315e-18,1.2429019719e-15,5.3886155968e-19,-1.0167505000e-18 + +inv_v=6.1258103208e+06,1.0000002826e+00,-1.5372762184e-10,-5.9304261011e-15,-2.2612705361e-19,-4.3188331419e-05,-2.8225549995e-10,-7.8529116371e-16,1.7476576773e-19,-1.6875687989e-10,1.1236475299e-14,1.7042518057e-18,7.9300735257e-15,5.2881862699e-19,-3.9990736798e-19 + +inv_u=8.7760527928e+05,1.0000024735e+00,-2.8817540032e-10,-5.5627059451e-15,1.5543637570e-18,4.1357152105e-05,-4.2114813612e-11,-2.8523713454e-14,1.9109017837e-18,-3.3616407783e-10,-2.4382678126e-14,2.0245020199e-18,-1.2441377565e-15,-5.3885232238e-19,1.0167203661e-18 + + +Mapping between Danish System Storebælt and ETRS89/UTM zone 32 using complex +polynomials:: + + +proj=horner + +ellps=intl + +range=500000 + +fwd_origin=4.94690026817276e+05,6.13342113183056e+06 + +inv_origin=6.19480258923588e+05,6.13258568148837e+06 + +deg=3 + +fwd_c=6.13258562111350e+06,6.19480105709997e+05,9.99378966275206e-01,-2.82153291753490e-02,-2.27089979140026e-10,-1.77019590701470e-09,1.08522286274070e-14,2.11430298751604e-15 + +inv_c=6.13342118787027e+06,4.94690181709311e+05,9.99824464710368e-01,2.82279070814774e-02,7.66123542220864e-11,1.78425334628927e-09,-1.05584823306400e-14,-3.32554258683744e-15 + +Parameters +################################################################################ + +Setting up Horner polynomials requires many coefficients being explicitly +written, even for polynomials of low degree. For this reason it is recommended +to store the polynomial definitions in an :ref:`init file <init_files>` for +easier writing and reuse. + +Required +------------------------------------------------------------------------------- + +Below is a list of required parameters that can be set for the Horner polynomial +transformation. As stated above, the transformation takes to forms, either using +real or complex polynomials. These are divided into separate sections below. +Parameters from the two sections are mutually exclusive, that is parameters +describing real and complex polynomials can't be mixed. + +.. include:: ../options/ellps.rst + +.. option:: +deg=<value> + + Degree of polynomial + +.. option:: +fwd_origin=<northing,easting> + + Coordinate of origin for the forward mapping + +.. option:: +inv_origin=<northing,easting> + + Coordinate of origin for the inverse mapping + +Real polynomials +.............................................................................. + +The following parameters has to be set if the transformation consists of +polynomials in real space. Each parameter takes a comma-separated list of +coefficients. The number of coefficients is governed by the degree, :math:`d`, +of the polynomial: + +.. math:: + + N = \frac{(d + 1)(d + 2)}{2} + +.. option:: +fwd_u=<u_11,u_12,...,u_ij,..,u_mn> + + Coefficients for the forward transformation i.e. latitude to northing + as described in :eq:`real_poly`. + +.. option:: +fwd_v=<v_11,v_12,...,v_ij,..,v_mn> + + Coefficients for the forward transformation i.e. longitude to easting + as described in :eq:`real_poly`. + +.. option:: +inv_u=<u_11,u_12,...,u_ij,..,u_mn> + + Coefficients for the inverse transformation i.e. latitude to northing + as described in :eq:`real_poly`. + +.. option:: +inv_v=<v_11,v_12,...,v_ij,..,v_mn> + + Coefficients for the inverse transformation i.e. longitude to easting + as described in :eq:`real_poly`. + + + +Complex polynomials +.............................................................................. + +The following parameters has to be set if the transformation consists of +polynomials in complex space. Each parameter takes a comma-separated list of +coefficients. The number of coefficients is governed by the degree, :math:`d`, +of the polynomial: + +.. math:: + + N = 2d + 2 + +.. option:: +fwd_c=<c_1,c_2,...,c_N> + + Coefficients for the complex forward transformation + as described in :eq:`complex_poly`. + +.. option:: +inv_c=<c_1,c_2,...,c_N> + + Coefficients for the complex inverse transformation + as described in :eq:`complex_poly`. + +Optional +------------------------------------------------------------------------------- + +.. option:: +range=<value> + + Radius of the region of validity. + +.. option:: +uneg + + Express latitude as southing. Only applies for complex polynomials. + +.. option:: +vneg + + Express longitude as westing. Only applies for complex polynomials. + + +Further reading +################################################################################ + +#. `Wikipedia <https://en.wikipedia.org/wiki/Horner%27s_method>`_ diff --git a/_sources/operations/transformations/index.rst.txt b/_sources/operations/transformations/index.rst.txt new file mode 100644 index 00000000..a413b8f6 --- /dev/null +++ b/_sources/operations/transformations/index.rst.txt @@ -0,0 +1,24 @@ +.. _transformation_list: + +================================================================================ +Transformations +================================================================================ + +Transformations coordinate operation in which the two coordinate reference +systems are based on different datums. + +.. toctree:: + :maxdepth: 1 + + affine + defmodel + deformation + geogoffset + helmert + horner + molodensky + molobadekas + hgridshift + tinshift + vgridshift + xyzgridshift diff --git a/_sources/operations/transformations/molobadekas.rst.txt b/_sources/operations/transformations/molobadekas.rst.txt new file mode 100644 index 00000000..b7d638bf --- /dev/null +++ b/_sources/operations/transformations/molobadekas.rst.txt @@ -0,0 +1,147 @@ +.. _molobadekas: + +================================================================================ +Molodensky-Badekas transform +================================================================================ + +.. versionadded:: 6.0.0 + +The Molodensky-Badekas transformation changes coordinates from one reference frame to +another by means of a 10-parameter shift. + +.. note:: + + It should not be confused with the :ref:`Molodensky` transform which + operates directly in the geodetic coordinates. Molodensky-Badekas can rather + be seen as a variation of :ref:`Helmert` + ++-----------------+-------------------------------------------------------------------+ +| **Alias** | molobadekas | ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 3D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ + +The Molodensky-Badekas transformation is a variation of the :ref:`Helmert` where +the rotational terms are not directly applied to the ECEF coordinates, but on +cartesian coordinates relative to a reference point (usually close to Earth surface, +and to the area of use of the transformation). When ``px`` = ``py`` = ``pz`` = 0, +this is equivalent to a 7-parameter Helmert transformation. + +Example ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Transforming coordinates from La Canoa to REGVEN: + +:: + + proj=molobadekas convention=coordinate_frame + x=-270.933 y=115.599 z=-360.226 rx=-5.266 ry=-1.238 rz=2.381 + s=-5.109 px=2464351.59 py=-5783466.61 pz=974809.81 + + +Parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. note:: + + All parameters (except convention) are optional but at least one should be + used, otherwise the operation will return the coordinates unchanged. + +.. option:: +convention=coordinate_frame/position_vector + + Indicates the convention to express the rotational terms when a 3D-Helmert / + 7-parameter more transform is involved. + + The two conventions are equally popular and a frequent source of confusion. + The coordinate frame convention is also described as an clockwise + rotation of the coordinate frame. It corresponds to EPSG method code + 1034 (in the geocentric domain) or 9636 (in the geographic domain) + The position vector convention is also described as an anticlockwise + (counter-clockwise) rotation of the coordinate frame. + It corresponds to as EPSG method code 1061 (in the geocentric domain) or + 1063 (in the geographic domain). + + The result obtained with parameters specified in a given convention + can be obtained in the other convention by negating the rotational parameters + (``rx``, ``ry``, ``rz``) + +.. option:: +x=<value> + + Translation of the x-axis given in meters. + +.. option:: +y=<value> + + Translation of the y-axis given in meters. + +.. option:: +z=<value> + + Translation of the z-axis given in meters. + +.. option:: +s=<value> + + Scale factor given in ppm. + +.. option:: +rx=<value> + + X-axis rotation given arc seconds. + +.. option:: +ry=<value> + + Y-axis rotation given in arc seconds. + +.. option:: +rz=<value> + + Z-axis rotation given in arc seconds. + +.. option:: +px=<value> + + Coordinate along the x-axis of the reference point given in meters. + +.. option:: +py=<value> + + Coordinate along the y-axis of the reference point given in meters. + +.. option:: +pz=<value> + + Coordinate along the z-axis of the reference point given in meters. + +Mathematical description ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +In the *Position Vector* convention, we define :math:`R_x = radians \left( rx \right)`, +:math:`R_z = radians \left( ry \right)` and :math:`R_z = radians \left( rz \right)` + +In the *Coordinate Frame* convention, :math:`R_x = - radians \left( rx \right)`, +:math:`R_z = - radians \left( ry \right)` and :math:`R_z = - radians \left( rz \right)` + +.. math:: + :label: 10param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^{output} = + \begin{bmatrix} + T_x + P_x\\ + T_y + P_y\\ + T_z + P_z\\ + \end{bmatrix} + + \left(1 + s \times 10^{-6}\right) + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X^{input} - P_x\\ + Y^{input} - P_y\\ + Z^{input} - P_z\\ + \end{bmatrix} + \end{align} diff --git a/_sources/operations/transformations/molodensky.rst.txt b/_sources/operations/transformations/molodensky.rst.txt new file mode 100644 index 00000000..df0b00a2 --- /dev/null +++ b/_sources/operations/transformations/molodensky.rst.txt @@ -0,0 +1,96 @@ +.. _molodensky: + +================================================================================ +Molodensky transform +================================================================================ + +.. versionadded:: 5.0.0 + +The Molodensky transformation resembles a :ref:`Helmert` with zero +rotations and a scale of unity, but converts directly from geodetic coordinates to +geodetic coordinates, without the intermediate shifts to and from cartesian +geocentric coordinates, associated with the Helmert transformation. +The Molodensky transformation is simple to implement and to parametrize, requiring +only the 3 shifts between the input and output frame, and the corresponding +differences between the semimajor axes and flattening parameters of the reference +ellipsoids. Due to its algorithmic simplicity, it was popular prior to the +ubiquity of digital computers. Today, it is mostly interesting for historical +reasons, but nevertheless indispensable due to the large amount of data that has +already been transformed that way :cite:`EversKnudsen2017`. + ++---------------------+----------------------------------------------------------+ +| **Alias** | molodensky | ++---------------------+----------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical) | ++---------------------+----------------------------------------------------------+ +| **output type** | Geodetic coordinates (horizontal), meters (vertical) | ++---------------------+----------------------------------------------------------+ + +The Molodensky transform can be used to perform a datum shift from coordinate +:math:`(\phi_1, \lambda_1, h_1)` to :math:`(\phi_2, \lambda_2, h_2)` where the two +coordinates are referenced to different ellipsoids. This is based on three +assumptions: + + 1. The cartesian axes, :math:`X, Y, Z`, of the two ellipsoids are parallel. + 2. The offset, :math:`\delta X, \delta Y, \delta Z`, between the two ellipsoid + are known. + 3. The characteristics of the two ellipsoids, expressed as the difference in + semimajor axis (:math:`\delta a`) and flattening (:math:`\delta f`), are known. + +The Molodensky transform is mostly used for transforming between old systems +dating back to the time before computers. The advantage of the Molodensky transform +is that it is fairly simple to compute by hand. The ease of computation come at the +cost of limited accuracy. + +A derivation of the mathematical formulas for the Molodensky transform can be found +in :cite:`Deakin2004`. + + +Examples +############################################################################### + +The abridged Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 abridged + +The same transformation using the standard Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 + + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. option:: +da=<value> + + Difference in semimajor axis of the defining ellipsoids. + +.. option:: +df=<value> + + Difference in flattening of the defining ellipsoids. + +.. option:: +dx=<value> + + Offset of the X-axes of the defining ellipsoids. + +.. option:: +dy=<value> + + Offset of the Y-axes of the defining ellipsoids. + +.. option:: +dz=<value> + + Offset of the Z-axes of the defining ellipsoids. + +.. include:: ../options/ellps.rst + +Optional +------------------------------------------------------------------------------- + +.. option:: +abridged + + Use the abridged version of the Molodensky transform. diff --git a/_sources/operations/transformations/tinshift.rst.txt b/_sources/operations/transformations/tinshift.rst.txt new file mode 100644 index 00000000..2135266b --- /dev/null +++ b/_sources/operations/transformations/tinshift.rst.txt @@ -0,0 +1,215 @@ +.. _tinshift: + +================================================================================ +Triangulated Irregular Network based transformation +================================================================================ + +.. versionadded:: 7.2.0 + ++---------------------+--------------------------------------------------------------------+ +| **Alias** | tinshift | ++---------------------+--------------------------------------------------------------------+ +| **Input type** | Projected or geographic coordinates (horizontal), meters (vertical)| ++---------------------+--------------------------------------------------------------------+ +| **Output type** | Projected or geographic coordinates (horizontal), meters (vertical)| ++---------------------+--------------------------------------------------------------------+ +| **Domain** | 2D or 3D | ++---------------------+--------------------------------------------------------------------+ +| **Available forms** | Forward and inverse | ++---------------------+--------------------------------------------------------------------+ + + +The ``tinshift`` transformation takes one mandatory +argument, ``file``, that points to a JSON file, which contains the +triangulation and associated metadata. Input and output coordinates must be +geographic or projected coordinates. +Depending on the content of the JSON file, horizontal, vertical or both +components of the coordinates may be transformed. + +The transformation is invertible, with the same computational complexity than +the forward transformation. + +Parameters +------------------------------------------------------------------------------- + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +file=<filename> + + Filename to the JSON file for the TIN. + + +Example +------------------------------------------------------------------------------- + +Transforming a point with the Finland EPSG:2393 ("KKJ / Finland Uniform +Coordinate System") projected CRS to EPSG:3067 ("ETRS89 / TM35FIN(E,N)") + +:: + + $ echo 3210000.0000 6700000.0000 0 2020 | cct +proj=tinshift +file=./triangulation_kkj.json + + 209948.3217 6697187.0009 0.0000 2020 + + +Algorithm ++++++++++ + +Internally, ``tinshift`` ingest the whole file into memory. It is considered that +triangulation should be small enough for that. + +When a point is transformed, one must find the triangle into which it falls into. +Instead of iterating over all triangles, we build a in-memory quadtree to speed-up +the identification of candidates triangles. + +To determine if a point falls into a triangle, one computes its 3 +`barycentric coordinates <https://en.wikipedia.org/wiki/Barycentric_coordinate_system#Conversion_between_barycentric_and_Cartesian_coordinates>`_ +from its projected coordinates, :math:`\lambda_i` for :math:`i=1,2,3`. +They are real values (in the [0,1] range for a point inside the triangle), +giving the weight of each of the 3 vertices of the triangles. + +Once those weights are known, interpolating the target horizontal +coordinate is a matter of doing the linear combination of those weights with +the target horizontal coordinates at the 3 vertices of the triangle (:math:`Xt_i` and :math:`Yt_i`): + +.. math:: + + X_{target} = Xt_1 * \lambda_1 + Xt_2 * \lambda_2 + Xt_3 * \lambda_3 + + Y_{target} = Yt_1 * \lambda_1 + Yt_2 * \lambda_2 + Yt_3 * \lambda_3 + +This interpolation is exact at the vertices of the triangulation, and has linear properties +inside each triangle. It is completely equivalent to other formulations of +triangular interpolation, such as + +.. math:: + + X_{target} = A + X_{source} * B + Y_{source} * C + + Y_{target} = D + X_{source} * E + Y_{source} * F + +where the A, B, C, D, E, F constants (for a given triangle) are found by solving +the 2 systems of 3 linear equations, constraint by the source and target coordinate pairs +of the 3 vertices of the triangle: + +.. math:: + + Xt_i = A + Xs_i * B + Ys_i * C + + Yt_i = D + Xs_i * E + Ys_i * F + +Similarly for a vertical coordinate transformation, where :math:`Zoff_i` is the vertical +offset at each vertex of the triangle: + +.. math:: + + Z_{target} = Z_{source} + Zoff_1 * \lambda_1 + Zoff_2 * \lambda_2 + Zoff_3 * \lambda_3 + +Constraints on the triangulation +++++++++++++++++++++++++++++++++ + +No check is done on the consistence of the triangulation. It is highly +recommended that triangles do not overlap each other (when considering the +source coordinates or the forward transformation, or the target coordinates for +the inverse transformation), otherwise which triangle will be selected is +unspecified. Besides that, the triangulation does not need to have particular +properties (like being a Delaunay triangulation) + +File format ++++++++++++ + +The triangulation is stored in a text-based format, using JSON as a serialization. + +Below a minimal example, from the KKJ to ETRS89 transformation, with just a +single triangle: + +.. literalinclude:: ../../../../data/tests/tinshift_crs_implicit.json + :language: json + + +So after the generic metadata, we define the input and output CRS (informative +only), and that the transformation affects horizontal components of +coordinates. We name the columns of the ``vertices`` and ``triangles`` arrays. +We defined the source and target coordinates of each vertex, and define a +triangle by referring to the index of its vertices in the ``vertices`` array. + +More formally, the specific items for the triangulation file are: + +input_crs + String identifying the CRS of source coordinates + in the vertices. Typically ``EPSG:XXXX``. If the transformation is for vertical + component, this should be the code for a compound CRS (can be EPSG:XXXX+YYYY + where XXXX is the code of the horizontal CRS and YYYY the code of the vertical CRS). + For example, for the KKJ->ETRS89 transformation, this is EPSG:2393 + (``KKJ / Finland Uniform Coordinate System``). The input coordinates are assumed + to be passed in the "normalized for visualisation" / "GIS friendly" order, + that is longitude, latitude for geographic coordinates and + easting, northing for projected coordinates. + + +output_crs + String identifying the CRS of target coordinates in the vertices. + Typically ``EPSG:XXXX``. If the transformation is for vertical component, + this should be the code for a compound CRS (can be EPSG:XXXX+YYYY where + XXXX is the code of the horizontal CRS and YYYY the code of the vertical CRS). + For example, for the KKJ->ETRS89 transformation, this is EPSG:3067 + (\"ETRS89 / TM35FIN(E,N)\"). The output coordinates will be returned in + the "normalized for visualisation" / "GIS friendly" order, + that is longitude, latitude for geographic coordinates and + easting, northing for projected coordinates. + + +transformed_components + Array which may contain one or two strings: "horizontal" when horizontal + components of the coordinates are transformed and/or "vertical" when the + vertical component is transformed. + + +fallback_strategy + String identifying how to treat points that do not fall into any of the + specified triangles. This item is available for ``format_version`` >= 1.1. + Possible values are ``none``, ``nearest_side`` and ``nearest_centroid``. The + default is ``none`` and signifies, that points that fall outside the + specified triangles are not transformed. This is also the behaviour for + ``format_version`` before 1.1. If ``fallback_strategy`` is set to + ``nearest_side``, then points that do not fall into any triangle are + transformed according to the triangle closest to them by euclidean distance. + If ``fallback_strategy`` is set to ``nearest_centroid``, then points that do + not fall into any triangle are transformed according to the triangle with the + closest centroid (intersection of its medians). + + +vertices_columns + Specify the name of the columns of the rows in the ``vertices`` + array. There must be exactly as many elements in ``vertices_columns`` as in a + row of ``vertices``. The following names have a special meaning: ``source_x``, + ``source_y``, ``target_x``, ``target_y``, ``source_z``, ``target_z`` and + ``offset_z``. ``source_x`` and ``source_y`` are compulsory. + ``source_x`` is for the source longitude (in degree) or easting. + ``source_y`` is for the source latitude (in degree) or northing. + ``target_x`` and ``target_y`` are compulsory when ``horizontal`` is specified + in ``transformed_components``. (``source_z`` and ``target_z``) or + ``offset_z`` are compulsory when ``vertical`` is specified in ``transformed_components`` + + +triangles_columns + Specify the name of the columns of the rows in the + ``triangles`` array. There must be exactly as many elements in ``triangles_columns`` + as in a row of ``triangles``. The following names have a special meaning: + ``idx_vertex1``, ``idx_vertex2``, ``idx_vertex3``. They are compulsory. + + +vertices + An array whose items are themselves arrays with as many columns as + described in ``vertices_columns``. + + +triangles + An array whose items are themselves arrays with as many columns as + described in ``triangles_columns``. + The value of the ``idx_vertexN`` columns must be indices + (between 0 and len(``vertices``-1) of items of the ``vertices`` array. + +A `JSON schema <https://proj.org/schemas/triangulation.schema.json>`_ is available +for this file format. diff --git a/_sources/operations/transformations/vgridshift.rst.txt b/_sources/operations/transformations/vgridshift.rst.txt new file mode 100644 index 00000000..5a31ae8f --- /dev/null +++ b/_sources/operations/transformations/vgridshift.rst.txt @@ -0,0 +1,133 @@ +.. _vgridshift: + +================================================================================ +Vertical grid shift +================================================================================ + +.. versionadded:: 5.0.0 + +Change Vertical datum change by grid shift + ++-----------------+--------------------------------------------------------------------+ +| **Alias** | vgridshift | ++-----------------+--------------------------------------------------------------------+ +| **Domain** | 3D and 4D | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++-----------------+--------------------------------------------------------------------+ + +The vertical grid shift is done by offsetting the vertical input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid. Here we change the vertical +reference from the ellipsoid to the global geoid model, EGM96:: + + +proj=vgridshift +grids=egm96_15.gtx + + +More than one grid can be loaded at the same time, for instance in the case where +a better geoid model than the global is available for a certain area. Here the +gridshift is set up so that the local DVR90 geoid model takes precedence over +the global model:: + + +proj=vgridshift +grids=@dvr90.gtx,egm96_15.gtx + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ search path. The list of grids is prioritized so that +grids in the start of the list takes precedence over the grids in the back of the +list. + +PROJ supports the GTX file format for vertical grid corrections. Details +about all the format can be found in the GDAL documentation. GDAL both reads and +writes the format. Using GDAL for construction of new grids is recommended. + +Temporal gridshifting +################################################################################ +.. versionadded:: 5.1.0 + +By initializing the vertical gridshift operation with a central epoch, it can be +used as a step function applying the grid offsets only if a coordinate is +transformed from an epoch before grids central epoch to an epoch after. This is +handy in transformations where it is necessary to handle deformations caused by +seismic activity. + +The central epoch of the grid is controlled with :option:`+t_epoch` and the final +epoch of the coordinate is set with :option:`+t_final`. The observation epoch of +the coordinate is part of the coordinate tuple. + +Suppose we want to model the deformation of the 2008 earthquake in Iceland in +a transformation of data from 2005 to 2009:: + + echo 63.992 -21.014 10.0 2005.0 | cct +proj=vgridshift +grids=iceland2008.gtx +t_epoch=2008.4071 +t_final=2009.0 + 63.992 -21.014 10.11 2005.0 + +.. note:: + The timestamp of the resulting coordinate is still 2005.0. The observation + time is always kept unchanged as it would otherwise be impossible to do the + inverse transformation. + +Temporal gridshifting is especially powerful in transformation pipelines where +several gridshifts can be chained together, effectively acting as a series of +step functions that can be applied to a coordinate that is propagated through +time. In the following example we establish a pipeline that allows transformation +of coordinates from any given epoch up until the current date, applying only +those gridshifts that have central epochs between the observation epoch and +the final epoch:: + + +proj=pipeline +t_final=now + +step +proj=vgridshift +grids=earthquake_1.gtx +t_epoch=2010.421 + +step +proj=vgridshift +grids=earthquake_2.gtx +t_epoch=2013.853 + +step +proj=vgridshift +grids=earthquake_3.gtx +t_epoch=2017.713 + +.. note:: + The special epoch *now* is used when specifying the final epoch with + :option:`+t_final`. This results in coordinates being transformed to the + current date. Additionally, :option:`+t_final` is used as a + :ref:`global pipeline parameter<global-pipeline-parameter>`, which means + that it is applied to all the steps in the pipeline. + +In the above transformation, a coordinate with observation epoch 2009.32 would +be subject to all three gridshift steps in the pipeline. A coordinate with +observation epoch 2014.12 would only by offset by the last step in the pipeline. + +Parameters +################################################################################ + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an `@` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids are expected to be in GTX format. + +Optional ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. include:: ../options/t_epoch.rst +.. versionadded:: 5.1.0 +.. include:: ../options/t_final.rst +.. versionadded:: 5.1.0 + +.. option:: +multiplier=<value> + + Specify the multiplier to apply to the grid value in the forward transformation + direction, such that: + + .. math:: + :label: multiplier_formula + + Z_{target} = Z_{source} + multiplier \times gridvalue + + The multiplier can be used to control whether the gridvalue should be added + or subtracted, and if unit conversion must be done (the multiplied gridvalue + must be expressed in metre). + + Note that the default is `-1.0` for historical reasons. +.. versionadded:: 5.2.0 diff --git a/_sources/operations/transformations/xyzgridshift.rst.txt b/_sources/operations/transformations/xyzgridshift.rst.txt new file mode 100644 index 00000000..e76b3a63 --- /dev/null +++ b/_sources/operations/transformations/xyzgridshift.rst.txt @@ -0,0 +1,93 @@ +.. _xyzgridshift: + +================================================================================ +Geocentric grid shift +================================================================================ + +.. versionadded:: 7.0.0 + +Geocentric translation using a grid shift + ++-----------------+-------------------------------------------------------------------+ +| **Alias** | xyzgridshift | ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 3D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ + +Perform a geocentric translation by bilinear interpolation of dx, dy, dz +translation values from a grid. The grid is referenced against either the +2D geographic CRS corresponding to the input (or sometimes output) CRS. + +This method is described (in French) in :cite:`NTF_88` +and as EPSG operation method code 9655 in :cite:`IOGP2018` (§2.4.4.1.1 +France geocentric interpolation). + +The translation in the grids are added to the input coordinates in the forward direction, +and subtracted in the reverse direction. +By default (if ``grid_ref=input_crs``), in the forward direction, the input coordinates +are converted to their geographic equivalent to directly read and interpolate from +the grid. In the reverse direction, an iterative method is used to be able to find +the grid locations to read. +If ``grid_ref=output_crs`` is used, then the reverse strategy is applied: iterative +method in the forward direction, and direct read in the reverse direction. + +Example +------------------------------------------------------------------------------- + +NTF to RGF93 transformation using :file:`gr3df97a.tif` grid + +:: + + +proj=pipeline + +step +proj=push +v_3 + +step +proj=cart +ellps=clrk80ign + +step +proj=xyzgridshift +grids=gr3df97a.tif +grid_ref=output_crs +ellps=GRS80 + +step +proj=cart +ellps=GRS80 +inv + +step +proj=pop +v_3 + +Parameters +################################################################################ + +The ellipsoid parameters should be the ones consistent with ``grid_ref``. +They are used to perform a geocentric to geographic conversion to find the +translation parameters. + + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. include:: ../options/ellps.rst + +.. option:: +grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an ``@`` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids are expected to be in GeoTIFF format. If no metadata is provided, + the first, second and third samples are assumed to be the geocentric + translation along X, Y and Z axis respectively, in metres. + +Optional ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +grid_ref=input_crs/output_crs + + Specify in which CRS the grid is referenced to. The default value is + input_crs. That is the grid is referenced in the geographic CRS corresponding + to the input geocentric CRS. + + If output_crs is specified, the grid is referenced in the geographic CRS corresponding + to the output geocentric CRS. This is for example the case for the French + :file:`gr3df97a.tif` grid converting from NTF to RGF93, but referenced against RGF93. + Thus in the forward direction (NTF->RGF93), an iterative method is used to find + the appropriate shift. + +.. option:: +multiplier=<value> + + Specify the multiplier to apply to the grid values. Defaults to 1.0 + diff --git a/_sources/resource_files.rst.txt b/_sources/resource_files.rst.txt new file mode 100644 index 00000000..966c3f1a --- /dev/null +++ b/_sources/resource_files.rst.txt @@ -0,0 +1,496 @@ +.. _resource_files: + +================================================================================ +Resource files +================================================================================ + +A number of files containing preconfigured transformations and default parameters +for certain projections are bundled with the PROJ distribution. Init files +contain preconfigured proj-strings for various coordinate reference systems +and the `defaults` file contains default values for parameters of select +projections. + +In addition to the bundled init files the PROJ project also distributes a number +of packages containing transformation grids and additional init files not included +in the main PROJ package. + +.. _resource_file_paths: + +Where are PROJ resource files looked for ? +------------------------------------------------------------------------------- + +PROJ will attempt to locate its resource files - database, transformation grids +or init files - from several directories. +The following paths are checked in order: + +- For resource files that have an explicit relative or absolute path, + the directory specified in the filename. + +- Path resolved by the callback function set with + the :c:func:`proj_context_set_file_finder`. If it is set, the next tests + will not be run. + +- Path(s) set with the :c:func:`proj_context_set_search_paths`. If set, the + next tests will not be run. + +.. _user_writable_directory: + +- .. versionadded:: 7.0 + + The PROJ user writable directory, which is : + + * on Windows, ``${LOCALAPPDATA}/proj`` + * on macOS, ``${HOME}/Library/Application Support/proj`` + * on other platforms (Linux), ``${XDG_DATA_HOME}/proj`` if + :envvar:`XDG_DATA_HOME` is defined. Else ``${HOME}/.local/share/proj`` + +- Path(s) set with by the environment variable :envvar:`PROJ_LIB`. + On Linux/macOS/Unix, use ``:`` to separate paths. On Windows, ``;`` + +- .. versionadded:: 7.0 + + The :file:`../share/proj/` and its contents are found automatically + at run-time if the installation respects the build structure. That is, the + binaries and :file:`proj.dll`/:file:`libproj.so` are installed under + :file:`../bin/` or :file:`../lib/`, and resource files are in + :file:`../share/proj/`. + +- A path built into PROJ as its resource installation directory (whose value is + ``$(pkgdatadir)`` for builds using the Makefile build system or + ``${CMAKE_INSTALL_PREFIX}/${DATADIR}`` for CMake builds). Note, however, + that since this is a hard-wired path setting, it only works if the whole + PROJ installation is not moved somewhere else. + + .. note:: + + If PROJ is built with the ``PROJ_LIB_ENV_VAR_TRIED_LAST`` CMake option + then this hard-wired path will be tried before looking at the environment + variable :envvar:`PROJ_LIB`. + +- The current directory + +When networking capabilities are enabled, either by API with the +:c:func:`proj_context_set_enable_network` function or when the +:envvar:`PROJ_NETWORK` environment variable is set to ``ON``, PROJ will +attempt to use remote grids stored on CDN (Content Delivery Network) storage. + +.. _proj-db: + +:file:`proj.db` +------------------------------------------------------------------------------- + +A proj installation includes a SQLite database of transformation information +that must be accessible for the library to work properly. The library will +print an error if the database can't be found. + +.. _proj-ini: + +:file:`proj.ini` +------------------------------------------------------------------------------- + +.. versionadded:: 7.0 + +:file:`proj.ini` is a text configuration file, mostly dedicated at setting up +network related parameters. + +Its default content is: + +:: + + [general] + ; Lines starting by ; are commented lines. + ; + + ; Network capabilities disabled by default. + ; Can be overridden with the PROJ_NETWORK=ON environment variable. + ; network = on + + ; Can be overridden with the PROJ_NETWORK_ENDPOINT environment variable. + cdn_endpoint = https://cdn.proj.org + + cache_enabled = on + + cache_size_MB = 300 + + cache_ttl_sec = 86400 + + ; Filename of the Certificate Authority (CA) bundle. + ; Can be overriden with the PROJ_CURL_CA_BUNDLE / CURL_CA_BUNDLE environment variable. + ; (added in PROJ 9.0) + ; ca_bundle_path = /path/to/cabundle.pem + + ; Transverse Mercator (and UTM) default algorithm: auto, evenden_snyder or poder_engsager + ; * evenden_snyder is the fastest, but less accurate far from central meridian + ; * poder_engsager is slower, but more accurate far from central meridian + ; * default will auto-select between the two above depending on the coordinate + ; to transform and will use evenden_snyder if the error in doing so is below + ; 0.1 mm (for an ellipsoid of the size of Earth) + tmerc_default_algo = poder_engsager + + +Transformation grids +------------------------------------------------------------------------------- + +Grid files are important for shifting and transforming between datums. + +PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections and +the GTX file format for vertical corrections. Details about the formats can be +found in the `GDAL documentation <http://gdal.org/>`_. GDAL reads and writes +all formats. Using GDAL for construction of new grids is recommended. + +.. _datumgrid: + +External resources and packaged grids +------------------------------------------------------------------------------- + +proj-data ++++++++++ + +The ``proj-data`` package is a collection of all the resource files that are +freely available for use with PROJ. The package is maintained on +`GitHub <https://github.com/OSGeo/PROJ-data>`_ and the contents of the package +are show-cased on the `PROJ CDN <https://cdn.proj.org/>`_. The contents of the +package can be installed using the :program:`projsync` package or by downloading +the zip archive of the package and unpacking in the :envvar:`PROJ_LIB` directory. + +proj-datumgrid +++++++++++++++ + +.. note:: + + The packages described below can be used with PROJ 7 and later but are + primarily meant to be used with PROJ 6 and earlier versions. + The ``proj-datumgrid`` series of packages are not maintained anymore and + are only kept available for legacy purposes. + +For a functioning build of PROJ prior to version 7, installation of the +`proj-datumgrid <https://github.com/OSGeo/proj-datumgrid>`_ is needed. If you +have installed PROJ from a package system chances are that this will already be +done for you. The *proj-datumgrid* package provides transformation grids that +are essential for many of the predefined transformations in PROJ. Which grids +are included in the package can be seen on the +`proj-datumgrid repository <https://github.com/OSGeo/proj-datumgrid>`_ as well +as descriptions of those grids. This is the main grid package and the only one +that is required. It includes various older grids that is mostly needed for +legacy reasons. Without this package, the test suite fails miserably. + +Regional packages ++++++++++++++++++ + +In addition to the default ``proj-datumgrid`` package regional packages are also +distributed. These include grids and init files that are valid within the given +region. The packages are divided into geographical regions in order to keep the +needed disk space by PROJ at a minimum. Some users may have a use for resource +files covering several regions in which case they can download more than one. + +At the moment three regional resource file packages are distributed: + +* `Europe <https://github.com/OSGeo/proj-datumgrid/tree/master/europe#proj-datumgrid-europe>`_ +* `Oceania <https://github.com/OSGeo/proj-datumgrid/tree/master/oceania#proj-datumgrid-oceania>`_ +* `North America <https://github.com/OSGeo/proj-datumgrid/tree/master/north-america#proj-datumgrid-north-america>`_ + +If someone supplies grids relevant for Africa, South-America, Asia or Antarctica +we will create new regional packages. + +Click the links to jump to the relevant README files for each package. Details +on the content of the packages maintained there. + +.. tip:: + To download the various datumgrid packages head to the :ref:`download section <download>`. + +World package ++++++++++++++ + +The `world package <https://github.com/OSGeo/proj-datumgrid/tree/master/world#proj-datumgrid-world>`_ +includes grids that have global extent, e.g. the global geoid model EGM08. + +-latest packages +++++++++++++++++ + +All packages above come in different versions, e.g., ``proj-datumgrid-1.8`` or +``proj-datumgrid-europe-1.4``. The ``-latest`` packages are symbolic links to the +latest version of a given package. That means that the link +https://download.osgeo.org/proj/proj-datumgrid-north-america-latest.zip is +equivalent to https://download.osgeo.org/proj/proj-datumgrid-north-america-1.2.zip +(as of the time of writing this). + +.. _transformation_grids: + +Other transformation grids +------------------------------------------------------------------------------- + +Below is a list of grid resources for various countries which are not +included in the grid distributions mentioned above. + +Free grids ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The following is a list of grids distributed under a free and open license. + +Hungary +................................................................................ + +`Hungarian grid <https://github.com/OSGeoLabBp/eov2etrs/>`__ ETRS89 - HD72/EOV (epsg:23700), both horizontal and elevation grids + + +.. _nonfreegrids: + +Non-Free Grids ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Not all grid shift files have licensing that allows them to be freely +distributed, but can be obtained by users through free and legal methods. + +Austria +................................................................................ + +Overview of `Austrian grids <http://www.bev.gv.at/portal/page?_pageid=713,1569828&_dad=portal&_schema=PORTAL>`__ and other resources +related to the local geodetic reference. + +Brazil +................................................................................ + +`Brazilian grids <http://www.ibge.gov.br/home/geociencias/geodesia/param_transf/default_param_transf.shtm>`__ for datums Corrego Alegre 1961, Corrego Alegre 1970-72, SAD69 and SAD69(96) + +Netherlands +................................................................................ + +`Dutch grid <https://www.nsgi.nl/geodetische-infrastructuur/coordinatentransformatie>`__ (Registration required before download) + +Portugal +................................................................................ + +`Portuguese grids <http://www.fc.up.pt/pessoas/jagoncal/coordenadas/index.htm>`__ for ED50, Lisbon 1890, Lisbon 1937 and Datum 73 + +South Africa +................................................................................ + +`South African grid <http://eepublishers.co.za/article/datum-transformations-using-the-ntv2-grid.html>`__ (Cape to Hartebeesthoek94 or WGS84) + +Spain +................................................................................ + +`Spanish grids <http://www.ign.es/ign/layoutIn/herramientas.do#DATUM>`__ for ED50. + + +HTDP ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +This section describes the use of the :file:`crs2crs2grid.py` script and the HTDP +(Horizontal Time Dependent Positioning) grid shift modelling program from +NGS/NOAA to produce PROJ compatible grid shift files for fine grade +conversions between various NAD83 epochs and WGS84. Traditionally PROJ has +treated NAD83 and WGS84 as equivalent and failed to distinguish between +different epochs or realizations of those datums. At the scales of much +mapping this is adequate but as interest grows in high resolution imagery and +other high resolution mapping this is inadequate. Also, as the North American +crust drifts over time the displacement between NAD83 and WGS84 grows (more +than one foot over the last two decades). + +Getting and building HTDP +................................................................................ + +The HTDP modelling program is written in FORTRAN. The source and documentation +can be found on the HTDP page at http://www.ngs.noaa.gov/TOOLS/Htdp/Htdp.shtml + +On Linux systems it will be necessary to install GFortran or some Fortran +compiler. For Ubuntu something like the following should work. + +:: + + apt-get install gfortran + +To compile the program do something like the following to produce the binary +:program:`htdp` from the source code. + +:: + + gfortran htdp.for -o htdp + +Getting :file:`crs2crs2grid.py` +................................................................................ + +The :file:`crs2crs2grid.py` script can be found at +https://github.com/OSGeo/gdal/blob/master/swig/python/gdal-utils/osgeo_utils/samples/crs2crs2grid.py + +The script depends on having the GDAL Python bindings operational; if they are not you +will get an error such as: + + +:: + + Traceback (most recent call last): + File "./crs2crs2grid.py", line 37, in <module> + from osgeo import gdal, gdal_array, osr + ImportError: No module named osgeo + +Usage +................................................................................ + +:: + + crs2crs2grid.py + <src_crs_id> <src_crs_date> <dst_crs_id> <dst_crs_year> + [-griddef <ul_lon> <ul_lat> <ll_lon> <ll_lat> <lon_count> <lat_count>] + [-htdp <path_to_exe>] [-wrkdir <dirpath>] [-kwf] + -o <output_grid_name> + + -griddef: by default the following values for roughly the continental USA + at a six minute step size are used: + -127 50 -66 25 251 611 + -kwf: keep working files in the working directory for review. + +:: + + crs2crs2grid.py 29 2002.0 8 2002.0 -o nad83_2002.ct2 + +The goal of :file:`crs2crs2grid.py` is to produce a grid shift file for a designated +region. The region is defined using the ``-griddef`` switch. When missing a +continental US region is used. The script creates a set of sample points for +the grid definition, runs :program:`htdp` against it and then parses the +resulting points and computes a point by point shift to encode into the final +grid shift file. By default it is assumed that :program:`htdp` is in the +executable path. If not, please provide the path to the executable using the +``-htdp`` switch. + +The :program:`htdp` program supports transformations between many CRSes and for each (or +most?) of them you need to provide a date at which the CRS is fixed. The full +set of CRS Ids available in the HTDP program are: + +:: + + 1...NAD_83(2011) (North America tectonic plate fixed) + 29...NAD_83(CORS96) (NAD_83(2011) will be used) + 30...NAD_83(2007) (NAD_83(2011) will be used) + 2...NAD_83(PA11) (Pacific tectonic plate fixed) + 31...NAD_83(PACP00) (NAD 83(PA11) will be used) + 3...NAD_83(MA11) (Mariana tectonic plate fixed) + 32...NAD_83(MARP00) (NAD_83(MA11) will be used) + + 4...WGS_72 16...ITRF92 + 5...WGS_84(transit) = NAD_83(2011) 17...ITRF93 + 6...WGS_84(G730) = ITRF92 18...ITRF94 = ITRF96 + 7...WGS_84(G873) = ITRF96 19...ITRF96 + 8...WGS_84(G1150) = ITRF2000 20...ITRF97 + 9...PNEOS_90 = ITRF90 21...IGS97 = ITRF97 + 10...NEOS_90 = ITRF90 22...ITRF2000 + 11...SIO/MIT_92 = ITRF91 23...IGS00 = ITRF2000 + 12...ITRF88 24...IGb00 = ITRF2000 + 13...ITRF89 25...ITRF2005 + 14...ITRF90 26...IGS05 = ITRF2005 + 15...ITRF91 27...ITRF2008 + 28...IGS08 = ITRF2008 + +The typical use case is mapping from NAD83 on a particular date to WGS84 on +some date. In this case the source CRS Id "29" (NAD_83(CORS96)) and the +destination CRS Id is "8 (WGS_84(G1150)). It is also necessary to select the +source and destination date (epoch). For example: + +:: + + crs2crs2grid.py 29 2002.0 8 2002.0 -o nad83_2002.ct2 + +The output is a CTable2 format grid shift file suitable for use with PROJ +(4.8.0 or newer). It might be utilized something like: + + +:: + + cs2cs +proj=latlong +ellps=GRS80 +nadgrids=./nad83_2002.ct2 +to +proj=latlong +datum=WGS84 + +See Also +................................................................................ + +* http://www.ngs.noaa.gov/TOOLS/Htdp/Htdp.shtml - NGS/NOAA page about the HTDP + model and program. Source for the HTDP program can be downloaded from here. + + +.. _init_files: + +Init files +------------------------------------------------------------------------------- + +Init files are used for preconfiguring proj-strings for often used +transformations, such as those found in the EPSG database. Most init files contain +transformations from a given coordinate reference system to WGS84. This makes +it easy to transform between any two coordinate reference systems with +:program:`cs2cs`. Init files can however contain any proj-string and don't necessarily +have to follow the *cs2cs* paradigm where WGS84 is used as a pivot datum. The +ITRF init file is a good example of that. + +A number of init files come pre-bundled with PROJ but it is also possible to +add your own custom init files. PROJ looks for the init files in the directory +listed in the :envvar:`PROJ_LIB` environment variable. + +The format of init files is an identifier in angled brackets and a +proj-string: + +:: + + <3819> +proj=longlat +ellps=bessel + +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs <> + +The above example is the first entry from the ``epsg`` init file. So, this is the +coordinate reference system with ID 3819 in the EPSG database. Comments can be +inserted by prefixing them with a "#". With version 4.10.0 a new special metadata +entry is now accepted in init files. It can be parsed with a function from the public +API. The metadata entry in the epsg init file looks like this at the time of writing: + +:: + +<metadata> +version=9.0.0 +origin=EPSG +lastupdate=2017-01-10 + +Pre-configured proj-strings from init files are used in the following way: + +:: + + $ cs2cs -v +proj=latlong +to +init=epsg:3819 + # ---- From Coordinate System ---- + #Lat/long (Geodetic alias) + # + # +proj=latlong +ellps=WGS84 + # ---- To Coordinate System ---- + #Lat/long (Geodetic alias) + # + # +init=epsg:3819 +proj=longlat +ellps=bessel + # +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs + +It is possible to override parameters when using ``+init``. Just add the parameter +to the proj-string alongside the ``+init`` parameter. For instance by overriding +the ellipsoid as in the following example + +:: + + +init=epsg:25832 +ellps=intl + +where the Hayford ellipsoid is used instead of the predefined GRS80 ellipsoid. + +It is also possible to add additional parameters not specified in the init file, +for instance by adding a central epoch when applying the ITRF2014:NOAM plate +motion model: + +:: + + +init=ITRF2014:NOAM +t_epoch=2010.0 + +which then expands to + +:: + + +proj=helmert +drx=0.000024 +dry=-0.000694 +drz=-0.000063 +convention=position_vector +t_epoch=2010.0 + +Below is a list of the init files that are packaged with PROJ. + + ======== ================================================================ + Name Description + ======== ================================================================ + GL27 Great Lakes Grids + ITRF2000 Full set of transformation parameters between ITRF2000 and other + ITRF's + ITRF2008 Full set of transformation parameters between ITRF2008 and other + ITRF's + ITRF2014 Full set of transformation parameters between ITRF2014 and other + ITRF's + nad27 State plane coordinate systems, North American Datum 1927 + nad83 State plane coordinate systems, North American Datum 1983 + ======== ================================================================ diff --git a/_sources/specifications/geodetictiffgrids.rst.txt b/_sources/specifications/geodetictiffgrids.rst.txt new file mode 100644 index 00000000..2e47858b --- /dev/null +++ b/_sources/specifications/geodetictiffgrids.rst.txt @@ -0,0 +1,645 @@ +.. _geodetictiffgrids: + +================================================================================ +Geodetic TIFF grids (GTG) +================================================================================ + +.. versionadded:: 7.0 + +Introduction +++++++++++++ + +The Geodetic TIFF grid format has been introduced per :ref:`rfc4`. It is a +profile of the TIFF and GeoTIFF formats that addresses the specific requirements +of geodetic grids: horizontal shifts, vertical shifts, velocity grids, etc... +It also follows the `Cloud Optimized GeoTIFF <http://cogeo.org>`_ principles. + +Such grids are available on a :ref:`CDN of GeoTIFF grids <cdn_grids>`. + +.. _gtg_general_description: + +General description ++++++++++++++++++++ + +The general principles that guide the following requirements and recommendations +are such that files will be properly recognized by PROJ, and also by GDAL which +is an easy way to inspect such grid files: + +- `TIFF 6.0 <https://www.awaresystems.be/imaging/tiff/specification/TIFF6.pdf>`_ + based (could possibly be BigTIFF without code changes, if we ever + need some day to handle grids larger than 4GB) + +- `GeoTIFF 1.1 <http://docs.opengeospatial.org/is/19-008r4/19-008r4.html>`_ for the georeferencing. + GeoTIFF 1.1 is a recent standard, compared to the original GeoTIFF 1.0 version, + but its backward compatibility is excellent, so that should not cause much trouble + to readers that are not official GeoTIFF 1.1 compliant. + +- Files hosted on the CDN will use a Geographic 2D CRS for the GeoTIFF GeoKeys. + That CRS is intended to be the interpolation CRS as defined in + `OGC Abstract Specification Topic 2 <http://docs.opengeospatial.org/as/18-005r4/18-005r4.html>`_, + that is the CRS to which grid values are referred to. + + Given that they will nominally be related to the EPSG dataset, the `GeodeticCRSGeoKey + <http://docs.opengeospatial.org/is/19-008r4/19-008r4.html#_requirements_class_geodeticcrsgeokey>`_ + will be used to store the EPSG code of the CRS. If the CRS cannot be reliably + encoded through that key or other geokeys, the ``interpolation_crs_wkt`` metadata + item detailed afterwards should be used. + + This CRS will be generally the source CRS (for geographic to + geographic horizontal shift grids, or geographic to vertical shift grids), but + for vertical to vertical CRS adjustment, this will be the geographic CRS to + which the grid is referenced. In some very rare cases of geographic to vertical + shift grids, the interpolation CRS might be a geographic CRS that is not the + same as the source CRS (into which ellipsoidal height are expressed). The only + instance we have in mind is for the EPSG:7001 "ETRS89 to NAP height (1)" transformation + using the naptrans2008 VDatum-grid which is referenced to Amersfoort EPSG:4289 + instead of ETRS89... + + On the reading side, PROJ will ignore that information: + the CRS is already stored in the source_crs or interpolation_crs column of the + grid_transformation table. + + For geographic to vertical shift files (geoid models), the GeoTIFF 1.1 + convention will be used to store the value of the `VerticalGeoKey + <http://docs.opengeospatial.org/is/19-008r4/19-008r4.html#_requirements_class_verticalgeokey>`_ + So a geoid model that apply to WGS 84 EPSG:4979 will have GeodeticCRSGeoKey = 4326 + and VerticalGeoKey = 4979. + +- Files hosted on the CDN will use the GeoTIFF defined `ModelTiepointTag and ModelPixelScaleTag + <http://docs.opengeospatial.org/is/19-008r4/19-008r4.html#_raster_to_model_coordinate_transformation_requirements>`_ TIFF tags + to store the coordinates of the upper-left pixel and the resolution of the pixels. + On the reading side, they will be required and ModelTransformationTag will be ignored. + + .. note:: + + Regarding anti-meridian handling, a variety of possibilities exist. + We do not attempt to standardize this and files hosted on the CDN will use + a georeferencing close to the original data producer. + For example, NOAA vertical grids that apply to Conterminous USA might even have a top-left + longitude beyond 180 (for consistency with Alaska grids, whose origin is < 180) + Anti-meridian handling in PROJ has probably issues. This RFC does not attempt + to address them in particular, as they are believed to be orthogonal to the + topics it covers, and being mostly implementation issues. + +- Files hosted on the CDN will use the `GTRasterTypeGeoKey + <http://docs.opengeospatial.org/is/19-008r4/19-008r4.html#_requirements_class_gtrastertypegeokey>`_ + = PixelIsPoint convention. + This is the convention used by most existing grid formats currently. Note that GDAL + typically use a PixelIsArea convention (but can handle both conventions), so the + georeferencing it displays when opening a .gsb or .gtx file appears to have a + half-pixel shift regarding to the coordinates stored in the original grid file. On + the reading side, PROJ will accept both conventions (for equivalent georeferencing, + the value of the origin in a PixelIsArea convention is shifted by a half-pixel + towards the upper-left direction). Unspecified behavior if this GeoKey is absent. + +- Files hosted on the CDN will be tiled, presumably with 256x256 tiles (small + grids that are smaller than 256x256 will use a single strip). On the reading + side, PROJ will accept TIFF files with any strip or tile organization. + Tiling is expressed by specifying the TileWidth, TileHeight, TileOffsets + and TileByteCounts tags. Strip organization is expressed by specifying the + RowsPerStrip, StripByteCounts and StripOffsets tags. + +- Files hosted on the CDN will use `Compression + <https://www.awaresystems.be/imaging/tiff/tifftags/compression.html>`_ = DEFLATE + or LZW (to be determined, possibly with + `Predictor <https://www.awaresystems.be/imaging/tiff/tifftags/predictor.html>`_ = 2 + or 3) + On the reading side, PROJ will accept TIFF files with any compression method + (appropriate for the data types and PhotometricInterpretation considered) + supported by the libtiff build used by PROJ. Of course uncompressed files will be supported. + +- Files hosted on the CDN will use little-endian byte ordering. On the reading + side, libtiff will transparently handle both little-endian and big-endian + ordering. + +- Files hosted on the CDN will use PlanarConfiguration=Separate. + The tools described in a later section will order blocks so that blocks needed + for a given location are close to each other. + On the reading side, PROJ will handle also PlanarConfiguration=Contig. + +- Files hosted on the CDN will generally use Float32 (BitsPerSample=32 and SampleFormat=IEEEFP) + Files may be created using Signed Int 16 ( + `BitsPerSample <https://www.awaresystems.be/imaging/tiff/tifftags/bitspersample.html>`_ =16 and + `SampleFormat <https://www.awaresystems.be/imaging/tiff/tifftags/sampleformat.html>`_ = INT), + Unsigned Int 16 (BitsPerSample=16 and SampleFormat=UINT), Signed Int 32 or Unsigned Int 32 generally with an + associate scale/offset. + On the reading side, only those three data types will be supported as well. + +- Files hosted on the CDN will have a `PhotometricInterpretation + <https://www.awaresystems.be/imaging/tiff/tifftags/photometricinterpretation.html>`_ = MinIsBlack. + It will be assumed, and ignored on the reading side. + +- Files hosted on the CDN will nominally have: + + * `SamplesPerPixel <https://www.awaresystems.be/imaging/tiff/tifftags/samplesperpixel.html>`_ = 2 + for horizontal shift grid, with the first sample being the longitude offset + and the second sample being the latitude offset. + + * SamplesPerPixel = 1 for vertical shift grids. + + * SamplesPerPixel = 3 for deformation models combining + horizontal and vertical adjustments. + + And even for the current identified needs of horizontal or vertical shifts, + more samples may be present (to indicate for example uncertainties), but + will be ignored by PROJ. + + The `ExtraSamples <https://www.awaresystems.be/imaging/tiff/tifftags/extrasamples.html>`_ + tag should be set to a value of SamplesPerPixel - 1 (given the rules that + apply for PhotometricInterpretation = MinIsBlack) + +- The `ImageDescription <https://www.awaresystems.be/imaging/tiff/tifftags/imagedescription.html>`_ + tag may be used to convey extra information about the name, provenance, version + and last updated date of the grid. + Will be set when possible for files hosted on the CDN. + Ignored by PROJ. + +- The `Copyright <https://www.awaresystems.be/imaging/tiff/tifftags/copyright.html>`_ + tag may be used to convey extra information about the copyright and license of the grid. + Will be set when possible for files hosted on the CDN. + Ignored by PROJ. + +- The `DateTime <https://www.awaresystems.be/imaging/tiff/tifftags/datetime.html>`_ + tag may be used to convey the date at which the file has been created or + converted. In case of a file conversion, for example from NTv2, this will be + the date at which the conversion has been performed. The ``ImageDescription`` + tag however will contain the latest of the CREATED or UPDATED fields from the NTv2 file. + Will be set when possible for files hosted on the CDN. + Ignored by PROJ. + +- Files hosted on the CDN will use the `GDAL_NODATA + <https://www.awaresystems.be/imaging/tiff/tifftags/gdal_nodata.html>`_ tag to encode + the value of the nodata / missing value, when it applies to the grid. + + If offset and/or scaling is used, the nodata value corresponds to the raw value, + before applying offset and scaling. + The value found in this tag, if present, will be honoured (to the extent to + which current PROJ code makes use of nodata). + For floating point data, writers are strongly discouraged to use non-finite values + (+/- infinity, NaN) of nodata to maximimize interoperability. + The GDAL_NODATA value applies to all samples of a given TIFF IFD. + +- Files hosted on the CDN will use the `GDAL_METADATA + <https://www.awaresystems.be/imaging/tiff/tifftags/gdal_metadata.html>`_ tag to encode extra + metadata not supported by baseline or extended TIFF. + + * The root XML node should be ``GDALMetadata`` + + * Zero, one or several child XML nodes ``Item`` may be present. + + * A Item should have a ``name`` attribute, and a child text node with its value. + ``role`` and ``sample`` attributes may be present for attributes that have + a special semantics (recognized by GDAL). The value of `sample` should be + a integer value between 0 and number_of_samples - 1. + + * Scale and offset to convert integer raw values to floating point values + may be expressed with XML `Item` elements whose name attribute is respectively + ``SCALE`` and ``OFFSET``, and their ``role`` attribute is respectively ``scale`` + and ``offset``. The decoded value will be: {offset} + {scale} * raw_value_from_geotiff_file + + For a offset value of 1 and scaling of 2, the following payload should be + stored: + + .. code-block:: xml + + <GDALMetadata> + <Item name="OFFSET" sample="0" role="offset">1</Item> + <Item name="SCALE" sample="0" role="scale">2</Item> + </GDALMetadata> + + * The type of the grid must be specified with a `Item` whose ``name`` is set + to ``TYPE``. + + Values recognized by PROJ currently are: + + - ``HORIZONTAL_OFFSET``: implies the presence of at least two samples. + The first sample must contain the latitude offset and the second + sample must contain the longitude offset. + Corresponds to PROJ :ref:`hgridshift` method. + + - ``VERTICAL_OFFSET_GEOGRAPHIC_TO_VERTICAL``: implies the presence of at least one sample. + The first sample must contain the vertical adjustment. Must be used when + the source/interpolation CRS is a Geographic CRS and the target CRS a Vertical CRS. + Corresponds to PROJ :ref:`vgridshift` method. + + - ``VERTICAL_OFFSET_VERTICAL_TO_VERTICAL``: implies the presence of at least one sample. + The first sample must contain the vertical adjustment. Must be used when + the source and target CRS are Vertical CRS. + Corresponds to PROJ :ref:`vgridshift` method. + + - ``GEOCENTRIC_TRANSLATION``: implies the presence of at least 3 samples. + The first 3 samples must be respectively the geocentric adjustments along + the X, Y and Z axis. Must be used when the source and target CRS are + geocentric CRS. The interpolation CRS must be a geographic CRS. + Corresponds to PROJ :ref:`xyzgridshift` method. + + - ``VELOCITY``: implies the presence of at least 3 samples. + The first 3 samples must be respectively the velocities along + the E(ast), N(orth), U(p) axis in the local topocentric coordinate system. + Corresponds to PROJ :ref:`deformation` method. + + - ``DEFORMATION_MODEL``: implies the presence of the ``DISPLACEMENT_TYPE`` + and ``UNCERTAINTY_TYPE`` metadata items. + Corresponds to PROJ :ref:`defmodel` method. + + For example: + + .. code-block:: xml + + <Item name="TYPE">HORIZONTAL_OFFSET</Item> + + * The description of each sample must be specified with a Item whose ``name`` + attribute is set to ``DESCRIPTION`` and ``role`` attribute to ``description``. + + Values recognized by PROJ for this Item are currently: + + + ``latitude_offset``: valid for TYPE=HORIZONTAL_OFFSET. Sample values should be + the value to add a latitude expressed in the CRS encoded in the GeoKeys + to obtain a latitude value expressed in the target CRS. + + + ``longitude_offset``: valid for TYPE=HORIZONTAL_OFFSET. Sample values should be + the value to add a longitude expressed in the CRS encoded in the GeoKeys + to obtain a longitude value expressed in the target CRS. + + + ``geoid_undulation``: valid for TYPE=VERTICAL_OFFSET_GEOGRAPHIC_TO_VERTICAL. + For a source CRS being a geographic CRS and a target CRS being a vertical CRS, + sample values should be the value to add to a geoid-related height (that + is expressed in the target CRS) to + get an ellipsoidal height (that is expressed in the source CRS), also + called the geoid undulation. + Note the possible confusion related to what is the source CRS and target CRS and + the semantics of the value stored (to convert from the source to the target, + one must subtract the value contained in the grid). This is the convention + used by the `EPSG:9665 <https://www.epsg-registry.org/export.htm?gml=urn:ogc:def:method:EPSG::9665>`_ + operation method. + + + ``vertical_offset``: valid for TYPE=VERTICAL_OFFSET_VERTICAL_TO_VERTICAL. + For a source and target CRS being vertical CRS, + sample values should be the value to add to an elevation expressed in the + source CRS to obtain a longitude value expressed in the target CRS. + + + ``x_translation`` / ``y_translation`` / ``z_translation``: valid for + TYPE=GEOCENTRIC_TRANSLATION. + Sample values should be the value to add to the input geocentric coordinates + expressed in the source CRS to geocentric coordinates expressed in the target CRS. + + + ``east_velocity`` / ``north_velocity`` / ``up_velocity``: valid for + TYPE=VELOCITY. + Sample values should be the velocity in a linear/time unit in a ENU local + topocentric coordinate system. + + + ``east_offset`` / ``north_offset`` / ``vertical_offset``: valid for + TYPE=DEFORMATION_MODEL. + For east_offset and north_offset, the unit might be degree or metre. + For vertical_offset, the unit must be metre. + + For example: + + .. code-block:: xml + + <Item name="DESCRIPTION" sample="0" role="description">latitude_offset</Item> + <Item name="DESCRIPTION" sample="1" role="description">longitude_offset</Item> + + Other values may be used (not used by PROJ): + + + ``latitude_offset_accuracy``: valid for TYPE=HORIZONTAL_OFFSET. Sample values should be + the accuracy of corresponding latitude_offset samples. Generally in metre (if converted from NTv2) + + + ``longitude_offset_accuracy``: valid for TYPE=HORIZONTAL_OFFSET. Sample values should be + the accuracy of corresponding longitude_offset samples. Generally in metre (if converted from NTv2) + + * The sign convention for the values of the ``longitude_offset`` channel + should be indicated with an Item named ``positive_value`` whose value + can be ``west`` or ``east``. NTv2 products originally use a ``west`` + convention, but when converting from them to GeoTIFF, the sign of those + samples will be inverted so they use a more natural ``east`` convention. + If this item is absent, the default value is ``east``. + + * The unit of the values stored in the grid must be specified for each + sample through an Item of name ``UNITTYPE`` and role ``unittype`` + Valid values should be the name of entries from the EPSG ``unitofmeasure`` + table. To maximize interoperability, writers are strongly encouraged to + limit themselves to the following values: + + For linear units: + + - ``metre`` (default value assumed if absent for vertical shift grid files, and value used for files stored on PROJ CDN) + - ``US survey foot`` + + For angular units: + + - ``degree`` + - ``arc-second`` (default value assumed if absent for longitude and latitude offset samples of horizontal shift grid files, and value used for files stored on PROJ CDN) + + For velocity units: + + - ``millimetres per year`` + + The longitude and latitude offset samples should use the same unit. + The geocentric translation samples should use the same unit. + The velocity samples should use the same unit. + + Example: + + .. code-block:: xml + + <Item name="UNITTYPE" sample="0" role="unittype">arc-second</Item> + <Item name="UNITTYPE" sample="1" role="unittype">arc-second</Item> + + * For TYPE=DEFORMATION_MODEL, the type of the displacement must be specified + with a `Item` whose ``name`` is set to ``DISPLACEMENT_TYPE``. + + The accepted values are: ``HORIZONTAL``, ``VERTICAL``, ``3D`` or ``NONE`` + + * For TYPE=DEFORMATION_MODEL, the type of the uncertainty must be specified + with a `Item` whose ``name`` is set to ``UNCERTAINTY_TYPE``. + + The accepted values are: ``HORIZONTAL``, ``VERTICAL``, ``3D`` or ``NONE`` + + * The ``target_crs_epsg_code`` metadata item should be present. + For a horizontal shift grid, this is the EPSG + code of the target geographic CRS. For a vertical shift grid, this is the + EPSG code of a the target vertical CRS. + If the target CRS has no associated EPSG code, ``target_crs_wkt`` must be + used. + Ignored by PROJ currently. + + * The ``target_crs_wkt`` metadata item must be present if the + ``target_crs_epsg_code`` cannot be used. + Its value should be a valid WKT string according to + `WKT:2015 <http://docs.opengeospatial.org/is/12-063r5/12-063r5.html>`_ + or `WKT:2019 <hhttp://docs.opengeospatial.org/is/18-010r7/18-010r7.html>`_ + Ignored by PROJ currently. + + * The ``source_crs_epsg_code`` metadata item must be present if the source + and interpolation CRS are not the same (typical use case is vertical CRS to vertical CRS + transformation), because the GeoKeys encode the interpolation CRS and not the source CRS. + If the source CRS has no associated EPSG code, ``source_crs_wkt`` must be + used. + Ignored by PROJ currently. + + * The ``source_crs_wkt`` metadata item must be present if the + ``source_crs_epsg_code`` cannot be used. + Its value should be a valid WKT string according to WKT:2015 or WKT:2019. + Ignored by PROJ currently. + + * The ``interpolation_crs_wkt`` metadata item may be present if the GeoKeys + cannot be used to express reliably the interpolation CRS. + Its value should be a valid WKT string according to WKT:2015 or WKT:2019. + Ignored by PROJ currently. + + * The ``recommended_interpolation_method`` metadata item may be present to + describe the method to use to interpolation values at locations not + coincident with nodes stored in the grid file. Potential values: ``bilinear``, + ``bicubic``. + Ignored by PROJ currently. + + * The ``area_of_use`` metadata item can be used to indicate plain text information + about the area of use of the grid (like "USA - Wisconsin"). In case of multiple + subgrids, it should be set only on the first one, but applies to the whole + set of grids, not just the first one. + + * The ``grid_name`` metadata item should be present if there are + subgrids for this grid (that is grids whose extent is contained in the extent + of this grid), or if this is a subgrid. + It is intended to be a relatively short identifier + Will be ignored by PROJ (this information can be inferred by the grids extent) + + * The ``parent_grid_name`` metadata item should be present if this is a + subgrid and its value should be equal to the parent's ``grid_name`` + Will be ignored by PROJ (this information can be inferred by the grids extent) + + * The ``number_of_nested_grids`` metadata item should be present if there are + subgrids for this grid (that is grids whose extent is contained in the extent + of this grid). + Will be ignored by PROJ (this information can be inferred by the grids extent) + +Example ++++++++ + +https://github.com/OSGeo/PROJ-data/blob/master/fr_ign/fr_ign_ntf_r93.tif has +been converted from https://github.com/OSGeo/proj-datumgrid/blob/master/ntf_r93.gsb +with https://github.com/OSGeo/PROJ-data/blob/master/grid_tools/ntv2_to_gtiff.py + +:: + + $ tiffinfo ntf_r93.tif + + TIFF Directory at offset 0x4e (78) + Image Width: 156 Image Length: 111 + Bits/Sample: 32 + Sample Format: IEEE floating point + Compression Scheme: AdobeDeflate + Photometric Interpretation: min-is-black + Extra Samples: 3<unspecified, unspecified, unspecified> + Samples/Pixel: 4 + Rows/Strip: 111 + Planar Configuration: separate image planes + ImageDescription: NTF (EPSG:4275) to RGF93 (EPSG:4171). Converted from ntf_r93.gsb (version IGN07_01, last updated on 2007-10-31) + DateTime: 2019:12:09 00:00:00 + Copyright: Derived from work by IGN France. Open License https://www.etalab.gouv.fr/wp-content/uploads/2014/05/Open_Licence.pdf + Tag 33550: 0.100000,0.100000,0.000000 + Tag 33922: 0.000000,0.000000,0.000000,-5.500000,52.000000,0.000000 + Tag 34735: 1,1,1,3,1024,0,1,2,1025,0,1,2,2048,0,1,4275 + Tag 42112: <GDALMetadata> + <Item name="grid_name">FRANCE</Item> + <Item name="target_crs_epsg_code">4171</Item> + <Item name="TYPE">HORIZONTAL_OFFSET</Item> + <Item name="UNITTYPE" sample="0" role="unittype">arc-second</Item> + <Item name="DESCRIPTION" sample="0" role="description">latitude_offset</Item> + <Item name="positive_value" sample="1">east</Item> + <Item name="UNITTYPE" sample="1" role="unittype">arc-second</Item> + <Item name="DESCRIPTION" sample="1" role="description">longitude_offset</Item> + <Item name="UNITTYPE" sample="2" role="unittype">arc-second</Item> + <Item name="DESCRIPTION" sample="2" role="description">latitude_offset_accuracy</Item> + <Item name="UNITTYPE" sample="3" role="unittype">arc-second</Item> + <Item name="DESCRIPTION" sample="3" role="description">longitude_offset_accuracy</Item> + </GDALMetadata> + + Predictor: floating point predictor 3 (0x3) + + +:: + + $ listgeo ntf_r93.tif + + Geotiff_Information: + Version: 1 + Key_Revision: 1.1 + Tagged_Information: + ModelTiepointTag (2,3): + 0 0 0 + -5.5 52 0 + ModelPixelScaleTag (1,3): + 0.1 0.1 0 + End_Of_Tags. + Keyed_Information: + GTModelTypeGeoKey (Short,1): ModelTypeGeographic + GTRasterTypeGeoKey (Short,1): RasterPixelIsPoint + GeodeticCRSGeoKey (Short,1): Code-4275 (NTF) + End_Of_Keys. + End_Of_Geotiff. + + GCS: 4275/NTF + Datum: 6275/Nouvelle Triangulation Francaise + Ellipsoid: 7011/Clarke 1880 (IGN) (6378249.20,6356515.00) + Prime Meridian: 8901/Greenwich (0.000000/ 0d 0' 0.00"E) + Projection Linear Units: User-Defined (1.000000m) + + Corner Coordinates: + Upper Left ( 5d30' 0.00"W, 52d 0' 0.00"N) + Lower Left ( 5d30' 0.00"W, 40d54' 0.00"N) + Upper Right ( 10d 6' 0.00"E, 52d 0' 0.00"N) + Lower Right ( 10d 6' 0.00"E, 40d54' 0.00"N) + Center ( 2d18' 0.00"E, 46d27' 0.00"N) + +:: + + $ gdalinfo ntf_r93.tif + + Driver: GTiff/GeoTIFF + Files: ntf_r93.tif + Size is 156, 111 + Coordinate System is: + GEOGCRS["NTF", + DATUM["Nouvelle Triangulation Francaise", + ELLIPSOID["Clarke 1880 (IGN)",6378249.2,293.466021293627, + 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]], + ID["EPSG",4275]] + Data axis to CRS axis mapping: 2,1 + Origin = (-5.550000000000000,52.049999999999997) + Pixel Size = (0.100000000000000,-0.100000000000000) + Metadata: + AREA_OR_POINT=Point + grid_name=FRANCE + target_crs_epsg_code=4171 + TIFFTAG_DATETIME=2019:12:09 00:00:00 + TIFFTAG_IMAGEDESCRIPTION=NTF (EPSG:4275) to RGF93 (EPSG:4171). Converted from ntf_r93.gsb (version IGN07_01, last updated on 2007-10-31) + TYPE=HORIZONTAL_OFFSET + Image Structure Metadata: + COMPRESSION=DEFLATE + INTERLEAVE=BAND + Corner Coordinates: + Upper Left ( -5.5500000, 52.0500000) ( 5d33' 0.00"W, 52d 3' 0.00"N) + Lower Left ( -5.5500000, 40.9500000) ( 5d33' 0.00"W, 40d57' 0.00"N) + Upper Right ( 10.0500000, 52.0500000) ( 10d 3' 0.00"E, 52d 3' 0.00"N) + Lower Right ( 10.0500000, 40.9500000) ( 10d 3' 0.00"E, 40d57' 0.00"N) + Center ( 2.2500000, 46.5000000) ( 2d15' 0.00"E, 46d30' 0.00"N) + Band 1 Block=156x111 Type=Float32, ColorInterp=Gray + Description = latitude_offset + Unit Type: arc-second + Band 2 Block=156x111 Type=Float32, ColorInterp=Undefined + Description = longitude_offset + Unit Type: arc-second + Metadata: + positive_value=east + Band 3 Block=156x111 Type=Float32, ColorInterp=Undefined + Description = latitude_offset_accuracy + Unit Type: arc-second + Band 4 Block=156x111 Type=Float32, ColorInterp=Undefined + Description = longitude_offset_accuracy + Unit Type: arc-second + +Multi-grid storage +++++++++++++++++++ + +Formats like NTv2 can contain multiple subgrids. This can be transposed to +TIFF by using several IFD chained together with the last 4 bytes (or 8 bytes +for BigTIFF) of an IFD pointing to the offset of the next one. + +The first IFD should have a full description according to the +:ref:`General description <gtg_general_description>`. +Subsequent IFD might have a more compact description, omitting for example, CRS +information if it is identical to the main IFD (which should be the case for +the currently envisionned use cases), or Copyright / ImageDescription metadata +items. + +Each IFD will have its +`NewSubfileType <https://www.awaresystems.be/imaging/tiff/tifftags/newsubfiletype.html>`_ +tag set to 0. + +If a low-resolution grid is available, it should be put before subgrids of +higher-resolution in the chain of IFD linking. On reading, PROJ will use the +value from the highest-resolution grid that contains the point of interest. + +For efficient reading from the network, files hosted on the CDN will use +a layout similar to the one described in the `low level paragraph of the Cloud Optimized GeoTIFF +GDAL driver page <https://gdal.org/drivers/raster/cog.html#low-level>`_ + +The layout for a file converted from NTv2 will for example be: + +- TIFF/BigTIFF header/signature and pointer to first IFD (Image File Directory) +- "ghost area" indicating the generated process +- IFD of the first grid, followed by TIFF tags values, excluding the TileOffsets and TileByteCounts arrays +- ... +- IFD of the last grid, followed by TIFF tags values, excluding the GDAL_METADATA tag, TileOffsets and TileByteCounts arrays +- TileOffsets and TileByteCounts arrays for first IFD +- ... +- TileOffsets and TileByteCounts arrays for last IFD +- Value of GDAL_METADATA tag for IFDs following the first IFD +- First IFD: Data corresponding to latitude offset of Block_0_0 +- First IFD: Data corresponding to longitude offset of Block_0_0 +- First IFD: Data corresponding to latitude offset of Block_0_1 +- First IFD: Data corresponding to longitude offset of Block_0_1 +- ... +- First IFD: Data corresponding to latitude offset of Block_n_m +- First IFD: Data corresponding to longitude offset of Block_n_m +- ... +- Last IFD: Data corresponding to latitude offset of Block_0_0 +- Last IFD: Data corresponding to longitude offset of Block_0_0 +- Last IFD: Data corresponding to latitude offset of Block_0_1 +- Last IFD: Data corresponding to longitude offset of Block_0_1 +- ... +- Last IFD: Data corresponding to latitude offset of Block_n_m +- Last IFD: Data corresponding to longitude offset of Block_n_m + +If longitude_offset_accuracy and latitude_offset_accuracy are present, this +will be followed by: + +- First IFD: Data corresponding to latitude offset accuracy of Block_0_0 +- First IFD: Data corresponding to longitude offset accuracy of Block_0_0 +- ... +- First IFD: Data corresponding to latitude offset accuracy of Block_n_m +- First IFD: Data corresponding to longitude offset accuracy of Block_n_m +- ... +- Last IFD: Data corresponding to latitude offset accuracy of Block_0_0 +- Last IFD: Data corresponding to longitude offset accuracy of Block_0_0 +- ... +- Last IFD: Data corresponding to latitude offset accuracy of Block_n_m +- Last IFD: Data corresponding to longitude offset accuracy of Block_n_m + +.. note:: + + TIFF has another mechanism to link IFDs, the SubIFD tag. This potentially + enables to define a hierarchy of IFDs (similar to HDF5 groups). There is no + support for that in most TIFF-using software, notably GDAL, and no compelling + need to have a nested hierarchy, so "flat" organization with the standard IFD chaining + mechanism is adopted. + +Examples of multi-grid dataset +++++++++++++++++++++++++++++++ + +https://github.com/OSGeo/PROJ-data/blob/master/au_icsm/au_icsm_GDA94_GDA2020_conformal.tif has +been converted from https://github.com/OSGeo/proj-datumgrid/blob/master/oceania/GDA94_GDA2020_conformal.gsb +with https://github.com/OSGeo/PROJ-data/blob/master/grid_tools/ntv2_to_gtiff.py + +It contains 5 subgrids. All essential metadata to list the subgrids and their +georeferencing is contained within the first 3 KB of the file. + +The file size is 4.8 MB using DEFLATE compression and floating-point predictor. +It results from a lossless conversion from the 83 MB of the original .gsb file. + +https://github.com/OSGeo/PROJ-data/blob/master/ca_nrc/ca_nrc_ntv2_0.tif has +been converted from https://github.com/OSGeo/proj-datumgrid/blob/master/north-america/ntv2_0.gsb + +It contains 114 subgrids. All essential metadata to list the subgrids and their +georeferencing is contained within the first 40 KB of the file. diff --git a/_sources/specifications/index.rst.txt b/_sources/specifications/index.rst.txt new file mode 100644 index 00000000..1853ca53 --- /dev/null +++ b/_sources/specifications/index.rst.txt @@ -0,0 +1,14 @@ +.. _specifications: + +================================================================================ +Specifications +================================================================================ + +PROJ implements a number of extensions to standards, that are described below +for the sake of broader interoperability. + +.. toctree:: + :maxdepth: 1 + + projjson + geodetictiffgrids diff --git a/_sources/specifications/projjson.rst.txt b/_sources/specifications/projjson.rst.txt new file mode 100644 index 00000000..c2280c0b --- /dev/null +++ b/_sources/specifications/projjson.rst.txt @@ -0,0 +1,269 @@ +.. _projjson: + +================================================================================ +PROJJSON +================================================================================ + +PROJJSON is a JSON encoding of +`WKT2:2019 / ISO-19162:2019 <http://docs.opengeospatial.org/is/18-010r7/18-010r7.html>`_, +which itself implements the model of +`OGC Topic 2: Referencing by coordinates <http://docs.opengeospatial.org/as/18-005r4/18-005r4.html>`_. +Apart from the difference of encodings, the semantics is intended to be exactly +the same as WKT2:2019. + +PROJJSON is available as input and output of PROJ since PROJ 6.2. + +The current version is 0.4. + +Schema +------ + +A JSON schema of its grammar is available at +https://proj.org/schemas/v0.4/projjson.schema.json + +History +------- + +* v0.4: additional properties allowed in id object (version, authority_citation, uri) +* v0.3: additional properties allowed in BoundCRS object (name, scope, area, bbox, usages, remarks, id, ids) +* v0.2: addition of geoid_model in VerticalCRS object. +* v0.1: initial version for PROJ 6.2 + +Content +------- + +The high level objects are: + +* Coordinate Reference Systems (CRS): + + - Common ones: + + + ``GeographicCRS`` + + ``GeodeticCRS`` + + ``ProjectedCRS`` + + ``CompoundCRS`` + + ``BoundCRS`` + + - More esoteric ones: + + + ``VerticalCRS`` + + ``EngineeringCRS`` + + ``TemporalCRS`` + + ``ParametricCRS`` + + ``DerivedGeographicCRS`` + + ``DerivedGeodeticCRS`` + + ``DerivedProjectedCRS`` + + ``DerivedVerticalCRS`` + + ``DerivedEngineeringCRS`` + + ``DerivedTemporalCRS`` + + ``DerivedParametricCRS`` + +* Coordinate operations: + + - ``Transformation`` + - ``Conversion`` + - ``ConcatenatedOperation`` + +* Others: + + - ``PrimeMeridian`` + - ``Ellipsoid`` + - ``Datum`` + - ``DatumEnsemble`` + +Examples +-------- + +GeographicCRS ++++++++++++++ + +The following invocation + +:: + + projinfo EPSG:4326 -o PROJJSON -q + +will output: + +.. code-block:: json + + { + "$schema": "https://proj.org/schemas/v0.1/projjson.schema.json", + "type": "GeographicCRS", + "name": "WGS 84", + "datum": { + "type": "GeodeticReferenceFrame", + "name": "World Geodetic System 1984", + "ellipsoid": { + "name": "WGS 84", + "semi_major_axis": 6378137, + "inverse_flattening": 298.257223563 + } + }, + "coordinate_system": { + "subtype": "ellipsoidal", + "axis": [ + { + "name": "Geodetic latitude", + "abbreviation": "Lat", + "direction": "north", + "unit": "degree" + }, + { + "name": "Geodetic longitude", + "abbreviation": "Lon", + "direction": "east", + "unit": "degree" + } + ] + }, + "area": "World", + "bbox": { + "south_latitude": -90, + "west_longitude": -180, + "north_latitude": 90, + "east_longitude": 180 + }, + "id": { + "authority": "EPSG", + "code": 4326 + } + } + + +ProjectedCRS +++++++++++++ + +The following invocation + +:: + + projinfo EPSG:32631 -o PROJJSON -q + +will output: + +.. code-block:: json + + { + "$schema": "https://proj.org/schemas/v0.1/projjson.schema.json", + "type": "ProjectedCRS", + "name": "WGS 84 / UTM zone 31N", + "base_crs": { + "name": "WGS 84", + "datum": { + "type": "GeodeticReferenceFrame", + "name": "World Geodetic System 1984", + "ellipsoid": { + "name": "WGS 84", + "semi_major_axis": 6378137, + "inverse_flattening": 298.257223563 + } + }, + "coordinate_system": { + "subtype": "ellipsoidal", + "axis": [ + { + "name": "Geodetic latitude", + "abbreviation": "Lat", + "direction": "north", + "unit": "degree" + }, + { + "name": "Geodetic longitude", + "abbreviation": "Lon", + "direction": "east", + "unit": "degree" + } + ] + }, + "id": { + "authority": "EPSG", + "code": 4326 + } + }, + "conversion": { + "name": "UTM zone 31N", + "method": { + "name": "Transverse Mercator", + "id": { + "authority": "EPSG", + "code": 9807 + } + }, + "parameters": [ + { + "name": "Latitude of natural origin", + "value": 0, + "unit": "degree", + "id": { + "authority": "EPSG", + "code": 8801 + } + }, + { + "name": "Longitude of natural origin", + "value": 3, + "unit": "degree", + "id": { + "authority": "EPSG", + "code": 8802 + } + }, + { + "name": "Scale factor at natural origin", + "value": 0.9996, + "unit": "unity", + "id": { + "authority": "EPSG", + "code": 8805 + } + }, + { + "name": "False easting", + "value": 500000, + "unit": "metre", + "id": { + "authority": "EPSG", + "code": 8806 + } + }, + { + "name": "False northing", + "value": 0, + "unit": "metre", + "id": { + "authority": "EPSG", + "code": 8807 + } + } + ] + }, + "coordinate_system": { + "subtype": "Cartesian", + "axis": [ + { + "name": "Easting", + "abbreviation": "E", + "direction": "east", + "unit": "metre" + }, + { + "name": "Northing", + "abbreviation": "N", + "direction": "north", + "unit": "metre" + } + ] + }, + "area": "World - N hemisphere - 0°E to 6°E - by country", + "bbox": { + "south_latitude": 0, + "west_longitude": 0, + "north_latitude": 84, + "east_longitude": 6 + }, + "id": { + "authority": "EPSG", + "code": 32631 + } + } diff --git a/_sources/usage/differences.rst.txt b/_sources/usage/differences.rst.txt new file mode 100644 index 00000000..3bc2f54d --- /dev/null +++ b/_sources/usage/differences.rst.txt @@ -0,0 +1,147 @@ +.. _differences: + +================================================================================ +Known differences between versions +================================================================================ + +Once in a while, a new version of PROJ causes changes in the existing behavior. +In this section we track deliberate changes to PROJ that break from previous +behavior. Most times that will be caused by a bug fix. Unfortunately, some bugs +have existed for so long that their faulty behavior is relied upon by software +that uses PROJ. + +Behavioural changes caused by new bugs are not tracked here, as they should be +fixed in later versions of PROJ. + +Version 4.6.0 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The default datum application behavior changed with the 4.6.0 release. PROJ +will now only apply a datum shift if both the source and destination coordinate +system have valid datum shift information. + +The PROJ 4.6.0 Release Notes states + + MAJOR: Rework :c:func:`pj_transform()` to avoid applying ellipsoid to ellipsoid + transformations as a datum shift when no datum info is available. + + +Version 5.0.0 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Longitude wrapping when using custom central meridian +------------------------------------------------------------------------------- + +By default PROJ wraps output longitudes in the range -180 to 180. Previous to +PROJ 5, this was handled incorrectly when a custom central meridian was set with +:option:`+lon_0`. This caused a change in sign on the resulting easting as seen +below:: + + $ proj +proj=merc +lon_0=110 + -70 0 + -20037508.34 0.00 + 290 0 + 20037508.34 0.00 + +From PROJ 5 on onwards, the same input now results in same coordinates, as seen +from the example below where PROJ 5 is used:: + + $ proj +proj=merc +lon_0=110 + -70 0 + -20037508.34 0.00 + 290 0 + -20037508.34 0.00 + +The change is made on the basis that :math:`\lambda=290^{\circ}` is a full +rotation of the circle larger than :math:`\lambda=-70^{\circ}` and hence +should return the same output for both. + +Adding the ``+over`` flag to the projection definition provides +the old behavior. + +Version 6.0.0 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Removal of :file:`proj_def.dat` +------------------------------- + +Before PROJ 6, the :file:`proj_def.dat` was used to provide general and per-projection +parameters, when ``+no_defs`` was not specified. It has now been removed. In case, +no ellipsoid or datum specification is provided in the PROJ string, the +default ellipsoid is GRS80 (was WGS84 in previous PROJ versions). + +Changes to :ref:`deformation<deformation>` +------------------------------------------------------------------ +.. _differences_deformation: + + +Reversed order of operation +........................... + +In the initial version of the of :ref:`deformation<deformation>` operation +the time span between :math:`t_{obs}` and :math:`t_c` was determined by the +expression + +.. math:: + + dt = t_c - t_{obs} + +With version 6.0.0 this has been reversed in order to behave similarly to +the :ref:`Helmert operation<helmert>`, which determines time differences as + +.. math:: + + dt = t_{obs} - t_c + +Effectively this means that the direction of the operation has been reversed, +so that what in PROJ 5 was a forward operation is now an inverse operation and +vice versa. + +Pipelines written for PROJ 5 can be migrated to PROJ 6 by adding :option:`+inv` +to forward steps involving the deformation operation. Similarly +:option:`+inv` should be removed from inverse steps to be compatible with +PROJ 6. + +Removed ``+t_obs`` parameter +............................. + +The ``+t_obs`` parameter was confusing for users since it effectively +overwrote the observation time in input coordinates. To make it more clear +what is the operation is doing, users are now required to directly specify +the time span for which they wish to apply a given deformation. The parameter +:option:`+dt` has been added for that purpose. The new parameter is mutually +exclusive with :option:`+t_epoch`. :option:`+dt` is used when deformation +for a set amount of time is needed and :option:`+t_epoch` is used (in +conjunction with the observation time of the input coordinate) when +deformation from a specific epoch to the observation time is needed. + +Version 6.3.0 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +projinfo +-------- + +Before PROJ 6.3.0, WKT1:GDAL was implicitly calling ``--boundcrs-to-wgs84``, to +add a ``TOWGS84[]`` node in some cases. This is no longer the case. + + +Version 7.0.0 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +proj +-------- + +Removed ``-ld`` option from application, since it promoted use of deprecated +parameters like ``+towgs`` and ``+datum``. + +cs2cs +-------- + +Removed ``-ld`` option from application, since it promoted use of deprecated +parameters like ``+towgs`` and ``+datum``. + +UTF-8 adoption +-------------- + +The value of all path, filenames passed to PROJ through function calls, PROJ +strings or environment variables should be encoded in UTF-8. diff --git a/_sources/usage/ellipsoids.rst.txt b/_sources/usage/ellipsoids.rst.txt new file mode 100644 index 00000000..cd4b0c43 --- /dev/null +++ b/_sources/usage/ellipsoids.rst.txt @@ -0,0 +1,159 @@ +.. _ellipsoids: + +================================================================================ +Ellipsoids +================================================================================ +An ellipsoid is a mathematically defined surface which approximates the *geoid*: +the surface of the Earth's gravity field, which is approximately the same as +mean sea level. + + +.. figure:: ../../images/general_ellipsoid.png + :width: 500 px + :align: center + :alt: Global and local fitting of the ellipsoid + + Global and local fitting of the ellipsoid + + +A complete ellipsoid definition comprises a size (primary) and a shape (secondary) +parameter. + +.. _ellipsoid_size_parameters: + +Ellipsoid size parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +R=<value> + + Radius of the sphere, :math:`R`. + +.. option:: +a=<value> + + Semi-major axis of the ellipsoid, :math:`a`. + +.. _ellipsoid_shape_parameters: + +Ellipsoid shape parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +rf=<value> + + Reverse flattening of the ellipsoid, :math:`1/f`. + +.. option:: +f=<value> + + Flattening of the ellipsoid, :math:`f`. + +.. option:: +es=<value> + + Eccentricity squared, :math:`e^2`. + +.. option:: +e=<value> + + Eccentricity, :math:`e`. + +.. option:: +b=<value> + + Semi-minor axis, :math:`b`. + +The ellipsoid definition may be augmented with a spherification flag, turning +the ellipsoid into a sphere with features defined by the ellipsoid. + +.. _ellipsoid_spherification_parameters: + +Ellipsoid spherification parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +R_A=<value> + + A sphere with the same surface area as the ellipsoid. + +.. option:: +R_V=<value> + + A sphere with the same volume as the ellipsoid. + +.. option:: +R_a=<value> + + A sphere with :math:`R = (a + b)/2` (arithmetic mean). + +.. option:: +R_g=<value> + + A sphere with :math:`R = \sqrt{ab}` (geometric mean). + +.. option:: +R_h=<value> + + A sphere with :math:`R = 2ab/(a+b)` (harmonic mean). + +.. option:: +R_lat_a=<phi> + + A sphere with :math:`R` being the arithmetic mean of the corresponding + ellipsoid at latitude :math:`\phi`. + +.. option:: +R_lat_g=<phi> + + A sphere with :math:`R` being the geometric mean of the corresponding + ellipsoid at latitude :math:`\phi`. + +If :option:`+R` is given as size parameter, any shape and spherification +parameters given are ignored. + +.. _ellipsoid_definitions: + +Built-in ellipsoid definitions ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The ``ellps=xxx`` parameter provides both size and shape for a number of +built-in ellipsoid definitions. + + ============ ================================= ============================ + ellps Parameters Datum name + ============ ================================= ============================ + GRS80 a=6378137.0 rf=298.257222101 GRS 1980(IUGG, 1980) + airy a=6377563.396 b=6356256.910 Airy 1830 + bessel a=6377397.155 rf=299.1528128 Bessel 1841 + clrk66 a=6378206.4 b=6356583.8 Clarke 1866 + intl a=6378388.0 rf=297. International 1909 (Hayford) + WGS60 a=6378165.0 rf=298.3 WGS 60 + WGS66 a=6378145.0 rf=298.25 WGS 66 + WGS72 a=6378135.0 rf=298.26 WGS 72 + WGS84 a=6378137.0 rf=298.257223563 WGS 84 + sphere a=6370997.0 b=6370997.0 Normal Sphere (r=6370997) + ============ ================================= ============================ + +If size and shape are given as ``ellps=xxx``, later shape and size parameters +are are taken into account as modifiers for the built-in ellipsoid definition. + +While this may seem strange, it is in accordance with historical PROJ +behavior. It can e.g. be used to define coordinates on the ellipsoid +scaled to unit semimajor axis by specifying ``+ellps=xxx +a=1`` + +.. _ellipsoid_transformation_examples: + +Transformation examples ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Spherical earth with radius 7000km: + +:: + + proj=laton R=7000000 + +Using the GRS80 ellipsoid: + +:: + + proj=laton ellps=GRS80 + +Expressing ellipsoid by semi-major axis and reverse flattening (:math:`1/f`): + +:: + + proj=laton a=6378137.0 rf=298.25 + +Spherical earth based on volume of ellipsoid + +:: + + proj=laton a=6378137.0 rf=298.25 +R_V + diff --git a/_sources/usage/environmentvars.rst.txt b/_sources/usage/environmentvars.rst.txt new file mode 100644 index 00000000..0439d918 --- /dev/null +++ b/_sources/usage/environmentvars.rst.txt @@ -0,0 +1,96 @@ +.. _environmentvars: + +================================================================================ +Environment variables +================================================================================ + +PROJ can be controlled by setting environment variables. Most users will +have a use for the :envvar:`PROJ_LIB`. + +On UNIX systems environment variables can be set for a shell-session with:: + + $ export VAR="some variable" + +or it can be set for just one command line call:: + + $ VAR="some variable" ./cmd + +Environment variables on UNIX are usually removed with the ``unset`` command:: + + $ unset VAR + +On windows systems environment variables can be set in the command line with:: + + > set VAR="some variable" + +``VAR`` will be available for the entire session, unless it is unset. This is +done by setting the variable with no content:: + + > set VAR= + +.. envvar:: PROJ_LIB + + The location of PROJ :doc:`resource files<../resource_files>`. + + Starting with PROJ 6, multiple directories can be specified. On Unix, they + should be separated by the colon (:) character. on Windows, by the semi-colon (;) + character. + + PROJ is hardcoded to look for resource files + in other locations as well, amongst those are the + installation directory (usually ``share/proj`` under the PROJ + installation root) and the current folder. + + You can also set the location of the resource files using + :func:`proj_context_set_search_paths` in the :file:`proj.h` API header. + +.. versionchanged:: 6.1.0 + + Starting with PROJ version 6.1.0, the paths set by + :func:`proj_context_set_search_paths` will have priority over the + :envvar:`PROJ_LIB` to allow for multiple versions of PROJ + resource files on your system without conflicting. + + +.. envvar:: PROJ_AUX_DB + + .. versionadded:: 8.1.0 + + To set the path to one or several auxiliary SQLite3 databases of structure + identical to the main :file:`proj.db` database and that can contain additional + object (CRS, transformation, ...) definitions. If several paths are + provided, they must be separated by the colon (:) character on Unix, and + on Windows, by the semi-colon (;) character. + + +.. envvar:: PROJ_DEBUG + + Set the debug level of PROJ. The default debug level is zero, which results + in no debug output when using PROJ. A number from 1-3, with 3 being the most + verbose setting. + +.. envvar:: PROJ_NETWORK + + .. versionadded:: 7.0.0 + + If set to ON, enable the capability to use remote grids stored on CDN + (Content Delivery Network) storage, when grids are not available locally. + Alternatively, the :c:func:`proj_context_set_enable_network` function can + be used. + +.. envvar:: PROJ_NETWORK_ENDPOINT + + .. versionadded:: 7.0.0 + + Define the endpoint of the CDN storage. Normally defined through the + :file:`proj.ini` configuration file locale in :envvar:`PROJ_LIB`. + Alternatively, the :c:func:`proj_context_set_url_endpoint` function can + be used. + +.. envvar:: PROJ_CURL_CA_BUNDLE + + .. versionadded:: 7.2.0 + + Define a custom path to the CA Bundle file. This can be useful if `curl` + and :envvar:`PROJ_NETWORK` are enabled. Alternatively, the + :c:func:`proj_curl_set_ca_bundle_path` function can be used. diff --git a/_sources/usage/index.rst.txt b/_sources/usage/index.rst.txt new file mode 100644 index 00000000..4bb75121 --- /dev/null +++ b/_sources/usage/index.rst.txt @@ -0,0 +1,21 @@ +.. _usage: + +================================================================================ +Using PROJ +================================================================================ + +The main purpose of PROJ is to transform coordinates from one coordinate +reference system to another. This can be achieved either with the included +command line applications or the C API that is a part of the software package. + + +.. toctree:: + :maxdepth: 1 + + quickstart + projections + transformation + ellipsoids + environmentvars + differences + network diff --git a/_sources/usage/network.rst.txt b/_sources/usage/network.rst.txt new file mode 100644 index 00000000..37a32d34 --- /dev/null +++ b/_sources/usage/network.rst.txt @@ -0,0 +1,107 @@ +.. _network: + +================================================================================ +Network capabilities +================================================================================ + +.. versionadded:: 7.0 + +PROJ 7.0 has introduced, per :ref:`rfc4`, the capability to work with grid files +that are not installed on the local machine where PROJ is executed. + +This enables to transparently download the parts of grids that are needed to +perform a coordinate transformation. + +.. _cdn_grids: + +CDN of GeoTIFF grids +-------------------- + +Files are accessed by default through a CDN (Content Delivery Network), +accessible through https://cdn.proj.org, that contains :ref:`geodetictiffgrids` +datasets which are mirrored and managed by the +https://github.com/OSGeo/PROJ-data/ GitHub project. +Files in the CDN are designed to be used by PROJ 7 or later, but any software +project wishing to use the CDN for shifting support are encouraged to +participate in the project and leverage the CDN. + +How to enable network capabilities ? +------------------------------------ + +This capability assumes that PROJ has been build against `libcurl`, and that +the user authorizes network access. + +Authorizing network access can be done in multiple ways: + + - enabling / uncommenting the ``network = on`` line of :ref:`proj-ini` + - defining the :envvar:`PROJ_NETWORK` environment variable to ON + - or using the :cpp:func:`proj_context_set_enable_network` with a + ``enabled = TRUE`` value. + +.. note:: + + Instead of using the `libcurl` implementation, an application using the PROJ + API can supply its own network implementation through C function callbacks + with :cpp:func:`proj_context_set_network_callbacks`. Enabling network use + must still be done with one of the above mentioned method. + +Setting endpoint +---------------- + +When this is enabled, and a grid is not found in the various locations where +:ref:`resource files are looked for <resource_file_paths>`, PROJ will then +attempt at loading the file from a remote server, which defaults to +https://cdn.proj.org in :ref:`proj-ini`. This location can be changed with +the :envvar:`PROJ_NETWORK_ENDPOINT` environment variable or with +:cpp:func:`proj_context_set_url_endpoint`. + +Caching +------- + +To avoid repeated access to network, a local cache of downloaded chunks of grids +is implemented as SQLite3 database, :file:`cache.db`, stored in the +:ref:`PROJ user writable directory <user_writable_directory>`. + +This local caching is enabled by default (can be changed in :ref:`proj-ini` or +with :cpp:func:`proj_grid_cache_set_enable`). The default maximum size of the +cache is 300 MB, which is more than half of the total size of grids available, +at time of writing. This size can also be customized in :ref:`proj-ini` or +with :cpp:func:`proj_grid_cache_set_max_size` + +Download API +------------ + +When on-demand loading of grid is not desirable, the PROJ API also offers the +capability to download whole grids in the +:ref:`PROJ user writable directory <user_writable_directory>` by using the +:cpp:func:`proj_is_download_needed` and :cpp:func:`proj_download_file` functions. + +Download utility +---------------- + +:ref:`projsync` is a tool for downloading resource files. + + +Mirroring +--------- + +If you are able, you are encouraged to mirror the grids via AWS S3 command line: + +:: + + aws s3 sync s3://cdn.proj.org . + +If direct S3 access is not possible, you can also use wget to locally mirror the +data: + +:: + + wget --mirror https://cdn.proj.org/ + +Acknowledgments +--------------- + +The s3://cdn.proj.org bucket is hosted by the +`Amazon Public Datasets program <https://aws.amazon.com/opendata/public-datasets/>`_. +CDN services are provided by the AWS Public Dataset team via +`CloudFront <https://aws.amazon.com/cloudfront/>`_ diff --git a/_sources/usage/projections.rst.txt b/_sources/usage/projections.rst.txt new file mode 100644 index 00000000..1f2e504f --- /dev/null +++ b/_sources/usage/projections.rst.txt @@ -0,0 +1,163 @@ +.. _projections_intro: + +================================================================================ +Cartographic projection +================================================================================ + +The foundation of PROJ is the large number of +:doc:`projections<../operations/projections/index>` available in the library. This section +is devoted to the generic parameters that can be used on any projection in the +PROJ library. + +Below is a list of PROJ parameters which can be applied to most coordinate +system definitions. This table does not attempt to describe the parameters +particular to particular projection types. These can be found on the pages +documenting the individual :doc:`projections<../operations/projections/index>`. + + ========== ================================================================ + Parameter Description + ========== ================================================================ + +a Semimajor radius of the ellipsoid axis + +axis Axis orientation + +b Semiminor radius of the ellipsoid axis + +ellps Ellipsoid name (see ``proj -le``) + +k Scaling factor (deprecated) + +k_0 Scaling factor + +lat_0 Latitude of origin + +lon_0 Central meridian + +lon_wrap Center longitude to use for wrapping (see below) + +over Allow longitude output outside -180 to 180 range, disables + wrapping (see below) + +pm Alternate prime meridian (typically a city name, see below) + +proj Projection name (see ``proj -l``) + +units meters, US survey feet, etc. + +vunits vertical units. + +x_0 False easting + +y_0 False northing + ========== ================================================================ + +In the sections below most of the parameters are explained in details. + +Units ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Horizontal units can be specified using the ``+units`` keyword with a symbolic +name for a unit (i.e. ``us-ft``). Alternatively the translation to meters can be +specified with the ``+to_meter`` keyword (i.e. 0.304800609601219 for US feet). The +``-lu`` argument to :program:`cs2cs` or :program:`proj` can be used to list +symbolic unit names. The default unit for projected coordinates is the meter. +A few special projections deviate from this behavior, most notably the +latlong pseudo-projection that returns degrees. + +Vertical (Z) units can be specified using the ``+vunits`` keyword with a +symbolic name for a unit (i.e. ``us-ft``). Alternatively the translation to +meters can be specified with the ``+vto_meter`` keyword (i.e. 0.304800609601219 +for US feet). The ``-lu`` argument to :program:`cs2cs` or :program:`proj` can +be used to list symbolic unit names. If no vertical units are specified, the +vertical units will default to be the same as the horizontal coordinates. + +.. note:: + :program:`proj` does not handle vertical units at all and hence the + ``+vto_meter`` argument will be ignored. + +Scaling of output units can be done by applying the ``+k_0`` argument. The +returned coordinates are scaled by the value assigned with the ``+k_0`` +parameter. + +False Easting/Northing ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Virtually all coordinate systems allow for the presence of a false easting +(``+x_0``) and northing (``+y_0``). Note that these values are always expressed in +meters even if the coordinate system is some other units. Some coordinate +systems (such as UTM) have implicit false easting and northing values. + +Longitude Wrapping ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +By default PROJ wraps output longitudes in the range -180 to 180. The ``+over`` +switch can be used to disable the default wrapping which is done at a low level +in ``pj_inv()``. This is particularly useful with projections like the +:doc:`equidistant cylindrical<../operations/projections/eqc>` +where it would be desirable for X values past -20000000 (roughly) to continue +past -180 instead of wrapping to +180. + +The ``+lon_wrap`` option can be used to provide an alternative means of doing +longitude wrapping within ``pj_transform()``. The argument to this option is a +center longitude. So ``+lon_wrap=180`` means wrap longitudes in the range 0 to +360. Note that ``+over`` does **not** disable ``+lon_wrap``. + +Prime Meridian ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +A prime meridian may be declared indicating the offset between the prime +meridian of the declared coordinate system and that of greenwich. A prime +meridian is declared using the "pm" parameter, and may be assigned a symbolic +name, or the longitude of the alternative prime meridian relative to greenwich. + +Currently prime meridian declarations are only utilized by the +``pj_transform()`` API call, not the ``pj_inv()`` and ``pj_fwd()`` calls. +Consequently the user utility :program:`cs2cs` does honour prime meridians but +the :program:`proj` user utility ignores them. + +The following predeclared prime meridian names are supported. These can be +listed using with ``cs2cs -lm``. + + =========== ================ + Meridian Longitude + =========== ================ + greenwich 0dE + lisbon 9d07'54.862"W + paris 2d20'14.025"E + bogota 74d04'51.3"E + madrid 3d41'16.48"W + rome 12d27'8.4"E + bern 7d26'22.5"E + jakarta 106d48'27.79"E + ferro 17d40'W + brussels 4d22'4.71"E + stockholm 18d3'29.8"E + athens 23d42'58.815"E + oslo 10d43'22.5"E + =========== ================ + +Example of use. The location ``long=0``, ``lat=0`` in the greenwich based lat/long +coordinates is translated to lat/long coordinates with Madrid as the prime +meridian. + +:: + + cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid + 0 0 + 3d41'16.48"E 0dN 0.000 + + +Axis orientation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Starting in PROJ 4.8.0, the +axis argument can be used to control the axis +orientation of the coordinate system. The default orientation is "easting, +northing, up" but directions can be flipped, or axes flipped using combinations +of the axes in the +axis switch. The values are: + +* "e" - Easting +* "w" - Westing +* "n" - Northing +* "s" - Southing +* "u" - Up +* "d" - Down + +They can be combined in +axis in forms like: + +* ``+axis=enu`` - the default easting, northing, elevation. +* ``+axis=neu`` - northing, easting, up - useful for "lat/long" geographic + coordinates, or south orientated transverse mercator. +* ``+axis=wnu`` - westing, northing, up - some planetary coordinate systems + have "west positive" coordinate systems + +.. note:: + + The ``+axis`` argument does not work with the :program:`proj` command line + utility. + + diff --git a/_sources/usage/quickstart.rst.txt b/_sources/usage/quickstart.rst.txt new file mode 100644 index 00000000..85e7aa95 --- /dev/null +++ b/_sources/usage/quickstart.rst.txt @@ -0,0 +1,69 @@ +.. _quickstart: + +================================================================================ +Quick start +================================================================================ + +Coordinate transformations are defined by, what in PROJ terminology is +known as, "proj-strings". A proj-string describes any transformation regardless of +how simple or complicated it might be. The simplest case is projection of geodetic +coordinates. This section focuses on the simpler cases and introduces the basic +anatomy of the proj-string. The complex cases are discussed in +:doc:`transformation`. + +A proj-strings holds the parameters of a given coordinate transformation, e.g. + +:: + + +proj=merc +lat_ts=56.5 +ellps=GRS80 + +I.e. a proj-string consists of a projection specifier, ``+proj``, a number of +parameters that applies to the projection and, if needed, a description of a +datum shift. In the example above geodetic coordinates are transformed to +projected space with the :doc:`Mercator projection<../operations/projections/merc>` with +the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every +projection in PROJ is identified by a shorthand such as ``merc`` in the above +example. + +By using the above projection definition as parameters for the command line +utility :program:`proj` we can convert the geodetic coordinates to projected space: + +:: + + $ proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + +If called as above :program:`proj` will be in interactive mode, letting you +type the input data manually and getting a response presented on screen. +:program:`proj` works as any UNIX filter though, which means that you can also +pipe data to the utility, for instance by using the :program:`echo` command: + +:: + + $ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + 3399483.80 752085.60 + + +PROJ also comes bundled with the :program:`cs2cs` utility which is used to +transform from one coordinate reference system to another. Say we want to +convert the above Mercator coordinates to UTM, we can do that with +:program:`cs2cs`: + +:: + + $ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to +proj=utm +zone=32 + 6103992.36 1924052.47 0.00 + +Notice the ``+to`` parameter that separates the source and destination +projection definitions. + +If you happen to know the EPSG identifiers for the two coordinates reference +systems you are transforming between you can use those with :program:`cs2cs`: + +:: + + $ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832 + 231950.54 1920310.71 0.00 + +In the above example we transform geodetic coordinates in the WGS84 reference +frame to UTM zone 32N coordinates in the ETRS89 reference frame. +UTM coordinates diff --git a/_sources/usage/transformation.rst.txt b/_sources/usage/transformation.rst.txt new file mode 100644 index 00000000..785ca65e --- /dev/null +++ b/_sources/usage/transformation.rst.txt @@ -0,0 +1,346 @@ +.. _transformation: + +================================================================================ +Geodetic transformation +================================================================================ + +PROJ can do everything from the most simple projection to very complex +transformations across many reference frames. While originally developed as a +tool for cartographic projections, PROJ has over time evolved into a powerful +generic coordinate transformation engine that makes it possible to do both +large scale cartographic projections as well as coordinate transformation at a +geodetic high precision level. This chapter delves into the details of how +geodetic transformations of varying complexity can be performed. + +In PROJ, two frameworks for geodetic transformations exists, the +*PROJ 4.x/5.x* / :program:`cs2cs` / :c:func:`pj_transform` +framework and the *transformation pipelines* framework. The first is the original, +and limited, framework for doing geodetic transforms in PROJ The latter is a +newer addition that aims to be a more complete transformation framework. Both are +described in the sections below. Large portions of the text are based on +:cite:`EversKnudsen2017`. + +Before describing the details of the two frameworks, let us first remark that +most cases of geodetic transformations can be expressed as a series of elementary +operations, the output of one operation being the input of the next. E.g. when +going from UTM zone 32, datum ED50, to UTM zone 32, datum ETRS89, one must, in the +simplest case, go through 5 steps: + +1. Back-project the UTM coordinates to geographic coordinates +2. Convert the geographic coordinates to 3D cartesian geocentric coordinates +3. Apply a Helmert transformation from ED50 to ETRS89 +4. Convert back from cartesian to geographic coordinates +5. Finally project the geographic coordinates to UTM zone 32 planar coordinates. + + +Transformation pipelines ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The homology between the above steps and a Unix shell style pipeline is evident. +It is there the main architectural inspiration behind the transformation pipeline +framework. The pipeline framework is realized by utilizing a special "projection", +that takes as its user supplied arguments, a series of elementary operations, +which it strings together in order to implement the full transformation needed. +Additionally, a number of elementary geodetic operations, including Helmert +transformations, general high order polynomial shifts and the Molodensky +transformation are available as part of the pipeline framework. +In anticipation of upcoming support for full time-varying transformations, we +also introduce a 4D spatiotemporal data type, and a programming interface +(API) for handling this. + +The Molodensky transformation converts directly from geodetic coordinates +in one datum, to geodetic coordinates in another datum, while the (typically more +accurate) Helmert transformation converts from 3D cartesian to 3D cartesian +coordinates. So when using the Helmert transformation one typically needs to do an +initial conversion from geodetic to cartesian coordinates, and a final conversion +the other way round, to arrive at the desired result. Fortunately, this three-step +compound transformation has the attractive characteristic that each step depends +only on the output of the immediately preceding step. Hence, we can build a +geodetic-to-geodetic Helmert transformation by tying together the outputs and inputs +of 3 steps (geodetic-to-cartesian → Helmert → cartesian-to-geodetic), pipeline style. +The pipeline driver, makes this kind of chained transformations possible. +The implementation is compact, consisting of just one pseudo-projection, called +``pipeline``, which takes as its arguments strings of elementary projections +(note: "projection" is the, slightly misleading, PROJ term used for any kind of +transformation). +The pipeline pseudo projection is supplemented by a number of elementary +transformations, all in all providing a framework for building high accuracy +solutions for a wide spectrum of geodetic tasks. + + +As a first example, let us take a look at the iconic +*geodetic → Cartesian → Helmert → geodetic* case (steps 2 to 4 in the example in +the introduction). In PROJ it can be implemented as + +:: + + proj=pipeline + step proj=cart ellps=intl + step proj=helmert convention=coordinate_frame + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + +The pipeline can be expanded at both ends to accommodate whatever coordinate type +is needed for input and output: In the example below, we transform from the +deprecated Danish System 45, a 2D system with some tension in the original defining +network, to UTM zone 33, ETRS89. The tension is reduced using a polynomial +transformation (the init=./s45b... step, s45b.pol is a file containing the +polynomial coefficients), taking the S45 coordinates to a technical coordinate +system (TC32), defined to represent "UTM zone 32 coordinates, as they would look if +the Helmert transformation between ED50 and ETRS89 was perfect". The TC32 +coordinates are then converted back to geodetic(ED50) coordinates, using an +inverse UTM projection, further to cartesian(ED50), then to cartesian(ETRS89), +using the relevant Helmert transformation, and back to geodetic(ETRS89), before +finally being projected onto the UTM zone 33, ETRS89 system. All in all a 6 step +pipeline, implementing a transformation with centimeter level accuracy from a +deprecated system with decimeter level tensions. + +:: + + proj=pipeline + step init=./s45b.pol:s45b_tc32 + step proj=utm inv ellps=intl zone=32 + step proj=cart ellps=intl + step proj=helmert convention=coordinate_frame + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + step proj=utm ellps=GRS80 zone=33 + +With the pipeline framework spatiotemporal transformation is possible. This is +possible by leveraging the time dimension in PROJ that enables 4D coordinates +(three spatial components and one temporal component) to be passed through a +transformation pipeline. In the example below a transformation from ITRF93 to +ITRF2000 is defined. The temporal component is given as GPS weeks in the input +data, but the 14-parameter Helmert transform expects temporal units in decimalyears. +Hence the first step in the pipeline is the unitconvert pseudo-projection that makes +sure the correct units are passed along to the Helmert transform. +Most parameters of the Helmert transform are taken from :cite:`Altamimi2002`, +except the epoch which is the epoch of the transformation. +The last step in the pipeline is converting the +coordinate timestamps back to GPS weeks. + +:: + + proj=pipeline + step proj=unitconvert t_in=gps_week t_out=decimalyear + step proj=helmert convention=coordinate_frame + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + rx=0.00039 ry=-0.00080 rz=0.00114 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + drx=0.00011 dry=0.00019 drz=-0.00007 + t_epoch=1988.0 + step proj=unitconvert t_in=decimalyear t_out=gps_week + + +PROJ 4.x/5.x paradigm ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. _cs2cs_specific_options: + + ============ ============================================================== + Parameter Description + ============ ============================================================== + +datum Datum name (see ``proj -ld``) + +geoidgrids Filename of GTX grid file to use for vertical datum transforms + +nadgrids Filename of NTv2 grid file to use for datum transforms + +towgs84 3 or 7 term datum transform parameters + +to_meter Multiplier to convert map units to 1.0m + +vto_meter Vertical conversion to meters + ============ ============================================================== + +.. warning:: + This section documents the behavior of PROJ 4.x and 5.x. In PROJ 6.x, + :program:`cs2cs` has been reworked to use :c:func:`proj_create_crs_to_crs` internally, + with *late binding* capabilities, and thus is no longer constrained to using + WGS84 as a pivot (also called as *early binding* method). + When :program:`cs2cs` of PROJ 6 is used with PROJ.4 expanded strings to describe the CRS, + including ``+towgs84``, ``+nadgrids`` and ``+geoidgrids``, it will generally give + the same results as earlier PROJ versions. When used with AUTHORITY:CODE + CRS descriptions, it may return different results. + +The *cs2cs* framework in PROJ 4 and 5 delivers a subset of the geodetic transformations available +with the *pipeline* framework. Coordinate transformations done in this framework +were transformed in a two-step process with WGS84 as a pivot datum. That is, the +input coordinates are transformed to WGS84 geodetic coordinates and then transformed +from WGS84 coordinates to the specified output coordinate reference system, by +utilizing either the Helmert transform, datum shift grids or a combination of both. +Datum shifts can be described in a proj-string with the parameters ``+towgs84``, +``+nadgrids`` and ``+geoidgrids``. +An inverse transform exists for all three and is applied if +specified in the input proj-string. The most common is ``+towgs84``, which is used to +define a 3- or 7-parameter Helmert shift from the input reference frame to WGS84. +Exactly which realization of WGS84 is not specified, hence a fair amount of +uncertainty is introduced in this step of the transformation. With the +nadgrids +parameter a non-linear planar correction derived from interpolation in a +correction grid can be applied. Originally this was implemented as a means to +transform coordinates between the North American datums NAD27 and NAD83, but +corrections can be applied for any datum for which a correction grid exists. The +inverse transform for the horizontal grid shift is "dumb", in the sense that the +correction grid is applied verbatim without taking into account that the inverse +operation is non-linear. Similar to the horizontal grid correction, ``+geoidgrids`` +can be used to perform grid corrections in the vertical component. +Both grid correction methods allow inclusion of more than one grid in the same +transformation + +In contrast to the *transformation pipeline* framework, transformations with the +*cs2cs* framework in PROJ 4 and 5 were expressed as two separate proj-strings. One proj-string *to* +WGS84 and one *from* WGS84. Together they form the mapping from the source +coordinate reference system to the destination coordinate reference system. +When used with the :program:`cs2cs` the source and destination CRS's are separated by the +special ``+to`` parameter. + +The following example demonstrates converting from the Greek GGRS87 datum +to WGS84 with the ``+towgs84`` parameter. + +:: + + cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62 + +to +proj=latlong +datum=WGS84 + 20 35 + 20d0'5.467"E 35d0'9.575"N 0.000 + +With PROJ 6, you can simply use the following: + +.. note:: With PROJ 6, the order of coordinates for EPSG geographic coordinate + reference systems is latitude first, longitude second. + +:: + + cs2cs "GGRS87" "WGS 84" + 35 20 + 35d0'9.575"N 20d0'5.467"E 0.000 + + cs2cs EPSG:4121 EPSG:4326 + 35 20 + 35d0'9.575"N 20d0'5.467"E 0.000 + +The EPSG database provides this example for transforming from WGS72 to WGS84 +using an approximated 7 parameter transformation. + +:: + + cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \ + +to +proj=latlong +datum=WGS84 + 4 55 + 4d0'0.554"E 55d0'0.09"N 0.000 + +With PROJ 6, you can simply use the following (note the reversed order for +latitude and longitude) + +:: + + cs2cs "WGS 72" "WGS 84" + 55 4 + 55d0'0.09"N 4d0'0.554"E 0.000 + + cs2cs EPSG:4322 EPSG:4326 + 55 4 + 55d0'0.09"N 4d0'0.554"E 0.000 + + +Grid Based Datum Adjustments ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In many places (notably North America and Australia) national geodetic +organizations provide grid shift files for converting between different datums, +such as NAD27 to NAD83. These grid shift files include a shift to be applied +at each grid location. Actually grid shifts are normally computed based on an +interpolation between the containing four grid points. + +PROJ supports use of grid files for shifting between various reference frames. +The grid shift table formats are CTable, NTv1 (the old Canadian format), and NTv2 +(:file:`.gsb` - the new Canadian and Australian format). + +The text in this section is based on the *cs2cs* framework. Gridshifting is off +course also possible with the *pipeline* framework. The major difference between the +two is that the *cs2cs* framework is limited to grid mappings to WGS84, whereas with +*transformation pipelines* it is possible to perform grid shifts between any two +reference frames, as long as a grid exists. + +Use of grid shifts with :program:`cs2cs` is specified using the ``+nadgrids`` +keyword in a coordinate system definition. For example: + +:: + + % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'2.952"W 50d0'0.111"N 0.000 + +In this case the :file:`/usr/local/share/proj/ntv1_can.dat` grid shift file was +loaded, and used to get a grid shift value for the selected point. + +It is possible to list multiple grid shift files, in which case each will be +tried in turn till one is found that contains the point being transformed. + +:: + + cs2cs +proj=latlong +ellps=clrk66 \ + +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + + +Skipping Missing Grids +................................................................................ + +The special prefix ``@`` may be prefixed to a grid to make it optional. If it +not found, the search will continue to the next grid. Normally any grid not +found will cause an error. For instance, the following would use the +:file:`ntv2_0.gsb` file if available, otherwise it would +fallback to using the :file:`ntv1_can.dat` file. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + +The null Grid +................................................................................ + +A special :file:`null` grid shift file is distributed with PROJ. +This file provides a zero shift for the whole world. It may be +listed at the end of a nadgrids file list if you want a zero shift to be +applied to points outside the valid region of all the other grids. Normally if +no grid is found that contains the point to be transformed an error will occur. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 45 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + -111 55 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + 111dW 55dN 0.000 + +For more information see the chapter on :ref:`transformation_grids`. + +Caveats +................................................................................ + +* Where grids overlap (such as conus and :file:`ntv1_can.dat` for instance) the first + found for a point will be used regardless of whether it is appropriate or + not. So, for instance, ``+nadgrids=ntv1_can.dat``,conus would result in + the Canadian data being used for some areas in the northern United States + even though the conus data is the approved data to use for the area. + Careful selection of files and file order is necessary. In some cases + border spanning datasets may need to be pre-segmented into Canadian and + American points so they can be properly grid shifted +* Additional detail on the grid shift being applied can be found by setting + the PROJ_DEBUG environment variable to a value. This will result in output + to stderr on what grid is used to shift points, the bounds of the various + grids loaded and so forth diff --git a/_sources/zreferences.rst.txt b/_sources/zreferences.rst.txt new file mode 100644 index 00000000..384281cd --- /dev/null +++ b/_sources/zreferences.rst.txt @@ -0,0 +1,11 @@ +.. _references: + +.. only:: not latex + + ================================================================================ + References + ================================================================================ + +.. bibliography:: references.bib + :cited: + :style: customstyle |