diff options
Diffstat (limited to 'docs')
45 files changed, 1274 insertions, 418 deletions
diff --git a/docs/plot/plotdefs.json b/docs/plot/plotdefs.json index daaf2ef8..bb0ebbe7 100644 --- a/docs/plot/plotdefs.json +++ b/docs/plot/plotdefs.json @@ -6,7 +6,8 @@ "lonmax": 180, "lonmin": -180, "name": "aea", - "projstring": "+proj=aea", + "#comment": "lat_1 and lat_2 values are previous defaults from now-removed proj_def.dat", + "projstring": "+proj=aea +lat_1=29.5 +lat_2=42.5", "res": "low", "type": "poly" }, @@ -623,7 +624,8 @@ "lonmax": -10, "lonmin": -160, "name": "lcc", - "projstring": "+proj=lcc +lon_0=-90", + "#comment": "lat_1 and lat_2 values are previous defaults from now-removed proj_def.dat", + "projstring": "+proj=lcc +lon_0=-90 +lat_1=33 +lat_2=45", "res": "med", "type": "poly" }, @@ -1233,6 +1235,17 @@ "type": "line" }, { + "filename": "times.png", + "latmax": 90, + "latmin": -90, + "lonmax": 180, + "lonmin": -180, + "name": "times", + "projstring": "+proj=times", + "res": "low", + "type": "poly" + }, + { "filename": "tissot.png", "latmax": 90, "latmin": -90, diff --git a/docs/source/about.rst b/docs/source/about.rst index 5e625288..3486f23f 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -2,7 +2,7 @@ About ############################################################################### -PROJ is a generic coordinate transformation software, that transforms geospatial +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. @@ -10,35 +10,22 @@ 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 -let developers use the functionality of PROJ in their own software without having +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 it's way into PROJ as well. Today PROJ support more +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. Citation ------------------------------------------------------------------------------- -To cite PROJ in publications use: - PROJ contributors (2018). PROJ coordinate transformation software - library. Open Source Geospatial Foundation. URL https://proj4.org/. +.. include:: ../../CITATION -A BibTeX entry for LaTeX users is - -.. code-block:: latex - - @Manual{, - title = {{PROJ} coordinate transformation software library}, - author = {{PROJ contributors}}, - organization = {Open Source Geospatial Foundation}, - year = {2018}, - url = {https://proj4.org/}, - } License ------------------------------------------------------------------------------- diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst index 249d523a..629e181c 100644 --- a/docs/source/apps/cct.rst +++ b/docs/source/apps/cct.rst @@ -13,7 +13,7 @@ cct Synopsis ******** - **cct** [ **-cIostvz** [ args ] ] *+opts[=arg]* file[s] + **cct** [**-cIostvz** [args]] *+opt[=arg]* ... file ... Description *********** @@ -70,7 +70,7 @@ The following control parameters can appear in any order: Print version number. -The *+args* arguments are associated with coordinate operation parameters. +The *+opt* arguments are associated with coordinate operation parameters. Usage varies with operation. .. only:: html diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst index 579dc65e..afe5a610 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/apps/cs2cs.rst @@ -11,11 +11,11 @@ cs2cs Synopsis ******** - **cs2cs** [ **-eEfIlrstvwW** [ args ] ] [ *+opts[=arg]* ] [ +to [*+opts[=arg]*] ] file[s] + **cs2cs** [**-eEfIlrstvwW** [args]] [*+opt[=arg]* ...] [+to *+opt[=arg]* ...] file ... or - **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} +to {target_crs} file[s] + **cs2cs** [**-eEfIlrstvwW** [args]] {source_crs} +to {target_crs} file ... where {source_crs} or {target_crs} is a PROJ string, a WKT string or a AUTHORITY:CODE (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS @@ -25,7 +25,7 @@ or or - **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} {target_crs} + **cs2cs** [**-eEfIlrstvwW** [args]] {source_crs} {target_crs} .. versionadded:: 6.0.0 @@ -132,12 +132,12 @@ The following control parameters can appear in any order: .. only:: man - The *+args* run-line arguments are associated with cartographic + The *+opt* run-line arguments are associated with cartographic parameters. .. only:: html - The *+args* run-line arguments are associated with cartographic + 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>`. diff --git a/docs/source/apps/geod.rst b/docs/source/apps/geod.rst index e890aede..2897445d 100644 --- a/docs/source/apps/geod.rst +++ b/docs/source/apps/geod.rst @@ -7,9 +7,9 @@ geod Synopsis ******** - **geod** *+ellps=<ellipse>* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s] + **geod** *+ellps=<ellipse>* [**-afFIlptwW** [args]] [*+opt[=arg]* ...] file ... - **invgeod** *+ellps=<ellipse>* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s] + **invgeod** *+ellps=<ellipse>* [**-afFIlptwW** [args]] [*+opt[=arg]* ...] file ... Description *********** @@ -85,7 +85,7 @@ The following command-line options can appear in any order: This option causes the azimuthal values to be output as unsigned DMS numbers between 0 and 360 degrees. Also note :option:`-f`. -The *+args* command-line options are associated with geodetic +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 diff --git a/docs/source/apps/gie.rst b/docs/source/apps/gie.rst index 8cbd2336..bab0ec69 100644 --- a/docs/source/apps/gie.rst +++ b/docs/source/apps/gie.rst @@ -172,7 +172,7 @@ gie command language proj=urm5 n=0.5 inv expect failure pjd_err_malformed_pipeline - See ``gie -l`` for a list of error codes that can be expected. + See :option:`gie --list<--list>` for a list of error codes that can be expected. .. option:: tolerance <tolerance> @@ -273,7 +273,7 @@ gie command language expect 173 -45 - See ``gie -l`` for a list of error codes that can be ignored. + See :option:`gie --list<--list>` for a list of error codes that can be ignored. .. option:: require_grid <grid_name> diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst index 8c2c8222..381b8933 100644 --- a/docs/source/apps/index.rst +++ b/docs/source/apps/index.rst @@ -4,15 +4,16 @@ Applications ================================================================================ -Bundled with PROJ comes a set of small command line utilities. The ``proj`` +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 ``cs2cs`` program operates similarly, but allows +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 ``geod`` program provides the ability to do -geodesic (great circle) computations. ``gie`` is the program used for -regression tests in PROJ. ``cct`` a 4D equivalent to the ``proj`` program, -performs transformation coordinate systems on a set of input points. -``projinfo`` performs queries for geodetic objects and coordinate operations. +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. .. toctree:: :maxdepth: 1 diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst index 7585411f..2dbd104a 100644 --- a/docs/source/apps/proj.rst +++ b/docs/source/apps/proj.rst @@ -12,9 +12,9 @@ proj Synopsis ******** - **proj** [ **-beEfiIlmorsStTvVwW** ] [ args ] ] [ *+args* ] file[s] + **proj** [**-beEfiIlmorsStTvVwW**] [args]] [*+opt[=arg]* ...] file ... - **invproj** [ **-beEfiIlmorsStTvVwW** ] [ args ] ] [ *+args* ] file[s] + **invproj** [**-beEfiIlmorsStTvVwW**] [args]] [*+opt[=arg]* ...] file ... Description @@ -156,7 +156,7 @@ The following control parameters can appear in any order the projected point. :option:`-v` is implied with this option. -The *+args* run-line arguments are associated with cartographic parameters. +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 @@ -167,7 +167,7 @@ also used for supporting files like datum shift files. .. only:: html - Usage of *+args* varies with projection and for a complete description + Usage of *+opt* varies with projection and for a complete description consult the :ref:`projection pages <projections>`. diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index 20225b25..fc816e40 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -16,7 +16,7 @@ Synopsis ******** | **projinfo** - | [-o formats] [-k crs|operation] [--summary] [-q] + | [-o formats] [-k crs|operation|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] @@ -29,12 +29,19 @@ Synopsis | {object_definition} | {object_reference} | (-s {srs_def} -t {srs_def}) | - where {object_definition} is a PROJ string, a - WKT string, an object name or a AUTHORITY:CODE - (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS - found in the proj.db database). + where {object_definition} or {srs_def} is - {object_reference} is a filename preceded with the '@' character. The + - a proj-string, + - a WKT string, + - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671"), + - 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") + + {object_reference} is a filename preceded by the '@' character. The file referenced by the {object_reference} must contain a valid {object_definition}. @@ -62,16 +69,16 @@ The following control parameters can appear in any order: Except ``all`` and ``default``, other formats can be preceded by ``-`` to disable them. -.. option:: -k crs|operation +.. option:: -k crs|operation|ellipsoid When used to query a single object with a AUTHORITY:CODE, determines the (k)ind of the object - in case there are CRS or coordinate operations with the same CODE. + 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, mentionning only the name of the coordinate + 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 @@ -107,8 +114,8 @@ The following control parameters can appear in any order: .. 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 specfied explicitly with :option:`--area` or :option:`--bbox`, - or derivedi implictly from the area of use of the source and target CRS. + 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, 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 @@ -195,6 +202,16 @@ The following control parameters can appear in any order: 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:: --c-ify For developers only. Modify the string output of the utility so that it diff --git a/docs/source/bibstyle.py b/docs/source/bibstyle.py index 8e2cc02a..addfedbd 100644 --- a/docs/source/bibstyle.py +++ b/docs/source/bibstyle.py @@ -1,5 +1,6 @@ ############################################################################### # +# Project: PROJ # Purpose: Configure custom bibliography style for sphinxcontrib-bibtex # Author: Mike Toews <mwtoews at gmail.com> # @@ -53,11 +54,15 @@ class LinkLabelStyle(LabelStyle): class CustomStyle(UnsrtStyle): """Citation style in the References section""" + # TODO: Make more Harvard-like, i.e. year after name(s) default_label_style = 'linklabel' default_name_style = 'lastfirst' default_sorting_style = 'author_year_title' - # TODO: Make more Harvard-like, i.e. year after name(s) + + def __init__(self, **kwargs): + kwargs['abbreviate_names'] = True + UnsrtStyle.__init__(self, **kwargs) register_plugin('pybtex.style.labels', 'linklabel', LinkLabelStyle) diff --git a/docs/source/community/contributing.rst b/docs/source/community/contributing.rst index 867f7e1a..8ead82bd 100644 --- a/docs/source/community/contributing.rst +++ b/docs/source/community/contributing.rst @@ -36,6 +36,8 @@ 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 ------------------ diff --git a/docs/source/conf.py b/docs/source/conf.py index 0fd8d540..0abc17ff 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -66,7 +66,7 @@ copyright = u'1983-{0}'.format(now.year) # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -version = '6.0.0' +version = '6.1.0' # use same |release| as |version| release = version diff --git a/docs/source/development/migration.rst b/docs/source/development/migration.rst index 99143f20..df622ecb 100644 --- a/docs/source/development/migration.rst +++ b/docs/source/development/migration.rst @@ -1,6 +1,151 @@ .. _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_latlong; + double x, y; + + 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; + + /* 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(C, P); + if( 0 == P_for_GIS ) { + proj_destroy(P); + return 1; + } + proj_destroy(P); + P = P_for_GIS; + } + + while (scanf("%lf %lf", &c.lp.lam, &c.lp.phi) == 2) { + /* No need to convert to radian */ + c = proj_trans(P, PJ_FWD, c); + printf("%.2f\t%.2f\n", c.xy.x, c.xy.y); + } + + proj_destroy(P); + } + + +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` + | +| | (: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` | ++---------------------------------------+-------------------------------------------------+ + +================================================================================ Version 4 to 5 API Migration ================================================================================ @@ -66,7 +211,7 @@ 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 latitude and longitude from the command line and convert them to +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: @@ -76,21 +221,24 @@ We start by writing the program for PROJ v. 4: #include <proj_api.h> main(int argc, char **argv) { - projPJ pj_merc, pj_latlong; + projPJ pj_merc, pj_longlat; double x, y; - if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) ) + if (!(pj_longlat = pj_init_plus("+proj=longlat +ellps=clrk66")) ) return 1; - if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) ) + 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; - y *= DEG_TO_RAD; - p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL ); + 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; } @@ -115,6 +263,7 @@ The same program implemented using PROJ v. 5: 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 @@ -155,27 +304,27 @@ Function mapping from old to new API +---------------------------------------+---------------------------------------+ | Old API functions | New API functions | +=======================================+=======================================+ -| pj_fwd | proj_trans | +| pj_fwd | :c:func:`proj_trans` | +---------------------------------------+---------------------------------------+ -| pj_inv | proj_trans | +| pj_inv | :c:func:`proj_trans` | +---------------------------------------+---------------------------------------+ -| pj_fwd3 | proj_trans | +| pj_fwd3 | :c:func:`proj_trans` | +---------------------------------------+---------------------------------------+ -| pj_inv3 | proj_trans | +| pj_inv3 | :c:func:`proj_trans` | +---------------------------------------+---------------------------------------+ | pj_transform | proj_trans_array or proj_trans_generic| +---------------------------------------+---------------------------------------+ -| pj_init | proj_create | +| pj_init | :c:func:`proj_create` | +---------------------------------------+---------------------------------------+ -| pj_init_plus | proj_create | +| pj_init_plus | :c:func:`proj_create` | +---------------------------------------+---------------------------------------+ -| pj_free | proj_destroy | +| pj_free | :c:func:`proj_destroy` | +---------------------------------------+---------------------------------------+ -| pj_is_latlong | proj_angular_output | +| pj_is_latlong | :c:func:`proj_angular_output` | +---------------------------------------+---------------------------------------+ -| pj_is_geocent | proj_angular_outout | +| pj_is_geocent | :c:func:`proj_angular_output` | +---------------------------------------+---------------------------------------+ -| pj_get_def | proj_pj_info | +| pj_get_def | :c:func:`proj_pj_info` | +---------------------------------------+---------------------------------------+ | pj_latlong_from_proj | *No equivalent* | +---------------------------------------+---------------------------------------+ @@ -187,7 +336,7 @@ Function mapping from old to new API +---------------------------------------+---------------------------------------+ | pj_strerrno | *No equivalent* | +---------------------------------------+---------------------------------------+ -| pj_get_errno_ref | proj_errno | +| pj_get_errno_ref | :c:func:`proj_errno` | +---------------------------------------+---------------------------------------+ -| pj_get_release | proj_info | +| pj_get_release | :c:func:`proj_info` | +---------------------------------------+---------------------------------------+ diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst index 960cddbf..d53d98fd 100644 --- a/docs/source/development/quickstart.rst +++ b/docs/source/development/quickstart.rst @@ -25,69 +25,128 @@ See the :doc:`reference for more info on data types <reference/datatypes>`. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 43-45 + :lines: 43-46 :dedent: 4 -For use in multi-threaded programs the ``PJ_CONTEXT`` threading-context is used. +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 it created here. The section on :doc:`threads <threads>` discusses this in detail. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 48 + :lines: 50 :dedent: 4 -Next we create the ``PJ`` transformation object ``P`` with the function -``proj_create``. ``proj_create`` takes the threading context ``C`` created above, -and a proj-string that defines the desired transformation. Here we transform -from geodetic coordinate to UTM zone 32N. +Next we create the :c:type:`PJ` transformation object ``P`` with the function +:c:func:`proj_create_crs_to_crs`. :c:func:`proj_create_crs_to_crs` takes 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. +The strings for the source or target CRS may be PROJ strings (``+proj=longlat +datum=WGS84``), +CRS identified by their code (``EPSG:4326`` or ``urn:ogc:def:crs:EPSG::4326``) or +by a well-known text (WKT) 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]] + +). +The use of PROJ strings to describe a CRS is considered as legacy (one of the +main weakness of PROJ strings is their inability to describe a geodetic datum, +other than the few ones hardcoded in the ``+datum`` parameter). +Here we transform from geographic coordinates to UTM zone 32N. It is recommended to create one threading-context per thread used by the program. -This ensures that all ``PJ`` objects created in the same context will be sharing -resources such as error-numbers and loaded grids. -In case the creation of the ``PJ`` object fails an error message is displayed and -the program returns. See :doc:`errorhandling` for further +This ensures that all :c:type:`PJ` objects created in the same context will be +sharing resources such as error-numbers and loaded grids. +In case the creation of the :c:type:`PJ` object fails an error message is +displayed and the program returns. See :doc:`errorhandling` for further details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 50-52 + :lines: 52-60 :dedent: 4 -PROJ uses it's own data structures for handling coordinates. Here we use a -``PJ_COORD`` which is easily assigned with the function ``proj_coord``. Note -that the input values are converted to radians with ``proj_torad``. This is -necessary since PROJ is using radians internally. See :doc:`transformations` -for further details. +:c:func:`proj_create_crs_to_crs` creates a transformation object, which accepts +coordinates expressed in the units and axis order of the definition of the +source CRS, and return transformed coordinates in the units and axis order of +the definition of the target CRS. +For almost most geographic CRS, the units will be in most cases 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, on contrary the order will be +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 for the needs of your software, you want +a uniform axis order (and thus do not care about axis order mandated by the +authority defining the CRS), the :c:func:`proj_normalize_for_visualization` +function can be used to modify the PJ* object returned by +:c:func:`proj_create_crs_to_crs` so that it accepts as input and returns as +output coordinates using the traditional GIS order, that is longitude, latitude +(followed by elevation, time) for geographic CRS and easting, northing for most +projected CRS. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 56 + :lines: 65-71 :dedent: 4 -The coordinate defined above is transformed with ``proj_trans_coord``. For this -a ``PJ`` object, a transformation direction (either forward or inverse) and the -coordinate is needed. The transformed coordinate is returned in ``b``. -Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made. +PROJ uses its own data structures for handling coordinates. Here we use a +:c:type:`PJ_COORD` which is easily assigned with the function :c:func:`proj_coord`. +When using +proj=longlat, the order of coordinates is longitude, latitude, +and values are expressed in degrees. If you used instead a EPSG geographic CRS, +like EPSG:4326 (WGS84), it would be latitude, longitude. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 59-60 + :lines: 76 :dedent: 4 -The inverse transformation (UTM to geodetic) is done similar to above, -this time using ``PJ_INV`` as the direction. +The coordinate defined above is transformed with :c:func:`proj_trans`. For this +a :c:type:`PJ` object, a transformation direction (either forward or inverse) +and the coordinate is needed. The transformed coordinate is returned in ``b``. +Here the forward (:c:type:`PJ_FWD`) transformation from geographic to UTM is made. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 61-62 + :lines: 79-80 + :dedent: 4 + +The inverse transformation (UTM to geographic) is done similar to above, +this time using :c:type:`PJ_INV` as the direction. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 81-82 :dedent: 4 Before ending the program the allocated memory needs to be released again: .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 65-66 + :lines: 85-86 :dedent: 4 diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 4052ff82..64a4e8ca 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -29,9 +29,17 @@ 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, or object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", - "urn:ogc:def:coordinateOperation:EPSG::1671"). + 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"), + - 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") Example call: @@ -110,7 +118,8 @@ paragraph for more details. - 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` + - 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. @@ -144,6 +153,25 @@ paragraph for more details. :type `area`: PJ_AREA :returns: :c:type:`PJ*` +.. c:function:: PJ *proj_normalize_for_visualization(PJ_CONTEXT *ctx, const PJ* obj) + + .. versionadded:: 6.1.0 + + Returns a PJ* object whose axis order is the one expected for + visualization purposes. + + The input object must be a coordinate operation, that has been created with + proj_create_crs_to_crs(). + If the axis order of its source or target CRS is northing,easting, then an + axis swap operation will be inserted. + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context. + :param `obj`: Object of type CoordinateOperation + :returns: :c:type:`PJ*` + + .. c:function:: PJ* proj_destroy(PJ *P) Deallocate a :c:type:`PJ` transformation object. @@ -221,10 +249,16 @@ Coordinate transformation 3. of length one, i.e. a constant, which will be treated as a fully populated array of that constant value + .. note:: Even though he 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 behaviour + 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_transform` to handle transformation of a large class of application + :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: @@ -250,21 +284,22 @@ Coordinate transformation 0, 0 /* and the time is the constant 0.00 s */ ); - This is similar to the inner workings of the deprecated 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. + 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 (...)). + 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_transform` 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. + .. 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 PJ* P: Transformation object :param `direction`: Transformation direction @@ -631,23 +666,23 @@ Various .. c:function:: int proj_angular_input (PJ *P, enum PJ_DIRECTION dir) - Check if a operation expects angular input. + Check if a operation expects input in radians or not. :param `P`: Transformation object :type `P`: const PJ* :param `direction`: Starting direction of transformation :type `direction`: PJ_DIRECTION - :returns: :c:type:`int` 1 if angular input is expected, otherwise 0 + :returns: :c:type:`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 angular output. + Check if an operation returns output in radians or not. :param `P`: Transformation object :type `P`: const PJ* :param `direction`: Starting direction of transformation :type `direction`: PJ_DIRECTION - :returns: :c:type:`int` 1 if angular output is returned, otherwise 0 + :returns: :c:type:`int` 1 if output units is expected in radians, otherwise 0 C API for ISO-19111 functionality +++++++++++++++++++++++++++++++++ diff --git a/docs/source/download.rst b/docs/source/download.rst index 8eba39ba..f0939637 100644 --- a/docs/source/download.rst +++ b/docs/source/download.rst @@ -5,7 +5,7 @@ Download ================================================================================ Here you can download current and previous releases of PROJ. We only supply a -distribution of the source code and various resource files archives. See +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: @@ -13,28 +13,33 @@ distribution of the source code and various resource files archives. See Current Release -------------------------------------------------------------------------------- -* **2018-09-15** `proj-5.2.0.tar.gz`_ (`md5`_) +* **2019-03-01** `proj-6.0.0.tar.gz`_ (`md5`_) * **2018-09-15** `proj-datumgrid-1.8.zip`_ -* **2018-09-15** `proj-datumgrid-europe-1.1.zip`_ -* **2018-09-15** `proj-datumgrid-north-america-1.1.zip`_ +* **2019-03-01** `proj-datumgrid-europe-1.2.zip`_ +* **2019-03-01** `proj-datumgrid-north-america-1.2.zip`_ * **2018-03-01** `proj-datumgrid-oceania-1.0.zip`_ +* **2019-03-01** `proj-datumgrid-world-1.0.zip`_ * **PDF Manual** `proj.pdf`_ Past Releases -------------------------------------------------------------------------------- -* **2018-06-01** `proj-5.1.0.tar.gz`_ (`md5`_) -* **2018-04-01** `proj-5.0.1.tar.gz`_ (`md5`_) +* **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`_ -* **2016-09-11** `proj-datumgrid-1.6.zip`_ * **2018-03-01** `proj-datumgrid-1.7.zip`_ +* **2016-09-11** `proj-datumgrid-1.6.zip`_ +* **2018-09-15** `proj-datumgrid-europe-1.1.zip`_ +* **2018-09-15** `proj-datumgrid-north-america-1.1.zip`_ * **2018-03-01** `proj-datumgrid-europe-1.0.zip`_ * **2018-03-01** `proj-datumgrid-north-america-1.0.zip`_ +.. _`proj-6.0.0.tar.gz`: http://download.osgeo.org/proj/proj-6.0.0.tar.gz .. _`proj-5.2.0.tar.gz`: http://download.osgeo.org/proj/proj-5.2.0.tar.gz .. _`proj-5.1.0.tar.gz`: http://download.osgeo.org/proj/proj-5.1.0.tar.gz .. _`proj-5.0.1.tar.gz`: http://download.osgeo.org/proj/proj-5.0.1.tar.gz @@ -47,8 +52,11 @@ Past Releases .. _`proj-datumgrid-1.8.zip`: http://download.osgeo.org/proj/proj-datumgrid-1.8.zip .. _`proj-datumgrid-europe-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-europe-1.0.zip .. _`proj-datumgrid-europe-1.1.zip`: http://download.osgeo.org/proj/proj-datumgrid-europe-1.1.zip +.. _`proj-datumgrid-europe-1.2.zip`: http://download.osgeo.org/proj/proj-datumgrid-europe-1.2.zip .. _`proj-datumgrid-north-america-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.0.zip .. _`proj-datumgrid-north-america-1.1.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.1.zip +.. _`proj-datumgrid-north-america-1.2.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.2.zip .. _`proj-datumgrid-oceania-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-oceania-1.0.zip -.. _`md5`: http://download.osgeo.org/proj/proj-5.2.0.tar.gz.md5 +.. _`proj-datumgrid-world-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-world-1.0.zip +.. _`md5`: http://download.osgeo.org/proj/proj-6.0.0.tar.gz.md5 .. _`proj.pdf`: https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf diff --git a/docs/source/faq.rst b/docs/source/faq.rst index f72ec132..e6a2e54a 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -10,208 +10,73 @@ FAQ :depth: 3 :backlinks: none - - -Where can I find the list of projections and their arguments? +Which file formats does PROJ support? -------------------------------------------------------------------------------- -:doc:`Here<../operations/projections/index>`. +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:: -Additinoally, the ``proj`` command itself can report the list of projections -using the ``-lp`` option, the list of ellipsoids with the ``-le`` option, -the list of units with the ``-lu`` option, and the list of built-in datums with -the ``-ld`` option. + 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. -How do I do datum shifts between NAD27 and NAD83? +Can I transform from *abc* to *xyz*? -------------------------------------------------------------------------------- -Using the ``cs2cs`` application. The following example demonstrates using the -default shift parameters for NAD27 to NAD83: - -:: +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): - % cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +datum=NAD83 -117 30 +.. code-block:: console -producing: + $ ./projinfo -s EPSG:25832 -t EPSG:4093 -o PROJ + Candidate operations found: 1 + ------------------------------------- + Operation n°1: -:: + unknown id, Inverse of UTM zone 32N + DKTM1, 0 m, World - 117d0'2.901"W 30d0'0.407"N 0.000 + 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 -In order for datum shifting to work properly the various grid shift files must -be available. See below. More details are available in the -section on :doc:`resource files<resource_files>`. +See the :program:`projinfo` :ref:`documentation <projinfo>` for more info on +how to use it. -How do I build/configure PROJ to support datum shifting? +Coordinate reference system *xyz* is not in the EPSG registry, what do I do? -------------------------------------------------------------------------------- -After downloading and unpacking the PROJ source, also download and unpack the -set of datum shift files. See :ref:`download` for instructions how to fetch -and install these files +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. -A default build and install on Unix will normally build knowledge of the -directory where the grid shift files are installed into the PROJ library -(usually ``/usr/local/share/proj``). On Windows the library is normally built -thinking that C:\PROJ\NAD is the installed directory for the grid shift files. -If the built in concept of the PROJ data directory is incorrect, the ``PROJ_LIB`` -environment can be defined with the correct directory. +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. -How do I debug problems with NAD27/NAD83 datum shifting? +I found a bug in PROJ, how do I get it fixed? -------------------------------------------------------------------------------- -1. Verify that you have the binary files (eg. ``/usr/local/share/proj/conus``) - installed on your system. If not, see the previous question. -2. Try a datum shifting operation in relative isolation, such as with the :program:`cs2cs` - command listed above. Do you get reasonable results? If not it is likely - the grid shift files aren't being found. Perhaps you need to define - :envvar:`PROJ_LIB`? -3. The :program:`cs2cs` command and the underlying :c:func:`pj_transform()` API know how to do a - grid shift as part of a more complex coordinate transformation; however, it - is imperative that both the source and destination coordinate system be - defined with appropriate datum information. That means that implicitly or - explicitly there must be a ``+datum=`` clause, a ``+nadgrids=`` clause or a - ``+towgs84=`` clause. For instance - ``cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +ellps=WGS84`` won't work because defining the output - coordinate system as using the ellipse WGS84 isn't the same as defining it - to use the datum WGS84 (use ``+datum=WGS84``). If either the input or output - are not identified as having a datum, the datum shifting (and ellipsoid - change) step is just quietly skipped! -4. The :envvar:`PROJ_DEBUG` environment can be defined (any value) to force extra output - from the PROJ library to stderr (the text console normally) with - information on what data files are being opened and in some cases why a - transformation fails. - - :: - - export PROJ_DEBUG=ON - cs2cs ... - - - .. note:: - ``PROJ_DEBUG`` support is not yet very mature in the PROJ library. - -5. The :option:`-v` flag to :program:`cs2cs` can be useful in establishing more detail on what - parameters being used internally for a coordinate system. This will include - expanding the definition of ``+datum`` clause. - -How do I use EPSG coordinate system codes with PROJ? --------------------------------------------------------------------------------- +Please report bugs that you find to the issue tracker on GitHub. :ref:`Here's how +<add_bug_report>`. -There is somewhat imperfect translation between 2D geographic and projected -coordinate system codes and PROJ descriptions of the coordinate system -available in the ``epsg`` definition file that normally lives in the ``proj/data`` -directory. If installed (it is installed by default on Unix), it is possible -to use EPSG numbers like this: - -:: - - - % cs2cs -v +init=epsg:26711 - # ---- From Coordinate System ---- - #Universal Transverse Mercator (UTM) - # Cyl, Sph - # zone= south - # +init=epsg:26711 +proj=utm +zone=11 +ellps=clrk66 +datum=NAD27 +units=m - # +no_defs +nadgrids=conus,ntv1_can.dat - #--- following specified but NOT used - # +ellps=clrk66 - # ---- To Coordinate System ---- - #Lat/long (Geodetic) - # - # +proj=latlong +datum=NAD27 +ellps=clrk66 +nadgrids=conus,ntv1_can.dat - -The ``proj/data/epsg`` file can be browsed and searched in a text editor for -coordinate systems. There are known to be problems with some coordinate -systems, and any coordinate systems with odd axes, a non-greenwich prime -meridian or other quirkiness are unlikely to work properly. Caveat Emptor! - -How do I use 3 parameter and 7 parameter datum shifting --------------------------------------------------------------------------------- - -Datum shifts can be approximated with 3 and 7 parameter transformations. Their -use with :program:`cs2cs` is more fully described in the -:ref:`geodetic transformation<cs2cs_specific_options>` section. - -More generically, the :ref:`helmert` can be used with :program:`cct`. +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. - -Does PROJ work in different international numeric locales? +How do I contribute to PROJ? -------------------------------------------------------------------------------- -No. PROJ makes extensive use of the :c:func:`sprintf()` and :c:func:`atof()` C functions -internally to translate numeric values. If a locale is in effect that modifies -formatting of numbers, altering the role of commas and periods in numbers, then -PROJ will not work. This problem is common in some European locales. - -On UNIX-like platforms, this problem can be avoided by forcing the use of the -default numeric locale by setting the :envvar:`LC_NUMERIC` environment variable to C. - -:: - - $ export LC_NUMERIC=C - $ proj ... - -.. note:: - - NOTE: Per ticket #49, in PROJ 4.7.0 and later pj_init() operates with locale - overridden to "C" to avoid most locale specific processing for applications - using the API. Command line tools may still have issues. - -Changing Ellipsoid / Why can't I convert from WGS84 to Google Earth / Virtual Globe Mercator? ----------------------------------------------------------------------------------------------- - -The coordinate system definition for Google Earth, and Virtual Globe Mercator -is as follows, which uses a sphere as the earth model for the Mercator -projection. - -:: - - +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 - +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs - -But, if you do something like: - -:: - - cs2cs +proj=latlong +datum=WGS84 - +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 - +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs - -to convert between WGS84 and mercator on the sphere there will be substantial -shifts in the Y mercator coordinates. This is because internally :program:`cs2cs` is -having to adjust the lat/long coordinates from being on the sphere to being on -the WGS84 datum which has a quite differently shaped ellipsoid. - -In this case, and many other cases using spherical projections, the desired -approach is to actually treat the lat/long locations on the sphere as if they -were on WGS84 without any adjustments when using them for converting to other -coordinate systems. The solution is to "trick" PROJ into applying no change -to the lat/long values when going to (and through) WGS84. This can be -accomplished by asking PROJ to use a null grid shift file for switching from -your spherical lat/long coordinates to WGS84. - -:: - - cs2cs +proj=latlong +datum=WGS84 \ - +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 \ - +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs - -Note the strategic addition of ``+nadgrids=@null`` to the spherical projection -definition. - -Similar issues apply with many other datasets distributed with projections -based on a spherical earth model - such as many NASA datasets. This coordinate -system is now known by the EPSG code 3857 and has in the past been known as -EPSG:3785 and EPSG:900913. When using this coordinate system with GDAL/OGR it -is helpful to include the +wktext so the exact PROJ string will be preserved -in the WKT representation (otherwise key parameters like ``+nadgrids=@null`` will -be dropped): - -:: - - +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 - +units=m +nadgrids=@null +wktext +no_defs - +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? -------------------------------------------------------------------------------- @@ -219,32 +84,75 @@ 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 options does PROJ allow for the shape of the Earth (geodesy)? --------------------------------------------------------------------------------- - -See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c -for possible ellipse options. For example, putting ``+ellps=WGS84`` uses -the ``WGS84`` Earth shape. - -What if I want a spherical Earth? +What is the best format for describing coordinate reference systems? -------------------------------------------------------------------------------- -Use ``+ellps=sphere``. See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c -for the radius used in this case. +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. -How do I change the radius of the Earth? How do I use PROJ for work on Mars? --------------------------------------------------------------------------------- - -You can supply explicit values for the semi minor and semi major axes instead -of using the symbolic "sphere" value. Eg, if the radius were 2000000m: - -:: +For compatibility reasons PROJ supports several WKT dialects +(see :option:`projinfo -o`). If possible WKT2 should be used. - +proj=laea +lon_0=-40.000000 +lat_0=74.000000 +x_0=1000000 +y_0=1700000 +a=2000000 +b=2000000" - -How do I do False Eastings and False Northings? +Why is the axis ordering in PROJ not consistent? -------------------------------------------------------------------------------- -Use ``+x_0`` and ``+y_0`` in the projection string. - +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 +cartesain 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 :program:`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_2018 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]] diff --git a/docs/source/geodesic.rst b/docs/source/geodesic.rst index c7753404..11bb5e5c 100644 --- a/docs/source/geodesic.rst +++ b/docs/source/geodesic.rst @@ -93,7 +93,7 @@ The routines also calculate several other quantities of interest 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 + :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, @@ -159,7 +159,7 @@ 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 then 15 nanometers, compared to 0.1 mm + 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.) diff --git a/docs/source/index.rst b/docs/source/index.rst index 33fd096d..69f483ce 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -24,7 +24,7 @@ PROJ .. only:: html - PROJ is a generic coordinate transformation software, that transforms geospatial + 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. @@ -32,13 +32,13 @@ PROJ 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 - let developers use the functionality of PROJ in their own software without having + 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 it's way into PROJ as well. Today PROJ support more + 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. diff --git a/docs/source/install.rst b/docs/source/install.rst index ec441c1e..c050b86a 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -54,9 +54,9 @@ To install PROJ do the following: 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 packacke directory". The suggestions 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 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. diff --git a/docs/source/news.rst b/docs/source/news.rst index 4f95d954..8ec69dcf 100644 --- a/docs/source/news.rst +++ b/docs/source/news.rst @@ -3,6 +3,137 @@ News ############################################################################### +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 behaviour of :program:`proj`: Now only allow initialization of + projections (`#1162 <https://github.com/OSGeo/proj.4/issues/1162>`_) + +* Changed behaviour 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>`_) + +* Chaged behaviour: 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* diff --git a/docs/source/operations/conversions/index.rst b/docs/source/operations/conversions/index.rst index a9d137ab..42ad079d 100644 --- a/docs/source/operations/conversions/index.rst +++ b/docs/source/operations/conversions/index.rst @@ -15,6 +15,7 @@ conversions. cart geoc latlon + noop pop push unitconvert diff --git a/docs/source/operations/conversions/noop.rst b/docs/source/operations/conversions/noop.rst new file mode 100644 index 00000000..a35b2b58 --- /dev/null +++ b/docs/source/operations/conversions/noop.rst @@ -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/docs/source/operations/projections/aea.rst b/docs/source/operations/projections/aea.rst index 211ce83c..70b3e75e 100644 --- a/docs/source/operations/projections/aea.rst +++ b/docs/source/operations/projections/aea.rst @@ -25,17 +25,21 @@ Albers Equal Area :align: center :alt: Albers Equal Area - proj-string: ``+proj=aea`` + proj-string: ``+proj=aea +lat_1=29.5 +lat_2=42.5`` Options ################################################################################ -.. note:: All options are optional for the Albers Equal Area projection. +Required +-------------------------------------------------------------------------------- .. include:: ../options/lat_1.rst .. include:: ../options/lat_2.rst +Optional +-------------------------------------------------------------------------------- + .. include:: ../options/lon_0.rst .. include:: ../options/ellps.rst diff --git a/docs/source/operations/projections/comill.rst b/docs/source/operations/projections/comill.rst new file mode 100644 index 00000000..fa04ec18 --- /dev/null +++ b/docs/source/operations/projections/comill.rst @@ -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/docs/source/operations/projections/images/times.png b/docs/source/operations/projections/images/times.png Binary files differnew file mode 100644 index 00000000..b7d9c481 --- /dev/null +++ b/docs/source/operations/projections/images/times.png diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst index e6ec9076..c5b249c9 100644 --- a/docs/source/operations/projections/index.rst +++ b/docs/source/operations/projections/index.rst @@ -31,6 +31,7 @@ Projections map the spherical 3D space to a flat 2D space. cea chamb collg + comill crast denoy eck1 @@ -83,11 +84,13 @@ Projections map the spherical 3D space to a flat 2D space. merc mil_os mill + misrsom moll murd1 murd2 murd3 natearth + natearth2 nell nell_h nicol @@ -99,6 +102,7 @@ Projections map the spherical 3D space to a flat 2D space. omerc ortel ortho + patterson pconic poly putp1 @@ -115,6 +119,7 @@ Projections map the spherical 3D space to a flat 2D space. robin rouss rpoly + sch sinu somerc stere @@ -122,6 +127,7 @@ Projections map the spherical 3D space to a flat 2D space. gstmerc tcc tcea + times tissot tmerc tobmerc diff --git a/docs/source/operations/projections/lcc.rst b/docs/source/operations/projections/lcc.rst index 3b2032d6..d3ba026f 100644 --- a/docs/source/operations/projections/lcc.rst +++ b/docs/source/operations/projections/lcc.rst @@ -42,19 +42,23 @@ justifies adding this otherwise non-standard projection. :align: center :alt: Lambert Conformal Conic - proj-string: ``+proj=lcc +lon_0=-90`` + proj-string: ``+proj=lcc +lon_0=-90 +lat_1=33 +lat_2=45`` Parameters ################################################################################ -.. note:: All parameters are optional for the projection. +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +Optional +-------------------------------------------------------------------------------- .. include:: ../options/lon_0.rst .. include:: ../options/lat_0.rst -.. include:: ../options/lat_1.rst - .. include:: ../options/lat_2.rst .. include:: ../options/ellps.rst diff --git a/docs/source/operations/projections/misrsom.rst b/docs/source/operations/projections/misrsom.rst new file mode 100644 index 00000000..bb738fa0 --- /dev/null +++ b/docs/source/operations/projections/misrsom.rst @@ -0,0 +1,36 @@ +.. _misrsom: + +******************************************************************************** +Space oblique for MISR +******************************************************************************** + +.. 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/docs/source/operations/projections/natearth2.rst b/docs/source/operations/projections/natearth2.rst new file mode 100644 index 00000000..a5128ea9 --- /dev/null +++ b/docs/source/operations/projections/natearth2.rst @@ -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/docs/source/operations/projections/ob_tran.rst b/docs/source/operations/projections/ob_tran.rst index d0a051e0..378f1333 100644 --- a/docs/source/operations/projections/ob_tran.rst +++ b/docs/source/operations/projections/ob_tran.rst @@ -17,7 +17,7 @@ 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=obt_ran``, specifying the translation factors, :option:`+o_lat_p`, and +``+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 pole of the new coordinates, :math:`\alpha` and :math:`\beta` respectively, are to be placed diff --git a/docs/source/operations/projections/omerc.rst b/docs/source/operations/projections/omerc.rst index 7131df62..ba2edf45 100644 --- a/docs/source/operations/projections/omerc.rst +++ b/docs/source/operations/projections/omerc.rst @@ -4,6 +4,27 @@ 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 elliptical projection | ++---------------------+----------------------------------------------------------+ +| **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 @@ -11,6 +32,77 @@ 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 ################################################################################ @@ -62,7 +154,11 @@ Optional .. option:: +no_rot - Do not rotate axis. + 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 diff --git a/docs/source/operations/projections/patterson.rst b/docs/source/operations/projections/patterson.rst new file mode 100644 index 00000000..b68a14d0 --- /dev/null +++ b/docs/source/operations/projections/patterson.rst @@ -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/docs/source/operations/projections/sch.rst b/docs/source/operations/projections/sch.rst new file mode 100644 index 00000000..f987d75d --- /dev/null +++ b/docs/source/operations/projections/sch.rst @@ -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/docs/source/operations/projections/times.rst b/docs/source/operations/projections/times.rst new file mode 100644 index 00000000..33e12148 --- /dev/null +++ b/docs/source/operations/projections/times.rst @@ -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/docs/source/operations/projections/tmerc.rst b/docs/source/operations/projections/tmerc.rst index fd600001..a52e4059 100644 --- a/docs/source/operations/projections/tmerc.rst +++ b/docs/source/operations/projections/tmerc.rst @@ -28,7 +28,7 @@ The transverse Mercator projection in its various forms is the most widely used .. figure:: ./images/tmerc.png :width: 500 px :align: center - :alt: Transverse Mercator + :alt: Transverse Mercator proj-string: ``+proj=tmerc`` @@ -79,7 +79,9 @@ Parameters .. versionadded:: 6.0.0 - Use faster, less accurate algorithm for the Transverse Mercator. + Use the algorithm described in section "Elliptical Form" below. + It is faster than the default algorithm, but also diverges faster + as the distance from the central meridian increases. .. include:: ../options/lon_0.rst @@ -98,7 +100,7 @@ Parameters Mathematical definition ####################### -The formulas describing the Transverse Mercator are all taken from Evenden's [Evenden2005]_. +The formulas describing the Transverse Mercator below are quoted from Evenden's [Evenden2005]_. :math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``. @@ -148,6 +150,11 @@ Inverse projection Elliptical 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`. +The default algorithm is given by Poder and Engsager in :cite:`Poder1998` + Forward projection ================== @@ -169,7 +176,7 @@ Forward projection .. math:: - x &= k_0 \lambda \cos \phi \\ + 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) diff --git a/docs/source/operations/projections/tobmerc.rst b/docs/source/operations/projections/tobmerc.rst index d9a3eb05..69a4855d 100644 --- a/docs/source/operations/projections/tobmerc.rst +++ b/docs/source/operations/projections/tobmerc.rst @@ -66,7 +66,7 @@ Mathematical definition ####################### The formulas describing the Tobler-Mercator are taken from Waldo Tobler's -article :cite:`Tobler2017` +article :cite:`Tobler2018` Spherical form ************** diff --git a/docs/source/operations/projections/urm5.rst b/docs/source/operations/projections/urm5.rst index c44632d4..4d2dd557 100644 --- a/docs/source/operations/projections/urm5.rst +++ b/docs/source/operations/projections/urm5.rst @@ -14,12 +14,14 @@ Urmaev V Parameters ################################################################################ -.. note:: All parameters are optional for the projection. - +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. diff --git a/docs/source/operations/transformations/geogoffset.rst b/docs/source/operations/transformations/geogoffset.rst index f643485e..6ca4f64c 100644 --- a/docs/source/operations/transformations/geogoffset.rst +++ b/docs/source/operations/transformations/geogoffset.rst @@ -21,11 +21,11 @@ latitude coordinates, and an offset to the ellipsoidal height. 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:`EPSGGuidanceNumber7Part2`) +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 ellispoid height (dh being +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) diff --git a/docs/source/operations/transformations/horner.rst b/docs/source/operations/transformations/horner.rst index dd9b9cc9..5c88c292 100644 --- a/docs/source/operations/transformations/horner.rst +++ b/docs/source/operations/transformations/horner.rst @@ -28,7 +28,7 @@ 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:`EPSGGuidanceNumber7Part2`. +:cite:`Ruffhead2016` and :cite:`IOGP2018`. The polynomial evaluation in real number space is defined by the following equations: diff --git a/docs/source/operations/transformations/vgridshift.rst b/docs/source/operations/transformations/vgridshift.rst index 484ad4bf..04be5b1b 100644 --- a/docs/source/operations/transformations/vgridshift.rst +++ b/docs/source/operations/transformations/vgridshift.rst @@ -23,7 +23,7 @@ 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_16.gtx + +proj=vgridshift +grids=egm96_15.gtx More than one grid can be loaded at the same time, for instance in the case where @@ -31,7 +31,7 @@ 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_16.gtx + +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 diff --git a/docs/source/references.bib b/docs/source/references.bib index b36e1e2d..9829495f 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -3,8 +3,8 @@ @Article{Altamimi2002, - Title = {ITRF2000: A new release of the International Terrestrial Reference Frame for earth science applications}, - Author = {Z. Altamimi and P. Sillard and C. Boucher}, + Title = {{ITRF2000}: A new release of the {International Terrestrial Reference Frame} for earth science applications}, + Author = {Zuheir Altamimi and Patrick Sillard and Claude Boucher}, Journal = {Journal of Geophysical Research: Solid Earth}, Year = {2002}, Number = {B10}, @@ -22,12 +22,13 @@ Pages = {241--254}, Volume = {4}, - Url = {https://arxiv.org/abs/0908.1824} + Archiveprefix = {arXiv}, + Eprint = {0908.1824} } @Article{CalabrettaGreisen2002, Title = {Representations of celestial coordinates in {FITS}}, - Author = {Calabretta, M. R. and Greisen, E. W.}, + Author = {M. R. Calabretta and E. W. Greisen}, Journal = {Astronomy \& Astrophysics}, Year = {2002}, Number = {3}, @@ -39,7 +40,7 @@ @TechReport{ChanONeil1975, Title = {Feasibility Study of a Quadrilateralized Spherical Cube Earth Data Base}, - Author = {Chan, F. K. and O'Neill, E. M.}, + Author = {F. K. Chan and E. M. O'Neill}, Institution = {Computer Sciences Corporation, System Sciences Division}, Year = {1975}, @@ -68,12 +69,14 @@ Institution = {Department of Mathematical and Geospatial Sciences, RMIT University}, Year = {2004}, + Address = {Melborne, Australia}, + Url = {http://www.mygeodesy.id.au/documents/Molodensky%20V2.pdf} } @Article{EberHewitt1979, Title = {Conversion algorithms for the {CalCOFI} station grid}, - Author = {L. E. Eber and R.P. Hewitt}, + Author = {L. E. Eber and Roger P. Hewitt}, Journal = {California Cooperative Oceanic Fisheries Investigations Reports}, Year = {1979}, Pages = {135--137}, @@ -82,17 +85,9 @@ Url = {http://www.calcofi.org/publications/calcofireports/v20/Vol_20_Eber___Hewitt.pdf} } -@Manual{EPSGGuidanceNumber7Part2, - Title = {Geomatics Guidance Note 7, part 2 - Coordinate Conversions & Transformations including Formulas}, - Institution = {International Association For Oil And Gas Producers}, - Year = {2018}, - - Url = {https://www.iogp.org/bookstore/product/coordinate-conversions-and-transformation-including-formulas/} -} - @Manual{Evenden2005, Title = {libproj4: A Comprehensive Library of Cartographic Projection Functions (Preliminary Draft)}, - Author = {G. I. Evenden}, + Author = {Gerald I. Evenden}, Year = {2005}, Url = {https://github.com/OSGeo/proj.4/blob/master/docs/old/libproj.pdf} @@ -100,7 +95,7 @@ @Manual{Evenden1995, Title = {Cartographic Projection Procedures for the {UNIX} Environment --- {A} User's Manual}, - Author = {G. I. Evenden}, + Author = {Gerald I. Evenden}, Year = {1995}, Url = {https://pubs.usgs.gov/of/1990/of90-284/ofr90-284.pdf} @@ -108,10 +103,12 @@ @InProceedings{EversKnudsen2017, Title = {Transformation pipelines for {PROJ.4}}, - Author = {K. Evers and T. Knudsen}, + Author = {Kristian Evers and Thomas Knudsen}, Booktitle = {FIG Working Week 2017 Proceedings}, Year = {2017}, + Address = {Helsinki, Finland}, + Url = {http://www.fig.net/resources/proceedings/fig_proceedings/fig2017/papers/iss6b/ISS6B_evers_knudsen_9156.pdf} } @@ -140,9 +137,58 @@ Doi = {10.5281/zenodo.32050} } +@InProceedings{Hensley2002, + Title = {Improved Processing of {AIRSAR} Data Based on the {GeoSAR} Processor}, + Author = {Scott Hensley and Elaine Chapin and Adam Freedman and Thierry Michel}, + Booktitle = {AIRSAR Earth Science and Application Workshop}, + Year = {2002}, + + Address = {Pasadena, California}, + Organization = {Jet Propulsion Laboratory}, + + Url = {https://airsar.jpl.nasa.gov/documents/workshop2002/papers/T3.pdf} +} + +@TechReport{IOGP2018, + Title = {Geomatics Guidance Note 7, part 2: Coordinate Conversions \& Transformations including Formulas}, + Author = {IOGP}, + Institution = {International Association For Oil And Gas Producers}, + Year = {2018}, + Number = {373-7-2}, + Type = {IOGP Publication}, + + Url = {https://www.iogp.org/bookstore/product/coordinate-conversions-and-transformation-including-formulas/} +} + +@TechReport{ISO19111, + Title = {{Geographic information -- Referencing by coordinates}}, + Author = {ISO}, + Year = {2019}, + Type = {Standard}, + Key = {ISO 19111:2019}, + Month = Jan, + Volume = {2019}, + Address = {Geneva, CH}, + Institution = {International Organization for Standardization}, + Url = {http://docs.opengeospatial.org/as/18-005r4/18-005r4.html} +} + +@Article{Jenny2015, + Title = {A compromise aspect-adaptive cylindrical projection for world maps}, + Author = {Bernhard Jenny and Bojan Šavrič and Tom Patterson}, + Journal = {International Journal of Geographical Information Science}, + Year = {2015}, + Number = {6}, + Pages = {935--952}, + Volume = {29}, + + Doi = {10.1080/13658816.2014.997734}, + Url = {http://www.cartography.oregonstate.edu/pdf/2015_Jenny_etal_ACompromiseAspect-adaptiveCylindricalProjectionForWorldMaps.pdf} +} + @Article{Karney2013, Title = {Algorithms for geodesics}, - Author = {C. F. F. Karney}, + Author = {Charles F. F. Karney}, Journal = {Journal of Geodesy}, Year = {2013}, Number = {1}, @@ -154,7 +200,7 @@ @Article{Karney2011, Title = {Geodesics on an ellipsoid of revolution}, - Author = {C. F. F. Karney}, + Author = {Charles F. F. Karney}, Journal = {ArXiv e-prints}, Year = {2011}, @@ -165,7 +211,7 @@ @Article{Komsta2016, Title = {{ATPOL} geobotanical grid revisited -- a proposal of coordinate conversion algorithms}, - Author = {Ł. Komsta}, + Author = {Łukasz Komsta}, Journal = {Annales UMCS Sectio E Agricultura}, Year = {2016}, Number = {1}, @@ -175,10 +221,10 @@ @InProceedings{LambersKolb2012, Title = {Ellipsoidal Cube Maps for Accurate Rendering of Planetary-Scale Terrain Data}, - Author = {M. Lambers and A. Kolb}, + Author = {Lambers, Martin and Kolb, Andreas}, Booktitle = {Pacific Graphics Short Papers}, Year = {2012}, - Editor = {C. Bregler and P. Sander and M. Wimmer}, + Editor = {Chris Bregler and Pedro Sander and Michael Wimmer}, Publisher = {The Eurographics Association}, Doi = {10.2312/PE/PG/PG2012short/005-010} @@ -197,52 +243,103 @@ Url = {https://archive.org/details/DTIC_ADA026294} } -@article{Ruffhead2016, - author = {A. C. Ruffhead}, - title = {Introduction to multiple regression equations in datum transformations and their reversibility}, - journal = {Survey Review}, - volume = {50}, - number = {358}, - pages = {82-90}, - year = {2016}, - publisher = {Taylor & Francis}, - doi = {10.1080/00396265.2016.1244143}, +@Article{Patterson2014, + Title = {Introducing the {Patterson} Cylindrical Projection}, + Author = {Tom Patterson and Bojan Šavrič and Bernhard Jenny}, + Journal = {Cartographic Perspectives}, + Year = {2014}, + Volume = {78}, + + Doi = {10.14714/CP78.1270} } -@Book{Snyder1993, - Title = {Flattening the Earth}, - Author = {J. P. Snyder}, - Publisher = {University of Chicago Press}, - Year = {1993} +@TechReport{Poder1998, + Title = {Some Conformal Mappings and Transformations for Geodesy and Topographic Cartography}, + Author = {Knud Poder and Karsten Engsager}, + Institution = {National Survey and Cadastre}, + Year = {1998}, + + Address = {Copenhagen, Denmark}, + Type = {National Survey and Cadastre Publications}, + + ISBN = {87-7866-085-8}, + Pages = {63}, + Series = {4}, + Volume = {6} +} + +@Misc{Rittri2012, + Title = {New omerc approximations of {Denmark System 34}}, + + Author = {Mikael Rittri}, + HowPublished = {e-mail}, + Year = {2012}, + + Url = {https://lists.osgeo.org/pipermail/proj/2012-June/005926.html} +} + +@Article{Ruffhead2016, + Title = {Introduction to multiple regression equations in datum transformations and their reversibility}, + Author = {A. C. Ruffhead}, + Journal = {Survey Review}, + Year = {2016}, + Number = {358}, + Pages = {82--90}, + Volume = {50}, + + Doi = {10.1080/00396265.2016.1244143}, + Publisher = {Taylor \& Francis} } @Article{Savric2018, - Author = {B. Šavrič and T. Patterson and B. Jenny}, - Title = {The Equal Earth map projection}, + Title = {The {Equal Earth} map projection}, + Author = {Bojan Šavrič and Tom Patterson and Bernhard Jenny}, Journal = {International Journal of Geographical Information Science}, Year = {2018}, - Publisher = {Taylor & Francis}, + Number = {3}, + Pages = {454--465}, + Volume = {33}, + Doi = {10.1080/13658816.2018.1504949}, - Url = {https://www.researchgate.net/profile/Bojan_Savric2/publication/326879978_The_Equal_Earth_map_projection/links/5b69d0ae299bf14c6d951b77/The-Equal-Earth-map-projection.pdf} + Url = {https://www.researchgate.net/publication/326879978_The_Equal_Earth_map_projection} +} + +@Article{Savric2015, + Title = {The {Natural Earth II} world map projection}, + Author = {Bojan Šavrič and Tom Patterson and Bernhard Jenny}, + Journal = {International Journal of Cartography}, + Year = {2015}, + Number = {2}, + Pages = {123--133}, + Volume = {1}, + + Doi = {10.1080/23729333.2015.1093312}, + Url = {https://www.researchgate.net/publication/290447301_The_Natural_Earth_II_world_map_projection} +} + +@Book{Snyder1993, + Title = {Flattening the Earth}, + Author = {John P. Snyder}, + Publisher = {University of Chicago Press}, + Year = {1993} } @Article{Snyder1988, - Author = {J. P. Snyder }, Title = {New Equal-Area Map Projections For Noncircular Regions}, + Author = {John P. Snyder}, Journal = {The American Cartographer}, - Volume = {15}, - Number = {4}, - Pages = {341-356}, Year = {1988}, - Publisher = {Taylor and Francis}, + Number = {4}, + Pages = {341--356}, + Volume = {15}, - Doi = {10.1559/152304088783886784} + Doi = {10.1559/152304088783886784}, + Publisher = {Taylor and Francis} } - @TechReport{Snyder1987, Title = {Map Projections --- {A} Working Manual}, - Author = {J. P. Snyder}, + Author = {John P. Snyder}, Institution = {U.S. Geological Survey}, Year = {1987}, Number = {1395}, @@ -259,16 +356,17 @@ Edition = {15th} } -@Article{Tobler2017, - Author = {W. Tobler}, - Title = {A new companion for Mercator}, +@Article{Tobler2018, + Title = {A new companion for {Mercator}}, + Author = {Waldo Tobler}, Journal = {Cartography and Geographic Information Science}, - Volume = {45}, + Year = {2018}, Number = {3}, - Pages = {284-285}, - Publisher = {Taylor & Francis}, - Year = {2017}, + Pages = {284--285}, + Volume = {45}, + Doi = {10.1080/15230406.2017.1308837}, + Publisher = {Taylor \& Francis} } @Article{Verey2017, @@ -297,7 +395,7 @@ @Article{WeberMoore2013, Title = {Corrected Conversion Algorithms For The {CalCOFI} Station Grid And Their Implementation In Several Computer Languages}, - Author = {E. D. Weber and T. J. Moore}, + Author = {Edward D. Weber and Thomas J. Moore}, Journal = {California Cooperative Oceanic Fisheries Investigations Reports}, Year = {2013}, Pages = {1--10}, @@ -308,7 +406,7 @@ @Article{Zajac1978, Title = {Atlas of Distribution of Vascular Plants in {Poland} ({ATPOL})}, - Author = {A. Zajaç}, + Author = {Adam Zajaç}, Journal = {Taxon}, Year = {1978}, Number = {5/6}, diff --git a/docs/source/resource_files.rst b/docs/source/resource_files.rst index 53843571..d6f64175 100644 --- a/docs/source/resource_files.rst +++ b/docs/source/resource_files.rst @@ -106,7 +106,7 @@ Brazil Netherlands ................................................................................ -`Dutch grid <https://www.kadaster.nl/web/Themas/Registraties/Rijksdriehoeksmeting/Transformatie-van-coordinaten.htm>`__ (Registration required before download) +`Dutch grid <https://zakelijk.kadaster.nl/transformatie-van-coordinaten>`__ (Registration required before download) Portugal ................................................................................ diff --git a/docs/source/usage/differences.rst b/docs/source/usage/differences.rst index d5eebe8e..4d05543a 100644 --- a/docs/source/usage/differences.rst +++ b/docs/source/usage/differences.rst @@ -97,8 +97,8 @@ 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 +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. @@ -113,4 +113,4 @@ the time span for which they wish to apply a given deformation. The parameter 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.
\ No newline at end of file +deformation from a specific epoch to the observation time is needed. diff --git a/docs/source/usage/environmentvars.rst b/docs/source/usage/environmentvars.rst index 478e2eab..c8dfe28e 100644 --- a/docs/source/usage/environmentvars.rst +++ b/docs/source/usage/environmentvars.rst @@ -40,6 +40,16 @@ done by setting the variable with no content:: in other locations as well, amongst those are the users home directory, ``/usr/share/proj`` and the current folder. + You can also set the location of the resource files using + :func:`proj_context_set_search_paths` in the `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 mutliple versions of PROJ + resource files on your system without conflicting. + .. envvar:: PROJ_DEBUG Set the debug level of PROJ. The default debug level is zero, which results |
