diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css new file mode 100644 index 0000000000..b82d2881be --- /dev/null +++ b/docs/source/_static/theme_overrides.css @@ -0,0 +1,57 @@ +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} + +/* Align equation numbers to the right of the equation, not above */ +div.math { + position: relative; + padding-right: 2.5em; +} +.eqno { + height: 100%; + position: absolute; + right: 0; + padding-left: 5px; + padding-bottom: 5px; +} +.eqno:before { + /* Force vertical alignment of number */ + display: inline-block; + height: 100%; + vertical-align: middle; + content: ""; +} +.eqno .headerlink { + display: none; + visibility: hidden; + font-size: 14px; + padding-left: .3em; +} +.eqno:hover .headerlink { + display: inline-block; + visibility: hidden; + margin-right: -1.05em; +} +.eqno .headerlink:after { + visibility: visible; + content: "\f0c1"; + font-family: FontAwesome; + display: inline-block; + margin-left: -.9em; +} +/* Make responsive */ +.MathJax_Display { + max-width: 100%; + overflow-x: auto; + overflow-y: hidden; +} diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst deleted file mode 100644 index 1baaf1c592..0000000000 --- a/docs/source/apps/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _apps: - -================================================================================ -Applications -================================================================================ - -The proj program is limited to converting -between geographic and projection coordinates -within one datum. - -The cs2cs program operates similarly, but allows -translation between any pair of definable coor- -dinate systems, including support for datum -translation. - -The geod program provides the ability to compute -geodesic (Great Circle) computations. - - - -.. toctree:: - :maxdepth: 1 - - proj - cs2cs - geod - diff --git a/docs/source/conf.py b/docs/source/conf.py index cbd02f100e..af9d24dab7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# proj.4 documentation build configuration file, created by +# PROJ.4 documentation build configuration file, created by # sphinx-quickstart on Wed Feb 24 10:47:15 2016. # # This file is execfile()d with the current directory set to its @@ -14,6 +14,7 @@ import sys import os +import datetime # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -47,8 +48,9 @@ master_doc = 'index' # General information about the project. -project = u'proj.4' -copyright = u'1986?-2016' +project = u'PROJ.4' +now = datetime.datetime.now() +copyright = u'1983-{0}'.format(now.year) author = u'Gerald Evenden, Frank Warmerdam, and others' # The version info for the project you're documenting, acts as replacement for @@ -56,9 +58,9 @@ # built documents. # # The short X.Y version. -version = u'4.9.3' +version = u'5.0.0' # The full version, including alpha/beta/rc tags. -release = u'4.9.3' +release = u'5.0.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -140,7 +142,13 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['_static'] +html_static_path = ['_static'] + +html_context = { + 'css_files': [ + '_static/theme_overrides.css', # override wide tables in RTD theme + ], +} # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -230,7 +238,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'proj4.tex', u'proj.4 Documentation', + (master_doc, 'proj4.tex', u'PROJ.4 Documentation', u'Gerald Evenden', 'manual'), ] @@ -260,7 +268,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'proj4', u'proj.4 Documentation', + (master_doc, 'proj4', u'PROJ.4 Documentation', [author], 1) ] @@ -274,7 +282,7 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'proj4', u'proj.4 Documentation', + (master_doc, 'proj4', u'PROJ.4 Documentation', author, 'proj4', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 0000000000..e7f9101e0c --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,242 @@ +.. _contributing: + +=========================== +Contributing +=========================== + +PROJ.4 has a wide and varied user base. Some are highly skilled +geodesists with a deep knowledge of map projections and reference +systems, some are GIS software developers and others are GIS users. All +users, regardless of the profession or skill level, has the ability to +contribute to PROJ.4. Here's a few suggestion on how: + +- Help PROJ.4-users that is less experienced than yourself. +- Write a bug report +- Request a new feature +- Write documentation for your favorite map projection +- Fix a bug +- Implement a new feature + +In the following sections you can find some guidelines on how to +contribute. As PROJ.4 is managed on GitHub most contributions require +that you have a GitHub account. Familiarity with +`issues `__ and the `GitHub +Flow `__ is an advantage. + +Help a fellow PROJ.4 user +------------------------- + +The main forum for support for PROJ.4 is the mailing list. You can +subscribe to the mailing list +`here `__ and read the +archive `here `__. + +If you have questions about the usage of PROJ.4 the mailing list is also +the place to go. Please *do not* use the GitHub issue tracker as a +support forum. Your question is much more likely to be answered on the +mailing list, as many more people follow that than the issue tracker. + +Adding bug reports +------------------ + +Bug reports are handled in the `issue +tracker `__ on PROJ.4's home on +GitHub. Writing a good bug report is not easy. But fixing a poorly +documented bug is not easy either, so please put in the effort it takes +to create a thorough bug report. + +A good bug report includes at least: + +- A title that quickly explains the problem +- A description of the problem and how it can be reproduced +- Version of PROJ.4 being used +- Version numbers of any other relevant software being used, e.g. + operating system +- A description of what already has been done to solve the problem + +The more information that is given up front, the more likely it is that +a developer will find interest in solving the problem. You will probably +get follow-up questions after submitting a bug report. Please answer +them in a timely manner if you have an interest in getting the issue +solved. + +Finally, please only submit bug reports that are actually related to +PROJ.4. If the issue materializes in software that uses PROJ.4 it is +likely a problem with that particular software. Make sure that it +actually is a PROJ.4 problem before you submit an issue. If you can +reproduce the problem only by using tools from PROJ.4 it is definitely a +problem with PROJ.4. + +Feature requests +---------------- + +Got an idea for a new feature in PROJ.4? Submit a thorough description +of the new feature in the `issue +tracker `__. Please include any +technical documents that can help the developer make the new feature a +reality. An example of this could be a publicly available academic paper +that describes a new projection. Also, including a numerical test case +will make it much easier to verify that an implementation of your +requested feature actually works as you expect. + +Note that not all feature requests are accepted. + +Write documentation +------------------- + +PROJ.4 is in dire need of better documentation. Any contributiions of +documentation are greatly appreaciated. The PROJ.4 documentation is +available on `proj4.org `__. The website is generated +with `Sphinx `__. Contributions to +the documentation should be made as `Pull +Requests `__ on GitHub. + +If you intend to document one of PROJ.4's supported projections please +use the `Mercator projection `__ +as a template. + +Code contributions +------------------ + +Code contributions can be either bug fixes or new features. The process +is the same for both, so they will be discussed together in this +section. + +Making Changes +~~~~~~~~~~~~~~ + +- Create a topic branch from where you want to base your work. +- You usually should base your topic branch off of the master branch. +- To quickly create a topic branch: ``git checkout -b my-topic-branch`` +- Make commits of logical units. +- Check for unnecessary whitespace with ``git diff --check`` before + committing. +- Make sure your commit messages are in the `proper + format `__. +- Make sure you have added the necessary tests for your changes. +- Make sure that all tests pass + +Submitting Changes +~~~~~~~~~~~~~~~~~~ + +- Push your changes to a topic branch in your fork of the repository. +- Submit a pull request to the PROJ.4 repository in the OSGeo + organization. +- If your pull request fixes/references an issue, include that issue + number in the pull request. For example: + +:: + + Wiz the bang + + Fixes #123. + +- PROJ.4 developers will look at your patch and take an appropriate + action. + +Coding conventions +~~~~~~~~~~~~~~~~~~ + +Programming language +^^^^^^^^^^^^^^^^^^^^ + +PROJ.4 is developed strictly in ANSI C 89. + +Coding style +^^^^^^^^^^^^ + +We don't enforce any particular coding style, but please try to keep it +as simple as possible. If improving existing code, please try to conform +with the style of the locally surrounding code. + +Whitespace +^^^^^^^^^^ + +Throughout the PROJ.4 code base you will see differing whitespace use. +The general rule is to keep whitespace in whatever form it is in the +file you are currently editing. If the file has a mix of tabs and space +please convert the tabs to space in a separate commit before making any +other changes. This makes it a lot easier to see the changes in diffs +when evaulating the changed code. New files should use spaces as +whitespace. + +File names +^^^^^^^^^^ + +Files in which projections are implemented are prefixed with an +upper-case ``PJ_`` and most other files are prefixed with lower-case +``pj_``. Some file deviate from this pattern, most of them dates back to +the very early releases of PROJ.4. New contributions should follow the +pj-prefix pattern. Unless there are obvious reasons not to. + +Legalese +~~~~~~~~ + +Commiters are the front line gatekeepers to keep the code base clear of +improperly contributed code. It is important to the PROJ.4 users, +developers and the OSGeo foundation to avoid contributing any code to +the project without it being clearly licensed under the project license. + +Generally speaking the key issues are that those providing code to be +included in the repository understand that the code will be released +under the MIT/X license, and that the person providing the code has the +right to contribute the code. For the commiter themselves understanding +about the license is hopefully clear. For other contributors, the +commiter should verify the understanding unless the commiter is very +comfortable that the contributor understands the license (for instance +frequent contributors). + +If the contribution was developed on behalf of an employer (on work +time, as part of a work project, etc) then it is important that an +appropriate representative of the employer understand that the code will +be contributed under the MIT/X license. The arrangement should be +cleared with an authorized supervisor/manager, etc. + +The code should be developed by the contributor, or the code should be +from a source which can be rightfully contributed such as from the +public domain, or from an open source project under a compatible +license. + +All unusual situations need to be discussed and/or documented. + +Commiters should adhere to the following guidelines, and may be +personally legally liable for improperly contributing code to the source +repository: + +- Make sure the contributor (and possibly employer) is aware of the + contribution terms. +- Code coming from a source other than the contributor (such as adapted + from another project) should be clearly marked as to the original + source, copyright holders, license terms and so forth. This + information can be in the file headers, but should also be added to + the project licensing file if not exactly matching normal project + licensing (COPYING). +- Existing copyright headers and license text should never be stripped + from a file. If a copyright holder wishes to give up copyright they + must do so in writing to the foundation before copyright messages are + removed. If license terms are changed it has to be by agreement + (written in email is ok) of the copyright holders. +- Code with licenses requiring credit, or disclosure to users should be + added to COPYING. +- When substantial contributions are added to a file (such as + substantial patches) the author/contributor should be added to the + list of copyright holders for the file. +- If there is uncertainty about whether a change is proper to + contribute to the code base, please seek more information from the + project steering committee, or the foundation legal counsel. + +Additional Resources +-------------------- + +- `General GitHub documentation `__ +- `GitHub pull request + documentation `__ + +Acknowledgements +---------------- + +The *code contribution* section of this CONTRIBUTING file is inspired by +`PDAL's `__ +and the *legalese* section is modified from `GDAL contributer +guidelines `__ + diff --git a/docs/source/development/bindings.rst b/docs/source/development/bindings.rst index a1c2a9e0fb..80babcb20d 100644 --- a/docs/source/development/bindings.rst +++ b/docs/source/development/bindings.rst @@ -4,37 +4,37 @@ Language bindings ******************************************************************************** -Proj.4 bindings are available for a number of different development platforms. +PROJ.4 bindings are available for a number of different development platforms. Python ====== `pyproj `_: -Python interface (wrapper for proj.4) +Python interface (wrapper for PROJ.4) Ruby ======= `proj4rb `_: -Bindings for proj.4 in ruby +Bindings for PROJ.4 in ruby TCL ======== `proj4tcl `_: -Bindings for proj.4 in tcl (critcl source) +Bindings for PROJ.4 in tcl (critcl source) MySQL ===== `fProj4 `_: -Bindings for proj.4 in MySQL +Bindings for PROJ.4 in MySQL Excel ======== `proj.xll `_: -Excel add-in for proj.4 map projections +Excel add-in for PROJ.4 map projections Visual Basic ================== diff --git a/docs/source/projections/airy.rst b/docs/source/development/errorhandling.rst similarity index 54% rename from docs/source/projections/airy.rst rename to docs/source/development/errorhandling.rst index 307af3e340..58199e3f87 100644 --- a/docs/source/projections/airy.rst +++ b/docs/source/development/errorhandling.rst @@ -1,10 +1,7 @@ -.. _airy: +.. _errorhandling: -******************************************************************************** -Airy -******************************************************************************** +================================================================================ +Error handling +================================================================================ -.. image:: ./images/airy.png - :scale: 50% - :alt: Airy diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 2e6e5622c2..318e3778b3 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -5,13 +5,17 @@ Development ================================================================================ These pages are primarily focused towards developers either contributing to the -proj.4 project or using the library in their own software. +PROJ.4 project or using the library in their own software. .. toctree:: :maxdepth: 1 - api + quickstart + transformations + errorhandling threads + reference/index bindings + migration diff --git a/docs/source/development/migration.rst b/docs/source/development/migration.rst new file mode 100644 index 0000000000..d9014a366d --- /dev/null +++ b/docs/source/development/migration.rst @@ -0,0 +1,137 @@ +.. _API_migration: + +================================================================================ +Version 4 to 5 API Migration +================================================================================ + +This is a transition guide for developers wanting to migrate their code to use +PROJ version 5. + +The difference between the old and new API is best shown with 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 +projected coordinates with the Mercator projection. + +We start by writing the progran for PROJ v. 4: + +.. code-block:: C + + #include + + main(int argc, char **argv) { + projPJ pj_merc, pj_latlong; + double x, y; + + if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) ) + return 1; + if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) ) + 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 ); + printf("%.2f\t%.2f\n", x, y); + } + + return 0; + } + +The same program implemented using PROJ v. 5: + +.. code-block:: C + + #include + + main(int argc, char **argv) { + PJ *P; + PJ_COORD c; + + P = proj_create(PJ_DEFAULT_CTX, "+proj=merc +ellps=clrk66 +lat_ts=33"); + if (P==0) + return 1; + + while (scanf("%lf %lf", &c.lp.lam, &c.lp.phi) == 2) { + c.lp.lam = proj_todeg(c.lp.lam); + c.lp.phi = proj_todeg(c.lp.phi); + c = proj_trans(P, PJ_FWD, c); + printf("%.2f\t%.2f\n", c.xy.x, c.xy.y); + } + + } + +Looking at the two different programs, there's a few immediate +differences that catches the eye. First off, the included header file describing +the API has changed from ``proj_api.h`` to simply ``proj.h``. All functions in ``proj.h`` +belongs to the ``proj_`` namespace. + +With the new API also comes new datatypes. E.g. the transformation object ``projPJ`` +which has been changed to a pointer of type ``PJ``. This is done to highlight the +actual nature of the object, instead of hiding it away behind a typedef. New data +types for handling coordinates have also been introduced. In the above example we +use the ``PJ_COORD``, which is a union of various types. The benefit of this is that +it is possible to use the various structs in the union to communicate what state +the data is in at different points in the program. For instance as in the above +example where the coordinate is read from STDIN as a geodetic coordinate, +communicated to the reader of the code by using the ``c.lp`` struct. +After it has been projected we print it to STDOUT by accessing the individual +elements in ``c.xy`` to illustrate that the coordinate is now in projected space. +Data types are prefixed with `PJ_`. + +The final, and perhaps biggest, change is that the fundamental concept of +transformations in PROJ are now handled in a single transformation object (``PJ``) +and not by stating the source and destination systems as previously. It is of +course still possible to do just that, but the transformation object now +captures the whole transformation from source to destination in one. In the +example with the old API the source system is described as +``+proj=latlon +ellps=clrk66`` and the destination system is described as +``+proj=merc +ellps=clrk66 +lat_ts=33``. Since the Mercator projection accepts +geodetic coordinates as its input, the description of the source in this case +is superflous. We use that to our advantage in the new API and simply state +the destination. This is simple at a glance, but is actually a big conceptual +change. We are now focused on the path between two systems instead of what the +source and destination systems are. + + +Function mapping from old to new API +############################################################################### + ++---------------------------------------+---------------------------------------+ +| **Old API functions** | **New API functions** | ++---------------------------------------+---------------------------------------+ +| pj_fwd | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_inv | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_fwd3 | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_inv3 | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_transform | proj_trans_array or proj_trans_generic| ++---------------------------------------+---------------------------------------+ +| pj_init | proj_create | ++---------------------------------------+---------------------------------------+ +| pj_init_plus | proj_create | ++---------------------------------------+---------------------------------------+ +| pj_free | proj_destroy | ++---------------------------------------+---------------------------------------+ +| pj_is_latlong | proj_angular_output | ++---------------------------------------+---------------------------------------+ +| pj_is_geocent | proj_angular_outout | ++---------------------------------------+---------------------------------------+ +| pj_get_def | proj_pj_info | ++---------------------------------------+---------------------------------------+ +| pj_latlong_from_proj | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_set_finder | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_set_searchpath | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_deallocate_grids | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_strerrno | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_get_errno_ref | proj_errno | ++---------------------------------------+---------------------------------------+ +| pj_get_release | proj_info | ++---------------------------------------+---------------------------------------+ diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst new file mode 100644 index 0000000000..7137d85a59 --- /dev/null +++ b/docs/source/development/quickstart.rst @@ -0,0 +1,100 @@ +.. _dev_quickstart: + +================================================================================ +Quick start +================================================================================ + +This is a short introduction to the PROJ.4 API. In the following section we +create a simple program that transforms a geodetic coordinate to UTM and back +again. The program is explained a few lines at a time. The complete program can +be seen at the end of the section. + +See the following sections for more in-depth descriptions of different parts of +the PROJ.4 API or consult the :doc:`API reference ` for specifics. + +Before the PROJ.4 API can be used it is necessary to include the ``proj.h`` header +file. Here ``stdio.h`` is also included so we can print some text to the screen: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 39-40 + +Let's declare a few variables that'll be used later in the program. Each variable +will be discussed below. +See the :doc:`reference for more info on data types `. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 43-45 + :dedent: 4 + +For use in multi-threaded programs the ``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 ` discusses +this in detail. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 48 + :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. +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 +details. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 50-52 + :dedent: 4 + +PROJ.4 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.4 is using radians internally. See :doc:`transformations` +for further details. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 56 + :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. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 59-60 + :dedent: 4 + +The inverse transformation (UTM to geodetic) is done similar to above, +this time using ``PJ_INV`` as the direction. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 61-62 + :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 + :dedent: 4 + + +A complete compilable version of the above can be seen here: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :linenos: + :lines: 39- + diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst new file mode 100644 index 0000000000..1253b1a203 --- /dev/null +++ b/docs/source/development/reference/datatypes.rst @@ -0,0 +1,717 @@ +.. _datatypes: + +================================================================================ +Data types +================================================================================ + +This section describe the multiplude of data types in use in PROJ.4. As a rule +of thumb PROJ.4 data types are prefixed with ``PJ_``, or in one particular case, +is simply called :c:type:`PJ`. A few notable exceptions can be traced +back to the very early days of PROJ.4 when the ``PJ_`` prefix was not +consistenly used. + +Transformation objects +-------------------------------------------------------------------------------- + +.. c:type:: PJ + + Object containing everything related to a given projection or transformation. + As a user of the PROJ.4 library your are only exposed to pointers to this + object and the contents are hidden in the public API. :c:type:`PJ` objects + are created with :c:func:`proj_create` and destroyed with + :c:func:`proj_destroy`. + +.. c:type:: PJ_DIRECTION + + Enumeration that is used to convey in which direction a given transformation + should be performed. Used in transformation function call as described in + the section on :ref:`transformation functions `. + + Forward transformations are defined with the :c: + + .. code-block:: C + + typedef enum proj_direction { + PJ_FWD = 1, /* Forward */ + PJ_IDENT = 0, /* Do nothing */ + PJ_INV = -1 /* Inverse */ + } PJ_DIRECTION; + + .. c:member:: PJ_FWD + + Perform transformation in the forward direction. + + .. c:member:: PJ_IDENT + + Identity. Do nothing. + + .. c:member:: PJ_INV + + Perform transformation in the inverse direction. + +.. c:type:: PJ_CONTEXT + + Context objects enables safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` + object is connected to a context (if not specified, the default context is + used). All operations within a context should be performed in the same thread. + :c:type:`PJ_CONTEXT` objects are created with :c:func:`proj_context_create` + and destroyed with :c:func:`proj_context_destroy`. + + +.. c:type:: PJ_AREA + + Opaque object describing an area in which a transformation is performed. + + .. note:: This object is not fully implemented yet. It is used with + :c:func:`proj_create_crs_to_crs` to select the best transformation + between the two input coordinate reference systems. + +2 dimensional coordinates +-------------------------------------------------------------------------------- + +Various 2-dimensional coordinate data types. + +.. c:type:: LP + + Geodetic coordinate, latitude and longitude. Usually in radians. + + .. code-block:: C + + typedef struct { double lam, phi; } LP; + + .. c:member:: double LP.lam + + Longitude. Lambda. + + .. c:member:: double LP.phi + + Latitude. Phi. + + +.. c:type:: XY + + 2-dimensional cartesian coordinate. + + .. code-block:: C + + typedef struct { double x, y; } XY; + + + .. c:member:: double XY.lam + + Easting. + + .. c:member:: double XY.phi + + Northing. + + +.. c:type:: UV + + 2-dimensional generic coordinate. Usually used when contents can be either + a :c:type:`XY` or :c:type:`UV`. + + .. code-block:: C + + typedef struct {double u, v; } UV; + + + .. c:member:: double UV.u + + Longitude or easting, depending on use. + + .. c:member:: double UV.v + + Latitude or northing, depending on use. + + +3 dimensional coordinates +-------------------------------------------------------------------------------- + +The following data types are the 3-dimensional equivalents to the data +types above. + +.. c:type:: LPZ + + 3-dimensional version of :c:type:`LP`. Holds longitude, latitude and + vertical component. + + .. code-block:: C + + typedef struct { double lam, phi, z; } LPZ; + + .. c:member:: double LPZ.lam + + Longitude. Lambda. + + .. c:member:: double LPZ.phi + + Latitude. Phi. + + .. c:member:: double LPZ.z + + Vertical component. + + +.. c:type:: XYZ + + Cartesian coordinate in 3 dimensions. Extension of :c:type:`XY`. + + .. code-block:: C + + typedef struct { double x, y, z; } XYZ; + + .. c:member:: double XYZ.x + + Easting. + + .. c:member:: double XYZ.y + + Northing. + + .. c:member:: double XYZ.z + + Vertical component. + + +.. c:type:: UVW + + 3-dimensional extension of :c:type:`UV`. + + .. code-block:: C + + typedef struct {double u, v, w; } UVW; + + .. c:member:: double UVW.u + + Longitude or easting, depending on use. + + .. c:member:: double UVW.v + + Latitude or northing, depending on use. + + .. c:member:: double UVW.w + + Vertical component. + + +Spatiotemporal coordinate types +-------------------------------------------------------------------------------- + +The following data types are extensions of the triplets above into the time +domain. + + +.. c:type:: PJ_LPZT + + Spatiotemporal version of :c:type:`LPZ`. + + .. code-block:: C + + typedef struct { + double lam; + double phi; + double z; + double t; + } PJ_LPZT; + + + .. c:member:: double PJ_LPZT.lam + + Longitude. + + .. c:member:: double PJ_LPZT.phi + + Latitude + + .. c:member:: double PJ_LPZT.z + + Vertical component. + + .. c:member:: double PJ_LPZT.t + + Time component. + +.. c:type:: PJ_XYZT + + Generic spatiotemporal coordinate. Usefull for e.g. cartesian coordinates with + an attached time-stamp. + + .. code-block:: C + + typedef struct { + double x; + double y; + double z; + double t; + } PJ_XYZT; + + + .. c:member:: double PJ_XYZT.x + + Easting. + + .. c:member:: double PJ_XYZT.y + + Northing. + + .. c:member:: double PJ_XYZT.z + + Vertical component. + + .. c:member:: double PJ_XYZT.t + + Time component. + + +.. c:type:: PJ_UVWT + + Spatiotemporal version of :c:type:`PJ_UVW`. + + .. code-block:: C + + typedef struct { double u, v, w, t; } PJ_UVWT; + + .. c:member:: double PJ_UVWT.e + + First horizontal component. + + .. c:member:: double PJ_UVWT.n + + Second horizontal component. + + .. c:member:: double PJ_UVWT.w + + Vertical component. + + .. c:member:: double PJ_UVWT.t + + Temporal component. + + +Ancillary types for geodetic computations +-------------------------------------------------------------------------------- + + +.. c:type:: PJ_OPK + + Rotations, for instance three euler angles. + + .. code-block:: C + + typedef struct { double o, p, k; } PJ_OPK; + + .. c:member:: double PJ_OPK.o + + First rotation angle, omega. + + .. c:member:: double PJ_OPK.p + + Second rotation angle, phi. + + .. c:member:: double PJ_OPK.k + + Third rotation angle, kappa. + + +Complex coordinate types +-------------------------------------------------------------------------------- + + +.. c:type:: PJ_COORD + + General purpose coordinate union type usefull in two, three and four dimensions. + + .. code-block:: C + + typedef union { + double v[4]; + PJ_XYZT xyzt; + PJ_UVWT uvwt; + PJ_LPZT lpzt; + XYZ xyz; + UVW uvw; + LPZ lpz; + XY xy; + UV uv; + LP lp; + } PJ_COORD ; + + .. c:member:: double v[4] + + Generic four-dimensional vector. + + .. c:member:: PJ_XYZT PJ_COORD.xyzt + + Spatiotemporal cartesian coordinate. + + .. c:member:: PJ_UVWT PJ_COORD.uvwt + + Spatiotemporal generic coordinate. + + .. c:member:: PJ_LPZT PJ_COORD.lpzt + + Longitude, latitude, vertical and time components. + + .. c:member:: XYZ PJ_COORD.xyz + + 3-dimensional cartesian coordinate. + + .. c:member:: UVW PJ_COORD.uvw + + 3-dimensional generic coordinate. + + .. c:member:: LPZ PJ_COORD.lpz + + Longitude, latitude and vertical component. + + .. c:member:: XY PJ_COORD.xy + + 2-dimensional cartesian coordinate. + + .. c:member:: UV PJ_COORD.uv + + 2-dimensional generic coordinate. + + .. c:member:: LP PJ_COORD.lp + + Longitude and latitude. + + +Projection derivatives +------------------------------------------------------------------------------- + +.. c:type:: PJ_FACTORS + + Various cartographic properties, such as scale factors, angular distortion + and meridian convergence. Calculated with :c:func:`proj_factors`. Depending + on the underlying projection, values can be calculated either numerically + or analytically. + + .. code-block:: C + + typedef struct { + double meridional_scale; + double parallel_scale; + double areal_scale; + + double angular_distortion; + double meridian_parallel_angle; + double meridian_convergence; + + double tissot_semimajor; + double tissot_semiminor; + } PJ_FACTORS; + + .. c:member:: double PJ_FACTORS.meridional_scale + + Meridional scale at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.parallel_scale + + Parallel scale at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.areal_scale + + Areal scale factor at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.angular_distortion + + Angular distortion at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.meridian_parallel_angle + + Meridian/parallel angle, :math:`\theta^\prime`, at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.meridian_convergence + + Meridian convergence at coordinate :math:`\left(\lambda,\phi\right)`. + Sometimes also described as *grid declination*. + + .. c:member:: double PJ_FACTORS.tissot_semimajor + + Maximum scale error. + + .. c:member:: double PJ_FACTORS.tissot_semiminor + + Minimum scale error. + + +List structures +------------------------------------------------------------------------------- + +.. c:type:: PJ_OPERATIONS + + Description a PROJ.4 operation + + .. code-block:: C + + struct PJ_OPERATIONS { + char *id; /* operation keyword */ + PJ *(*proj)(PJ *); /* operation entry point */ + char * const *descr; /* description text */ + }; + + .. c:member:: char *id + + Operation keyword. + + .. c:member:: PJ *(*op)(PJ *) + + Operation entry point. + + .. c:member:: char * const * + + Description of operation. + + +.. c:type:: PJ_ELLPS + + Description of ellipsoids defined in PROJ.4 + + .. code-block:: C + + struct PJ_ELLPS { + char *id; + char *major; + char *ell; + char *name; + }; + + .. c:member:: char *id + + Keyword name of the ellipsoid. + + .. c:member:: char *major + + Semi-major axis of the ellipsoid, or radius in case of a sphere. + + .. c:member:: char *ell + + Elliptical parameter, e.g. `rf=298.257` or `b=6356772.2`. + + .. c:member:: char *name + + Name of the ellipsoid + +.. c:type:: PJ_UNITS + + Distance units defined in PROJ.4. + + .. code-block:: C + + struct PJ_UNITS { + char *id; /* units keyword */ + char *to_meter; /* multiply by value to get meters */ + char *name; /* comments */ + double factor; /* to_meter factor in actual numbers */ + }; + + .. c:member:: char *id + + Keyword for the unit. + + .. c:member:: char *to_meter + + Text representation of the factor that converts a given unit to meters + + .. c:member:: char *name + + Name of the unit. + + .. c:member:: double factor + + Conversion factor that converts the unit to meters. + +.. c:type:: PJ_PRIME_MERIDIANS + + Prime meridians defined in PROJ.4. + + .. code-block:: C + + struct PJ_PRIME_MERIDIANS { + char *id; + char *defn; + }; + + .. c:member:: char *id + + Keyword for the prime meridian + + .. c:member:: char *def + + Offset from Greenwich in DMS format. + +Info structures +------------------------------------------------------------------------------- + +.. c:type:: PJ_INFO + + Struct holding information about the current instance of PROJ.4. Struct is + populated by :c:func:`proj_info`. + + .. code-block:: C + + typedef struct { + char release[64]; + char version[64]; + int major; + int minor; + int patch; + char searchpath[512]; + } PJ_INFO; + + .. c:member:: char PJ_INFO.release[64] + + Release info. Version number and release date, + e.g. "Rel. 4.9.3, 15 August 2016". + + .. c:member:: char PJ_INFO.version[64] + + Text representation of the full version number, + e.g. "4.9.3". + + .. c:member:: int PJ_INFO.major + + Major version number. + + .. c:member:: int PJ_INFO.minor + + Minor version number. + + .. c:member:: int PJ_INFO.patch + + Patch level of release. + + .. c:member:: char PJ_INFO.searchpath[512] + + Search path for PROJ.4. List of directories separated by + semicolons, e.g. "C:\Users\doctorwho;C:\OSGeo4W64\\share\proj". + Grids and init files are looked for in directories in the search path. + +.. c:type:: PJ_PROJ_INFO + + Struct holding information about a :c:type:`PJ` object. Populated by + :c:func:`proj_pj_info`. + + .. code-block:: C + + typedef struct { + char id[16]; + char description[128]; + char definition[512]; + int has_inverse; + double accuracy; + } PJ_PROJ_INFO; + + .. c:member:: char PJ_PROJ_INFO.id[16] + + Short ID of the operation the :c:type:`PJ` object is based on, that is, + what comes afther the ``+proj=`` in a proj-string, e.g. "*merc*". + + .. c:member:: char PJ_PROJ_INFO.description[128] + + Long describes of the operation the :c:type:`PJ` object is based on, + e.g. "*Mercator Cyl, Sph&Ell lat_ts=*". + + .. c:member:: char PJ_PROJ_INFO.definition[512] + + The proj-string that was used to create the :c:type:`PJ` object with, + e.g. "*+proj=merc +lat_0=24 +lon_0=53 +ellps=WGS84*". + + .. c:member:: int PJ_PROJ_INFO.has_inverse + + 1 if an inverse mapping of the defined operation exists, otherwise 0. + + .. c:member:: double PJ_PROJ_INFO.accuracy + + Expected accuracy of the transformation. -1 if unknown. + +.. c:type:: PJ_GRID_INFO + + Struct holding information about a specific grid in the search path of + PROJ.4. Populated with the function :c:func:`proj_grid_info`. + + .. code-block:: C + + typedef struct { + char gridname[32]; + char filename[260]; + char format[8]; + LP lowerleft; + LP upperright; + int n_lon, n_lat; + double cs_lon, cs_lat; + } PJ_GRID_INFO; + + .. c:member:: char PJ_GRID_INFO.gridname[32] + + Name of grid, e.g. "*BETA2007.gsb*". + + .. c:member:: char PJ_GRID_INFO + + Full path of grid file, e.g. *"C:\\OSGeo4W64\\share\\proj\\BETA2007.gsb"* + + .. c:member:: char PJ_GRID_INFO.format[8] + + File format of grid file, e.g. "*ntv2*" + + .. c:member:: LP PJ_GRID_INFO.lowerleft + + Geodetic coordinate of lower left corner of grid. + + .. c:member:: LP PJ_GRID_INFO.upperright + + Geodetic coordinate of upper right corner of grid. + + .. c:member:: int PJ_GRID_INFO.n_lon + + Number of grid cells in the longitudinal direction. + + .. c:member:: int PJ_GRID_INFO.n_lat + + Number of grid cells in the latitudianl direction. + + .. c:member:: double PJ_GRID_INFO.cs_lon + + Cell size in the longitudinal direction. In radians. + + .. c:member:: double PJ_GRID_INFO.cs_lat + + Cell size in the latitudinal direction. In radians. + + +.. c:type:: PJ_INIT_INFO + + Struct holding information about a specific init file in the search path of + PROJ.4. Populated with the function :c:func:`proj_init_info`. + + .. code-block:: C + + typedef struct { + char name[32]; + char filename[260]; + char version[32]; + char origin[32]; + char lastupdate[16]; + } PJ_INIT_INFO; + + .. c:member:: char PJ_INIT_INFO.name[32] + + Name of init file, e.g. "*epsg*". + + .. c:member:: char PJ_INIT_INFO.filename[260] + + Full path of init file, e.g. "*C:\\OSGeo4W64\\share\\proj\\epsg*" + + .. c:member:: char PJ_INIT_INFO.version[32] + + Version number of init-file, e.g. "*9.0.0*" + + .. c:member:: char PJ_INIT_INFO.origin[32] + + Originating entity of the init file, e.g. "*EPSG*" + + .. c:member:: char PJ_INIT_INFO.lastupdate + + Date of last update of the init-file. diff --git a/docs/source/development/api.rst b/docs/source/development/reference/deprecated.rst similarity index 99% rename from docs/source/development/api.rst rename to docs/source/development/reference/deprecated.rst index 5b915edf30..c748d461f6 100644 --- a/docs/source/development/api.rst +++ b/docs/source/development/reference/deprecated.rst @@ -1,7 +1,7 @@ .. _api: ******************************************************************************** -API +Deprecated API ******************************************************************************** .. contents:: Contents @@ -143,7 +143,7 @@ definition into a projPJ object suitable for use with other API functions. On failure the function will return NULL and set pj_errno. The definition should be of the general form ``+proj=tmerc +lon_0 +datum=WGS84``. Refer to PROJ.4 documentation and -the :ref:`parameters` notes for additional detail. +the :ref:`transformation` notes for additional detail. Coordinate system objects allocated with ``pj_init_plus()`` should be deallocated with ``pj_free()``. diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst new file mode 100644 index 0000000000..ea1289541c --- /dev/null +++ b/docs/source/development/reference/functions.rst @@ -0,0 +1,566 @@ +.. _functions: + +================================================================================ +Functions +================================================================================ + +Threading contexts +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_CONTEXT* proj_context_create(void) + + Create a new threading-context. + + :returns: :c:type:`PJ_CONTEXT*` + +.. c:function:: void proj_context_destroy(PJ_CONTEXT *ctx) + + Deallacote a threading-context. + + :param PJ_CONTEXT* ctx: Threading context. + +Transformation setup +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ* proj_create(PJ_CONTEXT *ctx, const char *definition) + + Create a transformation object from a proj-string. + + Example call: + + .. code-block:: C + + PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel"); + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context. + :param `definition`: Proj-string of the desired transformation. + :type `definition`: const char* + + +.. c:function:: PJ* proj_create_argv(PJ_CONTEXT *ctx, int argc, char **argv) + + Create transformation object with argc/argv-style initialization. For this + application each parameter in the defining proj-string is an entry in :c:data:`argv`. + + Example call: + + .. code-block:: C + + char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"}; + PJ* P = proj_create_argv(0, 3, args); + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context + :param int argc: Count of arguments in :c:data:`argv` + :param char** argv: Vector of strings with proj-string parameters, e.g. ``+proj=merc`` + :returns: :c:type:`PJ*` + +.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to, PJ_AREA *area) + + Create a transformation object that is a pipeline between two known + coordinate reference systems. + + :c:data:`srid_from` and :c:data:`srid_to` should be the value part of a ``+init=...`` parameter + set, i.e. "epsg:25833" or "IGNF:AMST63". Any projection definition that + can be found in a init-file in :envvar:`PROJ_LIB` is a valid input to this function. + + For now the function mimics the cs2cs app: An input and an output CRS is + given and coordinates are transformed via a hub datum (WGS84). This + transformation strategy is referred to as "early-binding" by the EPSG. The + function can be extended to support "late-binding" transformations in the + future without affecting users of the function. When the function is extended + to the late-binding approach the :c:data:`area` argument will be used. For + now it is just a place-holder for a future improved implementation. + + Example call: + + .. code-block:: C + + PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833", 0); + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context. + :param `srid_from`: Source SRID. + :type `srid_from`: const char* + :param `srid_to`: Destination SRID. + :type `srid_to`: const char* + :param `area`: Descriptor of the desired area for the transformation. + :type `area`: PJ_AREA + :returns: :c:type:`PJ*` + +.. c:function:: PJ* proj_destroy(PJ *P) + + Deallocate a :c:type:`PJ` transformation object. + + :param PJ* P: + :returns: :c:type:`PJ*` + +.. _coord_trans_functions: + +Coordinate transformation +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +.. c:function:: PJ_COORD proj_trans(PJ *P, PJ_DIRECTION direction, PJ_COORD coord) + + Transform a single :c:type:`PJ_COORD` coordinate. + + :param PJ* P: + :param `direction`: Transformation direction. + :type `direction`: PJ_DIRECTION + :param PJ_COORD coord: Coordinate that will be transformed. + :returns: :c:type:`PJ_COORD` + + +.. c:function:: size_t proj_trans_generic(PJ *P, PJ_DIRECTION direction, \ + double *x, size_t sx, size_t nx, double *y, \ + size_t sy, size_t ny, double *z, size_t sz, size_t nz, \ + double *t, size_t st, size_t nt) + + Transform a series of coordinates, where the individual coordinate dimension + may be represented by an array that is either + + 1. fully populated + 2. a null pointer and/or a length of zero, which will be treated as a + fully populated array of zeroes + 3. of length one, i.e. a constant, which will be treated as a fully + populated array of that constant value + + 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 + specific data structures, without necessarily understanding the data structure + format, as in: + + .. code-block:: C + + typedef struct { + double x, y; + int quality_level; + char surveyor_name[134]; + } XYQS; + + XYQS survey[345]; + double height = 23.45; + size_t stride = sizeof (XYQS); + + ... + + proj_trans_generic ( + P, PJ_INV, sizeof(XYQS), + &(survey[0].x), stride, 345, /* We have 345 eastings */ + &(survey[0].y), stride, 345, /* ...and 345 northings. */ + &height, 1, /* The height is the constant 23.45 m */ + 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. + + In most cases, the stride will be identical for x, y, z, and t, since they will + typically be either individual arrays (stride = sizeof(double)), or strided + views into an array of application specific data structures (stride = sizeof (...)). + + But in order to support cases where :c:data:`x`, :c:data:`y`, :c:data:`z`, + and :c:data:`t` come from heterogeneous sources, individual strides, + :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, are used. + + .. note:: Since :c:func:`proj_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. + + :param PJ* P: Transformation object + :param `direction`: Transformation direction + :type `PJ_DIRECTION`: + :param double* x: Array of x-coordinates + :param double* y: Array of y-coordinates + :param double* z: Array of z-coordinates + :param double* t: Array of t-coordinates + :param size_t sx: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nx: Number of elements in the corresponding array + :param size_t sy: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nv: Number of elements in the corresponding array + :param size_t sz: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nz: Number of elements in the corresponding array + :param size_t st: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nt: Number of elements in the corresponding array + :returns: Number of transformations succesfully completed + + + +.. c:function:: size_t proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) + + Batch transform an array of :c:type:`PJ_COORD`. + + :param PJ* P: + :param `direction`: Transformation direction + :type `direction`: PJ_DIRECTION + :param size_t n: Number of cordinates in :c:data:`coord` + :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number + + +Initializers +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t) + + Initializer for the :c:type:`PJ_COORD` union. The function is + shorthand for the otherwise convoluted assignment. + Equivalent to + + .. code-block:: C + + PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}}; + + or + + .. code-block:: C + + PJ_COORD c; + // Assign using the PJ_XYZT struct in the union + c.xyzt.x = 10.0; + c.xyzt.y = 20.0; + c.xyzt.z = 30.0; + c.xyzt.t = 40.0; + + Since :c:type:`PJ_COORD` is a union of structs, the above assignment can + also be expressed in terms of the other types in the union, e.g. + :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`. + + + :param double x: 1st component in a :c:type:`PJ_COORD` + :param double y: 2nd component in a :c:type:`PJ_COORD` + :param double z: 3rd component in a :c:type:`PJ_COORD` + :param double t: 4th component in a :c:type:`PJ_COORD` + :returns: :c:type:`PJ_COORD` + +.. c:function:: PJ_OBS proj_obs(double x, double y, double z, double t,\ + double o, double p, double k,\ + int id, unsigned int flags) + + Initializer for the :c:type:`PJ_OBS` union. The function is + shorthand for the otherwise convoluted assignment. + Equivalent to + + .. code-block:: C + + PJ_OBS c = {{{1.0, 2.0, 3.0, 4.0}}, {{5.0, 6.0, 7.0}}, 8, 9}; + + or + + .. code-block:: C + + PJ_OBS c; + // Assign using the PJ_COORD part of the struct in the union + o.coo.v[0] = 1.0; + o.coo.v[1] = 2.0; + o.coo.v[2] = 3.0; + o.coo.v[3] = 4.0; + o.anc.v[0] = 5.0; + o.anc.v[1] = 6.0; + o.anc.v[2] = 7.0; + o.id = 8; + o.flags = 9; + + which is a bit too verbose in most practical applications. + + :param double x: 1st component in a :c:type:`PJ_COORD` + :param double y: 2nd component in a :c:type:`PJ_COORD` + :param double z: 3rd component in a :c:type:`PJ_COORD` + :param double t: 4th component in a :c:type:`PJ_COORD` + :param double o: 1st component in a :c:type:`PJ_TRIPLET` + :param double p: 2nd component in a :c:type:`PJ_TRIPLET` + :param double k: 3rd component in a :c:type:`PJ_TRIPLET` + :param int id: Ancillary data, e.g. an ID + :param `flags`: Flags + :type `flags`: unsigned int + :returns: :c:type:`PJ_OBS` + +Error reporting +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: int proj_errno(PJ *P) + + Get a reading of the current error-state of :c:data:`P`. An non-zero error + codes indicates an error either with the transformation setup or during a + transformation. + + :param: PJ* P: Transformation object. + + :returns: :c:type:`int` + +.. c:function:: void proj_errno_set(PJ *P, int err) + +Change the error-state of :c:data:`P` to `err`. + + :param PJ* P: Transformation object. + :param int err: Error number. + +.. c:function:: int proj_errno_reset(PJ *P) + + Clears the error number in :c:data:`P`, and bubbles it up to the context. + + Example: + + .. code-block:: C + + void foo (PJ *P) { + int last_errno = proj_errno_reset (P); + + do_something_with_P (P); + + /* failure - keep latest error status */ + if (proj_errno(P)) + return; + /* success - restore previous error status */ + proj_errno_restore (P, last_errno); + return; + } + + :param: PJ* P: Transformation object. + + :returns: :c:type:`int` Returns the previous value of the errno, for convenient reset/restore operations. + +.. c:function:: void proj_errno_restore(PJ *P, int err) + + Reduce some mental impedance in the canonical reset/restore use case: + Basically, :c:func:`proj_errno_restore()` is a synonym for + :c:func:`proj_errno_set()`, but the use cases are very different: + *set* indicate an error to higher level user code, *restore* passes previously + set error indicators in case of no errors at this level. + + Hence, although the inner working is identical, we provide both options, + to avoid some rather confusing real world code. + + See usage example under :c:func:`proj_errno_reset` + + :param PJ* P: Transformation object. + :param int err: Error code. + + + +Info functions +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_INFO proj_info(void) + + Get information about the current instance of the PROJ.4 library. + + :returns: :c:type:`PJ_INFO` + +.. c:function:: PJ_PROJ_INFO proj_pj_info(const PJ *P) + + Get information about a specific transformation object, :c:data:`P`. + + :param `P`: Transformation object + :type `P`: const PJ* + :returns: :c:type:`PJ_PROJ_INFO` + +.. c:function:: PJ_GRID_INFO proj_grid_info(const char *gridname) + + Get information about a specific grid. + + :param `gridname`: Gridname in the PROJ.4 searchpath + :type `gridname`: const char* + :returns: :c:type:`PJ_GRID_INFO` + +.. c:function:: PJ_INIT_INFO proj_init_info(const char *initname) + + Get information about a specific init file. + + :param `initname`: Init file in the PROJ.4 searchpath + :type `initname`: const char* + :returns: :c:type:`PJ_INIT_INFO` + +Lists +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: const PJ_OPERATIONS* proj_list_operations(void) + + Get a pointer to an array of all operations in PROJ.4. The last entry + of the returned array is a NULL-entry. The array is statically allocated + and does not need to be freed after use. + + Print a list of all operations in PROJ.4: + + .. code-block:: C + + PJ_OPERATIONS *ops; + for (ops = proj_list_operations(); ops->id; ++ops) + printf("%s\n", ops->id); + + + :returns: :c:type:`PJ_OPERATIONS*` + +.. c:function:: const PJ_ELLPS* proj_list_ellps(void) + + Get a pointer to an array of ellipsoids defined in PROJ.4. The last entry + of the returned array is a NULL-entry. The array is statically allocated + and does not need to be freed after use. + + :returns: :c:type:`PJ_ELLPS*` + +.. c:function:: const PJ_UNITS* proj_list_units(void) + + Get a pointer to an array of distance units defined in PROJ.4. The last + entry of the returned array is a NULL-entry. The array is statically + allocated and does not need to be freed after use. + + :returns: :c:type:`PJ_UNITS*` + +.. c:function:: const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void) + + Get a pointer to an array of prime meridians defined in PROJ.4. The last + entry of the returned array is a NULL-entry. The array is statically + allocated and does not need to be freed after use. + + :returns: :c:type:`PJ_PRIME_MERIDIANS*` + +Distances +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: double proj_lp_dist(const PJ *P, LP a, LP b) + + Calculate geodesic distance between two points in geodetic coordinates. + + :param PJ* P: Transformation object + :param LP a: Coordinate of first point + :param LP b: Coordinate of second point + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_lp_dist(const PJ *P, LPZ a, LPZ b) + + Calculate geodesic distance between two points in geodetic coordinates. + + :param PJ* P: Transformation object + :param LPZ a: Coordinate of first point + :param LPZ b: Coordinate of second point + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xy_dist(XY a, XY, b) + + Calculate 2-dimensional euclidean between two projected coordinates. + + :param XY a: First coordinate + :param XY b: Second coordinate + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xyz_dist(XYZ a, XYZ b) + + Calculate 3-dimensional euclidean between two projected coordinates. + + :param XYZ a: First coordinate + :param XYZ b: Second coordinate + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + + +Various +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coo) + + Measure internal consistency of a given transformation. The function + performs :c:data:`n` round trip transformations starting in either + the forward or reverse :c:data:`direction`. Returns the euclidean + distance of the starting point :c:data:`coo` and the resulting + coordinate after :c:data:`n` iterations back and forth. + + :param PJ* P: + :type `P`: const PJ* + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :param int n: Number of roundtrip transformations + :param PJ_OBS obs: Input coordinate + :returns: :c:type:`double` Distance between original coordinate and the \ + resulting coordinate after :c:data:`n` transformation iterations. + +.. c:function:: PJ_FACTORS proj_factors(PJ *P, LP lp) + + Calculate various cartographic properties, such as scale factors, angular + distortion and meridian convergence. Depending on the underlying projection + values will be calculated either numerically (default) or analytically. + + The function also calculates the partial derivatives of the given + coordinate. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `lp`: Geodetic coordinate + :type `lp`: const LP + :returns: :c:type:`PJ_FACTORS` + +.. c:function:: double proj_torad(double angle_in_degrees) + + Convert degrees to radians. + + :param double angle_in_degrees: Degrees + :returns: :c:type:`double` Radians + +.. c:function:: double proj_todeg(double angle_in_radians) + + Convert radians to degrees + + :param double angle_in_radians: Radians + :returns: :c:type:`double` Degrees + +.. c:function:: double proj_dmstor(const char *is, char **rs) + + Convert string of degrees, minutes and seconds to radians. + Works similarly to the C standard library function :c:func:`strtod`. + + :param `is`: Value to be converted to radians + :type `is`: const char* + :param `rs`: Reference to an already allocated char*, whose value is \ + set by the function to the next character in :c:data:`is` \ + after the numerical value. + +.. c:function:: char *proj_rtodms(char *s, double r, int pos, int neg) + + Convert radians to string representation of degrees, minutes and seconds. + + :param char* s: Buffer that holds the output string + :param double r: Value to convert to dms-representation + :param int pos: Character denoting positive direction, typically `'N'` or `'E'`. + :param int neg: Character denoting negative direction, typically `'S'` or `'W'`. + :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`) + + +.. c:function:: PJ_COORD proj_geoc_lat(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) + + Convert geographical to geocentric latitude. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :param `coo`: Coordinate + :type `coo`: PJ_COORD + :returns: :c:type:`PJ_COORD` Converted coordinate + + +.. c:function:: int proj_angular_input (PJ *P, enum PJ_DIRECTION dir) + + Check if a operation expects angular input. + + :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 + +.. c:function:: int proj_angular_output (PJ *P, enum PJ_DIRECTION dir) + + Check if an operation returns angular output. + + :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 + diff --git a/docs/source/development/reference/index.rst b/docs/source/development/reference/index.rst new file mode 100644 index 0000000000..9e92384cfe --- /dev/null +++ b/docs/source/development/reference/index.rst @@ -0,0 +1,12 @@ +.. _reference: + +================================================================================ +Reference +================================================================================ + +.. toctree:: + :maxdepth: 1 + + datatypes + functions + deprecated diff --git a/docs/source/development/threads.rst b/docs/source/development/threads.rst index 3307240808..a557fa07f6 100644 --- a/docs/source/development/threads.rst +++ b/docs/source/development/threads.rst @@ -4,11 +4,6 @@ Threads ================================================================================ -.. contents:: Contents - :depth: 3 - :backlinks: none - - This page is about efforts to make PROJ.4 thread safe. Key Thread Safety Issues diff --git a/docs/source/development/transformations.rst b/docs/source/development/transformations.rst new file mode 100644 index 0000000000..b03ce36876 --- /dev/null +++ b/docs/source/development/transformations.rst @@ -0,0 +1,7 @@ +.. _dev_transformations: + +================================================================================ +Transformations +================================================================================ + + diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 14ceda8501..8afdb35d88 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -212,7 +212,7 @@ 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.4 string will be preserved +is helpful to include the +wktext so the exact PROJ.4 string will be preserved in the WKT representation (otherwise key parameters like `+nadgrids=@null` will be dropped): @@ -302,7 +302,7 @@ Output of above command: 0 0.7853981633974483 0.00 41.94 -What options does proj.4 allow for the shape of the Earth (geodesy)? +What options does PROJ.4 allow for the shape of the Earth (geodesy)? -------------------------------------------------------------------------------- See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c @@ -315,7 +315,7 @@ What if I want a spherical Earth? Use ``+ellps=sphere``. See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c for the radius used in this case. -How do I change the radius of the Earth? How do I use proj.4 for work on Mars? +How do I change the radius of the Earth? How do I use PROJ.4 for work on Mars? -------------------------------------------------------------------------------- You can supply explicit values for the semi minor and semi major axes instead diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index 3495d8148a..21dd0f3475 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -1,4 +1,4 @@ -.. _glossary:: +.. _glossary: ================================================================================ Glossary diff --git a/docs/source/grids.rst b/docs/source/grids.rst index 99bcfdc106..7f362a9245 100644 --- a/docs/source/grids.rst +++ b/docs/source/grids.rst @@ -86,6 +86,8 @@ Hungary `Hungarian grid `__ ETRS89 - HD72/EOV (epsg:23700), both horizontal and elevation grids +.. _nonfreegrids: + Non-Free Grids -------------------------------------------------------------------------------- @@ -166,6 +168,3 @@ Netherlands ................................................................................ `Dutch grid `__ (Registration required before download) - - - diff --git a/docs/source/index.rst b/docs/source/index.rst index b6f15cae2f..324d52fc2a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,13 +1,13 @@ .. _home: ****************************************************************************** -proj.4 +PROJ.4 ****************************************************************************** -proj.4 is a standard UNIX filter function which converts geographic longitude +PROJ.4 is a standard UNIX filter function which converts geographic longitude and latitude coordinates into cartesian coordinates (and vice versa), and it is a C API for software developers to include coordinate transformation in their -own software. proj.4 is maintained on `GitHub `_. +own software. PROJ.4 is maintained on `GitHub `_. ============= ================================================================ @@ -34,15 +34,14 @@ Documentation .. toctree:: :maxdepth: 1 - download - faq - apps/index - projections/index - parameters + usage/index geodesic grids htpd development/index + faq + contributing + download glossary license references @@ -50,7 +49,7 @@ Documentation Mailing List ================================================================================ -The Proj.4 mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj +The PROJ.4 mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj Indices and tables ================== diff --git a/docs/source/parameters.rst b/docs/source/parameters.rst deleted file mode 100644 index e4623b9a27..0000000000 --- a/docs/source/parameters.rst +++ /dev/null @@ -1,459 +0,0 @@ -.. _parameters: - -================================================================================ -Parameters -================================================================================ - -:Date: 01/28/2016 - -.. contents:: Contents - :depth: 3 - :backlinks: none - - -This document attempts to describe a variety of the PROJ.4 parameters which can -be applied to all, or many coordinate system definitions. This document does -not attempt to describe the parameters particular to particular projection -types. Some of these can be found in the GeoTIFF `Projections Transform List -`__. The definitive -documentation for most parameters is Gerald's original documentation available -from the main PROJ.4 page. - -Parameter list --------------------------------------------------------------------------------- - -Common parameters: - -(this PROJ.4 distribution including `cs2cs` and datum support) - -:: - - +a Semimajor radius of the ellipsoid axis - +alpha ? Used with Oblique Mercator and possibly a few others - +axis Axis orientation (new in 4.8.0) - +b Semiminor radius of the ellipsoid axis - +datum Datum name (see `proj -ld`) - +ellps Ellipsoid name (see `proj -le`) - +k Scaling factor (old name) - +k_0 Scaling factor (new name) - +lat_0 Latitude of origin - +lat_1 Latitude of first standard parallel - +lat_2 Latitude of second standard parallel - +lat_ts Latitude of true scale - +lon_0 Central meridian - +lonc ? Longitude used with Oblique Mercator and possibly a few others - +lon_wrap Center longitude to use for wrapping (see below) - +nadgrids Filename of NTv2 grid file to use for datum transforms (see below) - +no_defs Don't use the /usr/share/proj/proj_def.dat defaults file - +over Allow longitude output outside -180 to 180 range, disables wrapping (see below) - +pm Alternate prime meridian (typically a city name, see below) - +proj Projection name (see `proj -l`) - +south Denotes southern hemisphere UTM zone - +to_meter Multiplier to convert map units to 1.0m - +towgs84 3 or 7 term datum transform parameters (see below) - +units meters, US survey feet, etc. - +vto_meter vertical conversion to meters. - +vunits vertical units. - +x_0 False easting - +y_0 False northing - +zone UTM zone - -Extended list provided by Gerald Evenden "grepped out of the RCS directory". - -(libproj4 by G.E.; no datum support) - -:: - - +a Semimajor radius of the ellipsoid axis - +alpha ? Used with Oblique Mercator and possibly a few others - +azi - +b Semiminor radius of the ellipsoid axis - +belgium - +beta - +czech - +e Eccentricity of the ellipsoid = sqrt(1 - b^2/a^2) = sqrt( f*(2-f) ) - +ellps Ellipsoid name (see `proj -le`) - +es Eccentricity of the ellipsoid squared - +f Flattening of the ellipsoid = 1-sqrt(1-e^2) (often presented as an inverse, e.g. 1/298) - +geoc - +guam - +h - +k Scaling factor (old name) - +K - +k_0 Scaling factor (new name) - +lat_0 Latitude of origin - +lat_1 Latitude of first standard parallel - +lat_2 Latitude of second standard parallel - +lat_b - +lat_t - +lat_ts Latitude of true scale - +lon_0 Central meridian - +lon_1 - +lon_2 - +lonc ? Longitude used with Oblique Mercator and possibly a few others - +lsat - +m - +M - +n - +no_cut - +no_off No offset. If present, do not offset origin to center of projection. Only used in Oblique Mercator projection. - +no_uoff Backwards compatible version of +no_off. - +no_rot - +ns - +o_alpha - +o_lat_1 - +o_lat_2 - +o_lat_c - +o_lat_p - +o_lon_1 - +o_lon_2 - +o_lon_c - +o_lon_p - +o_proj - +over - +p - +path - +proj Projection name (see `proj -l`) - +q - +R - +R_a - +R_A Compute radius such that the area of the sphere is the same as the area of the ellipsoid - +rf Reciprocal of the ellipsoid flattening term (e.g. 298) - +R_g - +R_h - +R_lat_a - +R_lat_g - +rot - +R_V - +s - +south Denotes southern hemisphere UTM zone - +sym - +t - +theta - +tilt - +to_meter Multiplier to convert map units to 1.0m - +units meters, US survey feet, etc. - +vopt - +W - +westo - +x_0 False easting - +y_0 False northing - +zone UTM zone - -See GE's `libproj4 -manual `__ for -further details (`copy in wayback machine `__). - -Further details for projection at http://www.remotesensing.org/geotiff/proj_list/ - -Units --------------------------------------------------------------------------------- - -Horizontal units can be specified using the +units= keyword with a symbolic -name for a unit (ie. us-ft). Alternatively the translation to meters can be -specified with the +to_meter keyword (ie. 0.304800609601219 for US feet). The -``-lu`` argument to cs2cs or proj can be used to list symbolic unit names. -The default unit for projected coordinates is the meter. -A few special projections deviate from this behaviour, most notably the -latlong pseudo-projection that returns degrees. - - -Vertical Units --------------------------------------------------------------------------------- - -Vertical (Z) units can be specified using the ``+vunits=`` keyword with a -symbolic name for a unit (ie. ``us-ft``). Alternatively the translation to -meters can be specified with the ``+vto_meter`` keyword (ie. 0.304800609601219 -for US feet). The ``-lu`` argument to cs2cs or proj can be used to list symbolic -unit names. If no vertical units are specified, the vertical units will -default to be the same as the horizontal coordinates. - -Note that vertical unit transformations are only supported in pj_transform() -and programs built on that such as cs2cs. The low level projections functions -pj_fwd() and pj_inv() and programs using them directly such as proj do not -handle vertical units at all. - -False Easting/Northing --------------------------------------------------------------------------------- - -Virtually all coordinate systems allow for the presence of a false easting -(``+x_0``) and northing (``+y_0``). Note that these values are always expressed in -meters even if the coordinate system is some other units. Some coordinate -systems (such as UTM) have implicit false easting and northing values. - -lon_wrap, over - Longitude Wrapping --------------------------------------------------------------------------------- - -By default PROJ.4 wraps output longitudes in the range -180 to 180. The +over -switch can be used to disable the default wrapping which is done at a low level -- in ``pj_inv()``. This is particularly useful with projections like eqc where -it would desirable for X values past -20000000 (roughly) to continue past --180 instead of wrapping to +180. - -The ``+lon_wrap`` option can be used to provide an alternative means of doing -longitude wrapping within ``pj_transform()``. The argument to this option is a -center longitude. So ``+lon_wrap=180`` means wrap longitudes in the range 0 to -360. Note that ``+over`` does **not** disable ``+lon_wrap``. - -pm - Prime Meridian --------------------------------------------------------------------------------- - -A prime meridian may be declared indicating the offset between the prime -meridian of the declared coordinate system and that of greenwich. A prime -meridian is clared using the "pm" parameter, and may be assigned a symbolic -name, or the longitude of the alternative prime meridian relative to greenwich. - -Currently prime meridian declarations are only utilized by the -``pj_transform()`` API call, not the ``pj_inv()`` and ``pj_fwd()`` calls. -Consequently the user utility ``cs2cs`` does honour prime meridians but the -proj user utility ignores them. - -The following predeclared prime meridian names are supported. These can be -listed using the cs2cs argument -lm. - -:: - - greenwich 0dE - lisbon 9d07'54.862"W - paris 2d20'14.025"E - bogota 74d04'51.3"E - madrid 3d41'16.48"W - rome 12d27'8.4"E - bern 7d26'22.5"E - jakarta 106d48'27.79"E - ferro 17d40'W - brussels 4d22'4.71"E - stockholm 18d3'29.8"E - athens 23d42'58.815"E - oslo 10d43'22.5"E - -Example of use. The location ``long=0``, ``lat=0`` in the greenwich based lat/long -coordinates is translated to lat/long coordinates with Madrid as the prime -meridian. - -:: - - cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid - 0 0 (input) - 3d41'16.48"E 0dN 0.000 (output) - -towgs84 - Datum transformation to WGS84 --------------------------------------------------------------------------------- - -Datum shifts can be approximated by 3 parameter spatial translations (in -geocentric space), or 7 parameter shifts (translation + rotation + scaling). -The parameters to describe this can be described using the towgs84 parameter. - -In the three parameter case, the three arguments are the translations to the -geocentric location in meters. - -For instance, the following demonstrates converting from the Greek GGRS87 datum -to WGS84. - -:: - - cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62 - +to +proj=latlong +datum=WGS84 - 20 35 - 20d0'5.467"E 35d0'9.575"N 8.570 - -The EPSG database provides this example for transforming from WGS72 to WGS84 -using an approximated 7 parameter transformation. - -:: - - cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \ - +to +proj=latlong +datum=WGS84 - 4 55 - 4d0'0.554"E 55d0'0.09"N 3.223 - -The seven parameter case uses ``delta_x``, ``delta_y``, ``delta_z``, ``Rx - -rotation X``, ``Ry - rotation Y``, ``Rz - rotation Z``, ``M_BF - Scaling``. -The three translation parameters are in meters as in the three parameter case. -The rotational parameters are in seconds of arc. The scaling is apparently the -scale change in parts per million. - -A more complete discussion of the 3 and 7 parameter transformations can be -found in the EPSG database (trf_method's 9603 and 9606). Within PROJ.4 the -following calculations are used to apply the ``towgs84`` transformation (going -to WGS84). The x, y and z coordinates are in geocentric coordinates. - -Three parameter transformation (simple offsets): - -:: - - x[io] = x[io] + defn->datum_params[0]; - y[io] = y[io] + defn->datum_params[1]; - z[io] = z[io] + defn->datum_params[2]; - -Seven parameter transformation (translation, rotation and scaling): - -:: - - #define Dx_BF (defn->datum_params[0]) - #define Dy_BF (defn->datum_params[1]) - #define Dz_BF (defn->datum_params[2]) - #define Rx_BF (defn->datum_params[3]) - #define Ry_BF (defn->datum_params[4]) - #define Rz_BF (defn->datum_params[5]) - #define M_BF (defn->datum_params[6]) - - x_out = M_BF*( x[io] - Rz_BF*y[io] + Ry_BF*z[io]) + Dx_BF; - y_out = M_BF*( Rz_BF*x[io] + y[io] - Rx_BF*z[io]) + Dy_BF; - z_out = M_BF*(-Ry_BF*x[io] + Rx_BF*y[io] + z[io]) + Dz_BF; - -Note that EPSG method 9607 (coordinate frame rotation) coefficients can be -converted to EPSG method 9606 (position vector 7-parameter) supported by PROJ.4 -by reversing the sign of the rotation vectors. The methods are otherwise the -same. - -nadgrids - Grid Based Datum Adjustments --------------------------------------------------------------------------------- - -In many places (notably North America and Austrialia) national geodetic -organizations provide grid shift files for converting between different datums, -such as NAD27 to NAD83. These grid shift files include a shift to be applied -at each grid location. Actually grid shifts are normally computed based on an -interpolation between the containing four grid points. - -PROJ.4 currently supports use of grid shift files for shifting between datums -and WGS84 under some circumstances. The grid shift table formats are ctable -(the binary format produced by the PROJ.4 ``nad2bin`` program), NTv1 (the old -Canadian format), and NTv2 (``.gsb`` - the new Canadian and Australian format). - -Use of grid shifts is specified using the ``nadgrids`` keyword in a coordinate -system definition. For example: - - -:: - - % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 50 - EOF - 111d0'2.952"W 50d0'0.111"N 0.000 - -In this case the ``/usr/local/share/proj/ntv1_can.dat`` grid shift file was -loaded, and used to get a grid shift value for the selected point. - -It is possible to list multiple grid shift files, in which case each will be -tried in turn till one is found that contains the point being transformed. - -:: - - cs2cs +proj=latlong +ellps=clrk66 \ - +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 44 - EOF - 111d0'2.788"W 43d59'59.725"N 0.000 - -Skipping Missing Grids -................................................................................ - -The special prefix ``@`` may be prefixed to a grid to make it optional. If it -not found, the search will continue to the next grid. Normally any grid not -found will cause an error. For instance, the following would use the -``ntv2_0.gsb`` file if available (see [[NonFreeGrids]]), otherwise it would -fallback to using the ``ntv1_can.dat`` file. - -:: - - cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 50 - EOF - 111d0'3.006"W 50d0'0.103"N 0.000 - -The null Grid -................................................................................ - -A special ``null`` grid shift file is shift with releases after 4.4.6 (not -inclusive). This file provides a zero shift for the whole world. It may be -listed at the end of a nadgrids file list if you want a zero shift to be -applied to points outside the valid region of all the other grids. Normally if -no grid is found that contains the point to be transformed an error will occur. - -:: - - cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 45 - EOF - 111d0'3.006"W 50d0'0.103"N 0.000 - - cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 44 - -111 55 - EOF - 111d0'2.788"W 43d59'59.725"N 0.000 - 111dW 55dN 0.000 - -Downloading and Installing Grids -................................................................................ - -The source distribution of PROJ.4 contains only the ntv1_can.dat file. To get -the set of US grid shift files it is necessary to download an additional -distribution of files from the PROJ.4 site, such as -ftp://ftp.remotesensing.org/pub/proj/proj-nad27-1.1.tar.gz. Overlay it on the -PROJ.4 source distribution, and re-configure, compile and install. The -distributed ASCII .lla files are converted into binary (platform specific) -files that are installed. On windows using the nmake /f makefile.vc nadshift -command in the proj\src directory to build and install these files. - -It appears we can't redistribute the Canadian NTv2 grid shift file freely, -though it is better than the NTv1 file. However, end users can download it for -free from the `NRCan web site -`__. After downloading -it, just dump it in the data directory with the other installed data files -(usually `/usr/local/share/proj`). See [[NonFreeGrids]] for details. - -Caveats -................................................................................ - -* Where grids overlap (such as conus and ntv1_can.dat for instance) the first - found for a point will be used regardless of whether it is appropriate or - not. So, for instance, ```+nadgrids=ntv1_can.dat```,conus would result in - the Canadian data being used for some areas in the northern United States - even though the conus data is the approved data to use for the area. - Careful selection of files and file order is necessary. In some cases - border spanning datasets may need to be pre-segmented into Canadian and - American points so they can be properly grid shifted -* There are additional grids for shifting between NAD83 and various HPGN - versions of the NAD83 datum. Use of these haven't been tried recently so - you may encounter problems. The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla - are examples of high precision grid shifts. Take care! -* Additional detail on the grid shift being applied can be found by setting - the PROJ_DEBUG environment variable to a value. This will result in output - to stderr on what grid is used to shift points, the bounds of the various - grids loaded and so forth -* PROJ.4 always assumes that grids contain a shift **to** NAD83 (essentially - WGS84). Other types of grids might or might not be usable - -Axis orientation --------------------------------------------------------------------------------- - -Starting in PROJ 4.8.0, the +axis argument can be used to control the axis -orientation of the coordinate system. The default orientation is "easting, -northing, up" but directions can be flipped, or axes flipped using combinations -of the axes in the +axis switch. The values are: - -* "e" - Easting -* "w" - Westing -* "n" - Northing -* "s" - Southing -* "u" - Up -* "d" - Down - -They can be combined in +axis in forms like: - -* ``+axis=enu`` - the default easting, northing, elevation. -* ``+axis=neu`` - northing, easting, up - useful for "lat/long" geographic - coordinates, or south orientated transverse mercator. -* ``+axis=wnu`` - westing, northing, up - some planetary coordinate systems - have "west positive" coordinate systems - -Note that the ``+axis`` argument only applies to coordinate transformations done -through ``pj_transform()`` (so it works with ``cs2cs``, but not with the proj -commandline program). diff --git a/docs/source/projections/aeqd.rst b/docs/source/projections/aeqd.rst deleted file mode 100644 index 949cd8a0c7..0000000000 --- a/docs/source/projections/aeqd.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _aeqd: - -******************************************************************************** -Azimuthal Equidistant -******************************************************************************** - -.. image:: ./images/aeqd.png - :scale: 50% - :alt: Azimuthal Equidistant - diff --git a/docs/source/references.rst b/docs/source/references.rst index e80e8caf1d..ad5f16bf50 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -4,6 +4,11 @@ References ================================================================================ +.. [AltamimiEtAl2002] Altamimi, Z., P. Sillard, and C. Boucher (2002), + ITRF2000: A new release of the International Terrestrial Reference Frame for earth science applications, + J. Geophys. Res., 107(B10), 2214, + `doi:10.1029/2001JB000561 `__. + .. [Bessel1825] F. W. Bessel, 1825, `The calculation of longitude and latitude from geodesic measurements @@ -24,6 +29,10 @@ References `_, Survey Review **30**\ (232), 61–66. +.. [Deakin2004] R.E. Deakin, 2004, + `The Standard and Abridged Molodensky Coordinate Transformation Formulae + `__. + .. [EberHewitt1979] L. E. Eber and R.P. Hewitt, 1979, `Conversion algorithms for the CALCOFI station grid `_, @@ -39,6 +48,11 @@ References (Preliminary Draft) `_. +.. [EversKnudsen2017] K. Evers and T. Knudsen, 2017, + `Transformation pipelines for PROJ.4 + `__, + FIG Working Week 2017 Proceedings. + .. [GeodesicBib] `A geodesic bibliography `_. diff --git a/docs/source/apps/cs2cs.rst b/docs/source/usage/apps/cs2cs.rst similarity index 99% rename from docs/source/apps/cs2cs.rst rename to docs/source/usage/apps/cs2cs.rst index ae8016fe8e..675379ef96 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/usage/apps/cs2cs.rst @@ -5,8 +5,6 @@ cs2cs ================================================================================ -.. Index:: cs2cs - ``cs2cs`` performs transformation between the source and destination cartographic coordinate system on a set of input points. The coordinate system transformation can include translation between projected and geographic coordinates as well as the application of datum shifts. diff --git a/docs/source/apps/geod.rst b/docs/source/usage/apps/geod.rst similarity index 98% rename from docs/source/apps/geod.rst rename to docs/source/usage/apps/geod.rst index 49fa492511..1e0092833c 100644 --- a/docs/source/apps/geod.rst +++ b/docs/source/usage/apps/geod.rst @@ -4,9 +4,6 @@ geod ================================================================================ - -.. Index:: geod - ``geod`` (direct) and ``invgeod`` (inverse) perform geodesic ("Great Circle") computations for determining latitude, longitude and back azimuth of a terminus point given a initial point latitude, @@ -157,7 +154,7 @@ which gives: 45d31'0.003"N 123d40'59.985"W 75d39'13.094" .. note:: - lack of precision in the distance value compromises the + Lack of precision in the distance value compromises the precision of the Portland location. Further reading diff --git a/docs/source/usage/apps/index.rst b/docs/source/usage/apps/index.rst new file mode 100644 index 0000000000..73c5c63c5b --- /dev/null +++ b/docs/source/usage/apps/index.rst @@ -0,0 +1,20 @@ +.. _apps: + +================================================================================ +Applications +================================================================================ + +Bundled with PROJ.4 comes a set of small command line utilities. The +``proj`` program is limited to converting between geographic and projection +coordinates within one datum. The ``cs2cs`` program operates similarly, but +allows translation between any pair of definable coordinate systems, including +support for basic datum translation. The ``geod`` program provides the ability +to do geodesic (great circle) computations. + +.. toctree:: + :maxdepth: 1 + + proj + cs2cs + geod + diff --git a/docs/source/apps/proj.rst b/docs/source/usage/apps/proj.rst similarity index 98% rename from docs/source/apps/proj.rst rename to docs/source/usage/apps/proj.rst index a06df383c3..424a0fef3f 100644 --- a/docs/source/apps/proj.rst +++ b/docs/source/usage/apps/proj.rst @@ -1,4 +1,4 @@ -:. _proj: +.. _proj: ================================================================================ proj @@ -7,7 +7,7 @@ proj .. Index:: proj -Proj and invproj perform respective forward and inverse transformation of cartographic data to +``proj`` and ``invproj`` perform respective forward and inverse transformation of cartographic data to or from cartesian data with a wide range of selectable projection functions. diff --git a/docs/source/usage/environmentvars.rst b/docs/source/usage/environmentvars.rst new file mode 100644 index 0000000000..38cb46de8a --- /dev/null +++ b/docs/source/usage/environmentvars.rst @@ -0,0 +1,43 @@ +.. _environmentvars: + +================================================================================ +Environment variables +================================================================================ + +PROJ.4 can be crontrolled by setting environment variables. Most users will +have a use for the :envvar:`PROJ_LIB`. + +On UNIX systems environment variables can be set for a shell-session with:: + + $ export VAR="some variable" + +or it can be set for just one command line call:: + + $ VAR="some variable" ./cmd + +Environment variables on UNIX are usually removed with the ``unset`` command:: + + $ unset VAR + +On windows systems environment variables can be set in the command line with:: + + > set VAR="some variable" + +```VAR`` will be available for the entire session, unless it is unset. This is +done by setting the variable with no content:: + + > set VAR= + +.. envvar:: PROJ_LIB + + The location of PROJ.4 :doc:`resource files`. + It is only possible to specify a single library in :envvar:`PROJ_LIB`; e.g. it + does not behave like PATH. PROJ.4 is hardcoded to look for resource files + in other locations as well, amongst those are the users home directory, + ``/usr/share/proj`` and the current folder. + +.. envvar:: PROJ_DEBUG + + Set the debug level of PROJ.4. The default debug level is zero, which results + in no debug output when using PROJ.4. A number from 1-3, whit 3 being the most + verbose setting. diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst new file mode 100644 index 0000000000..81ea4b6b8b --- /dev/null +++ b/docs/source/usage/index.rst @@ -0,0 +1,22 @@ +.. _usage: + +================================================================================ +Using PROJ.4 +================================================================================ + +The main purpose of PROJ.4 is to transform coordinates from one coordinate +reference system to another. This can be achieved either with the included +command line applications or the C API that is a part of the software package. + + +.. toctree:: + :maxdepth: 1 + + quickstart + apps/index + projections + transformation + resource_files + environmentvars + operations/index + diff --git a/docs/source/usage/operations/conversions/axisswap.rst b/docs/source/usage/operations/conversions/axisswap.rst new file mode 100644 index 0000000000..ddaad0751a --- /dev/null +++ b/docs/source/usage/operations/conversions/axisswap.rst @@ -0,0 +1,39 @@ +.. _axisswap: + +================================================================================ +Axis swap +================================================================================ + +Change the order and sign of 2,3 or 4 axes. + ++--------------+---------------------------------------------------------------+ +| **Options** | ++--------------+---------------------------------------------------------------+ +| `+order` | Ordered comma-separated list of axis, e.g. `+order=2,1,3,4` | ++--------------+---------------------------------------------------------------+ + + +Each of the possible four axes are numbered with 1-4, such that the first input axis +is 1, the second is 2 and so on. The output ordering is controlled by a list of the +input axes re-ordered to the new mapping. + +Examples +################################################################################ + +Reversing the order of the axes:: + + +proj=axisswap +order=4,3,2,1 + +Swapping the first two axes (x and y):: + + +proj=axisswap +order=2,1,3,4 + +The direction, or sign, of an axis can be changed by adding a minus in +front of the axis-number:: + + +proj=axisswap +order=1,-2,3,4 + +It is only necessary to specify the axes that are affected by the swap +operation:: + + +proj=axisswap +order=2,1 diff --git a/docs/source/usage/operations/conversions/cart.rst b/docs/source/usage/operations/conversions/cart.rst new file mode 100644 index 0000000000..0c3c7c239b --- /dev/null +++ b/docs/source/usage/operations/conversions/cart.rst @@ -0,0 +1,24 @@ +.. _cart: + +================================================================================ +Cartesian to geodetic conversion +================================================================================ + +Convert geodetic coordinates to cartesian coordinates. + ++--------------+--------------------------------------------------------------------+ +| **Options** | ++--------------+--------------------------------------------------------------------+ +| `+ellps` | Ellipsoid of the input coordinates. If used together with the | +| |  ellipsoid parameters below, ``+ellps`` is overwritten. | ++--------------+--------------------------------------------------------------------+ +| `+a` | Semi-major radius of ellipsoid axis. | ++--------------+--------------------------------------------------------------------+ +| `+b` | Semi-minor radius of ellipsoid axis. | ++--------------+--------------------------------------------------------------------+ +| `+es` | Eccentricity of ellipsoid. | ++--------------+--------------------------------------------------------------------+ +| `+f` | Flattening of ellipsoid. | ++--------------+--------------------------------------------------------------------+ + + diff --git a/docs/source/usage/operations/conversions/index.rst b/docs/source/usage/operations/conversions/index.rst new file mode 100644 index 0000000000..54324ec435 --- /dev/null +++ b/docs/source/usage/operations/conversions/index.rst @@ -0,0 +1,18 @@ +.. _conversions_list: + +================================================================================ +Conversions +================================================================================ + +Conversions are coordinate operations in which both coordinate reference systems +are based on the same datum. In PROJ.4 projections are differentiated from +conversions. + +.. toctree:: + :maxdepth: 1 + + axisswap + cart + lonlat + latlon + unitconvert diff --git a/docs/source/projections/latlon.rst b/docs/source/usage/operations/conversions/latlon.rst similarity index 100% rename from docs/source/projections/latlon.rst rename to docs/source/usage/operations/conversions/latlon.rst diff --git a/docs/source/projections/lonlat.rst b/docs/source/usage/operations/conversions/lonlat.rst similarity index 100% rename from docs/source/projections/lonlat.rst rename to docs/source/usage/operations/conversions/lonlat.rst diff --git a/docs/source/usage/operations/conversions/unitconvert.rst b/docs/source/usage/operations/conversions/unitconvert.rst new file mode 100644 index 0000000000..ad8482071b --- /dev/null +++ b/docs/source/usage/operations/conversions/unitconvert.rst @@ -0,0 +1,112 @@ +.. _unitconvert: + +================================================================================ +Unit conversion +================================================================================ + +Convert between various distance and time units. + ++--------------+--------------------------------------------------------------------+ +| **Options** | ++--------------+--------------------------------------------------------------------+ +| `+xy_in` | Input unit of the horizontal components. | ++--------------+--------------------------------------------------------------------+ +| `+xy_out` | Output unit of the horizontal components. | ++--------------+--------------------------------------------------------------------+ +| `+z_in` | Input unit of the vertical component. | ++--------------+--------------------------------------------------------------------+ +| `+z_out` | Output unit of the vertical component. | ++--------------+--------------------------------------------------------------------+ +| `+t_in` | Input unit of the time component. | ++--------------+--------------------------------------------------------------------+ +| `+t_out` | Output unit of the time component. | ++--------------+--------------------------------------------------------------------+ + +There are many examples of coordinate reference systems that are expressed in +other units than the meter. There are also many cases where temporal data +has to be translated to different units. The `unitconvert` operation takes care +of that. + +Many North American systems are defined with coordinates in feet. For example +in Vermont:: + + +proj=pipeline + +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k=0.999964286 +x_0=500000.00001016 +y_0=0 + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +Often when working with GNNS data the timestamps are presented in GPS-weeks, +but when the data transformed with the `helmert` operation timestamps are +expected to be in units of decimalyears. This can be fixed with `unitconvert`:: + + +proj=pipeline + +step +proj=unitconvert +t_in=gpsweek +t_out=decimalyear + +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ... + + +Distance units +############################################################################### + +In the table below all distance units supported by PROJ.4 is listed. +The same list can also be produced on the command line with `proj` or `cs2cs`, +by adding the `-lu` flag when calling the utility. + ++----------+---------------------------------+ +| Label | Name | ++----------+---------------------------------+ +| km | Kilometer | ++----------+---------------------------------+ +| m | Meter | ++----------+---------------------------------+ +| dm | Decimeter | ++----------+---------------------------------+ +| cm | Centimeter | ++----------+---------------------------------+ +| mm | Millimeter | ++----------+---------------------------------+ +| kmi | International Nautical Mile | ++----------+---------------------------------+ +| in | International Inch | ++----------+---------------------------------+ +| ft | International Foot | ++----------+---------------------------------+ +| yd | International Yard | ++----------+---------------------------------+ +| mi | International Statute Mile | ++----------+---------------------------------+ +| fath | International Fathom | ++----------+---------------------------------+ +| ch | International Chain | ++----------+---------------------------------+ +| link | International Link | ++----------+---------------------------------+ +| us-in | U.S. Surveyor's Inch | ++----------+---------------------------------+ +| us-ft | U.S. Surveyor's Foot | ++----------+---------------------------------+ +| us-yd | U.S. Surveyor's Yard | ++----------+---------------------------------+ +| us-ch | U.S. Surveyor's Chain | ++----------+---------------------------------+ +| us-mi | U.S. Surveyor's Statute Mile | ++----------+---------------------------------+ +| ind-yd | Indian Yard | ++----------+---------------------------------+ +| ind-ft | Indian Foot | ++----------+---------------------------------+ +| ind-ch | Indian Chain | ++----------+---------------------------------+ + + +Time units +############################################################################### + +In the table below all time units supported by PROJ.4 is listed. + ++--------------+-----------------------------+ +| mjd | Modfied Julian date | ++--------------+-----------------------------+ +| decimalyear | Decimal year | ++--------------+-----------------------------+ +| gps_week | GPS Week | ++--------------+-----------------------------+ + diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst new file mode 100644 index 0000000000..baae0e0ae0 --- /dev/null +++ b/docs/source/usage/operations/index.rst @@ -0,0 +1,21 @@ +.. _operations: + +================================================================================ +Coordinate operations +================================================================================ + +Coordinate operations in PROJ.4 are divided into three groups: +Projections, conversions and transformations. +Projections are purely cartographic mappings of the sphere onto the plane. +Technically projections are conversions (according to ISO standards), though in +PROJ.4 projections are distinguished from conversions. Conversions are coordinate +operations that do not exert a change in reference frame. Operations that do +exert a change in reference frame are called transformations. + +.. toctree:: + :maxdepth: 1 + + projections/index + conversions/index + transformations/index + diff --git a/docs/source/usage/operations/projections/aeqd.rst b/docs/source/usage/operations/projections/aeqd.rst new file mode 100644 index 0000000000..32165e49db --- /dev/null +++ b/docs/source/usage/operations/projections/aeqd.rst @@ -0,0 +1,22 @@ +.. _aeqd: + +******************************************************************************** +Azimuthal Equidistant +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+guam` | Use Guam elliptical formulas. Defaults to false. | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/aeqd.png + :scale: 50% + :alt: Azimuthal Equidistant + diff --git a/docs/source/usage/operations/projections/airy.rst b/docs/source/usage/operations/projections/airy.rst new file mode 100644 index 0000000000..d273059297 --- /dev/null +++ b/docs/source/usage/operations/projections/airy.rst @@ -0,0 +1,26 @@ +.. _airy: + +******************************************************************************** +Airy +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_b` | | ++---------------------+----------------------------------------------------------+ +| `+no_cut` | Do not cut at hemisphere limit | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/airy.png + :scale: 50% + :alt: Airy + diff --git a/docs/source/projections/aitoff.rst b/docs/source/usage/operations/projections/aitoff.rst similarity index 100% rename from docs/source/projections/aitoff.rst rename to docs/source/usage/operations/projections/aitoff.rst diff --git a/docs/source/projections/alsk.rst b/docs/source/usage/operations/projections/alsk.rst similarity index 100% rename from docs/source/projections/alsk.rst rename to docs/source/usage/operations/projections/alsk.rst diff --git a/docs/source/projections/apian.rst b/docs/source/usage/operations/projections/apian.rst similarity index 100% rename from docs/source/projections/apian.rst rename to docs/source/usage/operations/projections/apian.rst diff --git a/docs/source/projections/august.rst b/docs/source/usage/operations/projections/august.rst similarity index 100% rename from docs/source/projections/august.rst rename to docs/source/usage/operations/projections/august.rst diff --git a/docs/source/projections/bacon.rst b/docs/source/usage/operations/projections/bacon.rst similarity index 100% rename from docs/source/projections/bacon.rst rename to docs/source/usage/operations/projections/bacon.rst diff --git a/docs/source/projections/bipc.rst b/docs/source/usage/operations/projections/bipc.rst similarity index 100% rename from docs/source/projections/bipc.rst rename to docs/source/usage/operations/projections/bipc.rst diff --git a/docs/source/projections/boggs.rst b/docs/source/usage/operations/projections/boggs.rst similarity index 100% rename from docs/source/projections/boggs.rst rename to docs/source/usage/operations/projections/boggs.rst diff --git a/docs/source/projections/bonne.rst b/docs/source/usage/operations/projections/bonne.rst similarity index 100% rename from docs/source/projections/bonne.rst rename to docs/source/usage/operations/projections/bonne.rst diff --git a/docs/source/projections/calcofi.rst b/docs/source/usage/operations/projections/calcofi.rst similarity index 99% rename from docs/source/projections/calcofi.rst rename to docs/source/usage/operations/projections/calcofi.rst index 3c1e5f7a8d..650416c1df 100644 --- a/docs/source/projections/calcofi.rst +++ b/docs/source/usage/operations/projections/calcofi.rst @@ -22,7 +22,7 @@ California Cooperative Oceanic Fisheries Investigations program, known as CalCOF +---------------------+----------------------------------------------------------+ -.. image:: ../../images/calcofi.png +.. image:: ../../../../images/calcofi.png :scale: 50% :align: center :alt: Cal Coop Ocean Fish Invest Lines/Stations diff --git a/docs/source/projections/cass.rst b/docs/source/usage/operations/projections/cass.rst similarity index 100% rename from docs/source/projections/cass.rst rename to docs/source/usage/operations/projections/cass.rst diff --git a/docs/source/projections/cc.rst b/docs/source/usage/operations/projections/cc.rst similarity index 100% rename from docs/source/projections/cc.rst rename to docs/source/usage/operations/projections/cc.rst diff --git a/docs/source/projections/ccon.rst b/docs/source/usage/operations/projections/ccon.rst similarity index 69% rename from docs/source/projections/ccon.rst rename to docs/source/usage/operations/projections/ccon.rst index 6197f06193..8a858e385b 100644 --- a/docs/source/projections/ccon.rst +++ b/docs/source/usage/operations/projections/ccon.rst @@ -4,22 +4,37 @@ Central Conic ******************************************************************************** +This is central (centrographic) projection on cone tangent at ``lat_0`` latitude, +identical with ``conic()`` projection from ``mapproj`` R package. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the standard parallel | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Lukasz Komsta | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_1` | Latitude of standard parallel. | ++---------------------+----------------------------------------------------------+ + .. image:: ./images/ccon.png :scale: 50% - :alt: Central Conic + :alt: Central Conic -This is central (centrographic) projection on cone tangent at ``lat_0`` latitude, -identical with ``conic()`` projection from ``mapproj`` R package. Usage ######## This simple projection is rarely used, as it is not equidistant, equal-area, nor -conformal. +conformal. An example of usage (and the main reason to implement this projection in proj4) -is the ATPOL geobotanical grid of Poland, developed in Institute of Botany, -Jagiellonian University, Krakow, Poland in 1970s [Zajac1978]_. The grid was +is the ATPOL geobotanical grid of Poland, developed in Institute of Botany, +Jagiellonian University, Krakow, Poland in 1970s [Zajac1978]_. The grid was originally handwritten on paper maps and further copied by hand. The projection (together with strange Earth radius) was chosen by its creators as the compromise fit to existing maps during first software development in DOS era. Many years later @@ -47,7 +62,7 @@ Forward projection .. math:: - y = \cot \phi_0 - r \cos (\lambda\sin\phi_0) + y = \cot \phi_0 - r \cos (\lambda\sin\phi_0) Inverse projection @@ -110,9 +125,3 @@ and it should give the following results: 3.707419E+04 6.768262E+05 0.000000E+00 6.960534E+05 6.722946E+05 0.000000E+00 3.300000E+05 3.500000E+05 0.000000E+00 - - - - - - diff --git a/docs/source/projections/cea.rst b/docs/source/usage/operations/projections/cea.rst similarity index 100% rename from docs/source/projections/cea.rst rename to docs/source/usage/operations/projections/cea.rst diff --git a/docs/source/projections/chamb.rst b/docs/source/usage/operations/projections/chamb.rst similarity index 100% rename from docs/source/projections/chamb.rst rename to docs/source/usage/operations/projections/chamb.rst diff --git a/docs/source/projections/collg.rst b/docs/source/usage/operations/projections/collg.rst similarity index 100% rename from docs/source/projections/collg.rst rename to docs/source/usage/operations/projections/collg.rst diff --git a/docs/source/projections/crast.rst b/docs/source/usage/operations/projections/crast.rst similarity index 100% rename from docs/source/projections/crast.rst rename to docs/source/usage/operations/projections/crast.rst diff --git a/docs/source/projections/denoy.rst b/docs/source/usage/operations/projections/denoy.rst similarity index 100% rename from docs/source/projections/denoy.rst rename to docs/source/usage/operations/projections/denoy.rst diff --git a/docs/source/projections/eck1.rst b/docs/source/usage/operations/projections/eck1.rst similarity index 100% rename from docs/source/projections/eck1.rst rename to docs/source/usage/operations/projections/eck1.rst diff --git a/docs/source/projections/eck2.rst b/docs/source/usage/operations/projections/eck2.rst similarity index 100% rename from docs/source/projections/eck2.rst rename to docs/source/usage/operations/projections/eck2.rst diff --git a/docs/source/projections/eck3.rst b/docs/source/usage/operations/projections/eck3.rst similarity index 100% rename from docs/source/projections/eck3.rst rename to docs/source/usage/operations/projections/eck3.rst diff --git a/docs/source/projections/eck4.rst b/docs/source/usage/operations/projections/eck4.rst similarity index 100% rename from docs/source/projections/eck4.rst rename to docs/source/usage/operations/projections/eck4.rst diff --git a/docs/source/projections/eck5.rst b/docs/source/usage/operations/projections/eck5.rst similarity index 100% rename from docs/source/projections/eck5.rst rename to docs/source/usage/operations/projections/eck5.rst diff --git a/docs/source/projections/eck6.rst b/docs/source/usage/operations/projections/eck6.rst similarity index 100% rename from docs/source/projections/eck6.rst rename to docs/source/usage/operations/projections/eck6.rst diff --git a/docs/source/projections/eqc.rst b/docs/source/usage/operations/projections/eqc.rst similarity index 100% rename from docs/source/projections/eqc.rst rename to docs/source/usage/operations/projections/eqc.rst diff --git a/docs/source/projections/eqdc.rst b/docs/source/usage/operations/projections/eqdc.rst similarity index 100% rename from docs/source/projections/eqdc.rst rename to docs/source/usage/operations/projections/eqdc.rst diff --git a/docs/source/projections/etmerc.rst b/docs/source/usage/operations/projections/etmerc.rst similarity index 100% rename from docs/source/projections/etmerc.rst rename to docs/source/usage/operations/projections/etmerc.rst diff --git a/docs/source/projections/euler.rst b/docs/source/usage/operations/projections/euler.rst similarity index 100% rename from docs/source/projections/euler.rst rename to docs/source/usage/operations/projections/euler.rst diff --git a/docs/source/projections/fahey.rst b/docs/source/usage/operations/projections/fahey.rst similarity index 100% rename from docs/source/projections/fahey.rst rename to docs/source/usage/operations/projections/fahey.rst diff --git a/docs/source/projections/fouc.rst b/docs/source/usage/operations/projections/fouc.rst similarity index 100% rename from docs/source/projections/fouc.rst rename to docs/source/usage/operations/projections/fouc.rst diff --git a/docs/source/projections/fouc_s.rst b/docs/source/usage/operations/projections/fouc_s.rst similarity index 100% rename from docs/source/projections/fouc_s.rst rename to docs/source/usage/operations/projections/fouc_s.rst diff --git a/docs/source/projections/gall.rst b/docs/source/usage/operations/projections/gall.rst similarity index 100% rename from docs/source/projections/gall.rst rename to docs/source/usage/operations/projections/gall.rst diff --git a/docs/source/projections/geos.rst b/docs/source/usage/operations/projections/geos.rst similarity index 96% rename from docs/source/projections/geos.rst rename to docs/source/usage/operations/projections/geos.rst index 2e30924157..3b24e1f7d6 100644 --- a/docs/source/projections/geos.rst +++ b/docs/source/usage/operations/projections/geos.rst @@ -55,7 +55,7 @@ projection have a two-axis gimbal viewing geometry. This means that the differen scanning positions are obtained by rotating the gimbal along a N/S axis (or ``y``) and a E/W axis (or ``x``). -.. image:: ../../images/geos_sweep.png +.. image:: ../../../../images/geos_sweep.png :scale: 50% :alt: Gimbal geometry @@ -66,7 +66,7 @@ This example represents the scanning geometry of the Meteosat series satellite. However, the GOES satellite series use the opposite scanning geometry, with the E/W axis (``x``) as the sweep-angle axis, and the N/S (``y``) as the fixed-angle axis. -The sweep argument is used to tell proj.4 which on which axis the outer-gimbal +The sweep argument is used to tell PROJ.4 which on which axis the outer-gimbal is rotating. The possible values are x or y, y being the default. Thus, the scanning geometry of the Meteosat series satellite should take sweep as x, and GOES should take sweep as y. diff --git a/docs/source/projections/gins8.rst b/docs/source/usage/operations/projections/gins8.rst similarity index 100% rename from docs/source/projections/gins8.rst rename to docs/source/usage/operations/projections/gins8.rst diff --git a/docs/source/projections/gn_sinu.rst b/docs/source/usage/operations/projections/gn_sinu.rst similarity index 100% rename from docs/source/projections/gn_sinu.rst rename to docs/source/usage/operations/projections/gn_sinu.rst diff --git a/docs/source/projections/gnom.rst b/docs/source/usage/operations/projections/gnom.rst similarity index 100% rename from docs/source/projections/gnom.rst rename to docs/source/usage/operations/projections/gnom.rst diff --git a/docs/source/projections/goode.rst b/docs/source/usage/operations/projections/goode.rst similarity index 100% rename from docs/source/projections/goode.rst rename to docs/source/usage/operations/projections/goode.rst diff --git a/docs/source/projections/gs48.rst b/docs/source/usage/operations/projections/gs48.rst similarity index 100% rename from docs/source/projections/gs48.rst rename to docs/source/usage/operations/projections/gs48.rst diff --git a/docs/source/projections/gs50.rst b/docs/source/usage/operations/projections/gs50.rst similarity index 100% rename from docs/source/projections/gs50.rst rename to docs/source/usage/operations/projections/gs50.rst diff --git a/docs/source/projections/gstmerc.rst b/docs/source/usage/operations/projections/gstmerc.rst similarity index 100% rename from docs/source/projections/gstmerc.rst rename to docs/source/usage/operations/projections/gstmerc.rst diff --git a/docs/source/projections/hammer.rst b/docs/source/usage/operations/projections/hammer.rst similarity index 100% rename from docs/source/projections/hammer.rst rename to docs/source/usage/operations/projections/hammer.rst diff --git a/docs/source/projections/hatano.rst b/docs/source/usage/operations/projections/hatano.rst similarity index 100% rename from docs/source/projections/hatano.rst rename to docs/source/usage/operations/projections/hatano.rst diff --git a/docs/source/projections/healpix.rst b/docs/source/usage/operations/projections/healpix.rst similarity index 98% rename from docs/source/projections/healpix.rst rename to docs/source/usage/operations/projections/healpix.rst index 885ea3ea03..20815d7654 100644 --- a/docs/source/projections/healpix.rst +++ b/docs/source/usage/operations/projections/healpix.rst @@ -17,7 +17,7 @@ HEALPix | `No special options for this projection` | +---------------------+----------------------------------------------------------+ -.. image:: ../../images/healpix.png +.. image:: ../../../../images/healpix.png :scale: 75% :alt: HEALPix diff --git a/docs/source/projections/igh.rst b/docs/source/usage/operations/projections/igh.rst similarity index 100% rename from docs/source/projections/igh.rst rename to docs/source/usage/operations/projections/igh.rst diff --git a/docs/source/projections/images/aea.png b/docs/source/usage/operations/projections/images/aea.png similarity index 100% rename from docs/source/projections/images/aea.png rename to docs/source/usage/operations/projections/images/aea.png diff --git a/docs/source/projections/images/aeqd.png b/docs/source/usage/operations/projections/images/aeqd.png similarity index 100% rename from docs/source/projections/images/aeqd.png rename to docs/source/usage/operations/projections/images/aeqd.png diff --git a/docs/source/projections/images/airy.png b/docs/source/usage/operations/projections/images/airy.png similarity index 100% rename from docs/source/projections/images/airy.png rename to docs/source/usage/operations/projections/images/airy.png diff --git a/docs/source/projections/images/aitoff.png b/docs/source/usage/operations/projections/images/aitoff.png similarity index 100% rename from docs/source/projections/images/aitoff.png rename to docs/source/usage/operations/projections/images/aitoff.png diff --git a/docs/source/projections/images/alsk.png b/docs/source/usage/operations/projections/images/alsk.png similarity index 100% rename from docs/source/projections/images/alsk.png rename to docs/source/usage/operations/projections/images/alsk.png diff --git a/docs/source/projections/images/apian.png b/docs/source/usage/operations/projections/images/apian.png similarity index 100% rename from docs/source/projections/images/apian.png rename to docs/source/usage/operations/projections/images/apian.png diff --git a/docs/source/projections/images/august.png b/docs/source/usage/operations/projections/images/august.png similarity index 100% rename from docs/source/projections/images/august.png rename to docs/source/usage/operations/projections/images/august.png diff --git a/docs/source/projections/images/bacon.png b/docs/source/usage/operations/projections/images/bacon.png similarity index 100% rename from docs/source/projections/images/bacon.png rename to docs/source/usage/operations/projections/images/bacon.png diff --git a/docs/source/projections/images/bipc.png b/docs/source/usage/operations/projections/images/bipc.png similarity index 100% rename from docs/source/projections/images/bipc.png rename to docs/source/usage/operations/projections/images/bipc.png diff --git a/docs/source/projections/images/boggs.png b/docs/source/usage/operations/projections/images/boggs.png similarity index 100% rename from docs/source/projections/images/boggs.png rename to docs/source/usage/operations/projections/images/boggs.png diff --git a/docs/source/projections/images/bonne.png b/docs/source/usage/operations/projections/images/bonne.png similarity index 100% rename from docs/source/projections/images/bonne.png rename to docs/source/usage/operations/projections/images/bonne.png diff --git a/docs/source/projections/images/calcofi.png b/docs/source/usage/operations/projections/images/calcofi.png similarity index 100% rename from docs/source/projections/images/calcofi.png rename to docs/source/usage/operations/projections/images/calcofi.png diff --git a/docs/source/projections/images/cass.png b/docs/source/usage/operations/projections/images/cass.png similarity index 100% rename from docs/source/projections/images/cass.png rename to docs/source/usage/operations/projections/images/cass.png diff --git a/docs/source/projections/images/cc.png b/docs/source/usage/operations/projections/images/cc.png similarity index 100% rename from docs/source/projections/images/cc.png rename to docs/source/usage/operations/projections/images/cc.png diff --git a/docs/source/projections/images/ccon.png b/docs/source/usage/operations/projections/images/ccon.png similarity index 100% rename from docs/source/projections/images/ccon.png rename to docs/source/usage/operations/projections/images/ccon.png diff --git a/docs/source/projections/images/cea.png b/docs/source/usage/operations/projections/images/cea.png similarity index 100% rename from docs/source/projections/images/cea.png rename to docs/source/usage/operations/projections/images/cea.png diff --git a/docs/source/projections/images/chamb.png b/docs/source/usage/operations/projections/images/chamb.png similarity index 100% rename from docs/source/projections/images/chamb.png rename to docs/source/usage/operations/projections/images/chamb.png diff --git a/docs/source/projections/images/collg.png b/docs/source/usage/operations/projections/images/collg.png similarity index 100% rename from docs/source/projections/images/collg.png rename to docs/source/usage/operations/projections/images/collg.png diff --git a/docs/source/projections/images/comill.png b/docs/source/usage/operations/projections/images/comill.png similarity index 100% rename from docs/source/projections/images/comill.png rename to docs/source/usage/operations/projections/images/comill.png diff --git a/docs/source/projections/images/crast.png b/docs/source/usage/operations/projections/images/crast.png similarity index 100% rename from docs/source/projections/images/crast.png rename to docs/source/usage/operations/projections/images/crast.png diff --git a/docs/source/projections/images/denoy.png b/docs/source/usage/operations/projections/images/denoy.png similarity index 100% rename from docs/source/projections/images/denoy.png rename to docs/source/usage/operations/projections/images/denoy.png diff --git a/docs/source/projections/images/eck1.png b/docs/source/usage/operations/projections/images/eck1.png similarity index 100% rename from docs/source/projections/images/eck1.png rename to docs/source/usage/operations/projections/images/eck1.png diff --git a/docs/source/projections/images/eck2.png b/docs/source/usage/operations/projections/images/eck2.png similarity index 100% rename from docs/source/projections/images/eck2.png rename to docs/source/usage/operations/projections/images/eck2.png diff --git a/docs/source/projections/images/eck3.png b/docs/source/usage/operations/projections/images/eck3.png similarity index 100% rename from docs/source/projections/images/eck3.png rename to docs/source/usage/operations/projections/images/eck3.png diff --git a/docs/source/projections/images/eck4.png b/docs/source/usage/operations/projections/images/eck4.png similarity index 100% rename from docs/source/projections/images/eck4.png rename to docs/source/usage/operations/projections/images/eck4.png diff --git a/docs/source/projections/images/eck5.png b/docs/source/usage/operations/projections/images/eck5.png similarity index 100% rename from docs/source/projections/images/eck5.png rename to docs/source/usage/operations/projections/images/eck5.png diff --git a/docs/source/projections/images/eck6.png b/docs/source/usage/operations/projections/images/eck6.png similarity index 100% rename from docs/source/projections/images/eck6.png rename to docs/source/usage/operations/projections/images/eck6.png diff --git a/docs/source/projections/images/eqc.png b/docs/source/usage/operations/projections/images/eqc.png similarity index 100% rename from docs/source/projections/images/eqc.png rename to docs/source/usage/operations/projections/images/eqc.png diff --git a/docs/source/projections/images/eqdc.png b/docs/source/usage/operations/projections/images/eqdc.png similarity index 100% rename from docs/source/projections/images/eqdc.png rename to docs/source/usage/operations/projections/images/eqdc.png diff --git a/docs/source/projections/images/etmerc.png b/docs/source/usage/operations/projections/images/etmerc.png similarity index 100% rename from docs/source/projections/images/etmerc.png rename to docs/source/usage/operations/projections/images/etmerc.png diff --git a/docs/source/projections/images/euler.png b/docs/source/usage/operations/projections/images/euler.png similarity index 100% rename from docs/source/projections/images/euler.png rename to docs/source/usage/operations/projections/images/euler.png diff --git a/docs/source/projections/images/fahey.png b/docs/source/usage/operations/projections/images/fahey.png similarity index 100% rename from docs/source/projections/images/fahey.png rename to docs/source/usage/operations/projections/images/fahey.png diff --git a/docs/source/projections/images/fouc.png b/docs/source/usage/operations/projections/images/fouc.png similarity index 100% rename from docs/source/projections/images/fouc.png rename to docs/source/usage/operations/projections/images/fouc.png diff --git a/docs/source/projections/images/fouc_s.png b/docs/source/usage/operations/projections/images/fouc_s.png similarity index 100% rename from docs/source/projections/images/fouc_s.png rename to docs/source/usage/operations/projections/images/fouc_s.png diff --git a/docs/source/projections/images/gall.png b/docs/source/usage/operations/projections/images/gall.png similarity index 100% rename from docs/source/projections/images/gall.png rename to docs/source/usage/operations/projections/images/gall.png diff --git a/docs/source/projections/images/geos.png b/docs/source/usage/operations/projections/images/geos.png similarity index 100% rename from docs/source/projections/images/geos.png rename to docs/source/usage/operations/projections/images/geos.png diff --git a/docs/source/projections/images/gins8.png b/docs/source/usage/operations/projections/images/gins8.png similarity index 100% rename from docs/source/projections/images/gins8.png rename to docs/source/usage/operations/projections/images/gins8.png diff --git a/docs/source/projections/images/gn_sinu.png b/docs/source/usage/operations/projections/images/gn_sinu.png similarity index 100% rename from docs/source/projections/images/gn_sinu.png rename to docs/source/usage/operations/projections/images/gn_sinu.png diff --git a/docs/source/projections/images/gnom.png b/docs/source/usage/operations/projections/images/gnom.png similarity index 100% rename from docs/source/projections/images/gnom.png rename to docs/source/usage/operations/projections/images/gnom.png diff --git a/docs/source/projections/images/goode.png b/docs/source/usage/operations/projections/images/goode.png similarity index 100% rename from docs/source/projections/images/goode.png rename to docs/source/usage/operations/projections/images/goode.png diff --git a/docs/source/projections/images/gs48.png b/docs/source/usage/operations/projections/images/gs48.png similarity index 100% rename from docs/source/projections/images/gs48.png rename to docs/source/usage/operations/projections/images/gs48.png diff --git a/docs/source/projections/images/gs50.png b/docs/source/usage/operations/projections/images/gs50.png similarity index 100% rename from docs/source/projections/images/gs50.png rename to docs/source/usage/operations/projections/images/gs50.png diff --git a/docs/source/projections/images/gstmerc.png b/docs/source/usage/operations/projections/images/gstmerc.png similarity index 100% rename from docs/source/projections/images/gstmerc.png rename to docs/source/usage/operations/projections/images/gstmerc.png diff --git a/docs/source/projections/images/hammer.png b/docs/source/usage/operations/projections/images/hammer.png similarity index 100% rename from docs/source/projections/images/hammer.png rename to docs/source/usage/operations/projections/images/hammer.png diff --git a/docs/source/projections/images/hatano.png b/docs/source/usage/operations/projections/images/hatano.png similarity index 100% rename from docs/source/projections/images/hatano.png rename to docs/source/usage/operations/projections/images/hatano.png diff --git a/docs/source/projections/images/healpix.png b/docs/source/usage/operations/projections/images/healpix.png similarity index 100% rename from docs/source/projections/images/healpix.png rename to docs/source/usage/operations/projections/images/healpix.png diff --git a/docs/source/projections/images/igh.png b/docs/source/usage/operations/projections/images/igh.png similarity index 100% rename from docs/source/projections/images/igh.png rename to docs/source/usage/operations/projections/images/igh.png diff --git a/docs/source/projections/images/imw_p.png b/docs/source/usage/operations/projections/images/imw_p.png similarity index 100% rename from docs/source/projections/images/imw_p.png rename to docs/source/usage/operations/projections/images/imw_p.png diff --git a/docs/source/projections/images/isea.png b/docs/source/usage/operations/projections/images/isea.png similarity index 100% rename from docs/source/projections/images/isea.png rename to docs/source/usage/operations/projections/images/isea.png diff --git a/docs/source/projections/images/kav5.png b/docs/source/usage/operations/projections/images/kav5.png similarity index 100% rename from docs/source/projections/images/kav5.png rename to docs/source/usage/operations/projections/images/kav5.png diff --git a/docs/source/projections/images/kav7.png b/docs/source/usage/operations/projections/images/kav7.png similarity index 100% rename from docs/source/projections/images/kav7.png rename to docs/source/usage/operations/projections/images/kav7.png diff --git a/docs/source/projections/images/krovak.png b/docs/source/usage/operations/projections/images/krovak.png similarity index 100% rename from docs/source/projections/images/krovak.png rename to docs/source/usage/operations/projections/images/krovak.png diff --git a/docs/source/projections/images/labrd.png b/docs/source/usage/operations/projections/images/labrd.png similarity index 100% rename from docs/source/projections/images/labrd.png rename to docs/source/usage/operations/projections/images/labrd.png diff --git a/docs/source/projections/images/laea.png b/docs/source/usage/operations/projections/images/laea.png similarity index 100% rename from docs/source/projections/images/laea.png rename to docs/source/usage/operations/projections/images/laea.png diff --git a/docs/source/projections/images/lagrng.png b/docs/source/usage/operations/projections/images/lagrng.png similarity index 100% rename from docs/source/projections/images/lagrng.png rename to docs/source/usage/operations/projections/images/lagrng.png diff --git a/docs/source/projections/images/larr.png b/docs/source/usage/operations/projections/images/larr.png similarity index 100% rename from docs/source/projections/images/larr.png rename to docs/source/usage/operations/projections/images/larr.png diff --git a/docs/source/projections/images/lask.png b/docs/source/usage/operations/projections/images/lask.png similarity index 100% rename from docs/source/projections/images/lask.png rename to docs/source/usage/operations/projections/images/lask.png diff --git a/docs/source/projections/images/lcc.png b/docs/source/usage/operations/projections/images/lcc.png similarity index 100% rename from docs/source/projections/images/lcc.png rename to docs/source/usage/operations/projections/images/lcc.png diff --git a/docs/source/projections/images/lcca.png b/docs/source/usage/operations/projections/images/lcca.png similarity index 100% rename from docs/source/projections/images/lcca.png rename to docs/source/usage/operations/projections/images/lcca.png diff --git a/docs/source/projections/images/leac.png b/docs/source/usage/operations/projections/images/leac.png similarity index 100% rename from docs/source/projections/images/leac.png rename to docs/source/usage/operations/projections/images/leac.png diff --git a/docs/source/projections/images/lee_os.png b/docs/source/usage/operations/projections/images/lee_os.png similarity index 100% rename from docs/source/projections/images/lee_os.png rename to docs/source/usage/operations/projections/images/lee_os.png diff --git a/docs/source/projections/images/loxim.png b/docs/source/usage/operations/projections/images/loxim.png similarity index 100% rename from docs/source/projections/images/loxim.png rename to docs/source/usage/operations/projections/images/loxim.png diff --git a/docs/source/projections/images/lsat.png b/docs/source/usage/operations/projections/images/lsat.png similarity index 100% rename from docs/source/projections/images/lsat.png rename to docs/source/usage/operations/projections/images/lsat.png diff --git a/docs/source/projections/images/mbt_fps.png b/docs/source/usage/operations/projections/images/mbt_fps.png similarity index 100% rename from docs/source/projections/images/mbt_fps.png rename to docs/source/usage/operations/projections/images/mbt_fps.png diff --git a/docs/source/projections/images/mbt_s.png b/docs/source/usage/operations/projections/images/mbt_s.png similarity index 100% rename from docs/source/projections/images/mbt_s.png rename to docs/source/usage/operations/projections/images/mbt_s.png diff --git a/docs/source/projections/images/mbtfpp.png b/docs/source/usage/operations/projections/images/mbtfpp.png similarity index 100% rename from docs/source/projections/images/mbtfpp.png rename to docs/source/usage/operations/projections/images/mbtfpp.png diff --git a/docs/source/projections/images/mbtfpq.png b/docs/source/usage/operations/projections/images/mbtfpq.png similarity index 100% rename from docs/source/projections/images/mbtfpq.png rename to docs/source/usage/operations/projections/images/mbtfpq.png diff --git a/docs/source/projections/images/mbtfps.png b/docs/source/usage/operations/projections/images/mbtfps.png similarity index 100% rename from docs/source/projections/images/mbtfps.png rename to docs/source/usage/operations/projections/images/mbtfps.png diff --git a/docs/source/projections/images/merc.png b/docs/source/usage/operations/projections/images/merc.png similarity index 100% rename from docs/source/projections/images/merc.png rename to docs/source/usage/operations/projections/images/merc.png diff --git a/docs/source/projections/images/mil_os.png b/docs/source/usage/operations/projections/images/mil_os.png similarity index 100% rename from docs/source/projections/images/mil_os.png rename to docs/source/usage/operations/projections/images/mil_os.png diff --git a/docs/source/projections/images/mill.png b/docs/source/usage/operations/projections/images/mill.png similarity index 100% rename from docs/source/projections/images/mill.png rename to docs/source/usage/operations/projections/images/mill.png diff --git a/docs/source/projections/images/misrsom.png b/docs/source/usage/operations/projections/images/misrsom.png similarity index 100% rename from docs/source/projections/images/misrsom.png rename to docs/source/usage/operations/projections/images/misrsom.png diff --git a/docs/source/projections/images/moll.png b/docs/source/usage/operations/projections/images/moll.png similarity index 100% rename from docs/source/projections/images/moll.png rename to docs/source/usage/operations/projections/images/moll.png diff --git a/docs/source/projections/images/murd1.png b/docs/source/usage/operations/projections/images/murd1.png similarity index 100% rename from docs/source/projections/images/murd1.png rename to docs/source/usage/operations/projections/images/murd1.png diff --git a/docs/source/projections/images/murd2.png b/docs/source/usage/operations/projections/images/murd2.png similarity index 100% rename from docs/source/projections/images/murd2.png rename to docs/source/usage/operations/projections/images/murd2.png diff --git a/docs/source/projections/images/murd3.png b/docs/source/usage/operations/projections/images/murd3.png similarity index 100% rename from docs/source/projections/images/murd3.png rename to docs/source/usage/operations/projections/images/murd3.png diff --git a/docs/source/projections/images/natearth.png b/docs/source/usage/operations/projections/images/natearth.png similarity index 100% rename from docs/source/projections/images/natearth.png rename to docs/source/usage/operations/projections/images/natearth.png diff --git a/docs/source/projections/images/natearth2.png b/docs/source/usage/operations/projections/images/natearth2.png similarity index 100% rename from docs/source/projections/images/natearth2.png rename to docs/source/usage/operations/projections/images/natearth2.png diff --git a/docs/source/projections/images/nell.png b/docs/source/usage/operations/projections/images/nell.png similarity index 100% rename from docs/source/projections/images/nell.png rename to docs/source/usage/operations/projections/images/nell.png diff --git a/docs/source/projections/images/nell_h.png b/docs/source/usage/operations/projections/images/nell_h.png similarity index 100% rename from docs/source/projections/images/nell_h.png rename to docs/source/usage/operations/projections/images/nell_h.png diff --git a/docs/source/projections/images/nicol.png b/docs/source/usage/operations/projections/images/nicol.png similarity index 100% rename from docs/source/projections/images/nicol.png rename to docs/source/usage/operations/projections/images/nicol.png diff --git a/docs/source/projections/images/nsper.png b/docs/source/usage/operations/projections/images/nsper.png similarity index 100% rename from docs/source/projections/images/nsper.png rename to docs/source/usage/operations/projections/images/nsper.png diff --git a/docs/source/projections/images/nzmg.png b/docs/source/usage/operations/projections/images/nzmg.png similarity index 100% rename from docs/source/projections/images/nzmg.png rename to docs/source/usage/operations/projections/images/nzmg.png diff --git a/docs/source/projections/images/ob_tran.png b/docs/source/usage/operations/projections/images/ob_tran.png similarity index 100% rename from docs/source/projections/images/ob_tran.png rename to docs/source/usage/operations/projections/images/ob_tran.png diff --git a/docs/source/projections/images/ocea.png b/docs/source/usage/operations/projections/images/ocea.png similarity index 100% rename from docs/source/projections/images/ocea.png rename to docs/source/usage/operations/projections/images/ocea.png diff --git a/docs/source/projections/images/oea.png b/docs/source/usage/operations/projections/images/oea.png similarity index 100% rename from docs/source/projections/images/oea.png rename to docs/source/usage/operations/projections/images/oea.png diff --git a/docs/source/projections/images/omerc.png b/docs/source/usage/operations/projections/images/omerc.png similarity index 100% rename from docs/source/projections/images/omerc.png rename to docs/source/usage/operations/projections/images/omerc.png diff --git a/docs/source/projections/images/ortel.png b/docs/source/usage/operations/projections/images/ortel.png similarity index 100% rename from docs/source/projections/images/ortel.png rename to docs/source/usage/operations/projections/images/ortel.png diff --git a/docs/source/projections/images/ortho.png b/docs/source/usage/operations/projections/images/ortho.png similarity index 100% rename from docs/source/projections/images/ortho.png rename to docs/source/usage/operations/projections/images/ortho.png diff --git a/docs/source/projections/images/patterson.png b/docs/source/usage/operations/projections/images/patterson.png similarity index 100% rename from docs/source/projections/images/patterson.png rename to docs/source/usage/operations/projections/images/patterson.png diff --git a/docs/source/projections/images/pconic.png b/docs/source/usage/operations/projections/images/pconic.png similarity index 100% rename from docs/source/projections/images/pconic.png rename to docs/source/usage/operations/projections/images/pconic.png diff --git a/docs/source/projections/images/poly.png b/docs/source/usage/operations/projections/images/poly.png similarity index 100% rename from docs/source/projections/images/poly.png rename to docs/source/usage/operations/projections/images/poly.png diff --git a/docs/source/projections/images/putp1.png b/docs/source/usage/operations/projections/images/putp1.png similarity index 100% rename from docs/source/projections/images/putp1.png rename to docs/source/usage/operations/projections/images/putp1.png diff --git a/docs/source/projections/images/putp2.png b/docs/source/usage/operations/projections/images/putp2.png similarity index 100% rename from docs/source/projections/images/putp2.png rename to docs/source/usage/operations/projections/images/putp2.png diff --git a/docs/source/projections/images/putp3.png b/docs/source/usage/operations/projections/images/putp3.png similarity index 100% rename from docs/source/projections/images/putp3.png rename to docs/source/usage/operations/projections/images/putp3.png diff --git a/docs/source/projections/images/putp3p.png b/docs/source/usage/operations/projections/images/putp3p.png similarity index 100% rename from docs/source/projections/images/putp3p.png rename to docs/source/usage/operations/projections/images/putp3p.png diff --git a/docs/source/projections/images/putp4p.png b/docs/source/usage/operations/projections/images/putp4p.png similarity index 100% rename from docs/source/projections/images/putp4p.png rename to docs/source/usage/operations/projections/images/putp4p.png diff --git a/docs/source/projections/images/putp5.png b/docs/source/usage/operations/projections/images/putp5.png similarity index 100% rename from docs/source/projections/images/putp5.png rename to docs/source/usage/operations/projections/images/putp5.png diff --git a/docs/source/projections/images/putp5p.png b/docs/source/usage/operations/projections/images/putp5p.png similarity index 100% rename from docs/source/projections/images/putp5p.png rename to docs/source/usage/operations/projections/images/putp5p.png diff --git a/docs/source/projections/images/putp6.png b/docs/source/usage/operations/projections/images/putp6.png similarity index 100% rename from docs/source/projections/images/putp6.png rename to docs/source/usage/operations/projections/images/putp6.png diff --git a/docs/source/projections/images/putp6p.png b/docs/source/usage/operations/projections/images/putp6p.png similarity index 100% rename from docs/source/projections/images/putp6p.png rename to docs/source/usage/operations/projections/images/putp6p.png diff --git a/docs/source/projections/images/qsc.png b/docs/source/usage/operations/projections/images/qsc.png similarity index 100% rename from docs/source/projections/images/qsc.png rename to docs/source/usage/operations/projections/images/qsc.png diff --git a/docs/source/projections/images/qua_aut.png b/docs/source/usage/operations/projections/images/qua_aut.png similarity index 100% rename from docs/source/projections/images/qua_aut.png rename to docs/source/usage/operations/projections/images/qua_aut.png diff --git a/docs/source/projections/images/rhealpix.png b/docs/source/usage/operations/projections/images/rhealpix.png similarity index 100% rename from docs/source/projections/images/rhealpix.png rename to docs/source/usage/operations/projections/images/rhealpix.png diff --git a/docs/source/projections/images/robin.png b/docs/source/usage/operations/projections/images/robin.png similarity index 100% rename from docs/source/projections/images/robin.png rename to docs/source/usage/operations/projections/images/robin.png diff --git a/docs/source/projections/images/rouss.png b/docs/source/usage/operations/projections/images/rouss.png similarity index 100% rename from docs/source/projections/images/rouss.png rename to docs/source/usage/operations/projections/images/rouss.png diff --git a/docs/source/projections/images/rpoly.png b/docs/source/usage/operations/projections/images/rpoly.png similarity index 100% rename from docs/source/projections/images/rpoly.png rename to docs/source/usage/operations/projections/images/rpoly.png diff --git a/docs/source/projections/images/sinu.png b/docs/source/usage/operations/projections/images/sinu.png similarity index 100% rename from docs/source/projections/images/sinu.png rename to docs/source/usage/operations/projections/images/sinu.png diff --git a/docs/source/projections/images/somerc.png b/docs/source/usage/operations/projections/images/somerc.png similarity index 100% rename from docs/source/projections/images/somerc.png rename to docs/source/usage/operations/projections/images/somerc.png diff --git a/docs/source/projections/images/stere.png b/docs/source/usage/operations/projections/images/stere.png similarity index 100% rename from docs/source/projections/images/stere.png rename to docs/source/usage/operations/projections/images/stere.png diff --git a/docs/source/projections/images/sterea.png b/docs/source/usage/operations/projections/images/sterea.png similarity index 100% rename from docs/source/projections/images/sterea.png rename to docs/source/usage/operations/projections/images/sterea.png diff --git a/docs/source/projections/images/tcc.png b/docs/source/usage/operations/projections/images/tcc.png similarity index 100% rename from docs/source/projections/images/tcc.png rename to docs/source/usage/operations/projections/images/tcc.png diff --git a/docs/source/projections/images/tcea.png b/docs/source/usage/operations/projections/images/tcea.png similarity index 100% rename from docs/source/projections/images/tcea.png rename to docs/source/usage/operations/projections/images/tcea.png diff --git a/docs/source/projections/images/tissot.png b/docs/source/usage/operations/projections/images/tissot.png similarity index 100% rename from docs/source/projections/images/tissot.png rename to docs/source/usage/operations/projections/images/tissot.png diff --git a/docs/source/projections/images/tmerc.png b/docs/source/usage/operations/projections/images/tmerc.png similarity index 100% rename from docs/source/projections/images/tmerc.png rename to docs/source/usage/operations/projections/images/tmerc.png diff --git a/docs/source/projections/images/tpeqd.png b/docs/source/usage/operations/projections/images/tpeqd.png similarity index 100% rename from docs/source/projections/images/tpeqd.png rename to docs/source/usage/operations/projections/images/tpeqd.png diff --git a/docs/source/projections/images/tpers.png b/docs/source/usage/operations/projections/images/tpers.png similarity index 100% rename from docs/source/projections/images/tpers.png rename to docs/source/usage/operations/projections/images/tpers.png diff --git a/docs/source/projections/images/ups.png b/docs/source/usage/operations/projections/images/ups.png similarity index 100% rename from docs/source/projections/images/ups.png rename to docs/source/usage/operations/projections/images/ups.png diff --git a/docs/source/projections/images/urm5.png b/docs/source/usage/operations/projections/images/urm5.png similarity index 100% rename from docs/source/projections/images/urm5.png rename to docs/source/usage/operations/projections/images/urm5.png diff --git a/docs/source/projections/images/urmfps.png b/docs/source/usage/operations/projections/images/urmfps.png similarity index 100% rename from docs/source/projections/images/urmfps.png rename to docs/source/usage/operations/projections/images/urmfps.png diff --git a/docs/source/projections/images/utm.png b/docs/source/usage/operations/projections/images/utm.png similarity index 100% rename from docs/source/projections/images/utm.png rename to docs/source/usage/operations/projections/images/utm.png diff --git a/docs/source/projections/images/vandg.png b/docs/source/usage/operations/projections/images/vandg.png similarity index 100% rename from docs/source/projections/images/vandg.png rename to docs/source/usage/operations/projections/images/vandg.png diff --git a/docs/source/projections/images/vandg2.png b/docs/source/usage/operations/projections/images/vandg2.png similarity index 100% rename from docs/source/projections/images/vandg2.png rename to docs/source/usage/operations/projections/images/vandg2.png diff --git a/docs/source/projections/images/vandg3.png b/docs/source/usage/operations/projections/images/vandg3.png similarity index 100% rename from docs/source/projections/images/vandg3.png rename to docs/source/usage/operations/projections/images/vandg3.png diff --git a/docs/source/projections/images/vandg4.png b/docs/source/usage/operations/projections/images/vandg4.png similarity index 100% rename from docs/source/projections/images/vandg4.png rename to docs/source/usage/operations/projections/images/vandg4.png diff --git a/docs/source/projections/images/vitk1.png b/docs/source/usage/operations/projections/images/vitk1.png similarity index 100% rename from docs/source/projections/images/vitk1.png rename to docs/source/usage/operations/projections/images/vitk1.png diff --git a/docs/source/projections/images/wag1.png b/docs/source/usage/operations/projections/images/wag1.png similarity index 100% rename from docs/source/projections/images/wag1.png rename to docs/source/usage/operations/projections/images/wag1.png diff --git a/docs/source/projections/images/wag2.png b/docs/source/usage/operations/projections/images/wag2.png similarity index 100% rename from docs/source/projections/images/wag2.png rename to docs/source/usage/operations/projections/images/wag2.png diff --git a/docs/source/projections/images/wag3.png b/docs/source/usage/operations/projections/images/wag3.png similarity index 100% rename from docs/source/projections/images/wag3.png rename to docs/source/usage/operations/projections/images/wag3.png diff --git a/docs/source/projections/images/wag4.png b/docs/source/usage/operations/projections/images/wag4.png similarity index 100% rename from docs/source/projections/images/wag4.png rename to docs/source/usage/operations/projections/images/wag4.png diff --git a/docs/source/projections/images/wag5.png b/docs/source/usage/operations/projections/images/wag5.png similarity index 100% rename from docs/source/projections/images/wag5.png rename to docs/source/usage/operations/projections/images/wag5.png diff --git a/docs/source/projections/images/wag6.png b/docs/source/usage/operations/projections/images/wag6.png similarity index 100% rename from docs/source/projections/images/wag6.png rename to docs/source/usage/operations/projections/images/wag6.png diff --git a/docs/source/projections/images/wag7.png b/docs/source/usage/operations/projections/images/wag7.png similarity index 100% rename from docs/source/projections/images/wag7.png rename to docs/source/usage/operations/projections/images/wag7.png diff --git a/docs/source/projections/images/weren.png b/docs/source/usage/operations/projections/images/weren.png similarity index 100% rename from docs/source/projections/images/weren.png rename to docs/source/usage/operations/projections/images/weren.png diff --git a/docs/source/projections/images/wink1.png b/docs/source/usage/operations/projections/images/wink1.png similarity index 100% rename from docs/source/projections/images/wink1.png rename to docs/source/usage/operations/projections/images/wink1.png diff --git a/docs/source/projections/images/wink2.png b/docs/source/usage/operations/projections/images/wink2.png similarity index 100% rename from docs/source/projections/images/wink2.png rename to docs/source/usage/operations/projections/images/wink2.png diff --git a/docs/source/projections/images/wintri.png b/docs/source/usage/operations/projections/images/wintri.png similarity index 100% rename from docs/source/projections/images/wintri.png rename to docs/source/usage/operations/projections/images/wintri.png diff --git a/docs/source/projections/imw_p.rst b/docs/source/usage/operations/projections/imw_p.rst similarity index 100% rename from docs/source/projections/imw_p.rst rename to docs/source/usage/operations/projections/imw_p.rst diff --git a/docs/source/projections/index.rst b/docs/source/usage/operations/projections/index.rst similarity index 86% rename from docs/source/projections/index.rst rename to docs/source/usage/operations/projections/index.rst index 5ccf00459f..f7eb0c67e1 100644 --- a/docs/source/projections/index.rst +++ b/docs/source/usage/operations/projections/index.rst @@ -4,6 +4,11 @@ Projections ================================================================================ +Projections are coordinate operations that are technically conversions but since +projections are so fundamental to PROJ.4 we differentiate them from conversions. + +Projections map the spherical 3D space to a flat 2D space. + .. toctree:: :maxdepth: 1 @@ -62,8 +67,6 @@ Projections lagrng larr lask - lonlat - latlon lcc lcca leac diff --git a/docs/source/projections/isea.rst b/docs/source/usage/operations/projections/isea.rst similarity index 100% rename from docs/source/projections/isea.rst rename to docs/source/usage/operations/projections/isea.rst diff --git a/docs/source/projections/kav5.rst b/docs/source/usage/operations/projections/kav5.rst similarity index 100% rename from docs/source/projections/kav5.rst rename to docs/source/usage/operations/projections/kav5.rst diff --git a/docs/source/projections/kav7.rst b/docs/source/usage/operations/projections/kav7.rst similarity index 100% rename from docs/source/projections/kav7.rst rename to docs/source/usage/operations/projections/kav7.rst diff --git a/docs/source/projections/krovak.rst b/docs/source/usage/operations/projections/krovak.rst similarity index 100% rename from docs/source/projections/krovak.rst rename to docs/source/usage/operations/projections/krovak.rst diff --git a/docs/source/projections/labrd.rst b/docs/source/usage/operations/projections/labrd.rst similarity index 100% rename from docs/source/projections/labrd.rst rename to docs/source/usage/operations/projections/labrd.rst diff --git a/docs/source/projections/laea.rst b/docs/source/usage/operations/projections/laea.rst similarity index 100% rename from docs/source/projections/laea.rst rename to docs/source/usage/operations/projections/laea.rst diff --git a/docs/source/projections/lagrng.rst b/docs/source/usage/operations/projections/lagrng.rst similarity index 100% rename from docs/source/projections/lagrng.rst rename to docs/source/usage/operations/projections/lagrng.rst diff --git a/docs/source/projections/larr.rst b/docs/source/usage/operations/projections/larr.rst similarity index 100% rename from docs/source/projections/larr.rst rename to docs/source/usage/operations/projections/larr.rst diff --git a/docs/source/projections/lask.rst b/docs/source/usage/operations/projections/lask.rst similarity index 100% rename from docs/source/projections/lask.rst rename to docs/source/usage/operations/projections/lask.rst diff --git a/docs/source/projections/lcc.rst b/docs/source/usage/operations/projections/lcc.rst similarity index 100% rename from docs/source/projections/lcc.rst rename to docs/source/usage/operations/projections/lcc.rst diff --git a/docs/source/projections/lcca.rst b/docs/source/usage/operations/projections/lcca.rst similarity index 100% rename from docs/source/projections/lcca.rst rename to docs/source/usage/operations/projections/lcca.rst diff --git a/docs/source/projections/leac.rst b/docs/source/usage/operations/projections/leac.rst similarity index 100% rename from docs/source/projections/leac.rst rename to docs/source/usage/operations/projections/leac.rst diff --git a/docs/source/projections/lee_os.rst b/docs/source/usage/operations/projections/lee_os.rst similarity index 100% rename from docs/source/projections/lee_os.rst rename to docs/source/usage/operations/projections/lee_os.rst diff --git a/docs/source/projections/loxim.rst b/docs/source/usage/operations/projections/loxim.rst similarity index 100% rename from docs/source/projections/loxim.rst rename to docs/source/usage/operations/projections/loxim.rst diff --git a/docs/source/projections/lsat.rst b/docs/source/usage/operations/projections/lsat.rst similarity index 100% rename from docs/source/projections/lsat.rst rename to docs/source/usage/operations/projections/lsat.rst diff --git a/docs/source/projections/mbt_fps.rst b/docs/source/usage/operations/projections/mbt_fps.rst similarity index 100% rename from docs/source/projections/mbt_fps.rst rename to docs/source/usage/operations/projections/mbt_fps.rst diff --git a/docs/source/projections/mbt_s.rst b/docs/source/usage/operations/projections/mbt_s.rst similarity index 100% rename from docs/source/projections/mbt_s.rst rename to docs/source/usage/operations/projections/mbt_s.rst diff --git a/docs/source/projections/mbtfpp.rst b/docs/source/usage/operations/projections/mbtfpp.rst similarity index 100% rename from docs/source/projections/mbtfpp.rst rename to docs/source/usage/operations/projections/mbtfpp.rst diff --git a/docs/source/projections/mbtfpq.rst b/docs/source/usage/operations/projections/mbtfpq.rst similarity index 100% rename from docs/source/projections/mbtfpq.rst rename to docs/source/usage/operations/projections/mbtfpq.rst diff --git a/docs/source/projections/mbtfps.rst b/docs/source/usage/operations/projections/mbtfps.rst similarity index 100% rename from docs/source/projections/mbtfps.rst rename to docs/source/usage/operations/projections/mbtfps.rst diff --git a/docs/source/projections/merc.rst b/docs/source/usage/operations/projections/merc.rst similarity index 100% rename from docs/source/projections/merc.rst rename to docs/source/usage/operations/projections/merc.rst diff --git a/docs/source/projections/mil_os.rst b/docs/source/usage/operations/projections/mil_os.rst similarity index 100% rename from docs/source/projections/mil_os.rst rename to docs/source/usage/operations/projections/mil_os.rst diff --git a/docs/source/projections/mill.rst b/docs/source/usage/operations/projections/mill.rst similarity index 100% rename from docs/source/projections/mill.rst rename to docs/source/usage/operations/projections/mill.rst diff --git a/docs/source/projections/moll.rst b/docs/source/usage/operations/projections/moll.rst similarity index 100% rename from docs/source/projections/moll.rst rename to docs/source/usage/operations/projections/moll.rst diff --git a/docs/source/projections/murd1.rst b/docs/source/usage/operations/projections/murd1.rst similarity index 100% rename from docs/source/projections/murd1.rst rename to docs/source/usage/operations/projections/murd1.rst diff --git a/docs/source/projections/murd2.rst b/docs/source/usage/operations/projections/murd2.rst similarity index 100% rename from docs/source/projections/murd2.rst rename to docs/source/usage/operations/projections/murd2.rst diff --git a/docs/source/projections/murd3.rst b/docs/source/usage/operations/projections/murd3.rst similarity index 100% rename from docs/source/projections/murd3.rst rename to docs/source/usage/operations/projections/murd3.rst diff --git a/docs/source/projections/natearth.rst b/docs/source/usage/operations/projections/natearth.rst similarity index 100% rename from docs/source/projections/natearth.rst rename to docs/source/usage/operations/projections/natearth.rst diff --git a/docs/source/projections/nell.rst b/docs/source/usage/operations/projections/nell.rst similarity index 100% rename from docs/source/projections/nell.rst rename to docs/source/usage/operations/projections/nell.rst diff --git a/docs/source/projections/nell_h.rst b/docs/source/usage/operations/projections/nell_h.rst similarity index 100% rename from docs/source/projections/nell_h.rst rename to docs/source/usage/operations/projections/nell_h.rst diff --git a/docs/source/projections/nicol.rst b/docs/source/usage/operations/projections/nicol.rst similarity index 100% rename from docs/source/projections/nicol.rst rename to docs/source/usage/operations/projections/nicol.rst diff --git a/docs/source/projections/nsper.rst b/docs/source/usage/operations/projections/nsper.rst similarity index 100% rename from docs/source/projections/nsper.rst rename to docs/source/usage/operations/projections/nsper.rst diff --git a/docs/source/projections/nzmg.rst b/docs/source/usage/operations/projections/nzmg.rst similarity index 100% rename from docs/source/projections/nzmg.rst rename to docs/source/usage/operations/projections/nzmg.rst diff --git a/docs/source/projections/ob_tran.rst b/docs/source/usage/operations/projections/ob_tran.rst similarity index 100% rename from docs/source/projections/ob_tran.rst rename to docs/source/usage/operations/projections/ob_tran.rst diff --git a/docs/source/projections/ocea.rst b/docs/source/usage/operations/projections/ocea.rst similarity index 100% rename from docs/source/projections/ocea.rst rename to docs/source/usage/operations/projections/ocea.rst diff --git a/docs/source/projections/oea.rst b/docs/source/usage/operations/projections/oea.rst similarity index 100% rename from docs/source/projections/oea.rst rename to docs/source/usage/operations/projections/oea.rst diff --git a/docs/source/projections/omerc.rst b/docs/source/usage/operations/projections/omerc.rst similarity index 100% rename from docs/source/projections/omerc.rst rename to docs/source/usage/operations/projections/omerc.rst diff --git a/docs/source/projections/ortel.rst b/docs/source/usage/operations/projections/ortel.rst similarity index 100% rename from docs/source/projections/ortel.rst rename to docs/source/usage/operations/projections/ortel.rst diff --git a/docs/source/projections/ortho.rst b/docs/source/usage/operations/projections/ortho.rst similarity index 100% rename from docs/source/projections/ortho.rst rename to docs/source/usage/operations/projections/ortho.rst diff --git a/docs/source/projections/pconic.rst b/docs/source/usage/operations/projections/pconic.rst similarity index 100% rename from docs/source/projections/pconic.rst rename to docs/source/usage/operations/projections/pconic.rst diff --git a/docs/source/projections/poly.rst b/docs/source/usage/operations/projections/poly.rst similarity index 100% rename from docs/source/projections/poly.rst rename to docs/source/usage/operations/projections/poly.rst diff --git a/docs/source/projections/putp1.rst b/docs/source/usage/operations/projections/putp1.rst similarity index 100% rename from docs/source/projections/putp1.rst rename to docs/source/usage/operations/projections/putp1.rst diff --git a/docs/source/projections/putp2.rst b/docs/source/usage/operations/projections/putp2.rst similarity index 100% rename from docs/source/projections/putp2.rst rename to docs/source/usage/operations/projections/putp2.rst diff --git a/docs/source/projections/putp3.rst b/docs/source/usage/operations/projections/putp3.rst similarity index 100% rename from docs/source/projections/putp3.rst rename to docs/source/usage/operations/projections/putp3.rst diff --git a/docs/source/projections/putp3p.rst b/docs/source/usage/operations/projections/putp3p.rst similarity index 100% rename from docs/source/projections/putp3p.rst rename to docs/source/usage/operations/projections/putp3p.rst diff --git a/docs/source/projections/putp4p.rst b/docs/source/usage/operations/projections/putp4p.rst similarity index 100% rename from docs/source/projections/putp4p.rst rename to docs/source/usage/operations/projections/putp4p.rst diff --git a/docs/source/projections/putp5.rst b/docs/source/usage/operations/projections/putp5.rst similarity index 100% rename from docs/source/projections/putp5.rst rename to docs/source/usage/operations/projections/putp5.rst diff --git a/docs/source/projections/putp5p.rst b/docs/source/usage/operations/projections/putp5p.rst similarity index 100% rename from docs/source/projections/putp5p.rst rename to docs/source/usage/operations/projections/putp5p.rst diff --git a/docs/source/projections/putp6.rst b/docs/source/usage/operations/projections/putp6.rst similarity index 100% rename from docs/source/projections/putp6.rst rename to docs/source/usage/operations/projections/putp6.rst diff --git a/docs/source/projections/putp6p.rst b/docs/source/usage/operations/projections/putp6p.rst similarity index 100% rename from docs/source/projections/putp6p.rst rename to docs/source/usage/operations/projections/putp6p.rst diff --git a/docs/source/projections/qsc.rst b/docs/source/usage/operations/projections/qsc.rst similarity index 94% rename from docs/source/projections/qsc.rst rename to docs/source/usage/operations/projections/qsc.rst index dedd6ff4de..e3af2cee05 100644 --- a/docs/source/projections/qsc.rst +++ b/docs/source/usage/operations/projections/qsc.rst @@ -23,7 +23,7 @@ Quadrilateralized Spherical Cube The purpose of the Quadrilateralized Spherical Cube (QSC) projection is to project a sphere surface onto the six sides of a cube: -.. image:: ../../images/qsc_concept.jpg +.. image:: ../../../../images/qsc_concept.jpg :scale: 50% :align: center :alt: Quadrilateralized Spherical Cube @@ -112,32 +112,32 @@ Explanation: The resulting images can be laid out in a grid like below. -.. |topside| image:: ../../images/qsc_topside.jpg +.. |topside| image:: ../../../../images/qsc_topside.jpg :scale: 50% :align: middle :alt: Top side -.. |leftside| image:: ../../images/qsc_leftside.jpg +.. |leftside| image:: ../../../../images/qsc_leftside.jpg :scale: 50% :align: middle :alt: Left side -.. |frontside| image:: ../../images/qsc_frontside.jpg +.. |frontside| image:: ../../../../images/qsc_frontside.jpg :scale: 50% :align: middle :alt: Front side -.. |rightside| image:: ../../images/qsc_rightside.jpg +.. |rightside| image:: ../../../../images/qsc_rightside.jpg :scale: 50% :align: middle :alt: Right side -.. |backside| image:: ../../images/qsc_backside.jpg +.. |backside| image:: ../../../../images/qsc_backside.jpg :scale: 50% :align: middle :alt: Back side -.. |bottomside| image:: ../../images/qsc_bottomside.jpg +.. |bottomside| image:: ../../../../images/qsc_bottomside.jpg :scale: 50% :align: middle :alt: Bottom side diff --git a/docs/source/projections/qua_aut.rst b/docs/source/usage/operations/projections/qua_aut.rst similarity index 100% rename from docs/source/projections/qua_aut.rst rename to docs/source/usage/operations/projections/qua_aut.rst diff --git a/docs/source/projections/rhealpix.rst b/docs/source/usage/operations/projections/rhealpix.rst similarity index 98% rename from docs/source/projections/rhealpix.rst rename to docs/source/usage/operations/projections/rhealpix.rst index 1701558e05..5808cfaaad 100644 --- a/docs/source/projections/rhealpix.rst +++ b/docs/source/usage/operations/projections/rhealpix.rst @@ -21,7 +21,7 @@ rHEALPix | | Valid inputs are 0--3. Defaults to 0. | +---------------------+----------------------------------------------------------+ -.. image:: ../../images/rhealpix.png +.. image:: ../../../../images/rhealpix.png :scale: 75% :alt: rHEALPix diff --git a/docs/source/projections/robin.rst b/docs/source/usage/operations/projections/robin.rst similarity index 100% rename from docs/source/projections/robin.rst rename to docs/source/usage/operations/projections/robin.rst diff --git a/docs/source/projections/rouss.rst b/docs/source/usage/operations/projections/rouss.rst similarity index 100% rename from docs/source/projections/rouss.rst rename to docs/source/usage/operations/projections/rouss.rst diff --git a/docs/source/projections/rpoly.rst b/docs/source/usage/operations/projections/rpoly.rst similarity index 100% rename from docs/source/projections/rpoly.rst rename to docs/source/usage/operations/projections/rpoly.rst diff --git a/docs/source/projections/sinu.rst b/docs/source/usage/operations/projections/sinu.rst similarity index 100% rename from docs/source/projections/sinu.rst rename to docs/source/usage/operations/projections/sinu.rst diff --git a/docs/source/projections/somerc.rst b/docs/source/usage/operations/projections/somerc.rst similarity index 100% rename from docs/source/projections/somerc.rst rename to docs/source/usage/operations/projections/somerc.rst diff --git a/docs/source/projections/stere.rst b/docs/source/usage/operations/projections/stere.rst similarity index 100% rename from docs/source/projections/stere.rst rename to docs/source/usage/operations/projections/stere.rst diff --git a/docs/source/projections/sterea.rst b/docs/source/usage/operations/projections/sterea.rst similarity index 100% rename from docs/source/projections/sterea.rst rename to docs/source/usage/operations/projections/sterea.rst diff --git a/docs/source/projections/tcc.rst b/docs/source/usage/operations/projections/tcc.rst similarity index 100% rename from docs/source/projections/tcc.rst rename to docs/source/usage/operations/projections/tcc.rst diff --git a/docs/source/projections/tcea.rst b/docs/source/usage/operations/projections/tcea.rst similarity index 100% rename from docs/source/projections/tcea.rst rename to docs/source/usage/operations/projections/tcea.rst diff --git a/docs/source/projections/tissot.rst b/docs/source/usage/operations/projections/tissot.rst similarity index 100% rename from docs/source/projections/tissot.rst rename to docs/source/usage/operations/projections/tissot.rst diff --git a/docs/source/projections/tmerc.rst b/docs/source/usage/operations/projections/tmerc.rst similarity index 100% rename from docs/source/projections/tmerc.rst rename to docs/source/usage/operations/projections/tmerc.rst diff --git a/docs/source/projections/tpeqd.rst b/docs/source/usage/operations/projections/tpeqd.rst similarity index 100% rename from docs/source/projections/tpeqd.rst rename to docs/source/usage/operations/projections/tpeqd.rst diff --git a/docs/source/projections/tpers.rst b/docs/source/usage/operations/projections/tpers.rst similarity index 100% rename from docs/source/projections/tpers.rst rename to docs/source/usage/operations/projections/tpers.rst diff --git a/docs/source/projections/ups.rst b/docs/source/usage/operations/projections/ups.rst similarity index 100% rename from docs/source/projections/ups.rst rename to docs/source/usage/operations/projections/ups.rst diff --git a/docs/source/projections/urm5.rst b/docs/source/usage/operations/projections/urm5.rst similarity index 100% rename from docs/source/projections/urm5.rst rename to docs/source/usage/operations/projections/urm5.rst diff --git a/docs/source/projections/urmfps.rst b/docs/source/usage/operations/projections/urmfps.rst similarity index 100% rename from docs/source/projections/urmfps.rst rename to docs/source/usage/operations/projections/urmfps.rst diff --git a/docs/source/projections/utm.rst b/docs/source/usage/operations/projections/utm.rst similarity index 100% rename from docs/source/projections/utm.rst rename to docs/source/usage/operations/projections/utm.rst diff --git a/docs/source/projections/vandg.rst b/docs/source/usage/operations/projections/vandg.rst similarity index 100% rename from docs/source/projections/vandg.rst rename to docs/source/usage/operations/projections/vandg.rst diff --git a/docs/source/projections/vandg2.rst b/docs/source/usage/operations/projections/vandg2.rst similarity index 100% rename from docs/source/projections/vandg2.rst rename to docs/source/usage/operations/projections/vandg2.rst diff --git a/docs/source/projections/vandg3.rst b/docs/source/usage/operations/projections/vandg3.rst similarity index 100% rename from docs/source/projections/vandg3.rst rename to docs/source/usage/operations/projections/vandg3.rst diff --git a/docs/source/projections/vandg4.rst b/docs/source/usage/operations/projections/vandg4.rst similarity index 100% rename from docs/source/projections/vandg4.rst rename to docs/source/usage/operations/projections/vandg4.rst diff --git a/docs/source/projections/vitk1.rst b/docs/source/usage/operations/projections/vitk1.rst similarity index 100% rename from docs/source/projections/vitk1.rst rename to docs/source/usage/operations/projections/vitk1.rst diff --git a/docs/source/projections/wag1.rst b/docs/source/usage/operations/projections/wag1.rst similarity index 100% rename from docs/source/projections/wag1.rst rename to docs/source/usage/operations/projections/wag1.rst diff --git a/docs/source/projections/wag2.rst b/docs/source/usage/operations/projections/wag2.rst similarity index 100% rename from docs/source/projections/wag2.rst rename to docs/source/usage/operations/projections/wag2.rst diff --git a/docs/source/projections/wag3.rst b/docs/source/usage/operations/projections/wag3.rst similarity index 100% rename from docs/source/projections/wag3.rst rename to docs/source/usage/operations/projections/wag3.rst diff --git a/docs/source/projections/wag4.rst b/docs/source/usage/operations/projections/wag4.rst similarity index 100% rename from docs/source/projections/wag4.rst rename to docs/source/usage/operations/projections/wag4.rst diff --git a/docs/source/projections/wag5.rst b/docs/source/usage/operations/projections/wag5.rst similarity index 100% rename from docs/source/projections/wag5.rst rename to docs/source/usage/operations/projections/wag5.rst diff --git a/docs/source/projections/wag6.rst b/docs/source/usage/operations/projections/wag6.rst similarity index 100% rename from docs/source/projections/wag6.rst rename to docs/source/usage/operations/projections/wag6.rst diff --git a/docs/source/projections/wag7.rst b/docs/source/usage/operations/projections/wag7.rst similarity index 100% rename from docs/source/projections/wag7.rst rename to docs/source/usage/operations/projections/wag7.rst diff --git a/docs/source/projections/weren.rst b/docs/source/usage/operations/projections/weren.rst similarity index 100% rename from docs/source/projections/weren.rst rename to docs/source/usage/operations/projections/weren.rst diff --git a/docs/source/projections/wink1.rst b/docs/source/usage/operations/projections/wink1.rst similarity index 100% rename from docs/source/projections/wink1.rst rename to docs/source/usage/operations/projections/wink1.rst diff --git a/docs/source/projections/wink2.rst b/docs/source/usage/operations/projections/wink2.rst similarity index 100% rename from docs/source/projections/wink2.rst rename to docs/source/usage/operations/projections/wink2.rst diff --git a/docs/source/projections/wintri.rst b/docs/source/usage/operations/projections/wintri.rst similarity index 100% rename from docs/source/projections/wintri.rst rename to docs/source/usage/operations/projections/wintri.rst diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst new file mode 100644 index 0000000000..03e5db15ba --- /dev/null +++ b/docs/source/usage/operations/transformations/helmert.rst @@ -0,0 +1,388 @@ +.. _helmert: + +================================================================================ +Helmert transform +================================================================================ + +The Helmert transformation changes coordinates from one reference frame to +anoether by means of 3-, 4-and 7-parameter shifts, or one of their 6-, 8- and +14-parameter kinematic counterparts. + ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Options** | ++----------------+--------------------------------------------------------------------+ +| `x` | Translation of the x-axis [m]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `y` | Translation of the y-axis [m]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `z` | Translation of the z-axis. [m]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `s` | Scale factor [ppm]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `rx` | X-axis rotation in the 3D Helmert [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `ry` | Y-axis rotatoin in the 3D Helmert [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `rz` | Z-axis rotation in the 3D Helmert [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `theta` | Rotation angle in the 2D Helmert. [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dx` | Translation rate of the x-axis. [m/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dy` | Translation rate of the y-axis. [m/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dz` | Translation rate of the z-axis. [m/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `ds` | Scale rate factor [ppm/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `drx` | Rotation rate of the x-axis [arc seconds/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dry` | Rotation rate of the y-axis [arc seconds/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `drz` | Rotation rate of the y-axis [arc seconds/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `t_epoch` | Central epoch of transformation. [decimalyear]. Only used in | +| | spatiotemporal transformations. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `t_obs` | Observation time of coordinate(s). Mostly useful in 2D and 3D | +| | transformations. [decimalyear]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `exact` | Use exact transformation equations. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `transpose` | Transpose rotation matrix. *Optional*. | ++----------------+--------------------------------------------------------------------+ + +The Helmert transform, in all it's various incarnations, is used to perform reference +frame shifts. The transformation operates in cartesian space. It can be used to transform +planar coordinates from one datum to another, transform 3D cartesian +coordinates from one static reference frame to another or it can be used to do fully +kinematic transformations from global reference frames to local static frames. + +All of the parameters described in the table above are marked as optional. This is true +as long as at least one parameter is defined in the setup of the transformation. +The behaviour of the transformation depends on which parameters are used in the setup. +For instance, if a rate of change paramater is specified a kinematic version of the +transformation is used. + +The kinematic transformations require an observation time of the coordinate, as well +as a central epoch for the transformation. The latter is usually documented +alongside the rest of the transformation parameters for a given transformation. +The central eopch is controlled with the parameter `t_epoch`. The observation +time can either by stated as part of the coordinate when using PROJ's +4D-functionality or it can be controlled in the transformation setup by the +parameter `t_obs`. When `t_obs` is specified, all transformed coordinates are +treated as if they have the same observation time. + +Examples ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert: + +:: + + proj=helmert ellps=GRS80 x=-9597.3572 y=.6112 + s=0.304794780637 theta=-1.244048 + +Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters: + +:: + + proj=helmert ellps=GRS80 x=0.67678 y=0.65495 z=-0.52827 + rx=-0.022742 ry=0.012667 rz=0.022704 s=-0.01070 + +Transformation from `ITRF2000@2017.0` to `ITRF93@2017.0` using 15 parameters: + +:: + + proj=helmert ellps=GRS80 + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + rx=-0.00039 ry=0.00080 rz=-0.00114 + drx=-0.00011 dry=-0.00019 drz=0.00007 + epoch=1988.0 tobs=2017.0 transpose + +Mathematical description ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In the notation used below, :math:`\hat{P}` is the rate of change of a given transformation +parameter :math:`P`. :math:`\dot{P}` is the kinematically adjusted version of :math:`P`, +described by + +.. math:: + :label: propagation + + \dot{P}= P + \hat{P}\left(t - t_{central}\right) + +where :math:`t` is the observation time of the coordinate and :math:`t_{central}` is +the central epoch of the transformation. Equation :eq:`propagation` can be used to +propagate all transformation parameters in time. + +Superscripts of vectors denote the reference frame the coordinates in the vector belong to. + + +2D Helmert +------------------------------------------------------------------------------- + +The simplest version of the Helmert transform is the 2D case. In the 2-dimensional +case only the horizontal coordinates are changed. The coordinates can be +translated, rotated and scale. Translation is controlled with the `x` and `y` +parameters. The rotation is determined by `theta` and the scale is controlled with +the `s` paramaters. + +.. note:: + + The scaling parameter `s` is unitless for the 2D Helmert, as opposed to the + 3D version where the scaling parameter is given in units of ppm. + +Mathematically the 2D Helmert is described as: + +.. math:: + :label: 4param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + \end{bmatrix} + + s + \begin{bmatrix} + \hphantom{-}\cos \theta & \sin \theta \\ + -\sin \theta & \cos \theta \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + + +:eq:`4param` can be extended to a time-varying kinematic version by +adjusting the parameters with :eq:`propagation` to :eq:`4param`, which yields +the kinematic 2D Helmert transform: + +.. math:: + :label: 8param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \end{bmatrix} + + s(t) + \begin{bmatrix} + \hphantom{-}\cos \dot{\theta} & \sin \dot{\theta} \\ + -\sin\ \dot{\theta} & \cos \dot{\theta} \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + +All parameters in :eq:`8param` are determined by the use of :eq:`propagation`, +which applies the rate of change to each individual parameter for a given +timespan between :math:`t` and :math:`t_{central}`. + + +3D Helmert +------------------------------------------------------------------------------- + +The general form of the 3D Helmert is + +.. math:: + :label: general-helmert + + + \begin{align} + V^B = T + \left(1 + s \times 10^{-6}\right) \mathbf{R} V^A + \end{align} + +Where :math:`T` is a vector consisting of the three translation parameters, :math:`s` +is the scaling factor and :math:`\mathbf{R}` is a rotation matrix. :math:`V^A` and +:math:`V^B` are coordinate vectors, with :math:`V^A` being the input coordinate and +:math:`V^B` is the output coordinate. + +The rotation matrix is composed of three rotation matrices, one for each axis: + +.. math:: + + \begin{align} + \mathbf{R}_X &= \begin{bmatrix} 1 & 0 & 0\\ 0 & \cos\phi & -\sin\phi\\ 0 & \sin\phi & \cos\phi \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Y &= \begin{bmatrix} \cos\theta & 0 & \sin\theta\\ 0 & 1 & 0\\ -\sin\theta & 0 & \cos\theta \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Z &= \begin{bmatrix} \cos\psi & -\sin\psi & 0\\ \sin\psi & \cos\psi & 0\\ 0 & 0 & 1 \end{bmatrix} + \end{align} + +The three rotation matrices can be combined in one: + +.. math:: + + \begin{align} + \mathbf{R} = \mathbf{R_X} \mathbf{R_Y} \mathbf{R_Y} + \end{align} + +For :math:`\mathbf{R}`, this yields: + +.. math:: + :label: rot_exact + + \begin{bmatrix} + \cos\theta \cos\psi & -\cos\phi \sin\psi + \sin\phi \sin\theta \cos\psi & \sin\phi \sin\psi + \cos\phi \sin\theta \cos\psi \\ + \cos\theta\sin\psi & \cos\phi \cos\psi + \sin\phi \sin\theta \sin\psi & - \sin\phi \cos\psi + \cos\phi \sin\theta \sin\psi \\ + -\sin\theta & \sin\phi \cos\theta & \cos\phi \cos\theta \\ + \end{bmatrix} + + +Using the small angle approxition the rotation matrix can be simplified to + +.. math:: + :label: rot_approx + + \begin{align} \mathbf{R} = + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \end{align} + +Which allow us to express the most common version of the Helmert transform, +using the approximated rotation matrix: + + +.. math:: + :label: 7param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \left(1 + s \times 10^{-6}\right) + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +If the rotation matrix is transposed the transformation is effectively reversed. +This is cause for some confusion since there is no correct way of defining the +rotation matrix. Two conventions exists and they seem to be equally popular. +In PROJ the rotation matrix can be transposed by adding the `transpose` flag in +the transformation setup. + +Applying :eq:`propagation` we get the kinematic version of the approximated +3D Helmert: + +.. math:: + :label: 14param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \left(1 + \dot{s} \times 10^{-6}\right) + \begin{bmatrix} + 1 & -\dot{R_z} & \dot{R_y} \\ + \dot{R_z} & 1 & -\dot{R_x} \\ + -\dot{R_y} & \dot{R_x} & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + + + + +The Helmert transformation can be applied without using the rotation parameters, +in which case it becomes a simlpe translation of the origin of the coordinate +system. When using the Helmert in this version equation :eq:`general-helmert` +simplies to: + +.. math:: + :label: 3param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +That after application of :eq:`propagation` has the following kinematic +countpart: + +.. math:: + :label: 6param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} diff --git a/docs/source/usage/operations/transformations/hgridshift.rst b/docs/source/usage/operations/transformations/hgridshift.rst new file mode 100644 index 0000000000..bd147c2f73 --- /dev/null +++ b/docs/source/usage/operations/transformations/hgridshift.rst @@ -0,0 +1,36 @@ +.. _hgridshift: + +================================================================================ +Horizontal grid shift +================================================================================ + +Change of horizontal datum by grid shift. + ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `+grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ + +The horizontal grid shift is done by offsetting the planar input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid:: + + +hgridshift +grids=nzgr2kgrid0005.gsb + + +More than one grid can be loaded at the same time, for instance in case the +dataset needs to be transformed spans several countries. In this example grids +of the continental US, Alaska and Canada is loaded at the same time:: + + +hgridshift +grids=@conus,@alaska,@ntv2_0.gsb,@ntv_can.dat + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ.4 search path. The list of grids is prioritized so that +grids in the start of the list takes presedence over the grids in the back of the +list. + diff --git a/docs/source/usage/operations/transformations/index.rst b/docs/source/usage/operations/transformations/index.rst new file mode 100644 index 0000000000..112d9220fb --- /dev/null +++ b/docs/source/usage/operations/transformations/index.rst @@ -0,0 +1,16 @@ +.. _transformation_list: + +================================================================================ +Transformations +================================================================================ + +Transformations coordinate operation in which the two coordinate reference +systems are based on different datums. + +.. toctree:: + :maxdepth: 1 + + helmert + molodensky + hgridshift + vgridshift diff --git a/docs/source/usage/operations/transformations/molodensky.rst b/docs/source/usage/operations/transformations/molodensky.rst new file mode 100644 index 0000000000..d4ff3e7923 --- /dev/null +++ b/docs/source/usage/operations/transformations/molodensky.rst @@ -0,0 +1,74 @@ +.. _molodensky: + +================================================================================ +Molodensky transform +================================================================================ + +The Molodensky transformation resembles a :ref:`Helmert` with zero +rotations and a scale of unity, but converts directly from geodetic coordinates to +geodetic coordinates, without the intermediate shifts to and from cartesian +geocentric coordinates, associated with the Helmert transformation. +The Molodensky transformation is simple to implement and to parameterize, requiring +only the 3 shifts between the input and output frame, and the corresponding +differences between the semimajor axes and flattening parameters of the reference +ellipsoids. Due to its algorithmic simplicity, it was popular prior to the +ubiquity of digital computers. Today, it is mostly interesting for historical +reasons, but nevertheless indispensable due to the large amount of data that has +already been transformed that way [EversKnudsen2017]_. + ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates. | ++---------------------+----------------------------------------------------------+ +| **Output type** | Geodetic coordinates. | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+da` | Difference in semimajor axis of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+df` | Difference in flattening of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+dx` | Offset of the X-axes of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+dy` | Offset of the Y-axes of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+dz` | Offset of the Z-axes of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+ellps` | Ellipsoid definition of source coordinates. | +| | Any specification can be used (e.g. `+a`, `+rf`, etc). | +|   | If not specified, default ellipsoid is used. | ++---------------------+----------------------------------------------------------+ +| `+abridged` | Use the abridged version of the Molodensky transform. | +| | Optional. | ++---------------------+----------------------------------------------------------+ + +The Molodensky transform can be used to perform a datum shift from coordinate +:math:`(\phi_1, \lambda_1, h_1)` to :math:`(\phi_2, \lambda_2, h_2)` where the two +coordinates are referenced to different ellipsoids. This is based on three +assumptions: + + 1. The cartesian axes, :math:`X, Y, Z`, of the two ellipsoids are parallel. + 2. The offset, :math:`\delta X, \delta Y, \delta Z`, between the two ellipsoid + are known. + 3. The characteristics of the two ellipsoids, expressed as the difference in + semimajor axis (:math:`\delta a`) and flattening (:math:`\delta f`), are known. + +The Molodensky transform is mostly used for transforming between old systems +dating back to the time before computers. The advantage of the Molodensky transform +is that it is fairly simple to compute by hand. The ease of computation come at the +cost of limited accuracy. + +A derivation of the mathematical formulas for the Molodensky transform can be found +in [Deakin2004]_. + + +Examples +############################################################################### + +The abridged Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 abridged + +The same transformation using the standard Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 + diff --git a/docs/source/usage/operations/transformations/vgridshift.rst b/docs/source/usage/operations/transformations/vgridshift.rst new file mode 100644 index 0000000000..272b24abab --- /dev/null +++ b/docs/source/usage/operations/transformations/vgridshift.rst @@ -0,0 +1,38 @@ +.. _vgridshift: + +================================================================================ +Vertical grid shift +================================================================================ + +Change Vertical datum change by grid shift + ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical). | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates (horizontal), meters (vertical). | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `+grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ + +The vertical grid shift is done by offsetting the vertical input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid. Here we change the vertical +reference from the ellipsoid to the global geoid model, EGM96:: + + +vgridshift +grids=egm96_16.gtx + + +More than one grid can be loaded at the same time, for instance in the case where +a better geoid model than the global is available for a certain area. Here the +gridshift is set up so that the local DVR90 geoid model takes presedence over +the global model:: + + +vgridshift +grids=@dvr90.gtx,egm96_16.gtx + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ.4 search path. The list of grids is prioritized so that +grids in the start of the list takes presedence over the grids in the back of the +list. + diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst new file mode 100644 index 0000000000..8f0b358698 --- /dev/null +++ b/docs/source/usage/projections.rst @@ -0,0 +1,164 @@ +.. _projections_intro: + +================================================================================ +Cartographic projection +================================================================================ + +The foundation of PROJ.4 is the large number of +:doc:`projections` available in the library. This section +is devoted to the generic parameters that can be used on any projection in the +PROJ.4 library. + +Below is a list of PROJ.4 parameters which can be applied to most coordinate +system definitions. This table does not attempt to describe the parameters +particular to particular projection types. These can be found on the pages +documenting the individual :doc:`projections`. + + ========== ================================================================ + Parameter Description + ========== ================================================================ + +a Semimajor radius of the ellipsoid axis + +axis Axis orientation + +b Semiminor radius of the ellipsoid axis + +ellps Ellipsoid name (see ``proj -le``) + +k Scaling factor (deprecated) + +k_0 Scaling factor + +lat_0 Latitude of origin + +lon_0 Central meridian + +lon_wrap Center longitude to use for wrapping (see below) + +no_defs Don't use the /usr/share/proj/proj_def.dat defaults file + +over Allow longitude output outside -180 to 180 range, disables + wrapping (see below) + +pm Alternate prime meridian (typically a city name, see below) + +proj Projection name (see ``proj -l``) + +units meters, US survey feet, etc. + +vunits vertical units. + +x_0 False easting + +y_0 False northing + ========== ================================================================ + +In the sections below most of the parameters are explained in details. + +Units ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Horizontal units can be specified using the ``+units`` keyword with a symbolic +name for a unit (ie. ``us-ft``). Alternatively the translation to meters can be +specified with the ``+to_meter`` keyword (ie. 0.304800609601219 for US feet). The +``-lu`` argument to ``cs2cs`` or ``proj`` can be used to list symbolic unit names. +The default unit for projected coordinates is the meter. +A few special projections deviate from this behaviour, most notably the +latlong pseudo-projection that returns degrees. + +Vertical (Z) units can be specified using the ``+vunits`` keyword with a +symbolic name for a unit (ie. ``us-ft``). Alternatively the translation to +meters can be specified with the ``+vto_meter`` keyword (ie. 0.304800609601219 +for US feet). The ``-lu`` argument to ``cs2cs`` or ``proj`` can be used to list +symbolic unit names. If no vertical units are specified, the vertical units will +default to be the same as the horizontal coordinates. + +.. note:: + ``proj`` do not handle vertical units at all and hence the ``+vto_meter`` + argument will be ignored. + +Scaling of output units can be done by applying the ``+k_0`` argument. The +returned coordinates are scaled by the value assigned with the ``+k_0`` +parameter. + +False Easting/Northing ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Virtually all coordinate systems allow for the presence of a false easting +(``+x_0``) and northing (``+y_0``). Note that these values are always expressed in +meters even if the coordinate system is some other units. Some coordinate +systems (such as UTM) have implicit false easting and northing values. + +Longitude Wrapping ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +By default PROJ.4 wraps output longitudes in the range -180 to 180. The ``+over`` +switch can be used to disable the default wrapping which is done at a low level +in ``pj_inv()``. This is particularly useful with projections like the +:doc:`equidistant cylindrical` +where it would be desirable for X values past -20000000 (roughly) to continue +past -180 instead of wrapping to +180. + +The ``+lon_wrap`` option can be used to provide an alternative means of doing +longitude wrapping within ``pj_transform()``. The argument to this option is a +center longitude. So ``+lon_wrap=180`` means wrap longitudes in the range 0 to +360. Note that ``+over`` does **not** disable ``+lon_wrap``. + +Prime Meridian ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +A prime meridian may be declared indicating the offset between the prime +meridian of the declared coordinate system and that of greenwich. A prime +meridian is clared using the "pm" parameter, and may be assigned a symbolic +name, or the longitude of the alternative prime meridian relative to greenwich. + +Currently prime meridian declarations are only utilized by the +``pj_transform()`` API call, not the ``pj_inv()`` and ``pj_fwd()`` calls. +Consequently the user utility ``cs2cs`` does honour prime meridians but the +``proj`` user utility ignores them. + +The following predeclared prime meridian names are supported. These can be +listed using with ``cs2cs -lm``. + + =========== ================ + Meridian Longitude + =========== ================ + greenwich 0dE + lisbon 9d07'54.862"W + paris 2d20'14.025"E + bogota 74d04'51.3"E + madrid 3d41'16.48"W + rome 12d27'8.4"E + bern 7d26'22.5"E + jakarta 106d48'27.79"E + ferro 17d40'W + brussels 4d22'4.71"E + stockholm 18d3'29.8"E + athens 23d42'58.815"E + oslo 10d43'22.5"E + =========== ================ + +Example of use. The location ``long=0``, ``lat=0`` in the greenwich based lat/long +coordinates is translated to lat/long coordinates with Madrid as the prime +meridian. + +:: + + cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid + 0 0 (input) + 3d41'16.48"E 0dN 0.000 (output) + + +Axis orientation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Starting in PROJ 4.8.0, the +axis argument can be used to control the axis +orientation of the coordinate system. The default orientation is "easting, +northing, up" but directions can be flipped, or axes flipped using combinations +of the axes in the +axis switch. The values are: + +* "e" - Easting +* "w" - Westing +* "n" - Northing +* "s" - Southing +* "u" - Up +* "d" - Down + +They can be combined in +axis in forms like: + +* ``+axis=enu`` - the default easting, northing, elevation. +* ``+axis=neu`` - northing, easting, up - useful for "lat/long" geographic + coordinates, or south orientated transverse mercator. +* ``+axis=wnu`` - westing, northing, up - some planetary coordinate systems + have "west positive" coordinate systems + +.. note:: + + The ``+axis`` argument does not work with the ``proj`` command line + utility. + + diff --git a/docs/source/usage/quickstart.rst b/docs/source/usage/quickstart.rst new file mode 100644 index 0000000000..96bfbba1fe --- /dev/null +++ b/docs/source/usage/quickstart.rst @@ -0,0 +1,68 @@ +.. _quickstart: + +================================================================================ +Quick start +================================================================================ + +Coordinate transformations are defined by, what in PROJ.4 terminology is +known as, "proj-strings". A proj-string describes any transformation regardless of +how simple or complicated it might be. The simplest case is projection of geodetic +coordinates. This section focuses on the simpler cases and introduces the basic +anatomy of the proj-string. The complex cases are discussed in +:doc:`transformation`. + +A proj-strings holds the parameters of a given coordinate transformation, e.g. + +:: + + +proj=merc +lat_ts=56.5 +ellps=GRS80 + +I.e. a proj-string consists of a projection specifier, ``+proj``, a number of +parameters that applies to the projection and, if needed, a description of a +datum shift. In the example above geodetic coordinates are transformed to +projected space with the :doc:`Mercator projection` with +the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every +projection in PROJ.4 is identified by a shorthand such as ``merc`` in the above +example. + +By using the above projection definition as parameters for the command line +utility ``proj`` we can convert the geodetic coordinates to projected space: + +:: + + $ proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + +If called as above ``proj`` will be in interactive mode, letting you type the +input data manually and getting a responce presented on screen. ``proj`` +works as any UNIX filter though, which means that you can also pipe data to +the utility, for instance by using the ``echo`` command: + +:: + + $ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + 3399483.80 752085.60 + + +PROJ.4 also comes bundled with the ``cs2cs`` utility which is used to transform +from onecoordinate reference system to another. Say we want to convert +the above Mercator coordinates to UTM, we can do that with ``cs2cs``: + +:: + + $ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to +proj=utm +zone=32 + 6103992.36 1924052.47 0.00 + +Notice the ``+to`` parameter that seperates the source and destination +projection definitions. + +If you happen to know the EPSG identifiers for the two cordinates reference +systems you are transforming between you can use those with ``cs2cs``: + +:: + + $ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832 + 231950.54 1920310.71 0.00 + +In the above example we transform geodetic coordinates in the WGS84 reference +frame to UTM zone 32N coordinates in the ETRS89 reference frame. +UTM coordinates diff --git a/docs/source/usage/resource_files.rst b/docs/source/usage/resource_files.rst new file mode 100644 index 0000000000..9a2028792b --- /dev/null +++ b/docs/source/usage/resource_files.rst @@ -0,0 +1,121 @@ +.. _resource_files: + +================================================================================ +Resource files +================================================================================ + +A number of files containing preconfigured transformations and default parameters +for certain projections are bundled with the PROJ.4 distribution. Init files +contains preconfigured proj-strings for various coordinate reference systems +and the defaults file contains default values for parameters of select +projections. + +Init files +------------------------------------------------------------------------------- + +Init files are used for preconfiguring proj-strings for often used +transformations, such as those found in the EPSG database. Most init files contain +transformations from a given coordinate reference system to WGS84. This makes +it easy to transformations between any two coordinate reference systems with +``cs2cs``. Init files can however contain any proj-string and don't necesarily +have to follow the *cs2cs* paradigm where WGS84 is used as a pivot datum. The +ITRF init file is a good example of that. + +A number of init files come pre-bundled with PROJ.4 but it is also possible to +add your own custom init files. PROJ.4 looks for the init files in the directoty +listed in the ``PROJ_LIB`` environment variable. + +The format of init files made up of a identifier in angled brackets and a +proj-string: + +:: + + <3819> +proj=longlat +ellps=bessel + +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs <> + +The above example is the first entry from the ``epsg`` init file. So, this is the +coordinate reference system with ID 3819 in the EPSG database. Comments can be +inserted by prefixing them with a "#". With version 4.10.0 a new special metadata +entry is now accepted in init files. It can be parsed with a function from the public +API. The metadata entry in the epsg init file looks like this at the time of writing: + +:: + + +version=9.0.0 +origin=EPSG +lastupdate=2017-01-10 + +Pre-configured proj-strings from init files are used in the following way: + +:: + + $ cs2cs -v +proj=latlong +to +init=epsg:3819 + # ---- From Coordinate System ---- + #Lat/long (Geodetic alias) + # + # +proj=latlong +ellps=WGS84 + # ---- To Coordinate System ---- + #Lat/long (Geodetic alias) + # + # +init=epsg:3819 +proj=longlat +ellps=bessel + # +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs + +It is possible to override parameters when using ``+init``. Just add the parameter +to the proj-string alongside the ``+init`` parameter. For instance by overriding +the ellipsoid as in the following example + +:: + + +init=epsg:25832 +ellps=intl + +where the Hayford ellipsoid is used instead of the predefined GRS80 ellipsoid. +It is also possible to add additional parameters not specified in the init file, +for instance by adding an obervation epoch when transforming from ITRF2000 to +ITRF2005: + +:: + + +init=ITRF2000:ITRF2005 +tobs=2010.5 + +which then expands to + +:: + + +proj=helmert +x=-0.0001 +y=0.0008 +z=0.0058 +s=-0.0004 + +dx=0.0002 +dy=-0.0001 +dz=0.0018 +ds=-0.000008 + +epoch=2000.0 +transpose + +tobs=2010.5 + +Below is a list of the init files that are packaged with PROJ.4. + + ======== ================================================================ + Name Description + ======== ================================================================ + esri Auto-generated mapping from Esri projection index. Not + maintained any more + epsg EPSG database + GL27 Great Lakes Grids + IGNF French coordinate systems supplied by the IGNF + ITRF2000 Full set of transformation parameters between ITRF2000 and other + ITRF's + ITRF2008 Full set of transformation parameters between ITRF2008 and other + ITRF's + ITRF2014 Full set of transformation parameters between ITRF2014 and other + ITRF's + nad27 State plane coordinate systems, North American Datum 1927 + nad83 State plane coordinate systems, North American Datum 1983 + ======== ================================================================ + + +Defaults file +------------------------------------------------------------------------------- + +The ``proj_def.dat`` file supplies default parameters for PROJ.4. It uses the same +syntax as the init files described above. The identifiers in the defaults file +describe to what the parameters should apply. If the ```` identifier is +used, then all parameters in that section applies for all proj-strings. Otherwise +the identifier is connected to a specific projection. With the defaults file +supplied with PROJ.4 the default ellipsoid is set to WGS84 (for all proj-strings). +Apart from that only the Albers Equal Area, +:doc:`Lambert Conic Conformal` and the +:doc:`Lagrange` projections have default parameters. +Defaults can be ignored by adding the ``+no_def`` parameter to a proj-string. + diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst new file mode 100644 index 0000000000..98e607a78d --- /dev/null +++ b/docs/source/usage/transformation.rst @@ -0,0 +1,314 @@ +.. _transformation: + +================================================================================ +Geodetic transformation +================================================================================ + +PROJ.4 can do everything from the most simple projection to very complex +transformations across many reference frames. While originally developed as a +tool for cartographic projections, PROJ.4 has over time evolved into a powerfull +generic coordinate transformation engine that makes it possible to do both +large scale cartographic projections as well as coordinate transformation at a +geodetic high precision level. This chapter delves into the details of how +geodetec transformations of varying complexity can be performed. + +In PROJ.4, two frameworks for geodetic transformations exists, the *cs2cs* +framework and the *transformation pipelines* framework. The first is the original, +and limited, framework for doing geodetic transforms in PROJ.4 The latter is a +newer addition that aims to be a more complete transformation framework. Both are +described in the sections below. Large portions of the text are based on +[EversKnudsen2017]_. + +Before describing the details of the two frameworks, let us first remark that +most cases of geodetic transformations can be expressed as a series of elementary +operations, the output of one operation being the input of the next. E.g. when +going from UTM zone 32, datum ED50, to UTM zone 32, datum ETRS89, one must, in the +simplest case, go through 5 steps: + +1. Back-project the UTM coordinates to geographic coordinates +2. Convert the geographic coordinates to 3D cartesian geocentric coordinates +3. Apply a Helmert transformation from ED50 to ETRS89 +4. Convert back from cartesian to geographic coordinates +5. Finally project the geographic coordinates to UTM zone 32 planar coordinates. + + +Transformation pipelines ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The homology between the above steps and a Unix shell style pipeline is evident. +It is there the main architectural inspiration behind the transformation pipeline +framework. The pipeline framework is realized by utilizing a special "projection", +that takes as its user supplied arguments, a series of elementary operations, +which it strings together in order to implement the full transformation needed. +Additionally, a number of elementary geodetic operations, including Helmert +transformations, general high order polynomial shifts and the Molodensky +transformation are available as part of the pipeline framework. +In anticipation of upcoming support for full time-varying transformations, we +also introduce a 4D spatiotemporal data type, and a programming interface +(API) for handling this. + +The Molodensky transformation converts directly from geodetic coordinates +in one datum, to geodetic coordinates in another datum, while the (typically more +accurate) Helmert transformation converts from 3D cartesian to 3D cartesian +coordinates. So when using the Helmert transformation one typically needs to do an +initial conversion from geodetic to cartesian coordinates, and a final conversion +the other way round, to arrive at the desired result. Fortunately, this three-step +compound transformation has the attractive characteristic that each step depends +only on the output of the immediately preceding step. Hence, we can build a +geodetic-to-geodetic Helmert transformation by tying together the outputs and inputs +of 3 steps (geodetic-to-cartesian → Helmert → cartesian-to-geodetic), pipeline style. +The pipeline driver, makes this kind of chained transformations possible. +The implementation is compact, consisting of just one pseudo-projection, called +``pipeline``, which takes as its arguments strings of elementary projections +(note: "projection" is the, slightly misleading, PROJ.4 term used for any kind of +transformation). +The pipeline pseudo projection is supplemented by a number of elementary +transformations, all in all providing a framework for building high accuracy +solutions for a wide spectrum of geodetic tasks. + + +As a first example, let us take a look at the iconic +*geodetic → Cartesian → Helmert → geodetic* case (steps 2 to 4 in the example in +the itroduction). In PROJ.4 it can be implemented as + +:: + + proj=pipeline + step proj=cart ellps=intl + step proj=helmert + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + +The pipeline can be expanded at both ends to accommodate whatever coordinate type +is needed for input and output: In the example below, we transform from the +deprecated Danish System 45, a 2D system with some tension in the original defining +network, to UTM zone 33, ETRS89. The tension is reduced using a polynomial +transformation (the init=./s45b... step, s45b.pol is a file containing the +polynomial coefficients), taking the S45 coordinates to a technical coordinate +system (TC32), defined to represent "UTM zone 32 coordinates, as they would look if +the Helmert transformation between ED50 and ETRS89 was perfect". The TC32 +coordinates are then converted back to geodetic(ED50) coordinates, using an +inverse UTM projection, further to cartesian(ED50), then to cartesian(ETRS89), +using the relevant Helmert transformation, and back to geodetic(ETRS89), before +finally being projected onto the UTM zone 33, ETRS89 system. All in all a 6 step +pipeline, implementing a transformation with centimeter level accuracy from a +deprecated system with decimeter level tensions. + +:: + + proj=pipeline + step init=./s45b.pol:s45b_tc32 + step proj=utm inv ellps=intl zone=32 + step proj=cart ellps=intl + step proj=helmert + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + step proj=utm ellps=GRS80 zone=33 + +With the pipeline framework spatiotemporal transformation is possible. This is +possible by leveraging the time dimension in PROJ.4 that enables 4D coordinates +(three spatial components and one temporal component) to be passed through a +transformation pipeline. In the example below a transformation from ITRF93 to +ITRF2000 is defined. The temporal component is given as GPS weeks in the input +data, but the 14-parameter Helmert transform expects temporal units in decimalyears. +Hence the first step in the pipeline is the unitconvert pseudo-projection that makes +sure the correct units are passed along to the Helmert transform. +Most parameters of the Helmert transform are taken from [AltamimiEtAl2002]_, +except the epoch which is the epoch of the transformation. The default setting is to +use “coordinate frame” convention of the Helmert transform, but “position vector” +convention can also be used. The last step in the pipeline is converting the +coordinate timestamps back to GPS weeks. + +:: + + proj=pipeline + step proj=unitconvert t_in=gps_week t_out=decimalyear + step proj=helmert + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + rx=0.00039 ry=-0.00080 rz=0.00114 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + drx=0.00011 dry=0.00019 drz=-0.00007 + epoch=1988.0 + step proj=unitconvert t_in=decimalyear t_out=gps_week + + +cs2cs paradigm ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + ============ ============================================================== + Parameter Description + ============ ============================================================== + +datum Datum name (see ``proj -ld``) + +geoidgrids Filename of GTX grid file to use for vertical datum transforms + +nadgrids Filename of NTv2 grid file to use for datum transforms + +towgs84 3 or 7 term datum transform parameters + +to_meter Multiplier to convert map units to 1.0m + +vto_meter Vertical conversion to meters + ============ ============================================================== + +The *cs2cs* framework delivers a subset of the geodetic transformations available +with the *pipeline* framework. Coordinate transformations done in this framework +are transformed in a two-step process with WGS84 as a pivot datum That is, the +input coordinates are transformed to WGS84 geodetic coordinates and then transformed +from WGS84 coordinates to the specified output coordinate reference system, by +utilizing either the Helmert transform, datum shift grids or a combination of both. +Datum shifts can be described in a proj-string with the parameters ``+towgs84``, +``+nadgrids`` and ``+geoidgrids``. +An inverse transform exists for all three and is applied if +specified in the input proj-string. The most common is ``+towgs84``, which is used to +define a 3- or 7-parameter Helmert shift from the input reference frame to WGS84. +Exactly which realization of WGS84 is not specified, hence a fair amount of +uncertainty is introduced in this step of the transformation. With the +nadgrids +parameter a non-lineaer planar correction derived from interpolation in a +correction grid can be applied. Originally this was implemented as a means to +transform coordinates between the american datums NAD27 and NAD83, but corrections +can be applied for any datum for which a correction grid exists. The inverse +transform for the horizontal grid shift is "dumb", in the sense that the +correction grid is applied verbatim without taking into account that the inverse +operation is non-linear. Similar to the horizontal grid correction, ``+geoidgrids`` +can be used to perform grid corrections in the vertical component. +Both grid correction methods allow inclusion of more than one grid in the same +transformation + +In contrast to the *transformation pipeline* framework, transformations with the +*cs2cs* framework are expressed as two separate proj-strings. One proj-string *to* +WGS84 and one *from* WGS84. Together they form the mapping from the source +coordinate reference system to the destination coordinate reference system. +When used with the ``cs2cs`` the source and destination CRS's are separated by the +special ``+to`` parameter. + +The following example demonstrates converting from the Greek GGRS87 datum +to WGS84 with the ``+towgs84`` parameter. + +:: + + cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62 + +to +proj=latlong +datum=WGS84 + 20 35 + 20d0'5.467"E 35d0'9.575"N 8.570 + +The EPSG database provides this example for transforming from WGS72 to WGS84 +using an approximated 7 parameter transformation. + +:: + + cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \ + +to +proj=latlong +datum=WGS84 + 4 55 + 4d0'0.554"E 55d0'0.09"N 3.223 + + +Grid Based Datum Adjustments ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In many places (notably North America and Austrialia) national geodetic +organizations provide grid shift files for converting between different datums, +such as NAD27 to NAD83. These grid shift files include a shift to be applied +at each grid location. Actually grid shifts are normally computed based on an +interpolation between the containing four grid points. + +PROJ.4 supports use of grid files for shifting between various reference frames. +The grid shift table formats are ctable (the binary format produced by the PROJ.4 +``nad2bin`` program), NTv1 (the old Canadian format), and NTv2 (``.gsb`` - the new +Canadian and Australian format). + +The text in this section is based on the *cs2cs* framework. Gridshifting is off +course also possible with the *pipeline* framework. The major difference between the +two is that the *cs2cs* framework is limited to grid mappings to WGS84, whereas with +*transformation pipelines* it is possible to perform grid shifts between any two +reference frames, as long as a grid exists. + +Use of grid shifts with ``cs2cs`` is specified using the ``+nadgrids`` +keyword in a coordinate system definition. For example: + +:: + + % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'2.952"W 50d0'0.111"N 0.000 + +In this case the ``/usr/local/share/proj/ntv1_can.dat`` grid shift file was +loaded, and used to get a grid shift value for the selected point. + +It is possible to list multiple grid shift files, in which case each will be +tried in turn till one is found that contains the point being transformed. + +:: + + cs2cs +proj=latlong +ellps=clrk66 \ + +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + + +Skipping Missing Grids +................................................................................ + +The special prefix ``@`` may be prefixed to a grid to make it optional. If it +not found, the search will continue to the next grid. Normally any grid not +found will cause an error. For instance, the following would use the +``ntv2_0.gsb`` file if available (see :ref:`nonfreegrids`), otherwise it would +fallback to using the ``ntv1_can.dat`` file. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + +The null Grid +................................................................................ + +A special ``null`` grid shift file is shift with releases after 4.4.6 (not +inclusive). This file provides a zero shift for the whole world. It may be +listed at the end of a nadgrids file list if you want a zero shift to be +applied to points outside the valid region of all the other grids. Normally if +no grid is found that contains the point to be transformed an error will occur. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 45 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + -111 55 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + 111dW 55dN 0.000 + +For more information see the chapter on :ref:`Grids`. + +Caveats +................................................................................ + +* Where grids overlap (such as conus and ntv1_can.dat for instance) the first + found for a point will be used regardless of whether it is appropriate or + not. So, for instance, ``+nadgrids=ntv1_can.dat``,conus would result in + the Canadian data being used for some areas in the northern United States + even though the conus data is the approved data to use for the area. + Careful selection of files and file order is necessary. In some cases + border spanning datasets may need to be pre-segmented into Canadian and + American points so they can be properly grid shifted +* There are additional grids for shifting between NAD83 and various HPGN + versions of the NAD83 datum. Use of these haven't been tried recently so + you may encounter problems. The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla + are examples of high precision grid shifts. Take care! +* Additional detail on the grid shift being applied can be found by setting + the PROJ_DEBUG environment variable to a value. This will result in output + to stderr on what grid is used to shift points, the bounds of the various + grids loaded and so forth +* The *cs2cs* framework always assumes that grids contain a shift **to** NAD83 (essentially + WGS84). Other types of grids can be used with the *pipeline* framework. diff --git a/examples/pj_obs_api_mini_demo.c b/examples/pj_obs_api_mini_demo.c index 855c37f803..340214886a 100644 --- a/examples/pj_obs_api_mini_demo.c +++ b/examples/pj_obs_api_mini_demo.c @@ -31,6 +31,9 @@ and destructor may be left out, and the default context selected by passing a null-pointer to pj_create. + Note: This file is in-lined in the documentation. Any changes must be + reflected in docs/source/development/quickstart.rst + Thomas Knudsen, 2016-10-30/2017-07-06 *******************************************************************************/ #include @@ -53,7 +56,6 @@ int main (void) { a = proj_coord (proj_torad(12), proj_torad(55), 0, 0); /* transform to UTM zone 32, then back to geographical */ - /* note the use of union selectors to indicate what kind of coordinates are expected */ b = proj_trans_coord (P, PJ_FWD, a); printf ("easting: %g, northing: %g\n", b.en.e, b.en.n); b = proj_trans_coord (P, PJ_INV, b);