diff options
| author | PROJ deploybot <proj.bot@proj.bot> | 2022-03-22 20:00:06 +0000 |
|---|---|---|
| committer | PROJ deploybot <proj.bot@proj.bot> | 2022-03-22 20:00:06 +0000 |
| commit | a3f43744feec86272fe532124679d3a013ef9a8c (patch) | |
| tree | 27e4198db6011e3097eb7bcfe7197684aba7583a /_sources/operations | |
| download | PROJ-gh-pages.tar.gz PROJ-gh-pages.zip | |
update with results of commit https://github.com/OSGeo/PROJ/commit/53c07a8bd211b7aee4bc07a9c6726005504b7181gh-pages
Diffstat (limited to '_sources/operations')
178 files changed, 12782 insertions, 0 deletions
diff --git a/_sources/operations/conversions/axisswap.rst.txt b/_sources/operations/conversions/axisswap.rst.txt new file mode 100644 index 00000000..b8d606ff --- /dev/null +++ b/_sources/operations/conversions/axisswap.rst.txt @@ -0,0 +1,56 @@ +.. _axisswap: + +================================================================================ +Axis swap +================================================================================ + +.. versionadded:: 5.0.0 + +Change the order and sign of 2,3 or 4 axes. + ++---------------------+--------------------------------------------------------+ +| **Alias** | axisswap | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D, 3D or 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + + +Each of the possible four axes are numbered with 1--4, such that the first input axis +is 1, the second is 2 and so on. The output ordering is controlled by a list of the +input axes re-ordered to the new mapping. + +Usage +################################################################################ + +Reversing the order of the axes:: + + +proj=axisswap +order=4,3,2,1 + +Swapping the first two axes (x and y):: + + +proj=axisswap +order=2,1,3,4 + +The direction, or sign, of an axis can be changed by adding a minus in +front of the axis-number:: + + +proj=axisswap +order=1,-2,3,4 + +It is only necessary to specify the axes that are affected by the swap +operation:: + + +proj=axisswap +order=2,1 + +Parameters +################################################################################ + +.. option:: +order=<list> + + Ordered comma-separated list of axis, e.g. *+order=2,1,3,4*. + Adding a minus in front of an axis number results in a change of direction + for that axis, e.g. southward instead of northward. + + *Required.* diff --git a/_sources/operations/conversions/cart.rst.txt b/_sources/operations/conversions/cart.rst.txt new file mode 100644 index 00000000..239b1772 --- /dev/null +++ b/_sources/operations/conversions/cart.rst.txt @@ -0,0 +1,38 @@ +.. _cart: + +================================================================================ +Geodetic to cartesian conversion +================================================================================ + +.. versionadded:: 5.0.0 + +Convert geodetic coordinates to cartesian coordinates (in the forward path). + ++---------------------+--------------------------------------------------------+ +| **Alias** | cart | ++---------------------+--------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Geocentric cartesian coordinates | ++---------------------+--------------------------------------------------------+ + +This conversion converts geodetic coordinate values (longitude, latitude, +elevation above ellipsoid) to their geocentric (X, Y, Z) representation, where +the first axis (X) points from the Earth centre to the point of longitude=0, +latitude=0, the second axis (Y) points from the Earth centre to the point of +longitude=90, latitude=0 and the third axis (Z) points to the North pole. + +Usage +################################################################################ + +Convert geodetic coordinates to GRS80 cartesian coordinates:: + + echo 17.7562015132 45.3935192042 133.12 2017.8 | cct +proj=cart +ellps=GRS80 + 4272922.1553 1368283.0597 4518261.3501 2017.8000 + +Parameters +################################################################################ + +.. include:: ../options/ellps.rst diff --git a/_sources/operations/conversions/geoc.rst.txt b/_sources/operations/conversions/geoc.rst.txt new file mode 100644 index 00000000..6ee32ea6 --- /dev/null +++ b/_sources/operations/conversions/geoc.rst.txt @@ -0,0 +1,75 @@ +.. _geoc: + +================================================================================ +Geocentric Latitude +================================================================================ + +.. versionadded:: 5.0.0 + +Convert from Geodetic Latitude to Geocentric Latitude (in the forward path). + ++---------------------+--------------------------------------------------------+ +| **Alias** | geoc | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Geocentric angular coordinates | ++---------------------+--------------------------------------------------------+ + +The geodetic (or geographic) latitude (also called planetographic latitude +in the context of non-Earth bodies) is the angle between the equatorial plane +and the normal (vertical) to the ellipsoid surface at the considered point. +The geodetic latitude is what is normally used everywhere in PROJ when angular +coordinates are expected or produced. + +The geocentric latitude (also called planetocentric latitude in the context of +non-Earth bodies) is the angle between the equatorial plane and a line joining +the body centre to the considered point. + +.. image:: ./images/geocentric_latitude.png + :align: center + :scale: 100% + :alt: Geocentric latitude + + +.. note:: + + This conversion must be distinguished from the :ref:`cart` + which converts geodetic coordinates to geocentric coordinates in the cartesian + domain. + +Mathematical definition +####################### + +The formulas describing the conversion are taken from :cite:`Snyder1987` +(equation 3-28) + +Let :math:`\phi'` to be the geocentric latitude and :math:`\phi` the +geodetic latitude, then + +.. math:: + + \phi' = \arctan \left[ (1 - e^2) \tan \left( \phi \right) \right] + +The geocentric latitude is consequently lesser (in absolute value) than the geodetic +latitude, except at the equator and the poles where they are equal. + +On a sphere, they are always equal. + +Usage +################################################################################ + +Converting from geodetic latitude to geocentric latitude:: + + +proj=geoc +ellps=GRS80 + +Converting from geocentric latitude to geodetic latitude:: + + +proj=pipeline +step +proj=geoc +inv +ellps=GRS80 + +Parameters +################################################################################ + +.. include:: ../options/ellps.rst diff --git a/_sources/operations/conversions/index.rst.txt b/_sources/operations/conversions/index.rst.txt new file mode 100644 index 00000000..b335c2ac --- /dev/null +++ b/_sources/operations/conversions/index.rst.txt @@ -0,0 +1,23 @@ +.. _conversions_list: + +================================================================================ +Conversions +================================================================================ + +Conversions are coordinate operations in which both coordinate reference systems +are based on the same datum. In PROJ projections are differentiated from +conversions. + +.. toctree:: + :maxdepth: 1 + + axisswap + cart + geoc + latlon + noop + pop + push + set + topocentric + unitconvert diff --git a/_sources/operations/conversions/latlon.rst.txt b/_sources/operations/conversions/latlon.rst.txt new file mode 100644 index 00000000..25e2a143 --- /dev/null +++ b/_sources/operations/conversions/latlon.rst.txt @@ -0,0 +1,46 @@ +.. _latlon: + +******************************************************************************** +Lat/long (Geodetic alias) +******************************************************************************** + +Passes geodetic coordinates through unchanged. + ++---------------------+--------------------------------------------------------+ +| **Aliases** | latlon, latlong, lonlat, longlat | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ + +.. note:: Can not be used with the :program:`proj` application. + + +Parameters +################################################################################ + +No parameters will affect the output of the operation if used on it's own. +However, the parameters below can be used in a declarative manner when used with +:program:`cs2cs` or in a :ref:`transformation pipeline <pipeline>` . + +.. include:: ../options/ellps.rst + +.. option:: +datum=<value> + + Declare the datum used with the coordinates. Available options are: + ``WGS84``, ``GGRS87``, ``NAD38``, ``NAD27``, ``potsdam``, ``carthage``, + ``hermannskogel``, ``ire65``, ``nzgd49``, ``OSGB336``. + + .. note:: + + The ``+datum`` option is primarily available to support the legacy + use of PROJ.4 strings as CRS descriptors and should in most cases + be avoided. + +.. option:: +towgs84=<list> + + A list of three or seven :ref:`Helmert <helmert>` parameters that maps + the input coordinates to the WGS84 datum. diff --git a/_sources/operations/conversions/noop.rst.txt b/_sources/operations/conversions/noop.rst.txt new file mode 100644 index 00000000..a35b2b58 --- /dev/null +++ b/_sources/operations/conversions/noop.rst.txt @@ -0,0 +1,28 @@ +.. _noop: + +================================================================================ +No operation +================================================================================ + +.. versionadded:: 6.1.0 + +Pass a coordinate through unchanged. + ++---------------------+--------------------------------------------------------+ +| **Alias** | noop | ++---------------------+--------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +The no operation is a dummy operation that returns whatever is passed to it +as seen in this example:: + + $ echo 12 34 56 78 | cct +proj=noop + 12.0000 34.0000 56.0000 78.0000 + +The operation has no options and default options will not affect the output. + diff --git a/_sources/operations/conversions/pop.rst.txt b/_sources/operations/conversions/pop.rst.txt new file mode 100644 index 00000000..2c6d264a --- /dev/null +++ b/_sources/operations/conversions/pop.rst.txt @@ -0,0 +1,94 @@ +.. _pop: + +================================================================================ +Pop coordinate value to pipeline stack +================================================================================ + +.. versionadded:: 6.0.0 + +Retrieve components of a coordinate that was saved in a previous pipeline step. + ++---------------------+--------------------------------------------------------+ +| **Alias** | pop | ++---------------------+--------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +This operations makes it possible to retrieve coordinate components that was +saved in previous pipeline steps. A retrieved coordinate component is loaded, +or *popped*, from a memory stack that is part of a :ref:`pipeline<pipeline>`. +The pipeline coordinate stack is inspired by the stack data structure that is +commonly used in computer science. There's four stacks available: One four each +coordinate dimension. The dimensions, or coordinate components, are numbered +1--4. It is only possible to move data to and from the stack within the same +coordinate component number. Values can be saved to the stack by using the +:ref:`push operation<push>`. + +If the pop operation is used by itself, e.g. not in a pipeline, it will +function as a no-operation that passes the coordinate through unchanged. +Similarly, if no coordinate component is available on the stack to be popped +the operation does nothing. + +Examples +################################################################################ + +A common use of the :ref:`push<push>` and pop operations is in 3D +:ref:`Helmert<helmert>` transformations where only the horizontal components +are needed. This is often the case when combining heights from a legacy +vertical reference with a modern geocentric reference. Below is a an example of +such a transformation, where the horizontal part is transformed with a Helmert +operation but the vertical part is kept exactly as the input was. + +:: + + $ echo 12 56 12.3 2020 | cct +proj=pipeline \ + +step +proj=push +v_3 \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=3000 +y=1000 +z=2000 \ + +step +proj=cart +ellps=GRS80 +inv \ + +step +proj=pop +v_3 \ + + 12.0056753463 55.9866540552 12.3000 2000.0000 + +Note that the third coordinate component in the output is the same as the input. + +The same transformation without the push and pop operations would look like this:: + + $ echo 12 56 12.3 2020 | cct +proj=pipeline \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=3000 +y=1000 +z=2000 \ + +step +proj=cart +ellps=GRS80 +inv \ + + 12.0057 55.9867 3427.7404 2000.0000 + +Here the vertical component is adjusted significantly. + +Parameters +################################################################################ + +.. option:: +v_1 + + Retrieves the first coordinate component from the pipeline stack + +.. option:: +v_2 + + Retrieves the second coordinate component from the pipeline stack + +.. option:: +v_3 + + Retrieves the third coordinate component from the pipeline stack + +.. option:: +v_4 + + Retrieves the fourth coordinate component from the pipeline stack + + +Further reading +################################################################################ + +#. `Stack data structure on Wikipedia <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>`_ + diff --git a/_sources/operations/conversions/push.rst.txt b/_sources/operations/conversions/push.rst.txt new file mode 100644 index 00000000..a1f4423a --- /dev/null +++ b/_sources/operations/conversions/push.rst.txt @@ -0,0 +1,93 @@ +.. _push: + +================================================================================ +Push coordinate value to pipeline stack +================================================================================ + +.. versionadded:: 6.0.0 + +Save components of a coordinate from one step of a pipeline and make it +available for retrieving in another pipeline step. + ++---------------------+--------------------------------------------------------+ +| **Alias** | push | ++---------------------+--------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +This operations allows for components of coordinates to be saved for +application in a later step. A saved coordinate component is moved, or +*pushed*, to a memory stack that is part of a :ref:`pipeline<pipeline>`. The +pipeline coordinate stack is inspired by the stack data structure that is +commonly used in computer science. There's four stacks available: One four each +coordinate dimension. The dimensions, or coordinate components, are numbered +1--4. It is only possible to move data to and from the stack within the same +coordinate component number. Values can be moved off the stack again by using +the :ref:`pop operation<pop>`. + +If the push operation is used by itself, e.g. not in a pipeline, it will +function as a no-operation that passes the coordinate through unchanged. + +Examples +################################################################################ + +A common use of the push and :ref:`pop<pop>` operations is in 3D +:ref:`Helmert<helmert>` transformations where only the horizontal components +are needed. This is often the case when combining heights from a legacy +vertical reference with a modern geocentric reference. Below is a an example of +such a transformation, where the horizontal part is transformed with a Helmert +operation but the vertical part is kept exactly as the input was. + +:: + + $ echo 12 56 12.3 2020 | cct +proj=pipeline \ + +step +proj=push +v_3 \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=3000 +y=1000 +z=2000 \ + +step +proj=cart +ellps=GRS80 +inv \ + +step +proj=pop +v_3 \ + + 12.0056753463 55.9866540552 12.3000 2000.0000 + +Note that the third coordinate component in the output is the same as the input. + +The same transformation without the push and pop operations would look like this:: + + $ echo 12 56 12.3 2020 | cct +proj=pipeline \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=3000 +y=1000 +z=2000 \ + +step +proj=cart +ellps=GRS80 +inv \ + + 12.0057 55.9867 3427.7404 2000.0000 + +Here the vertical component is adjusted significantly. + +Parameters +################################################################################ + +.. option:: +v_1 + + Stores the first coordinate component on the pipeline stack + +.. option:: +v_2 + + Stores the second coordinate component on the pipeline stack + +.. option:: +v_3 + + Stores the third coordinate component on the pipeline stack + +.. option:: +v_4 + + Stores the fourth coordinate component on the pipeline stack + + +Further reading +################################################################################ + +#. `Stack data structure on Wikipedia <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>`_ + diff --git a/_sources/operations/conversions/set.rst.txt b/_sources/operations/conversions/set.rst.txt new file mode 100644 index 00000000..635d08d3 --- /dev/null +++ b/_sources/operations/conversions/set.rst.txt @@ -0,0 +1,76 @@ +.. _set: + +================================================================================ +Set coordinate value +================================================================================ + +.. versionadded:: 7.0.0 + +Set component(s) of a coordinate to a fixed value. + ++---------------------+--------------------------------------------------------+ +| **Alias** | set | ++---------------------+--------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +This operations allows for components of coordinates to be set to a fixed value. +This may be useful in :ref:`pipeline<pipeline>` when a step requires some +component, typically an elevation or a date, to be set to a fixed value. + +Example +################################################################################ + +In the ETRS89 to Dutch RD with NAP height transformation, the used ellipsoidal +height for the Helmert transformation is not the NAP height, but the height is +set to 0 m. This is an unconventional trick to get the same results as when the +effect of the Helmert transformation is included in the horizontal NTv2 grid. +For the forward transformation from ETRS89 to RD with NAP height, we need to set +the ellipsoidal ETRS89 height for the Helmert transformation to the equivalent +of 0 m NAP. This is 43 m for the centre of the Netherlands and this value can +be used as an approximation elsewhere (the effect of this approximation is +below 1 mm for the horizontal coordinates, in an area up to hundreds of km +outside the Netherlands). + +The ``+proj=set +v_3=0`` close to the end of the pipeline is to make it usable in +the reverse direction. + +:: + + $ cct -t 0 -d 4 +proj=pipeline \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=axisswap +order=2,1 \ + +step +proj=vgridshift +grids=nlgeo2018.gtx \ + +step +proj=push +v_3 \ + +step +proj=set +v_3=43 \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=-565.7346 +y=-50.4058 +z=-465.2895 +rx=-0.395023 +ry=0.330776 +rz=-1.876073 +s=-4.07242 +convention=coordinate_frame +exact \ + +step +proj=cart +inv +ellps=bessel \ + +step +proj=hgridshift +inv +grids=rdcorr2018.gsb,null \ + +step +proj=sterea +lat_0=52.156160556 +lon_0=5.387638889 +k=0.9999079 +x_0=155000 +y_0=463000 +ellps=bessel \ + +step +proj=set +v_3=0 \ + +step +proj=pop +v_3 + +Parameters +################################################################################ + +.. option:: +v_1=value + + Set the first coordinate component to the specified value + +.. option:: +v_2=value + + Set the second coordinate component to the specified value + +.. option:: +v_3=value + + Set the third coordinate component to the specified value + +.. option:: +v_4=value + + Set the fourth coordinate component to the specified value + diff --git a/_sources/operations/conversions/topocentric.rst.txt b/_sources/operations/conversions/topocentric.rst.txt new file mode 100644 index 00000000..14019965 --- /dev/null +++ b/_sources/operations/conversions/topocentric.rst.txt @@ -0,0 +1,117 @@ +.. _topocentric: + +================================================================================ +Geocentric to topocentric conversion +================================================================================ + +.. versionadded:: 8.0.0 + +Convert geocentric coordinates to topocentric coordinates (in the forward path). + ++---------------------+--------------------------------------------------------+ +| **Alias** | topocentric | ++---------------------+--------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geocentric cartesian coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Topocentric cartesian coordinates | ++---------------------+--------------------------------------------------------+ + +This operation converts geocentric coordinate values (X, Y, Z) to topocentric +(E/East, N/North, U/Up) values. This is also sometimes known as the ECEF (Earth +Centered Earth Fixed) to ENU conversion. + +Topocentric coordinates are expressed in a frame whose East and North axis form +a local tangent plane to the Earth's ellipsoidal surface fixed to a specific +location (the topocentric origin), and the Up axis points upwards along the +normal to that plane. + +.. image:: ./images/ECEF_ENU_Longitude_Latitude_relationships.png + :align: center + :scale: 100% + :alt: ENU coordinate frame + +.. + Source : https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates#/media/File:ECEF_ENU_Longitude_Latitude_relationships.svg + Public domain +.. + +The topocentric origin is a required parameter of the conversion, and can be +expressed either as geocentric coordinates (``X_0``, ``Y_0`` and ``Z_0``) or +as geographic coordinates (``lat_0``, ``lon_0``, ``h_0``). + +When conversion between geographic and topocentric coordinates is desired, the +topocentric conversion must be preceded by the :ref:`cart` conversion to +perform the initial geographic to geocentric coordinates conversion. + +The formulas used come from the "Geocentric/topocentric conversions" paragraph +of :cite:`IOGP2018`. ``+proj=topocentric`` alone corresponds to the ``EPSG:9836`` +conversion method, ``+proj=cart`` followed by ``+proj=topocentric`` corresponds +to ``EPSG:9837``. + +Usage +################################################################################ + +Convert geocentric coordinates to topocentric coordinates, with the topocentric +origin specified in geocentric coordinates:: + + echo 3771793.968 140253.342 5124304.349 2020 | \ + cct -d 3 +proj=topocentric +ellps=WGS84 +X_0=3652755.3058 +Y_0=319574.6799 +Z_0=5201547.3536 + + -189013.869 -128642.040 -4220.171 2020.0000 + +Convert geographic coordinates to topocentric coordinates, with the topocentric +origin specified in geographic coordinates:: + + echo 2.12955 53.80939444 73 2020 | cct -d 3 +proj=pipeline \ + +step +proj=cart +ellps=WGS84 \ + +step +proj=topocentric +ellps=WGS84 +lon_0=5 +lat_0=55 +h_0=200 + + -189013.869 -128642.040 -4220.171 2020.0000 + + +Parameters +################################################################################ + +.. include:: ../options/ellps.rst + +Topocentric origin described as geocentric coordinates +------------------------------------------------------ + +.. note:: + + The below options are mutually exclusive with the ones to express the origin as geographic coordinates. + +.. option:: +X_0=<value> + + Geocentric X value of the topocentric origin (in metre) + +.. option:: +Y_0=<value> + + Geocentric Y value of the topocentric origin (in metre) + +.. option:: +Z_0=<value> + + Geocentric Z value of the topocentric origin (in metre) + +Topocentric origin described as geographic coordinates +------------------------------------------------------ + +.. note:: + + The below options are mutually exclusive with the ones to express the origin as geocentric coordinates. + +.. option:: +lat_0=<value> + + Latitude of topocentric origin (in degree) + +.. option:: +lon_0=<value> + + Longitude of topocentric origin (in degree) + +.. option:: +h_0=<value> + + Ellipsoidal height of topocentric origin (in metre) + + *Defaults to 0.0.* diff --git a/_sources/operations/conversions/unitconvert.rst.txt b/_sources/operations/conversions/unitconvert.rst.txt new file mode 100644 index 00000000..13ca9228 --- /dev/null +++ b/_sources/operations/conversions/unitconvert.rst.txt @@ -0,0 +1,182 @@ +.. _unitconvert: + +================================================================================ +Unit conversion +================================================================================ + +.. versionadded:: 5.0.0 + +Convert between various distance, angular and time units. + ++---------------------+--------------------------------------------------------+ +| **Alias** | unitconvert | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D, 3D or 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +There are many examples of coordinate reference systems that are expressed in +other units than the meter. There are also many cases where temporal data +has to be translated to different units. The `unitconvert` operation takes care +of that. + +Many North American systems are defined with coordinates in feet. For example +in Vermont:: + + +proj=pipeline + +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k_0=0.999964286 +x_0=500000.00001016 +y_0=0 + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +Often when working with GNSS data the timestamps are presented in GPS-weeks, +but when the data transformed with the `helmert` operation timestamps are +expected to be in units of decimalyears. This can be fixed with `unitconvert`:: + + +proj=pipeline + +step +proj=unitconvert +t_in=gps_week +t_out=decimalyear + +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ... + +Parameters +################################################################################ + +.. option:: +xy_in=<unit> or <conversion_factor> + + Horizontal input units. See :ref:`distance_units` and :ref:`angular_units` + for a list of available units. `<conversion_factor>` is the conversion factor + from the input unit to metre for linear units, or to radian for angular + units. + +.. option:: +xy_out=<unit> or <conversion_factor> + + Horizontal output units. See :ref:`distance_units` and :ref:`angular_units` + for a list of available units. `<conversion_factor>` is the conversion factor + from the output unit to metre for linear units, or to radian for angular + units. + +.. option:: +z_in=<unit> or <conversion_factor> + + Vertical output units. See :ref:`distance_units` and :ref:`angular_units` + for a list of available units. `<conversion_factor>` is the conversion factor + from the input unit to metre for linear units, or to radian for angular + units. + +.. option:: +z_out=<unit> or <conversion_factor> + + Vertical output units. See :ref:`distance_units` and :ref:`angular_units` + for a list of available units. `<conversion_factor>` is the conversion factor + from the output unit to metre for linear units, or to radian for angular + units. + +.. option:: +t_in=<unit> + + Temporal input units. See :ref:`time_units` for a list of available units. + +.. option:: +t_out=<unit> + + Temporal output units. See :ref:`time_units` for a list of available units. + +.. _distance_units: + +Distance units +############################################################################### + +In the table below all distance units supported by PROJ are listed. +The same list can also be produced on the command line with :program:`proj` or +:program:`cs2cs`, by adding the `-lu` flag when calling the utility. + ++----------+---------------------------------+ +| Label | Name | ++==========+=================================+ +| km | Kilometer | ++----------+---------------------------------+ +| m | Meter | ++----------+---------------------------------+ +| dm | Decimeter | ++----------+---------------------------------+ +| cm | Centimeter | ++----------+---------------------------------+ +| mm | Millimeter | ++----------+---------------------------------+ +| kmi | International Nautical Mile | ++----------+---------------------------------+ +| in | International Inch | ++----------+---------------------------------+ +| ft | International Foot | ++----------+---------------------------------+ +| yd | International Yard | ++----------+---------------------------------+ +| mi | International Statute Mile | ++----------+---------------------------------+ +| fath | International Fathom | ++----------+---------------------------------+ +| ch | International Chain | ++----------+---------------------------------+ +| link | International Link | ++----------+---------------------------------+ +| us-in | U.S. Surveyor's Inch | ++----------+---------------------------------+ +| us-ft | U.S. Surveyor's Foot | ++----------+---------------------------------+ +| us-yd | U.S. Surveyor's Yard | ++----------+---------------------------------+ +| us-ch | U.S. Surveyor's Chain | ++----------+---------------------------------+ +| us-mi | U.S. Surveyor's Statute Mile | ++----------+---------------------------------+ +| ind-yd | Indian Yard | ++----------+---------------------------------+ +| ind-ft | Indian Foot | ++----------+---------------------------------+ +| ind-ch | Indian Chain | ++----------+---------------------------------+ + +.. _angular_units: + +Angular units +############################################################################### + +.. versionadded:: 5.2.0 + +In the table below all angular units supported by PROJ `unitconvert` are listed. + ++----------+---------------------------------+ +| Label | Name | ++==========+=================================+ +| deg | Degree | ++----------+---------------------------------+ +| grad | Grad | ++----------+---------------------------------+ +| rad | Radian | ++----------+---------------------------------+ + +.. _time_units: + +Time units +############################################################################### + +In the table below all time units supported by PROJ are listed. + + .. note:: + + When converting time units from a date-only format (`yyyymmdd`), PROJ + assumes a time value of 00:00 midnight. When converting time units + to a date-only format, PROJ rounds to the *nearest* date at 00:00 + midnight. That is, any time values less than 12:00 noon will round to + 00:00 on the same day. Time values greater than or equal to 12:00 noon + will round to 00:00 on the following day. + + ++--------------+-----------------------------+ +| Label | Name | ++==============+=============================+ +| mjd | Modified Julian date | ++--------------+-----------------------------+ +| decimalyear | Decimal year | ++--------------+-----------------------------+ +| gps_week | GPS Week | ++--------------+-----------------------------+ +| yyyymmdd | Date in yyyymmdd format | ++--------------+-----------------------------+ + diff --git a/_sources/operations/index.rst.txt b/_sources/operations/index.rst.txt new file mode 100644 index 00000000..d4582049 --- /dev/null +++ b/_sources/operations/index.rst.txt @@ -0,0 +1,22 @@ +.. _operations: + +================================================================================ +Coordinate operations +================================================================================ + +Coordinate operations in PROJ are divided into three groups: +Projections, conversions and transformations. +Projections are purely cartographic mappings of the sphere onto the plane. +Technically projections are conversions (according to ISO standards), though in +PROJ projections are distinguished from conversions. Conversions are coordinate +operations that do not exert a change in reference frame. Operations that do +exert a change in reference frame are called transformations. + +.. toctree:: + :maxdepth: 1 + + projections/index + conversions/index + transformations/index + pipeline + operations_computation diff --git a/_sources/operations/operations_computation.rst.txt b/_sources/operations/operations_computation.rst.txt new file mode 100644 index 00000000..5c2596e6 --- /dev/null +++ b/_sources/operations/operations_computation.rst.txt @@ -0,0 +1,785 @@ +.. _operations_computation: + +================================================================================ +Computation of coordinate operations between two CRS +================================================================================ + +:Author: Even Rouault +:Last Updated: 2021-02-10 + +Introduction +------------ + +When using :command:`projinfo -s {crs_def} -t {crs_def}`, +:command:`cs2cs {crs_def} {crs_def}` or the underlying +:c:func:`proj_create_crs_to_crs` or :cpp:func:`proj_create_operations` functions, +PROJ applies an algorithm to compute one or several candidate coordinate operations, +that can be expressed as a PROJ :ref:`pipeline <pipeline>` to transform between the source +and the target CRS. This document is about the description of this algorithm that +finds the actual operations to apply to be able later to perform transform coordinates. +So this is mostly about metadata management around coordinate operation methods, +and not about the actual mathematics used to implement those methods. +As a matter of fact with PROJ 6, there are about 60 000 +lines of code dealing with "metadata" management (including conversions between PROJ +strings, all CRS WKT variants), to be compared to 30 000 for the purely computation part. + +This document is meant as a plain text explanation of the code for developers, +but also as a in-depth examination of what happens under the hood for curious PROJ +users. It is important to keep in mind that it is not meant to be the ultimate +source of truth of how coordinate operations should be computed. There are clearly +implementation choices and compromises that can be questioned. + +Let us start with an example to research operations between the NAD27 and NAD83 +geographic CRS: + +.. code-block:: shell + + $ projinfo -s NAD27 -t NAD83 --summary --spatial-test intersects --grid-check none + + Candidate operations found: 10 + DERIVED_FROM(EPSG):1312, NAD27 to NAD83 (3), 1.0 m, Canada + DERIVED_FROM(EPSG):1313, NAD27 to NAD83 (4), 1.5 m, Canada - NAD27, at least one grid missing + DERIVED_FROM(EPSG):1241, NAD27 to NAD83 (1), 0.15 m, USA - CONUS including EEZ + DERIVED_FROM(EPSG):1243, NAD27 to NAD83 (2), 0.5 m, USA - Alaska including EEZ + DERIVED_FROM(EPSG):1573, NAD27 to NAD83 (6), 1.5 m, Canada - Quebec, at least one grid missing + EPSG:1462, NAD27 to NAD83 (5), 1.0 m, Canada - Quebec, at least one grid missing + EPSG:9111, NAD27 to NAD83 (9), 1.5 m, Canada - Saskatchewan, at least one grid missing + unknown id, Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, World, has ballpark transformation + EPSG:8555, NAD27 to NAD83 (7), 0.15 m, USA - CONUS and GoM, at least one grid missing + EPSG:8549, NAD27 to NAD83 (8), 0.5 m, USA - Alaska, at least one grid missing + +The algorithm involves many cases, so we will progress in the explanation from +the most simple case to more complex ones. We document here the working of this +algorithm as implemented in PROJ 8.0.0. +The results of some examples might also be quite sensitive to the content of the +PROJ database and the PROJ version used. + +From a code point of view, the entry point of the algorithm is the C++ +:cpp:func:`osgeo::proj::operation::CoordinateOperation::createOperations` method. + +It combines several strategies: + + - look up in the PROJ database for available operations + - consider the pair (source CRS, target CRS) to synthetize operations depending + on the nature of the source and target CRS. + +Geographic CRS to Geographic CRS, with known identifiers +-------------------------------------------------------- + +With the above example of two geographic CRS, that have an identified identifier, +(:program:`projinfo` internally resolves NAD27 to EPSG:4267 and NAD83 to EPSG:4269) +the algorithm will first search +in the coordinate operation related tables of the :file:`proj.db` if there are records +that list direct transformations between the source and the target CRS. The +transformations typically involve :ref:`Helmert <helmert>`-style operations or datum shift based on +grids (more esoteric operations are possible). + +A request similar to the following will be emitted: + +.. code-block:: shell + + $ sqlite3 proj.db "SELECT auth_name, code, name, method_name, accuracy FROM \ + coordinate_operation_view WHERE \ + source_crs_auth_name = 'EPSG' AND \ + source_crs_code = '4267' AND \ + target_crs_auth_name = 'EPSG' AND \ + target_crs_code = '4269'" + + EPSG|1241|NAD27 to NAD83 (1)|NADCON|0.15 + EPSG|1243|NAD27 to NAD83 (2)|NADCON|0.5 + EPSG|1312|NAD27 to NAD83 (3)|NTv1|1.0 + EPSG|1313|NAD27 to NAD83 (4)|NTv2|1.5 + EPSG|1462|NAD27 to NAD83 (5)|NTv1|1.0 + EPSG|1573|NAD27 to NAD83 (6)|NTv2|1.5 + EPSG|8549|NAD27 to NAD83 (8)|NADCON5 (2D)|0.5 + EPSG|8555|NAD27 to NAD83 (7)|NADCON5 (2D)|0.15 + EPSG|9111|NAD27 to NAD83 (9)|NTv2|1.5 + ESRI|108003|NAD_1927_To_NAD_1983_PR_VI|NTv2|0.05 + +As we have found direct transformations, we will not attempt any more complicated +research. +One can note in the above result set that a ESRI:108003 operation was found, +but as the source and target CRS are in the EPSG registry, and there are +operations between those CRS in the EPSG registry itself, transformations from +other authorities will be ignored (except if they are in the PROJ authority, +which can be used as an override). + +As those results all involve operations that does not have a perfect accuracy and that +does not cover the area of use of the 2 CRSs, a +'Ballpark geographic offset from NAD27 to NAD83' operation is synthetized by PROJ +(see :term:`Ballpark transformation`) + +Filtering and sorting of coordinate operations +---------------------------------------------- + +The last step is to filter and sort results in order of relevance. + +The filtering takes into account the following criteria to decide which operations +must be retained or discarded: + +* a minimum accuracy that the user might have expressed, +* an area of use on which the coordinate operation(s) must apply +* if the absence of grids needed by an operation must result in discarding it. + +The sorting algorithm determines the order of relevance of the operations we got. +A comparison function compares pair of operations to determine which of the +two is the most relevant. This is implemented by the :cpp:func:`operator ()` +method of the SortFunction structure. +When comparing two operations, the following criteria are used. The tests are +performed in the order they are listed below: + +1. consider as more relevant an operation that can be expressed as a PROJ operation string + (the database might list operations whose method is not (yet) implemented by PROJ) +2. if both operations evaluate identically with respect to the above criterion, + consider as more relevant an operation that does not include a synthetic + ballpark vertical transformation (occurs when there is a geoid model). +3. if both operations evaluate identically with respect to the above criterion, + consider as more relevant an operation that does not include a synthetic + ballpark horizontal transformation. +4. consider as more relevant an operation that refers to shift grids that are locally available. +5. consider as more relevant an operation that refers to grids that are available + in one of the proj-datumgrid packages, but not necessarily locally available +6. consider as more relevant an operation that has a known accuracy. +7. if two operations have unknown accuracy, consider as more relevant an operation + that uses grid(s) if the other one does not (grid based operations are assumed + to be more precise than operations relying on a few parameters) +8. consider as more relevant an operation whose area of use is larger + (note: the computation of the are of use is approximate, based on a bounding box) +9. consider as more relevant an operation that has a better accuracy. +10. in case of same accuracy, consider as more relevant an operation that does + not use grids (operations that use only parameters will be faster) +11. consider as more relevant an operation that involves less transformation steps + (transformation steps considered are the ones listed in the WKT output, not PROJ pipeline steps) +12. and for completeness, if two operations are comparable given all the above criteria, + consider as more relevant the one which has the shorter name, and if they + have the same length, consider as more relevant the one whose name comes last in + lexicographic order (e.g. "FOO to BAR (3)" will have higher precedence than + "FOO to BAR (2)") + +.. note:: + + :c:func:`proj_trans`, on the results returned by :c:func:`proj_create_crs_to_crs`, + will not necessarily use the operation that + is listed in first position due to the above algorithm. :c:func:`proj_trans` + has more context, since it has the coordinate to transform, so it can compare + this coordinate to the area of use of operations. Typically, the above criteria + will favor an operation that has a larger area of use over another one with a + smaller area, due to it being more generally applicable. But once coordinates are known, + :c:func:`proj_trans` can select an operation with a smaller + area of use that applies to the coordinate to transform. + +Geodetic/geographic CRS to Geodetic/geographic CRS, without known identifiers +----------------------------------------------------------------------------- + +In a number of situations, the source and/or target CRS do not have an identifier +(WKT without identifier, PROJ string, ..) +The first step is to try to find in the :file:`proj.db` a CRS of the same nature of +the CRS to identify and whose name exactly matches the one provided to the +:c:func:`createOperations` method. If there is exactly one match and that the CRS are +"computationally" equivalent, then use the code of the CRS for further computations. + +If this search did not succeed, or if the previous case with known CRS identifiers +did not result in matches in the database, the search will be based on the +datums. That is, a list of geographic CRS whose datum matches the datum of the +source and target CRS is searched for in the database (by querying the `geodetic_crs` +database table). If the datum has a known +identifier, we will use it, otherwise we will look for an equivalent datum in the +database based on the datum name. + +Let's consider the case where the datum of the source CRS is EPSG:6171 "Reseau +Geodesique Francais 1993" and the datum of the target CRS is EPSG:6258 "European +Terrestrial Reference System 1989". +For EPSG:6171, there are 10 matching (non-deprecated) geodetic CRSs: + +- EPSG:4171, RGF93, geographic 2D +- EPSG:4964, RGF93, geocentric +- EPSG:4965, RGF93, geographic 3D +- EPSG:7042, RGF93 (lon-lat), geographic 3D +- EPSG:7084, RGF93 (lon-lat), geographic 2D +- IGNF:RGF93, RGF93 cartesiennes geocentriques, geocentric +- IGNF:RGF93GDD, RGF93 geographiques (dd),geographic 2D +- IGNF:RGF93GEODD, RGF93 geographiques (dd), geographic 3D +- IGNF:RGF93G, RGF93 geographiques (dms), geographic 2D +- IGNF:RGF93GEO, RGF93 geographiques (dms), geographic 3D + +The first three entries from the EPSG dataset are typical: for each datum, +one can define a geographic 2D CRS (latitude, longitude), a geographic 3D crs +(latitude, longitude, ellipsoidal height) and a geocentric one. For that particular +case, the EPSG dataset has also included two extra definitions corresponding to a +longitude, latitude, [ellipsoidal height] coordinate system, as found in the official +French IGNF registry. This IGNF registry has also definitions for a geographic 2D +CRS (with an extra subtlety with an entry using decimal degree as unit and another +one degree-minute-second), geographic 3D and geocentric. + +For EPSG:6258, there are 7 matching (non-deprecated) geodetic CRSs: + +- EPSG:4258, ETRS89, geographic 2D +- EPSG:4936, ETRS89, geocentric +- EPSG:4937, ETRS89, geographic 3D +- IGNF:ETRS89, ETRS89 cartesiennes geocentriques, geocentric +- IGNF:ETRS89G, ETRS89 geographiques (dms), geographic 2D +- IGNF:ETRS89GEO, ETRS89 geographiques (dms), geographic 3D +- ESRI:104129, GCS_EUREF_FIN, geographic 2D + +So the 3 typical EPSG entries, 3 equivalent (with long, lat ordering for the +geographic CRS) and one from the ESRI registry; + +PROJ can now test 10 x 7 different combinations of source x target CRSs, using +the database searching method explained in the previous section. As soon as +one of this combination returns at least one non-ballpark combination, the result +set coming from that combination is used. PROJ will then add before that +transformation a conversion between the source CRS and the first intermediate CRS, +and will add at the end a conversion between the second intermediate CRS and the +target CRS. Those conversions are conversion between geographic 2D and geographic 3D +CRS or geographic 2D/3D and geocentric CRS. + +This is done by the :c:func:`createOperationsWithDatumPivot()` method. + +So if transforming between EPSG:7042, RGF93 (lon-lat), geographic 3D and +EPSG:4936, ETRS89, geocentric, one get the following concatenated operation, +chaining an axis order change, the null geocentric translation between +RGF93 and ETRS89 (EPSG:1591), and a conversion between geographic and geocentric +coordinates. This concatenated operation is assumed to have a perfect accuracy +as both the initial and final operations are conversions, and the middle transformation +accounts for the fact that the RGF93 datum is one realization of ETRS89, so they +are equivalent for most purposes. + +.. code-block:: shell + + $ projinfo -s EPSG:7042 -t EPSG:4936 + + Candidate operations found: 1 + ------------------------------------- + Operation No. 1: + + unknown id, axis order change (geographic3D horizontal) + RGF93 to ETRS89 (1) + Conversion from ETRS89 (geog2D) to ETRS89 (geocentric), 0 m, France + + PROJ string: + +proj=pipeline +step +proj=unitconvert +xy_in=deg +xy_out=rad +step +proj=cart +ellps=GRS80 + + WKT2:2019 string: + CONCATENATEDOPERATION["axis order change (geographic3D horizontal) + RGF93 to ETRS89 (1) + Conversion from ETRS89 (geog2D) to ETRS89 (geocentric)", + SOURCECRS[ + GEOGCRS["RGF93 (lon-lat)", + [...] + ID["EPSG",7042]]], + TARGETCRS[ + GEODCRS["ETRS89", + [...] + ID["EPSG",4936]]], + STEP[ + CONVERSION["axis order change (geographic3D horizontal)", + METHOD["Axis Order Reversal (Geographic3D horizontal)", + ID["EPSG",9844]], + ID["EPSG",15499]]], + STEP[ + COORDINATEOPERATION["RGF93 to ETRS89 (1)", + [...] + METHOD["Geocentric translations (geog2D domain)", + ID["EPSG",9603]], + PARAMETER["X-axis translation",0, + LENGTHUNIT["metre",1], + ID["EPSG",8605]], + PARAMETER["Y-axis translation",0, + LENGTHUNIT["metre",1], + ID["EPSG",8606]], + PARAMETER["Z-axis translation",0, + LENGTHUNIT["metre",1], + ID["EPSG",8607]], + OPERATIONACCURACY[0.0], + ID["EPSG",1591], + REMARK["May be taken as approximate transformation RGF93 to WGS 84 - see code 1671."]]], + STEP[ + CONVERSION["Conversion from ETRS89 (geog2D) to ETRS89 (geocentric)", + METHOD["Geographic/geocentric conversions", + ID["EPSG",9602]]]], + USAGE[ + SCOPE["unknown"], + AREA["France"], + BBOX[41.15,-9.86,51.56,10.38]]] + +Geodetic/geographic CRS to Geodetic/geographic CRS, without direct transformation +--------------------------------------------------------------------------------- + +Still considering transformations between geodetic/geographic CRS, but let's +consider that the lookup in the database for a transformation between +the source and target CRS (possibly going through the "equivalent" CRS based on +the same datum as detailed in the previous section) leads to an empty set. + +Of course, as most operations are invertible, one first tries to do a lookup switching +the source and target CRS, and inverting the resulting operation(s): + +.. code-block:: shell + + $ projinfo -s NAD83 -t NAD27 --spatial-test intersects --summary + + Candidate operations found: 10 + INVERSE(DERIVED_FROM(EPSG)):1312, Inverse of NAD27 to NAD83 (3), 2.0 m, Canada + INVERSE(DERIVED_FROM(EPSG)):1313, Inverse of NAD27 to NAD83 (4), 1.5 m, Canada - NAD27 + INVERSE(DERIVED_FROM(EPSG)):1241, Inverse of NAD27 to NAD83 (1), 0.15 m, USA - CONUS including EEZ + INVERSE(DERIVED_FROM(EPSG)):1243, Inverse of NAD27 to NAD83 (2), 0.5 m, USA - Alaska including EEZ + INVERSE(DERIVED_FROM(EPSG)):1573, Inverse of NAD27 to NAD83 (6), 1.5 m, Canada - Quebec, at least one grid missing + INVERSE(EPSG):1462, Inverse of NAD27 to NAD83 (5), 2.0 m, Canada - Quebec, at least one grid missing + INVERSE(EPSG):9111, Inverse of NAD27 to NAD83 (9), 1.5 m, Canada - Saskatchewan, at least one grid missing + unknown id, Ballpark geographic offset from NAD83 to NAD27, unknown accuracy, World, has ballpark transformation + INVERSE(EPSG):8555, Inverse of NAD27 to NAD83 (7), 0.15 m, USA - CONUS and GoM, at least one grid missing + INVERSE(EPSG):8549, Inverse of NAD27 to NAD83 (8), 0.5 m, USA - Alaska, at least one grid missing + +That was an easy case. Now let's consider the transformation between the Australian +CRS AGD84 and GDA2020. There is no direct transformation from AGD84 to GDA2020, or +in the reverse direction, even when considering alternative geodetic CRS based on +the underlying datums. PROJ will then do a cross-join in the coordinate_operation_view +table to find the tuples (op1, op2) of coordinate operations such that: + +- SOURCE_CRS = op1.source_crs AND op1.target_crs = op2.source_crs AND op2.target_crs = TARGET_CRS or +- SOURCE_CRS = op1.source_crs AND op1.target_crs = op2.target_crs AND op2.source_crs = TARGET_CRS or +- SOURCE_CRS = op1.target_crs AND op1.source_crs = op2.source_crs AND op2.target_crs = TARGET_CRS or +- SOURCE_CRS = op1.target_crs AND op1.source_crs = op2.target_crs AND op2.source_crs = TARGET_CRS + +Depending on which case is selected, op1 and op2 should be reversed, before +being concatenated. + +This logic is implement by the ``findsOpsInRegistryWithIntermediate()`` method. + +Assuming that the proj-datumgrid-oceania package is installed, we get the +following results for the AGD84 to GDA2020 coordinate operations lookup: + +.. code-block:: shell + + $ projinfo -s AGD84 -t GDA2020 --spatial-test intersects -o PROJ + + Candidate operations found: 4 + ------------------------------------- + Operation No. 1: + + unknown id, AGD84 to GDA94 (5) + GDA94 to GDA2020 (1), 0.11 m, Australia - AGD84 + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=hgridshift +grids=National_84_02_07_01.gsb \ + +step +proj=push +v_3 \ + +step +proj=cart +ellps=GRS80 \ + +step +proj=helmert +x=0.06155 +y=-0.01087 +z=-0.04019 \ + +rx=-0.0394924 +ry=-0.0327221 +rz=-0.0328979 \ + +s=-0.009994 +convention=coordinate_frame \ + +step +inv +proj=cart +ellps=GRS80 \ + +step +proj=pop +v_3 \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + + ------------------------------------- + Operation No. 2: + + unknown id, AGD84 to GDA94 (2) + GDA94 to GDA2020 (1), 1.01 m, Australia - AGD84 + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=push +v_3 \ + +step +proj=cart +ellps=aust_SA \ + +step +proj=helmert +x=-117.763 +y=-51.51 +z=139.061 \ + +rx=-0.292 +ry=-0.443 +rz=-0.277 +s=-0.191 \ + +convention=coordinate_frame \ + +step +proj=helmert +x=0.06155 +y=-0.01087 +z=-0.04019 \ + +rx=-0.0394924 +ry=-0.0327221 +rz=-0.0328979 \ + +s=-0.009994 +convention=coordinate_frame \ + +step +inv +proj=cart +ellps=GRS80 \ + +step +proj=pop +v_3 \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + + ------------------------------------- + Operation No. 3: + + unknown id, AGD84 to GDA94 (5) + GDA94 to GDA2020 (2), 0.15 m, unknown domain of validity + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=hgridshift +grids=National_84_02_07_01.gsb \ + +step +proj=hgridshift +grids=GDA94_GDA2020_conformal_and_distortion.gsb \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + + ------------------------------------- + Operation No. 4: + + unknown id, AGD84 to GDA94 (5) + GDA94 to GDA2020 (3), 0.15 m, unknown domain of validity + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=hgridshift +grids=National_84_02_07_01.gsb \ + +step +proj=hgridshift +grids=GDA94_GDA2020_conformal.gsb \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + +One can see that the selected intermediate CRS that has been used is GDA94. +This is a completely novel behavior of PROJ 6 as opposed to the logic of PROJ.4 +where datum transformations implied using EPSG:4326 / WGS 84 has the mandatory +datum hub. PROJ 6 no longer hardcodes it as the mandatory datum hub, and relies +on the database to find the appropriate hub(s). +Actually, WGS 84 has been considered during the above lookup, because there are +transformations between AGD84 and WGS 84 and WGS 84 and GDA2020. However those +have been discarded in a step which we did not mention previously: just after +the initial filtering of results and their sorting, there is a final filtering +that is done. In the list of sorted results, given two operations A and B that +have the same area of use, if B has an accuracy lower than A, and A does not use +grids, or all the needed grids are available, then B is discarded. + +If one forces the datum hub to be considered to be EPSG:4326, ones gets: + +.. code-block:: shell + + $ projinfo -s AGD84 -t GDA2020 --spatial-test intersects --pivot-crs EPSG:4326 -o PROJ + + Candidate operations found: 2 + ------------------------------------- + Operation No. 1: + + unknown id, AGD84 to WGS 84 (7) + Inverse of GDA2020 to WGS 84 (2), 4 m, Australia - AGD84 + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=push +v_3 \ + +step +proj=cart +ellps=aust_SA \ + +step +proj=helmert +x=-117.763 +y=-51.51 +z=139.061 \ + +rx=-0.292 +ry=-0.443 +rz=-0.277 \ + +s=-0.191 +convention=coordinate_frame \ + +step +inv +proj=cart +ellps=GRS80 \ + +step +proj=pop +v_3 \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + + ------------------------------------- + Operation No. 2: + + unknown id, AGD84 to WGS 84 (9) + Inverse of GDA2020 to WGS 84 (2), 4 m, Australia - AGD84 + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 \ + +step +proj=unitconvert +xy_in=deg +xy_out=rad \ + +step +proj=hgridshift +grids=National_84_02_07_01.gsb \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg \ + +step +proj=axisswap +order=2,1 + +Those operations are less accurate, since WGS 84 is assumed to be equivalent to +GDA2020 with an accuracy of 4 metre. This is an instance demonstrating that using +WGS 84 as a hub systematically can be sub-optimal. + +There are still situations where the attempt to find a hub CRS does not work, +because there is no such hub. This can occur for example when transforming from +GDA94 to the latest realization at time of writing of WGS 84, WGS 84 (G1762). +There are transformations between WGS 84 (G1762). Using the above described +techniques, we would only find one non-ballpark operation taking the route: +1. Conversion from GDA94 (geog2D) to GDA94 (geocentric): synthetized by PROJ +2. Inverse of ITRF2008 to GDA94 (1): from EPSG +3. Inverse of WGS 84 (G1762) to ITRF2008 (1): from EPSG +4. Conversion from WGS 84 (G1762) (geocentric) to WGS 84 (G1762): synthetized by PROJ + +This is not bad, but the global validity area of use is "Australia - onshore and EEZ", +whereas GDA94 has a larger area of use. +There is another road that can be taken by going through GDA2020 instead of ITRF2008. +The GDA94 to GDA2020 transformations operate on the respective geographic CRS, +whereas GDA2020 to WGS 84 (G1762) operate on the geocentric CRS. Consequently, +GDA2020 cannot be identifier as a hub by a "simple" self-join SQL request on +the coordinate operation table. This requires to do the join based on the datum +referenced by the source and target CRS of each operation rather than the +source and target CRS themselves. When there is a match, PROJ inserts the required +conversions between geographic and geocentric CRS to have a consistent concatenated +operation, like the following: +1. GDA94 to GDA2020 (1): from EPSG +2. Conversion from GDA2020 (geog2D) to GDA2020 (geocentric): synthetized by PROJ +3. GDA2020 to WGS 84 (G1762) (1): from EPSG +4. Conversion from WGS 84 (G1762) (geocentric) to WGS 84 (G1762) (geog2D): synthetized by PROJ + +Projected CRS to any target CRS +--------------------------------------------------------------------------------- + +This actually extends to any Derived CRS, whose Projected CRS is a well-known +particular case. Such transformations are done in 2 steps: + +1. Use the inverse conversion of the derived CRS to its base CRS, typically an + inverse map projection. +2. Find transformations from this base CRS to the target CRS. If the base CRS + is the target CRS, this step can be skipped. + +.. code-block:: shell + + $ projinfo -s EPSG:32631 -t RGF93 + + Candidate operations found: 1 + ------------------------------------- + Operation No. 1: + + unknown id, Inverse of UTM zone 31N + Inverse of RGF93 to WGS 84 (1), 1 m, France + + PROJ string: + +proj=pipeline +step +inv +proj=utm +zone=31 +ellps=WGS84 +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1 + +This is implemented by the ``createOperationsDerivedTo`` method + +For the symmetric case, source CRS to a derived CRS, the above algorithm is applied +by switching the source and target CRS, and then inverting the resulting operation(s). +This is mostly a matter of avoiding to write very similar code twice. This logic +is also applied to all below cases when considering the transformation between 2 different +types of objects. + +.. _verttogeog: + +Vertical CRS to a Geographic CRS +--------------------------------------------------------------------------------- + +Such transformation is normally not meant as being used as standalone by PROJ +users, but as an internal computation step of a Compound CRS to a target CRS. + +In cases where we are lucky, the PROJ database will have a transformation registered +between those: + +.. code-block:: shell + + $ projinfo -s "NAVD88 height" -t "NAD83(2011)" -o PROJ --spatial-test intersects + Candidate operations found: 11 + ------------------------------------- + Operation No. 1: + + INVERSE(DERIVED_FROM(EPSG)):9229, Inverse of NAD83(2011) to NAVD88 height (3), 0.015 m, USA - CONUS - onshore + + PROJ string: + +proj=vgridshift +grids=g2018u0.gtx +multiplier=1 + + +But in cases where there is no match, the ``createOperationsVertToGeog`` method +will be used to synthetize a ballpark vertical transformation, just taking care +of unit changes, and axis reversal in case the vertical CRS was a depth rather than +a height. Of course the results of such an operation are questionable, hence the +ballpark qualifier and a unknown accuracy advertized for such an operation. + +Vertical CRS to a Vertical CRS +--------------------------------------------------------------------------------- + +Overall logic is similar to the above case. There might be direct operations in +the PROJ database, involving grid transformations or simple offsets. The fallback +case is to synthetize a ballpark transformation. + +This is implemented by the ``createOperationsVertToVert`` method + +.. code-block:: shell + + $ projinfo -s "NGVD29 depth (ftUS)" -t "NAVD88 height" --spatial-test intersects -o PROJ + + Candidate operations found: 3 + ------------------------------------- + Operation No. 1: + + unknown id, Inverse of NGVD29 height (ftUS) to NGVD29 depth (ftUS) + NGVD29 height (ftUS) to NGVD29 height (m) + NGVD29 height (m) to NAVD88 height (3), 0.02 m, USA - CONUS east of 89°W - onshore + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=1,2,-3 +step +proj=unitconvert +z_in=us-ft +z_out=m +step +proj=vgridshift +grids=vertcone.gtx +multiplier=0.001 + + ------------------------------------- + Operation No. 2: + + unknown id, Inverse of NGVD29 height (ftUS) to NGVD29 depth (ftUS) + NGVD29 height (ftUS) to NGVD29 height (m) + NGVD29 height (m) to NAVD88 height (2), 0.02 m, USA - CONUS 89°W-107°W - onshore + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=1,2,-3 +step +proj=unitconvert +z_in=us-ft +z_out=m +step +proj=vgridshift +grids=vertconc.gtx +multiplier=0.001 + + ------------------------------------- + Operation No. 3: + + unknown id, Inverse of NGVD29 height (ftUS) to NGVD29 depth (ftUS) + NGVD29 height (ftUS) to NGVD29 height (m) + NGVD29 height (m) to NAVD88 height (1), 0.02 m, USA - CONUS west of 107°W - onshore + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=1,2,-3 +step +proj=unitconvert +z_in=us-ft +z_out=m +step +proj=vgridshift +grids=vertconw.gtx +multiplier=0.001 + + +Compound CRS to a Geographic CRS +--------------------------------------------------------------------------------- + +A typical example of a Compound CRS is a CRS made of a geographic or projected CRS +as the horizontal component, and a vertical CRS. E.g. "NAD83 + NAVD88 height" + +When the horizontal component of the compound source CRS is a projected CRS, we +first look for the operation from this source CRS to another compound CRS made +of the geographic CRS base of the projected CRS, +like "NAD83 / California zone 1 (ftUS) + NAVD88 height" to "NAD83 + NAVD88 height", +which ultimately goes to one of the above described case. Then we can consider +the transformation from a compound CRS made of a geographic CRS to another geographic CRS. + +It first starts by the vertical transformations from the vertical CRS of the +source compound CRS to the target geographic CRS, using the strategy detailed +in :ref:`Vertical CRS to a Geographic CRS <verttogeog>` + +What we did not mention is that when there is not a transformation registered +between the vertical CRS and the target geographic CRS, PROJ attempts to find +transformations between that vertical CRS and any other geographic CRS. This is +clearly an approximation. +If the research of the vertical CRS to the target geographic CRS resulted in +operations that use grids that are not available, as another approximation, we +research operations from the vertical CRS to the source geographic CRS for the +vertical component. + +Once we got those more or less accurate vertical transformations, we must consider +the horizontal transformation(s). The algorithm iterates over all found vertical +transformations and look for their target geographic CRS. This will be used as +the interpolation CRS for horizontal transformations. PROJ will then look for +available transformations from the source geographic CRS to the interpolation CRS +and from the interpolation CRS to the target geographic CRS. There is then a +3-level loop to create the final set of operations chaining together: + +- the horizontal transformation from the source geographic CRS to the interpolation CRS +- the vertical transformation from the source vertical CRS to the interpolation CRS +- the horizontal transformation from the interpolation CRS to the target geographic CRS. + +This is implemented by the ``createOperationsCompoundToGeog`` method + +Example: + +.. code-block:: shell + + $ projinfo -s "NAD83(NSRS2007) + NAVD88 height" -t "WGS 84 (G1762)" --spatial-test intersects --summary + + Candidate operations found: 21 + unknown id, Inverse of NAD83(NSRS2007) to NAVD88 height (1) + NAD83(NSRS2007) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.05 m, USA - CONUS - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (7) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, 95°W to 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (7) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, 95°W to 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (6) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, 112°W to 95°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (6) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, 112°W to 95°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (2) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, 112°W to 95°W + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (2) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, 112°W to 95°W + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (3) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, 95°W to 78°W + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (3) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, 95°W to 78°W + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (5) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, west of 112°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (5) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, west of 112°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (1) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, west of 112°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (1) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, west of 112°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (4) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, east of 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (4) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS north of 41°N, east of 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (8) + NAD83(HARN) to WGS 84 (1) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, east of 78°W - onshore + unknown id, Inverse of NAD83(HARN) to NAD83(NSRS2007) (1) + Inverse of NAD83(HARN) to NAVD88 height (8) + NAD83(HARN) to WGS 84 (3) + WGS 84 to WGS 84 (G1762), 3.15 m, USA - CONUS south of 41°N, east of 78°W - onshore + unknown id, Ballpark geographic offset from NAD83(NSRS2007) to NAD83(FBN) + Inverse of NAD83(FBN) to NAVD88 height (1) + Ballpark geographic offset from NAD83(FBN) to WGS 84 (G1762), unknown accuracy, USA - CONUS - onshore, has ballpark transformation + unknown id, Ballpark geographic offset from NAD83(NSRS2007) to NAD83(2011) + Inverse of NAD83(2011) to NAVD88 height (3) + Ballpark geographic offset from NAD83(2011) to WGS 84 (G1762), unknown accuracy, USA - CONUS - onshore, has ballpark transformation + unknown id, Ballpark geographic offset from NAD83(NSRS2007) to NAD83(2011) + Inverse of NAD83(2011) to NAVD88 height (3) + Conversion from NAD83(2011) (geog2D) to NAD83(2011) (geocentric) + Inverse of ITRF2008 to NAD83(2011) (1) + Inverse of WGS 84 (G1762) to ITRF2008 (1) + Conversion from WGS 84 (G1762) (geocentric) to WGS 84 (G1762) (geog2D), unknown accuracy, USA - CONUS - onshore, has ballpark transformation + unknown id, NAD83(NSRS2007) to WGS 84 (1) + WGS 84 to WGS 84 (G1762) + Transformation from NAVD88 height to WGS 84 (G1762) (ballpark vertical transformation, without ellipsoid height to vertical height correction), unknown accuracy, USA - CONUS and Alaska; PRVI, has ballpark transformation + + +CompoundCRS to CompoundCRS +--------------------------------------------------------------------------------- + +There is some similarity with the previous paragraph. We first research the +vertical transformations between the two vertical CRS. + +1. If there is such a transformation, be it direct, or if both vertical CRS + relate to a common intermediate CRS. + If it has a registered interpolation geographic CRS, then it is used. + Otherwise we fallback to the geographic CRS of the source CRS. + + Finally, a 3-level loop to create the final set of operations chaining together: + + - the horizontal transformation from the source CRS to the interpolation CRS + - the vertical transformation + - the horizontal transformation from the interpolation CRS to the target CRS. + + Example: + + .. code-block:: shell + + $ projinfo -s "NAD27 + NGVD29 height (ftUS)" -t "NAD83 + NAVD88 height" --spatial-test intersects --summary + + Candidate operations found: 20 + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + NAD27 to NAD83 (1), 0.17 m, USA - CONUS east of 89°W - onshore + unknown id, NGVD29 height (ftUS) to NAVD88 height (2) + NAD27 to NAD83 (1), 0.17 m, USA - CONUS 89°W-107°W - onshore + unknown id, NGVD29 height (ftUS) to NAVD88 height (1) + NAD27 to NAD83 (1), 0.17 m, USA - CONUS west of 107°W - onshore + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + NAD27 to NAD83 (3), 1.02 m, unknown domain of validity + unknown id, NGVD29 height (ftUS) to NAVD88 height (2) + NAD27 to NAD83 (3), 1.02 m, unknown domain of validity + unknown id, NGVD29 height (ftUS) to NAVD88 height (1) + NAD27 to NAD83 (3), 1.02 m, unknown domain of validity + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + NAD27 to NAD83 (5), 1.02 m, unknown domain of validity, at least one grid missing + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + NAD27 to NAD83 (6), 1.52 m, unknown domain of validity, at least one grid missing + unknown id, NGVD29 height (ftUS) to NAVD88 height (2) + NAD27 to NAD83 (9), 1.52 m, unknown domain of validity, at least one grid missing + unknown id, NGVD29 height (ftUS) to NAVD88 height (1) + NAD27 to NAD83 (9), 1.52 m, unknown domain of validity, at least one grid missing + unknown id, NGVD29 height (ftUS) to NAVD88 height (3) + Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, USA - CONUS east of 89°W - onshore, has ballpark transformation + unknown id, NGVD29 height (ftUS) to NAVD88 height (2) + Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, USA - CONUS 89°W-107°W - onshore, has ballpark transformation + unknown id, NGVD29 height (ftUS) to NAVD88 height (1) + Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, USA - CONUS west of 107°W - onshore, has ballpark transformation + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (1), unknown accuracy, USA - CONUS including EEZ, has ballpark transformation + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (3), unknown accuracy, Canada, has ballpark transformation + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (4), unknown accuracy, Canada - NAD27, has ballpark transformation + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (5), unknown accuracy, Canada - Quebec, has ballpark transformation, at least one grid missing + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (6), unknown accuracy, Canada - Quebec, has ballpark transformation, at least one grid missing + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + NAD27 to NAD83 (9), unknown accuracy, Canada - Saskatchewan, has ballpark transformation, at least one grid missing + unknown id, Transformation from NGVD29 height (ftUS) to NAVD88 height (ballpark vertical transformation) + Ballpark geographic offset from NAD27 to NAD83, unknown accuracy, World, has ballpark transformation + + +2. Otherwise, when there is no such transformation, we decompose into 3 steps: + + - transform from the source CRS to the geographic 3D CRS corresponding to it + - transform from the geographic 3D CRS corresponding to the source CRS to the + geographic 3D CRS corresponding to the target CRS + - transform from the geographic 3D CRS corresponding to the target CRS to the + target CRS. + + Example: + + .. code-block:: shell + + $ projinfo -s "WGS 84 + EGM96 height" -t "ETRS89 + Belfast height" --spatial-test intersects --summary + + Candidate operations found: 7 + unknown id, Inverse of WGS 84 to EGM96 height (1) + Inverse of ETRS89 to WGS 84 (1) + ETRS89 to Belfast height (2), 2.014 m, UK - Northern Ireland - onshore + unknown id, Inverse of WGS 84 to EGM96 height (1) + Inverse of ETRS89 to WGS 84 (1) + ETRS89 to Belfast height (1), 2.03 m, UK - Northern Ireland - onshore, at least one grid missing + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of OSGB 1936 to WGS 84 (4) + OSGB 1936 to ETRS89 (2) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (2), 19.044 m, unknown domain of validity + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of OSGB 1936 to WGS 84 (2) + OSGB 1936 to ETRS89 (2) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (2), 11.044 m, unknown domain of validity + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of TM75 to WGS 84 (2) + TM75 to ETRS89 (3) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (2), 2.424 m, UK - Northern Ireland - onshore, at least one grid missing + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of TM75 to WGS 84 (2) + TM75 to ETRS89 (3) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (1), 2.44 m, UK - Northern Ireland - onshore, at least one grid missing + unknown id, Inverse of WGS 84 to EGM96 height (1) + Null geographic offset from WGS 84 (geog3D) to WGS 84 (geog2D) + Inverse of OSGB 1936 to WGS 84 (4) + OSGB 1936 to ETRS89 (2) + Null geographic offset from ETRS89 (geog2D) to ETRS89 (geog3D) + ETRS89 to Belfast height (1), 19.06 m, unknown domain of validity, at least one grid missing + + +This is implemented by the ``createOperationsCompoundToCompound`` method + +When the source or target CRS is a BoundCRS +--------------------------------------------------------------------------------- + +The BoundCRS concept is an hybrid concept where a CRS is linked to a transformation +from it to a hub CRS, typically WGS 84. This is a long-time practice in PROJ.4 +strings with the ``+towgs84``, ``+nadgrids`` and ``+geoidgrids`` keywords, or the +``TOWGS84[]`` node of WKT 1. When encountering those attributes when parsing +a CRS string, PROJ will create a BoundCRS object capturing this transformation. +A BoundCRS object can also be provided with a WKT2 string, and in that case with +a hub CRS being potentially different from WGS 84. + +Let's consider the case of a transformation between a BoundCRS +("+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 ++ellps=airy +towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489 +units=m" +which used to be the PROJ.4 definition of "OSGB 1936 / British National Grid") +and a target Geographic CRS, ETRS89. + +We apply the following steps: + +- transform from the base of the source CRS (that is the CRS wrapped by BoundCRS, + here a ProjectedCRS) to the geographic CRS of this base CRS +- apply the transformation of the BoundCRS to go from the geographic CRS of this base CRS + to the hub CRS of the BoundCRS, in that instance WGS 84. +- apply a transformation from the hub CRS to the target CRS. + +This is implemented by the ``createOperationsBoundToGeog`` method + +Example: + +.. code-block:: shell + + $ projinfo -s "+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489 +units=m +type=crs" -t ETRS89 -o PROJ + + Candidate operations found: 1 + ------------------------------------- + Operation No. 1: + + unknown id, Inverse of unknown + Transformation from unknown to WGS84 + Inverse of ETRS89 to WGS 84 (1), unknown accuracy, Europe - ETRS89 + + PROJ string: + +proj=pipeline +step +inv +proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +step +proj=push +v_3 +step +proj=cart +ellps=airy +step +proj=helmert +x=446.448 +y=-125.157 +z=542.06 +rx=0.15 +ry=0.247 +rz=0.842 +s=-20.489 +convention=position_vector +step +inv +proj=cart +ellps=GRS80 +step +proj=pop +v_3 +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1 + +There are other situations with BoundCRS, involving vertical transformations, +or transforming to other objects than a geographic CRS, but the curious reader +will have to inspect the code for the actual gory details. diff --git a/_sources/operations/pipeline.rst.txt b/_sources/operations/pipeline.rst.txt new file mode 100644 index 00000000..97b58e3e --- /dev/null +++ b/_sources/operations/pipeline.rst.txt @@ -0,0 +1,161 @@ +.. _pipeline: + +================================================================================ +The pipeline operator +================================================================================ + +.. versionadded:: 5.0.0 + +Construct complex operations by daisy-chaining operations in a sequential pipeline. + ++-----------------+--------------------------------------------------------------------+ +| **Alias** | pipeline | ++-----------------+--------------------------------------------------------------------+ +| **Domain** | 2D, 3D and 4D | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Any | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Any | ++-----------------+--------------------------------------------------------------------+ + +.. note:: See the section on :ref:`transformation` for a more thorough introduction + to the concept of transformation pipelines in PROJ. + + +With the pipeline operation it is possible to perform several operations after each +other on the same input data. This feature makes it possible to create transformations +that are made up of more than one operation, e.g. performing a datum shift and then +applying a suitable map projection. Theoretically any transformation between two +coordinate reference systems is possible to perform using the pipeline operation, +provided that the necessary coordinate operations in each step is available in PROJ. + +A pipeline is made up of a number of steps, with each step being a coordinate operation +in itself. By connecting these individual steps sequentially we end up with a concatenated +coordinate operation. An example of this is a transformation from geodetic coordinates +on the GRS80 ellipsoid to a projected system where the east-west and north-east axes has +been swapped: + +:: + + +proj=pipeline +ellps=GRS80 +step +proj=merc +step +proj=axisswap +order=2,1 + +Here the first step is applying the :ref:`merc` projection and the second step is +applying the :ref:`axisswap` conversion. Note that the `+ellps=GRS80` is specified +before the first occurrence of `+step`. This means that the GRS80 ellipsoid is used +in both steps, since any parameter stated before the first occurrence of `+step` is +treated as a global parameter and is transferred to each individual steps. + + +Rules for pipelines +------------------------------------------------------------------------------- + +**1. Pipelines must consist of at least one step.** + +:: + + +proj=pipeline + +Will result in an error. + +**2. Pipelines can only be nested if the nested pipeline is defined in an init file.** + +:: + + +proj=pipeline + +step +proj=pipeline +step +proj=merc +step +proj=axisswap +order=2,1 + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +Results in an error, while + +:: + + +proj=pipeline + +step +init=predefined_pipelines:projectandswap + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +does not. + +**3. Pipelines without a forward path can't be constructed.** + +:: + + +proj=pipeline +step +inv +proj=urm5 + +Will result in an error since :ref:`urm5` does not have an inverse operation defined. + +.. _global-pipeline-parameter: + +**4. Parameters added before the first `+step` are global and will be applied to all steps.** + +In the following the GRS80 ellipsoid will be applied to all steps. + +:: + + +proj=pipeline +ellps=GRS80 + +step +proj=cart + +step +proj=helmert +x=10 +y=3 +z=1 + +step +proj=cart +inv + +step +proj=merc + +**5. Units of operations must match between steps.** + +.. versionadded:: 5.1.0 + +The output units of step *n* must match the expected input unit of step *n+1*. E.g., you can't +pass an operation that outputs projected coordinates to an operation that expects angular units +(degrees). An example of such a unit mismatch is displayed below. + +:: + + +proj=pipeline + +step +proj=merc # Mercator outputs projected coordinates + +step +proj=robin # The Robinson projection expects angular input + +Parameters +------------------------------------------------------------------------------- + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +step + + Separate each step in a pipeline. + + +Optional ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +inv + + Invert a step in a pipeline. + +.. option:: +omit_fwd + + .. versionadded:: 6.3.0 + + Skip a step of the pipeline when it is followed in the forward path. + + The following example shows a combined use of :ref:`push <push>` and :ref:`pop <pop>` operators, + with ``omit_fwd`` and ``omit_inv`` options, to implement a vertical adjustment that must + be done in a interpolation CRS that is different from the horizontal CRS + used in input and output. +omit_fwd in the forward path avoid a useless + inverse horizontal transformation and relies on the pop operator to restore + initial horizontal coordinates. +omit_inv serves the similar purpose when + the pipeline is executed in the reverse direction + + :: + + +proj=pipeline + +step +proj=unitconvert +xy_in=deg +xy_out=rad + +step +proj=push +v_1 +v_2 + +step +proj=hgridshift +grids=nvhpgn.gsb +omit_inv + +step +proj=vgridshift +grids=g1999u05.gtx +multiplier=1 + +step +inv +proj=hgridshift +grids=nvhpgn.gsb +omit_fwd + +step +proj=pop +v_1 +v_2 + +step +proj=unitconvert +xy_in=rad +xy_out=deg + +.. option:: +omit_inv + + .. versionadded:: 6.3.0 + + Skip a step of the pipeline when it is followed in the reverse path. diff --git a/_sources/operations/projections/adams_hemi.rst.txt b/_sources/operations/projections/adams_hemi.rst.txt new file mode 100644 index 00000000..96fe78f1 --- /dev/null +++ b/_sources/operations/projections/adams_hemi.rst.txt @@ -0,0 +1,42 @@ +.. _adams_hemi: + +******************************************************************************** +Adams Hemisphere in a Square +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | adams_hemi | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/adams_hemi.png + :width: 500 px + :align: center + :alt: Adams Hemisphere in a Square + + proj-string: ``+proj=adams_hemi`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/adams_ws1.rst.txt b/_sources/operations/projections/adams_ws1.rst.txt new file mode 100644 index 00000000..3283ff57 --- /dev/null +++ b/_sources/operations/projections/adams_ws1.rst.txt @@ -0,0 +1,42 @@ +.. _adams_ws1: + +******************************************************************************** +Adams World in a Square I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | adams_ws1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/adams_ws1.png + :width: 500 px + :align: center + :alt: Adams World in a Square I + + proj-string: ``+proj=adams_ws1`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/adams_ws2.rst.txt b/_sources/operations/projections/adams_ws2.rst.txt new file mode 100644 index 00000000..60630286 --- /dev/null +++ b/_sources/operations/projections/adams_ws2.rst.txt @@ -0,0 +1,42 @@ +.. _adams_ws2: + +******************************************************************************** +Adams World in a Square II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | adams_ws2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/adams_ws2.png + :width: 500 px + :align: center + :alt: Adams World in a Square II + + proj-string: ``+proj=adams_ws2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/aea.rst.txt b/_sources/operations/projections/aea.rst.txt new file mode 100644 index 00000000..47a24251 --- /dev/null +++ b/_sources/operations/projections/aea.rst.txt @@ -0,0 +1,52 @@ +.. _aea: + +******************************************************************************** +Albers Equal Area +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | aea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/aea.png + :width: 500 px + :align: center + :alt: Albers Equal Area + + proj-string: ``+proj=aea +lat_1=29.5 +lat_2=42.5`` + +Options +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/aeqd.rst.txt b/_sources/operations/projections/aeqd.rst.txt new file mode 100644 index 00000000..3c5566ec --- /dev/null +++ b/_sources/operations/projections/aeqd.rst.txt @@ -0,0 +1,49 @@ +.. _aeqd: + +******************************************************************************** +Azimuthal Equidistant +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Alias** | aeqd | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/aeqd.png + :width: 500 px + :align: center + :alt: Azimuthal Equidistant + + proj-string: ``+proj=aeqd`` + + +Options +################################################################################ + +.. note:: All options are optional for the Azimuthal Equidistant projection. + +.. option:: +guam + + Use Guam ellipsoidal formulas. Only accurate near the Island of Guam + (:math:`\lambda\approx 144.5^{\circ}`, :math:`\phi\approx 13.5^{\circ}`) + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst diff --git a/_sources/operations/projections/airy.rst.txt b/_sources/operations/projections/airy.rst.txt new file mode 100644 index 00000000..04af065e --- /dev/null +++ b/_sources/operations/projections/airy.rst.txt @@ -0,0 +1,58 @@ +.. _airy: + +******************************************************************************** +Airy +******************************************************************************** + +The Airy projection is an azimuthal minimum error projection for the region +within the small or great circle defined by an angular distance, +:math:`\phi_b`, from the tangency point of the plane :math:`( \lambda_0, \phi_0 )`. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | airy | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. figure:: ./images/airy.png + :width: 500 px + :align: center + :alt: Airy + + proj-string: ``+proj=airy`` + +Options +################################################################################ + +.. option:: +lat_b + + Angular distance from tangency point of the plane :math:`( \lambda_0, \phi_0 )` + where the error is kept at minimum. + + *Defaults to 90° (suitable for hemispherical maps).* + +.. option:: +no_cut + + Do not cut at hemisphere limit + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/R.rst diff --git a/_sources/operations/projections/aitoff.rst.txt b/_sources/operations/projections/aitoff.rst.txt new file mode 100644 index 00000000..7508445d --- /dev/null +++ b/_sources/operations/projections/aitoff.rst.txt @@ -0,0 +1,40 @@ +.. _aitoff: + +******************************************************************************** +Aitoff +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | aitoff | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/aitoff.png + :width: 500 px + :align: center + :alt: Aitoff + + proj-string: ``+proj=aitoff`` + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/alsk.rst.txt b/_sources/operations/projections/alsk.rst.txt new file mode 100644 index 00000000..5c2b416f --- /dev/null +++ b/_sources/operations/projections/alsk.rst.txt @@ -0,0 +1,39 @@ +.. _alsk: + +******************************************************************************** +Modified Stereographic of Alaska +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Modified azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Alaska | ++---------------------+----------------------------------------------------------+ +| **Alsk** | alsk | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/alsk.png + :width: 500 px + :align: center + :alt: Modified Stereographic of Alaska + + proj-string: ``+proj=alsk`` + +Options +################################################################################ + +.. note:: All options are optional for the projection. + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst diff --git a/_sources/operations/projections/apian.rst.txt b/_sources/operations/projections/apian.rst.txt new file mode 100644 index 00000000..870dc0ce --- /dev/null +++ b/_sources/operations/projections/apian.rst.txt @@ -0,0 +1,44 @@ +.. _apian: + +******************************************************************************** +Apian Globular I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | apian | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/apian.png + :width: 500 px + :align: center + :alt: Apian Globular I + + proj-string: ``+proj=apian`` + +Options +################################################################################ + +.. note:: All options are optional for the Apian Globular projection. + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/august.rst.txt b/_sources/operations/projections/august.rst.txt new file mode 100644 index 00000000..ae5c95dc --- /dev/null +++ b/_sources/operations/projections/august.rst.txt @@ -0,0 +1,42 @@ +.. _august: + +******************************************************************************** +August Epicycloidal +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | august | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/august.png + :width: 500 px + :align: center + :alt: August Epicycloidal + + proj-string: ``+proj=august`` + +Parameters +################################################################################ + +.. note:: All options are optional for the August Epicycloidal projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/bacon.rst.txt b/_sources/operations/projections/bacon.rst.txt new file mode 100644 index 00000000..8e2fda9e --- /dev/null +++ b/_sources/operations/projections/bacon.rst.txt @@ -0,0 +1,42 @@ +.. _bacon: + +******************************************************************************** +Bacon Globular +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | bacon | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/bacon.png + :width: 500 px + :align: center + :alt: Bacon Globular + + proj-string: ``+proj=bacon`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Bacon Globular projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/bertin1953.rst.txt b/_sources/operations/projections/bertin1953.rst.txt new file mode 100644 index 00000000..65afcf62 --- /dev/null +++ b/_sources/operations/projections/bertin1953.rst.txt @@ -0,0 +1,64 @@ +.. _bertin1953: + +******************************************************************************** +Bertin 1953 +******************************************************************************** + +.. versionadded:: 6.0.0 + ++---------------------+-------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+-------------------------------+ +| **Available forms** | Forward, spherical projection | ++---------------------+-------------------------------+ +| **Defined area** | Global | ++---------------------+-------------------------------+ +| **Alias** | bertin1953 | ++---------------------+-------------------------------+ +| **Domain** | 2D | ++---------------------+-------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+-------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+-------------------------------+ + + + +.. figure:: ./images/bertin1953.png + :width: 500 px + :align: center + :alt: Bertin 1953 + + proj-string: ``+proj=bertin1953`` + + +The Bertin 1953 projection is intended for making world maps. Created by Jacques Bertin +in 1953, this projection was the go-to choice of the French cartographic school when they +wished to represent phenomena on a global scale. The projection was formulated in 2017 +by Philippe Rivière for visionscarto.net. + + +Usage +############################################################################### + +The Bertin 1953 projection has no special options. Its rotation parameters +are fixed. Here is an example of a forward projection with scale 1:: + + $ echo 122 47 | src/proj +proj=bertin1953 +R=1 + 0.72 0.73 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. Philippe Rivière (2017). `Bertin Projection (1953) <https://visionscarto.net/bertin-projection-1953>`, Visionscarto.net. diff --git a/_sources/operations/projections/bipc.rst.txt b/_sources/operations/projections/bipc.rst.txt new file mode 100644 index 00000000..9ac73750 --- /dev/null +++ b/_sources/operations/projections/bipc.rst.txt @@ -0,0 +1,46 @@ +.. _bipc: + +******************************************************************************** +Bipolar conic of western hemisphere +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | bipc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/bipc.png + :width: 500 px + :align: center + :alt: Bipolar conic of western hemisphere + + proj-string: ``+proj=bipc +ns`` + +Parameters +################################################################################ + +.. note:: All options are optional for the Bipolar Conic projection. + +.. option:: +ns + + Return non-skewed cartesian coordinates. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/boggs.rst.txt b/_sources/operations/projections/boggs.rst.txt new file mode 100644 index 00000000..82f43733 --- /dev/null +++ b/_sources/operations/projections/boggs.rst.txt @@ -0,0 +1,42 @@ +.. _boggs: + +******************************************************************************** +Boggs Eumorphic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | boggs | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/boggs.png + :width: 500 px + :align: center + :alt: Boggs Eumorphic + + proj-string: ``+proj=boggs`` + +Parameters +################################################################################ + +.. note:: All options are optional for the Boggs Eumorphic projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/bonne.rst.txt b/_sources/operations/projections/bonne.rst.txt new file mode 100644 index 00000000..1b81237b --- /dev/null +++ b/_sources/operations/projections/bonne.rst.txt @@ -0,0 +1,50 @@ +.. _bonne: + +******************************************************************************** +Bonne (Werner lat_1=90) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | bonne | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/bonne.png + :width: 500 px + :align: center + :alt: Bonne (Werner lat_1=90) + + proj-string: ``+proj=bonne +lat_1=10`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/calcofi.rst.txt b/_sources/operations/projections/calcofi.rst.txt new file mode 100644 index 00000000..829c5060 --- /dev/null +++ b/_sources/operations/projections/calcofi.rst.txt @@ -0,0 +1,107 @@ +.. _calcofi: + +******************************************************************************** +Cal Coop Ocean Fish Invest Lines/Stations +******************************************************************************** + +The CalCOFI pseudo-projection is the line and station coordinate system of the +California Cooperative Oceanic Fisheries Investigations program, known as CalCOFI, for sampling offshore of the west coast of the U.S. and Mexico. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Only valid for the west coast of USA and Mexico | ++---------------------+----------------------------------------------------------+ +| **Alias** | calcofi | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. image:: ../../../images/calcofi.png + :width: 500 px + :align: center + :alt: Cal Coop Ocean Fish Invest Lines/Stations + +The coordinate system is based on the Mercator projection with units rotated -30 +degrees from the meridian so that they are oriented with the coastline of the Southern California Bight and Baja California. +Lines increase from Northwest to Southeast. +A unit of line is 12 nautical miles. Stations increase from inshore to offshore. +A unit of station is equal to 4 nautical miles. +The rotation point is located at line 80, station 60, or 34.15 degrees N, -121.15 degrees W, and is depicted by the red dot in the figure. +By convention, the ellipsoid of Clarke 1866 is used to calculate CalCOFI coordinates. + +The CalCOFI program is a joint research effort by the U.S. National Oceanic and +Atmospheric Administration, University of California Scripps Oceanographic Institute, and California Department of Fish and Game. +Surveys have been conducted for the CalCOFI program since 1951, creating one of the oldest and most scientifically valuable joint oceanographic and fisheries data sets in the world. +The CalCOFI line and station coordinate system is now used by several other programs including the Investigaciones Mexicanas de la Corriente de California (IMECOCAL) program offshore of Baja California. +The figure depicts some commonly sampled locations from line 40 to line 156.7 and offshore to station 120. Blue numbers indicate line (bottom) or station (left) numbers along the grid. Note that lines spaced at approximate 3-1/3 intervals are commonly sampled, e.g., lines 43.3 and 46.7. + +Usage +############################################################################### + +A typical forward CalCOFI projection would be from lon/lat coordinates on the +Clark 1866 ellipsoid. +For example:: + + proj +proj=calcofi +ellps=clrk66 -E <<EOF + -121.15 34.15 + EOF + +Output of the above command:: + + -121.15 34.15 80.00 60.00 + +The reverse projection from line/station coordinates to lon/lat would be entered +as:: + + proj +proj=calcofi +ellps=clrk66 -I -E -f "%.2f" <<EOF + 80.0 60.0 + EOF + +Output of the above command:: + + 80.0 60.0 -121.15 34.15 + +Options +################################################################################ + +.. note:: All options are optional for the CalCOFI projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +Mathematical definition +################################################################################ + +The algorithm used to make conversions is described in :cite:`EberHewitt1979` with +a few corrections reported in :cite:`WeberMoore2013`. + + +Further reading +################################################################################ + +#. `General information about the CalCOFI program <http://www.calcofi.org>`_ +#. `The Investigaciones Mexicanas de la Corriente de California <http://imecocal.cicese.mx>`_ + + + + + + + + + + + + + + diff --git a/_sources/operations/projections/cass.rst.txt b/_sources/operations/projections/cass.rst.txt new file mode 100644 index 00000000..073fe6cc --- /dev/null +++ b/_sources/operations/projections/cass.rst.txt @@ -0,0 +1,172 @@ +.. _cass: + +******************************************************************************** +Cassini (Cassini-Soldner) +******************************************************************************** + +Although the Cassini projection has been largely replaced by the Transverse Mercator, it is still in limited use outside the United States and was one of the major topographic mapping projections until the early 20th century. + ++---------------------+-------------------------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+-------------------------------------------------------------------------+ +| **Available forms** | Forward and inverse, Spherical and ellipsoidal | ++---------------------+-------------------------------------------------------------------------+ +| **Defined area** | Global, but best used near the central meridian with long, narrow areas | ++---------------------+-------------------------------------------------------------------------+ +| **Alias** | cass | ++---------------------+-------------------------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+-------------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+-------------------------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+-------------------------------------------------------------------------+ + + +.. figure:: ./images/cass.png + :width: 500 px + :align: center + :alt: Cassini + + proj-string: ``+proj=cass`` + +Usage +##### + +There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini-Soldner version was adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century :cite:`Steers1970`. +Many of these maps were prepared at a scale of 1:2,500. +The Cassini-Soldner was also used for the detailed mapping of many German states during the same period. + + +Example using EPSG 30200 (Trinidad 1903, units in clarke's links):: + + $ echo 0.17453293 -1.08210414 | proj +proj=cass +lat_0=10.44166666666667 +lon_0=-61.33333333333334 +x_0=86501.46392051999 +y_0=65379.0134283 +a=6378293.645208759 +b=6356617.987679838 +to_meter=0.201166195164 + 66644.94 82536.22 + +Example using EPSG 3068 (Soldner Berlin):: + + $ echo 13.5 52.4 | proj +proj=cass +lat_0=52.41864827777778 +lon_0=13.62720366666667 +x_0=40000 +y_0=10000 +ellps=bessel +units=m + 31343.05 7932.76 + +Options +################################################################################ + +.. note:: All options are optional for the Cassini projection. + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. option:: +hyperbolic + + Use modified form of the standard Cassini-Soldner projection known as the Hyperbolic Cassini-Soldner. + This is used in particular for the "Vanua Levu Grid" of the island of Vanua Levu, Fiji (EPSG:3139) + + +Mathematical definition +####################### + +The formulas describing the Cassini projection are taken from :cite:`Snyder1987`. + +:math:`\phi_0` is the latitude of origin that match the center of the map (default to 0). It can be set with ``+lat_0``. + + +Spherical form +============== + +Forward projection +------------------ + +.. math:: + + x = \arcsin(\cos(\phi) \sin(\lambda)) + +.. math:: + + y = \arctan2(\tan(\phi), \cos(\lambda)) - \phi_0 + +Inverse projection +------------------ + +.. math:: + + \phi = \arcsin(\sin(y+\phi_0) \cos(x)) + +.. math:: + + \lambda = \arctan2(\tan(x), \cos(y+\phi_0)) + +Ellipsoidal form +================ + +Forward projection +------------------ + +.. math:: + + N = (1 - e^2 \sin^2(\phi))^{-1/2} + +.. math:: + + T = \tan^2(\phi) + +.. math:: + + A = \lambda \cos(\phi) + +.. math:: + + C = \frac{e^2}{1-e^2} cos^2(\phi) + +.. math:: + + x = N ( A - T \frac{A^3}{6} - (8-T+8C)T\frac{A^5}{120}) + +.. math:: + + y = M(\phi) - M(\phi_0) + N \tan(\phi)(\frac{A^2}{2} + (5-T+6C)\frac{A^4}{24}) + +and M() is the meridional distance function. + +Inverse projection +------------------ + +.. math:: + + \phi' = M^{-1}(M(\phi_0)+y) + +if :math:`\phi' = \frac{\pi}{2}` then :math:`\phi=\phi'` and :math:`\lambda=0` + +otherwise evaluate T and N above using :math:`\phi'` and + +.. math:: + + R = (1 - e^2)(1 - e^2 sin^2 \phi')^{-3/2} + +.. math:: + + D = x/N + +.. math:: + + \phi = \phi' - \tan \phi' \frac{N}{R}(\frac{D^2}{2}-(1+3T)\frac{D^4}{24}) + +.. math:: + + \lambda = \frac{(D - T\frac{D^3}{3} + (1+3T)T\frac{D^5}{15})}{\cos \phi'} + +.. _further-reading: + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Equirectangular_projection>`_ +#. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas <http://www.ihsenergy.com/epsg/guid7.pdf>`_ diff --git a/_sources/operations/projections/cc.rst.txt b/_sources/operations/projections/cc.rst.txt new file mode 100644 index 00000000..c6f3927a --- /dev/null +++ b/_sources/operations/projections/cc.rst.txt @@ -0,0 +1,42 @@ +.. _cc: + +******************************************************************************** +Central Cylindrical +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | cc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/cc.png + :width: 500 px + :align: center + :alt: Central Cylindrical + + proj-string: ``+proj=cc`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Central Cylindrical projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/ccon.rst.txt b/_sources/operations/projections/ccon.rst.txt new file mode 100644 index 00000000..949da8b5 --- /dev/null +++ b/_sources/operations/projections/ccon.rst.txt @@ -0,0 +1,159 @@ +.. _ccon: + +******************************************************************************** +Central Conic +******************************************************************************** + +.. versionadded:: 5.0.0 + +This is central (centrographic) projection on cone tangent at :option:``lat_1`` +latitude, identical with ``conic()`` projection from ``mapproj`` R package. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the standard parallel | ++---------------------+----------------------------------------------------------+ +| **Alias** | ccon | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/ccon.png + :width: 500 px + :align: center + :alt: Central Conic + + proj-string: ``+proj=ccon +lat_1=52 +lon_0=19`` + +Usage +######## + +This simple projection is rarely used, as it is not equidistant, equal-area, nor +conformal. + +An example of usage (and the main reason to implement this projection in proj4) +is the ATPOL geobotanical grid of Poland, developed in Institute of Botany, +Jagiellonian University, Krakow, Poland in 1970s :cite:`Zajac1978`. The grid was +originally handwritten on paper maps and further copied by hand. The projection +(together with strange Earth radius) was chosen by its creators as the compromise +fit to existing maps during first software development in DOS era. Many years later +it is still de facto standard grid in Polish geobotanical research. + +The ATPOL coordinates can be achieved with with the following parameters: + +:: + + +proj=ccon +lat_1=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000 + +For more information see :cite:`Komsta2016` and :cite:`Verey2017`. + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. option:: +lat_1=<value> + + Standard parallel of projection. + +Optional +------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + + +Mathematical definition +################################################################################ + + +Forward projection +------------------------------------------------------------------------------- + +.. math:: + + r = \cot \phi_0 - \tan (\phi - \phi_0) + +.. math:: + + x = r \sin (\lambda\sin\phi_0) + +.. math:: + + y = \cot \phi_0 - r \cos (\lambda\sin\phi_0) + + +Inverse projection +------------------------------------------------------------------------------- + +.. math:: + + y = \cot \phi_0 - y + +.. math:: + + \phi = \phi_0 - \tan^{-1} ( \sqrt{x^2+y^2} - \cot \phi_0 ) + +.. math:: + + \lambda = \frac{\tan^{-1} \sqrt{x^2+y^2}}{\sin \phi_0} + +Reference values +################################################################################ + +For ATPOL to WGS84 test, run the following script: + +:: + + #!/bin/bash + cat << EOF | src/cs2cs -v -f "%E" +proj=ccon +lat_1=52 +lat_0=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000 +to +proj=longlat + 0 0 + 0 700000 + 700000 0 + 700000 700000 + 330000 350000 + EOF + +It should result with + +:: + + 1.384023E+01 5.503040E+01 0.000000E+00 + 1.451445E+01 4.877385E+01 0.000000E+00 + 2.478271E+01 5.500352E+01 0.000000E+00 + 2.402761E+01 4.875048E+01 0.000000E+00 + 1.900000E+01 5.200000E+01 0.000000E+00 + +Analogous script can be run for reverse test: + +:: + + cat << EOF | src/cs2cs -v -f "%E" +proj=longlat +to +proj=ccon +lat_1=52 +lat_0=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000 + 24 55 + 15 49 + 24 49 + 19 52 + EOF + +and it should give the following results: + +:: + + 6.500315E+05 4.106162E+03 0.000000E+00 + 3.707419E+04 6.768262E+05 0.000000E+00 + 6.960534E+05 6.722946E+05 0.000000E+00 + 3.300000E+05 3.500000E+05 0.000000E+00 diff --git a/_sources/operations/projections/cea.rst.txt b/_sources/operations/projections/cea.rst.txt new file mode 100644 index 00000000..3f8af65f --- /dev/null +++ b/_sources/operations/projections/cea.rst.txt @@ -0,0 +1,79 @@ +.. _cea: + +******************************************************************************** +Equal Area Cylindrical +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | cea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/cea.png + :width: 500 px + :align: center + :alt: Equal Area Cylindrical + + proj-string: ``+proj=cea`` + +Named specializations +################################################################################ + +The Equal Area Cylindrical projection is sometimes known under other names when +it is instanciated with particular values of the ``lat_ts`` parameter: + ++----------------------------------+------------+ +| **Name** | **lat_ts** | ++----------------------------------+------------+ +| Lambert cylindrical equal-area | 0 | ++----------------------------------+------------+ +| Behrmann | 30 | ++----------------------------------+------------+ +| Gall-Peters | 45 | ++----------------------------------+------------+ + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Equal Area Cylindrical projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. note:: + + ``lat_ts`` and ``k_0`` are mutually exclusive. If ``lat_ts`` + is specified, it is equivalent to setting ``k_0`` to + :math:`\frac{\cos \phi_{ts}}{\sqrt{1 - e^2 \sin^2 \phi_{ts}}}` + +Further reading +############### + +#. `Wikipedia: Lambert cylindrical equal-area <https://en.wikipedia.org/wiki/Lambert_cylindrical_equal-area_projection>`_ + +#. `Wikipedia: Gall-Peters <https://en.wikipedia.org/wiki/Gall%E2%80%93Peters_projection>`_ + +#. `Wikipedia: Behrmann <https://en.wikipedia.org/wiki/Behrmann_projection>`_ diff --git a/_sources/operations/projections/chamb.rst.txt b/_sources/operations/projections/chamb.rst.txt new file mode 100644 index 00000000..c33017a5 --- /dev/null +++ b/_sources/operations/projections/chamb.rst.txt @@ -0,0 +1,72 @@ +.. _chamb: + +******************************************************************************** +Chamberlin Trimetric +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | chamb | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/chamb.png + :width: 500 px + :align: center + :alt: Chamberlin Trimetric + + proj-string: ``+proj=chamb +lat_1=10 +lon_1=30 +lon_2=40`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. note:: Control points should be oriented clockwise. + +.. option:: +lat_1=<value> + + Latitude of the first control point. + +.. option:: +lon_1=<value> + + Longitude of the first control point. + +.. option:: +lat_2=<value> + + Latitude of the second control point. + +.. option:: +lon_2=<value> + + Longitude of the second control point. + +.. option:: +lat_3=<value> + + Latitude of the third control point. + +.. option:: +lon_3=<value> + + Longitude of the third control point. + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/col_urban.rst.txt b/_sources/operations/projections/col_urban.rst.txt new file mode 100644 index 00000000..df2873dd --- /dev/null +++ b/_sources/operations/projections/col_urban.rst.txt @@ -0,0 +1,49 @@ +.. _col_urban: + +******************************************************************************** +Colombia Urban +******************************************************************************** + +.. versionadded:: 7.2 + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse ellipsoidal projection | ++---------------------+----------------------------------------------------------+ +| **Alias** | col_urban | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +From :cite:`IOGP2018`: + + The capital cites of each department in Colombia use an urban projection for large + scale topographic mapping of the urban areas. It is based on a plane through + the origin at an average height for the area, eliminating the need for corrections + to engineering survey observations. + + proj-string: ``+proj=col_urban`` + +Parameters +################################################################################ + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. option:: +h_0=<value> + + Projection plane origin height (in metre) + + *Defaults to 0.0.* diff --git a/_sources/operations/projections/collg.rst.txt b/_sources/operations/projections/collg.rst.txt new file mode 100644 index 00000000..f0ed215f --- /dev/null +++ b/_sources/operations/projections/collg.rst.txt @@ -0,0 +1,43 @@ +.. _collg: + +******************************************************************************** +Collignon +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | collg | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/collg.png + :width: 500 px + :align: center + :alt: Collignon + + proj-string: ``+proj=collg`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Collignon projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/comill.rst.txt b/_sources/operations/projections/comill.rst.txt new file mode 100644 index 00000000..fa04ec18 --- /dev/null +++ b/_sources/operations/projections/comill.rst.txt @@ -0,0 +1,46 @@ +.. _comill: + +******************************************************************************** +Compact Miller +******************************************************************************** + +The Compact Miller projection is a cylindrical map projection with a +height-to-width ratio of 0.6:1. + +See :cite:`Jenny2015` + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | comill | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/comill.png + :width: 500 px + :align: center + :alt: Compact Miller + + proj-string: ``+proj=comill`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/crast.rst.txt b/_sources/operations/projections/crast.rst.txt new file mode 100644 index 00000000..406c300a --- /dev/null +++ b/_sources/operations/projections/crast.rst.txt @@ -0,0 +1,43 @@ +.. _crast: + +******************************************************************************** +Craster Parabolic (Putnins P4) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | crast | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/crast.png + :width: 500 px + :align: center + :alt: Craster Parabolic (Putnins P4) + + proj-string: ``+proj=crast`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Craster Parabolic projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/denoy.rst.txt b/_sources/operations/projections/denoy.rst.txt new file mode 100644 index 00000000..b2913379 --- /dev/null +++ b/_sources/operations/projections/denoy.rst.txt @@ -0,0 +1,42 @@ +.. _denoy: + +******************************************************************************** +Denoyer Semi-Elliptical +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | denoy | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/denoy.png + :width: 500 px + :align: center + :alt: Denoyer Semi-Elliptical + + proj-string: ``+proj=denoy`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Denoyer Semi-Elliptical projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck1.rst.txt b/_sources/operations/projections/eck1.rst.txt new file mode 100644 index 00000000..28359977 --- /dev/null +++ b/_sources/operations/projections/eck1.rst.txt @@ -0,0 +1,49 @@ +.. _eck1: + +******************************************************************************** +Eckert I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck1.png + :width: 500 px + :align: center + :alt: Eckert I + + proj-string: ``+proj=eck1`` + + +.. math:: + + x &= 2 \sqrt{2/3\pi} \lambda (1- |\phi|/\pi) + + y &= 2 \sqrt{2/3\pi}\phi + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert I projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck2.rst.txt b/_sources/operations/projections/eck2.rst.txt new file mode 100644 index 00000000..aaa1ccd5 --- /dev/null +++ b/_sources/operations/projections/eck2.rst.txt @@ -0,0 +1,42 @@ +.. _eck2: + +******************************************************************************** +Eckert II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck2.png + :width: 500 px + :align: center + :alt: Eckert II + + proj-string: ``+proj=eck2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert II projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck3.rst.txt b/_sources/operations/projections/eck3.rst.txt new file mode 100644 index 00000000..94ef3a33 --- /dev/null +++ b/_sources/operations/projections/eck3.rst.txt @@ -0,0 +1,42 @@ +.. _eck3: + +******************************************************************************** +Eckert III +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck3.png + :width: 500 px + :align: center + :alt: Eckert III + + proj-string: ``+proj=eck3`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert III projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck4.rst.txt b/_sources/operations/projections/eck4.rst.txt new file mode 100644 index 00000000..e62a4fd8 --- /dev/null +++ b/_sources/operations/projections/eck4.rst.txt @@ -0,0 +1,49 @@ +.. _eck4: + +******************************************************************************** +Eckert IV +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck4 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck4.png + :width: 500 px + :align: center + :alt: Eckert IV + + proj-string: ``+proj=eck4`` + +.. math:: + + x = \lambda(1+cos\phi) / \sqrt{ 2 + \pi } + +.. math:: + y = 2 \phi / \sqrt { 2 + \pi } + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert IV projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck5.rst.txt b/_sources/operations/projections/eck5.rst.txt new file mode 100644 index 00000000..cfc888ff --- /dev/null +++ b/_sources/operations/projections/eck5.rst.txt @@ -0,0 +1,42 @@ +.. _eck5: + +******************************************************************************** +Eckert V +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck5 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck5.png + :width: 500 px + :align: center + :alt: Eckert V + + proj-string: ``+proj=eck5`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert V projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eck6.rst.txt b/_sources/operations/projections/eck6.rst.txt new file mode 100644 index 00000000..1026b555 --- /dev/null +++ b/_sources/operations/projections/eck6.rst.txt @@ -0,0 +1,42 @@ +.. _eck6: + +******************************************************************************** +Eckert VI +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eck6 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eck6.png + :width: 500 px + :align: center + :alt: Eckert VI + + proj-string: ``+proj=eck6`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Eckert VI projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eqc.rst.txt b/_sources/operations/projections/eqc.rst.txt new file mode 100644 index 00000000..964a5f16 --- /dev/null +++ b/_sources/operations/projections/eqc.rst.txt @@ -0,0 +1,131 @@ +.. _eqc: + +******************************************************************************** +Equidistant Cylindrical (Plate Carrée) +******************************************************************************** + +The simplest of all projections. Standard parallels (0° when omitted) may be specified that determine latitude of true scale (k=h=1). + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+----------------------------------------------------------+ +| **Alias** | eqc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eqc.png + :width: 500 px + :align: center + :alt: Equidistant Cylindrical (Plate Carrée) + + proj-string: ``+proj=eqc`` + +Usage +######## + +Because of the distortions introduced by this projection, it has little use in navigation or cadastral mapping and finds its main use in thematic mapping. +In particular, the plate carrée has become a standard for global raster datasets, such as Celestia and NASA World Wind, because of the particularly simple relationship between the position of an image pixel on the map and its corresponding geographic location on Earth. + +The following table gives special cases of the cylindrical equidistant projection. + ++---------------------------------------------------------+--------------------------+ +| Projection Name | (lat ts=) :math:`\phi_0` | ++=========================================================+==========================+ +| Plain/Plane Chart | 0° | ++---------------------------------------------------------+--------------------------+ +| Simple Cylindrical | 0° | ++---------------------------------------------------------+--------------------------+ +| Plate Carrée | 0° | ++---------------------------------------------------------+--------------------------+ +| Ronald Miller—minimum overall scale distortion | 37°30′ | ++---------------------------------------------------------+--------------------------+ +| E.Grafarend and A.Niermann | 42° | ++---------------------------------------------------------+--------------------------+ +| Ronald Miller—minimum continental scale distortion | 43°30′ | ++---------------------------------------------------------+--------------------------+ +| Gall Isographic | 45° | ++---------------------------------------------------------+--------------------------+ +| Ronald Miller Equirectangular | 50°30′ | ++---------------------------------------------------------+--------------------------+ +| E.Grafarend and A.Niermann minimum linear distortion | 61°7′ | ++---------------------------------------------------------+--------------------------+ + + +Example using EPSG 32662 (WGS84 Plate Carrée):: + + $ echo 2 47 | proj +proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +units=m + 222638.98 5232016.07 + +Example using Plate Carrée projection with true scale at latitude 30° and central meridian 90°W:: + + $ echo -88 30 | proj +proj=eqc +lat_ts=30 +lon_0=90w + 192811.01 3339584.72 + +Parameters +################################################################################ + + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +Mathematical definition +####################### + +The formulas describing the Equidistant Cylindrical projection are all taken from :cite:`Snyder1987`. + +:math:`\phi_{ts}` is the latitude of true scale, that mean the standard parallels where the scale of the projection is true. It can be set with ``+lat_ts``. + +:math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``. + + +Forward projection +================== + +.. math:: + + x = \lambda \cos \phi_{ts} + +.. math:: + + y = \phi - \phi_0 + +Inverse projection +================== + +.. math:: + + \lambda = x / cos \phi_{ts} + +.. math:: + + \phi = y + \phi_0 + + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Equirectangular_projection>`_ +#. `Wolfram Mathworld <http://mathworld.wolfram.com/CylindricalEquidistantProjection.html>`_ + + diff --git a/_sources/operations/projections/eqdc.rst.txt b/_sources/operations/projections/eqdc.rst.txt new file mode 100644 index 00000000..881a9282 --- /dev/null +++ b/_sources/operations/projections/eqdc.rst.txt @@ -0,0 +1,52 @@ +.. _eqdc: + +******************************************************************************** +Equidistant Conic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | eqdc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/eqdc.png + :width: 500 px + :align: center + :alt: Equidistant Conic + + proj-string: ``+proj=eqdc +lat_1=55 +lat_2=60`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/eqearth.rst.txt b/_sources/operations/projections/eqearth.rst.txt new file mode 100644 index 00000000..bb6d22ce --- /dev/null +++ b/_sources/operations/projections/eqearth.rst.txt @@ -0,0 +1,68 @@ +.. _eqearth: + +******************************************************************************** +Equal Earth +******************************************************************************** + +.. versionadded:: 5.2.0 + ++---------------------+-----------------------------------------------------------+ +| **Classification** | Pseudo cylindrical | ++---------------------+-----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal projection | ++---------------------+-----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+-----------------------------------------------------------+ +| **Alias** | eqearth | ++---------------------+-----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+-----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+-----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+-----------------------------------------------------------+ + + + +.. figure:: ./images/eqearth.png + :width: 500 px + :align: center + :alt: Equal Earth + + proj-string: ``+proj=eqearth`` + + +The Equal Earth projection is intended for making world maps. Equal Earth is a +projection inspired by the Robinson projection, but unlike +the Robinson projection retains the relative size of areas. The projection +was designed in 2018 by Bojan Savric, Tom Patterson and Bernhard Jenny :cite:`Savric2018`. + + +Usage +############################################################################### + +The Equal Earth projection has no special options. Here is +an example of an forward projection on a sphere with a radius of 1 m:: + + $ echo 122 47 | src/proj +proj=eqearth +R=1 + 1.55 0.89 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. Bojan Savric, Tom Patterson & Bernhard Jenny (2018). `The Equal Earth map projection <https://www.researchgate.net/profile/Bojan_Savric2/publication/326879978_The_Equal_Earth_map_projection/links/5b69d0ae299bf14c6d951b77/The-Equal-Earth-map-projection.pdf>`_, International Journal of Geographical Information Science diff --git a/_sources/operations/projections/euler.rst.txt b/_sources/operations/projections/euler.rst.txt new file mode 100644 index 00000000..bac89855 --- /dev/null +++ b/_sources/operations/projections/euler.rst.txt @@ -0,0 +1,51 @@ +.. _euler: + +******************************************************************************** +Euler +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | euler | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/euler.png + :width: 500 px + :align: center + :alt: Euler + + proj-string: ``+proj=euler +lat_1=67 +lat_2=75`` + + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/fahey.rst.txt b/_sources/operations/projections/fahey.rst.txt new file mode 100644 index 00000000..39a7b1be --- /dev/null +++ b/_sources/operations/projections/fahey.rst.txt @@ -0,0 +1,42 @@ +.. _fahey: + +******************************************************************************** +Fahey +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | fahey | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/fahey.png + :width: 500 px + :align: center + :alt: Fahey + + proj-string: ``+proj=fahey`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Fahey projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/fouc.rst.txt b/_sources/operations/projections/fouc.rst.txt new file mode 100644 index 00000000..3bcb3e7d --- /dev/null +++ b/_sources/operations/projections/fouc.rst.txt @@ -0,0 +1,42 @@ +.. _fouc: + +******************************************************************************** +Foucaut +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | fouc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/fouc.png + :width: 500 px + :align: center + :alt: Foucaut + + proj-string: ``+proj=fouc`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Foucaut projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/fouc_s.rst.txt b/_sources/operations/projections/fouc_s.rst.txt new file mode 100644 index 00000000..1938b637 --- /dev/null +++ b/_sources/operations/projections/fouc_s.rst.txt @@ -0,0 +1,63 @@ +.. _fouc_s: + +******************************************************************************** +Foucaut Sinusoidal +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | fouc_s | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/fouc_s.png + :width: 500 px + :align: center + :alt: Foucaut Sinusoidal + + proj-string: ``+proj=fouc_s`` + + +The `y`-axis is based upon a weighted mean of the cylindrical equal-area and +the sinusoidal projections. Parameter :math:`n=n` is the weighting factor where +:math:`0 <= n <= 1`. + +.. math:: + + x &= \lambda \cos \phi / (n + (1 - n) \ cos \phi) + + y &= n \phi + (1 - n) \sin \phi + +For the inverse, the Newton-Raphson method can be used to determine +:math:`\phi` from the equation for :math:`y` above. As :math:`n \rightarrow 0` and +:math:`\phi \rightarrow \pi/2`, convergence is slow but for :math:`n = 0`, :math:`\phi = +\sin^1y` + + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Foucaut Sinusoidal projection. + +.. option:: +n=<value> + + Weighting factor. Value should be in the interval 0-1. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gall.rst.txt b/_sources/operations/projections/gall.rst.txt new file mode 100644 index 00000000..ba83d450 --- /dev/null +++ b/_sources/operations/projections/gall.rst.txt @@ -0,0 +1,111 @@ +.. _gall: + +******************************************************************************** +Gall (Gall Stereographic) +******************************************************************************** + +The Gall stereographic projection, presented by James Gall in 1855, is a cylindrical projection. +It is neither equal-area nor conformal but instead tries to balance the distortion inherent in any projection. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, Spherical | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gall | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gall.png + :width: 500 px + :align: center + :alt: Gall (Gall Stereographic) + + proj-string: ``+proj=gall`` + +Usage +##### + +The need for a world map which avoids some of the scale exaggeration of the Mercator projection has led to some commonly used cylindrical modifications, as well as to other modifications which are not cylindrical. +The earliest common cylindrical example was developed by James Gall of Edinburgh about 1855 (Gall, 1885, p. 119-123). +His meridians are equally spaced, but the parallels are spaced at increasing intervals away from the Equator. +The parallels of latitude are actually projected onto a cylinder wrapped about the sphere, but cutting it at lats. 45° N. and S., the point of perspective being a point on the Equator opposite the meridian being projected. +It is used in several British atlases, but seldom in the United States. +The Gall projection is neither conformal nor equal-area, but has a blend of various features. +Unlike the Mercator, the Gall shows the poles as lines running across the top and bottom of the map. + +.. note:: + + The Gall projection must not be confused with the Gall-Peters one, the later + being a specialization of :ref:`cea`. + +Example using Gall Stereographic :: + + $ echo 9 51 | proj +proj=gall +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +units=m + 708432.90 5193386.36 + +Example using Gall Stereographic (Central meridian 90°W) :: + + $ echo 9 51 | proj +proj=gall +lon_0=90w +x_0=0 +y_0=0 +ellps=WGS84 +units=m + 7792761.91 5193386.36 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + + +Mathematical definition +####################### + +The formulas describing the Gall Stereographic are all taken from :cite:`Snyder1993`. + +Spherical form +************** + +Forward projection +================== + +.. math:: + + x = \frac{\lambda}{\sqrt{2}} + +.. math:: + + y = (1+\frac{\sqrt{2}}{2}) \tan(\phi/2) + +Inverse projection +================== + +.. math:: + + \phi = 2 \arctan( \frac{y}{1+\frac{\sqrt{2}}{2}} ) + +.. math:: + + \lambda = \sqrt{2} x + + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Gall_stereographic_projection>`_ +#. `Cartographic Projection Procedures for the UNIX Environment-A User's Manual <http://sites.lsa.umich.edu/zhukov/wp-content/uploads/sites/140/2014/08/projection-procedures.pdf>`_ diff --git a/_sources/operations/projections/geos.rst.txt b/_sources/operations/projections/geos.rst.txt new file mode 100644 index 00000000..9b8bf21b --- /dev/null +++ b/_sources/operations/projections/geos.rst.txt @@ -0,0 +1,103 @@ +.. _geos: + +******************************************************************************** +Geostationary Satellite View +******************************************************************************** + +The geos projection pictures how a geostationary satellite scans the earth at regular +scanning angle intervals. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | geos | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/geos.png + :width: 500 px + :align: center + :alt: Geostationary Satellite View + + proj-string: ``+proj=geos +h=35785831.0 +lon_0=-60 +sweep=y`` + +Usage +############################################################################### + +In order to project using the geos projection you can do the following:: + + proj +proj=geos +h=35785831.0 + +The required argument ``h`` is the viewing point (satellite position) height above +the earth. + +The projection coordinate relate to the scanning angle by the following simple +relation:: + + scanning_angle (radians) = projection_coordinate / h + + +Note on sweep angle +------------------------------------------------------------------------------- + +The viewing instrument on-board geostationary satellites described by this +projection have a two-axis gimbal viewing geometry. This means that the different +scanning positions are obtained by rotating the gimbal along a N/S axis (or ``y``) +and a E/W axis (or ``x``). + +.. image:: ../../..//images/geos_sweep.png + :width: 500 px + :align: center + :alt: Gimbal geometry + +In the image above, the outer-gimbal axis, or sweep-angle axis, is the N/S axis (``y``) +while the inner-gimbal axis, or fixed-angle axis, is the E/W axis (``x``). + +This example represents the scanning geometry of the Meteosat series satellite. +However, the GOES satellite series use the opposite scanning geometry, with the +E/W axis (``x``) as the sweep-angle axis, and the N/S (``y``) as the fixed-angle axis. + +The sweep argument is used to tell PROJ which on which axis the outer-gimbal +is rotating. The possible values are x or y, y being the default. Thus, the +scanning geometry of the Meteosat series satellite should take sweep as y, and +GOES should take sweep as x. + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. include:: ../options/h.rst + + +Optional +------------------------------------------------------------------------------- + +.. option:: +sweep=<axis> + + Sweep angle axis of the viewing instrument. Valid options are *"x"* and *"y*". + + *Defaults to "y".* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + + diff --git a/_sources/operations/projections/gins8.rst.txt b/_sources/operations/projections/gins8.rst.txt new file mode 100644 index 00000000..07c26912 --- /dev/null +++ b/_sources/operations/projections/gins8.rst.txt @@ -0,0 +1,42 @@ +.. _gins8: + +******************************************************************************** +Ginsburg VIII (TsNIIGAiK) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gins8 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gins8.png + :width: 500 px + :align: center + :alt: Ginsburg VIII (TsNIIGAiK) + + proj-string: ``+proj=gins8`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Ginsburg VIII projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gn_sinu.rst.txt b/_sources/operations/projections/gn_sinu.rst.txt new file mode 100644 index 00000000..a42e1d14 --- /dev/null +++ b/_sources/operations/projections/gn_sinu.rst.txt @@ -0,0 +1,43 @@ +.. _gn_sinu: + +******************************************************************************** +General Sinusoidal Series +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gn_sinu | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gn_sinu.png + :width: 500 px + :align: center + :alt: General Sinusoidal Series + + proj-string: ``+proj=gn_sinu +m=2 +n=3`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the General Sinusoidal Series + projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gnom.rst.txt b/_sources/operations/projections/gnom.rst.txt new file mode 100644 index 00000000..1bbb5034 --- /dev/null +++ b/_sources/operations/projections/gnom.rst.txt @@ -0,0 +1,44 @@ +.. _gnom: + +******************************************************************************** +Gnomonic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gnom | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gnom.png + :width: 500 px + :align: center + :alt: Gnomonic + + proj-string: ``+proj=gnom +lat_0=90 +lon_0=-50`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Gnomonic projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/goode.rst.txt b/_sources/operations/projections/goode.rst.txt new file mode 100644 index 00000000..55f0f370 --- /dev/null +++ b/_sources/operations/projections/goode.rst.txt @@ -0,0 +1,42 @@ +.. _goode: + +******************************************************************************** +Goode Homolosine +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | goode | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/goode.png + :width: 500 px + :align: center + :alt: Goode Homolosine + + proj-string: ``+proj=goode`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Goode Homolosine projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gs48.rst.txt b/_sources/operations/projections/gs48.rst.txt new file mode 100644 index 00000000..b8088fb4 --- /dev/null +++ b/_sources/operations/projections/gs48.rst.txt @@ -0,0 +1,40 @@ +.. _gs48: + +******************************************************************************** +Modified Stereographic of 48 U.S. +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | The lower 48 states of the U.S. | ++---------------------+----------------------------------------------------------+ +| **Alias** | gs48 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gs48.png + :width: 500 px + :align: center + :alt: Modified Stereographic of 48 U.S. + + proj-string: ``+proj=gs48`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gs50.rst.txt b/_sources/operations/projections/gs50.rst.txt new file mode 100644 index 00000000..a5694f94 --- /dev/null +++ b/_sources/operations/projections/gs50.rst.txt @@ -0,0 +1,40 @@ +.. _gs50: + +******************************************************************************** +Modified Stereographic of 50 U.S. +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | All 50 states of the U.S. | ++---------------------+----------------------------------------------------------+ +| **Alias** | gs50 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gs50.png + :width: 500 px + :align: center + :alt: Modified Stereographic of 50 U.S. + + proj-string: ``+proj=gs50`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/gstmerc.rst.txt b/_sources/operations/projections/gstmerc.rst.txt new file mode 100644 index 00000000..33c68eff --- /dev/null +++ b/_sources/operations/projections/gstmerc.rst.txt @@ -0,0 +1,48 @@ +.. _gstmerc: + +******************************************************************************** +Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | gstmerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/gstmerc.png + :width: 500 px + :align: center + :alt: Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) + + proj-string: ``+proj=gstmerc`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/guyou.rst.txt b/_sources/operations/projections/guyou.rst.txt new file mode 100644 index 00000000..89d455be --- /dev/null +++ b/_sources/operations/projections/guyou.rst.txt @@ -0,0 +1,42 @@ +.. _guyou: + +******************************************************************************** +Guyou +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | guyou | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/guyou.png + :width: 500 px + :align: center + :alt: Guyou + + proj-string: ``+proj=guyou`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/hammer.rst.txt b/_sources/operations/projections/hammer.rst.txt new file mode 100644 index 00000000..c3551d0c --- /dev/null +++ b/_sources/operations/projections/hammer.rst.txt @@ -0,0 +1,55 @@ +.. _hammer: + +******************************************************************************** +Hammer & Eckert-Greifendorff +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | hammer | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/hammer.png + :width: 500 px + :align: center + :alt: Hammer & Eckert-Greifendorff + + proj-string: ``+proj=hammer`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +W=<value> + + Set to 0.5 for the Hammer projection and 0.25 for the Eckert-Greifendorff + projection. :option:`+W` has to be larger than zero. + + *Defaults to 0.5.* + +.. option:: +M=<value> + + :option:`+M` has to be larger than zero. + + *Defaults to 1.0.* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/hatano.rst.txt b/_sources/operations/projections/hatano.rst.txt new file mode 100644 index 00000000..35bc32c3 --- /dev/null +++ b/_sources/operations/projections/hatano.rst.txt @@ -0,0 +1,84 @@ +.. _hatano: + +******************************************************************************** +Hatano Asymmetrical Equal Area +******************************************************************************** + + + + ++---------------------+----------------------------------------------------------+ +| **Classification** | :term:`Pseudocylindrical Projection` | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | hatano | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. figure:: ./images/hatano.png + :width: 500 px + :align: center + :alt: Hatano Asymmetrical Equal Area + + proj-string: ``+proj=hatano`` + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + + +Mathematical Definition +-------------------------------------------------------------------------------- + +Forward +................................................................................ + +.. math:: + + x &= 0.85\lambda \cos \theta + + y &= C_y \sin \theta + + P(\theta) &= 2\theta + \sin 2\theta - C_p \sin \phi + + P'(\theta) &= 2(1 + \cos 2\theta) + + \theta_0 &= 2\phi + + +==================================== ================== =================== +Condition :math:`C_y` :math:`C_p` +==================================== ================== =================== +For :math:`\phi > 0` 1.75859 2.67595 +For :math:`\phi < 0` 1.93052 2.43763 +==================================== ================== =================== + +For :math:`\phi = 0`, :math:`y \leftarrow 0`, and :math:`x \leftarrow 0.85\lambda`. + +Further reading +-------------------------------------------------------------------------------- + +#. `Compare Map Projections <http://map-projections.net/single-view/hatano>`__ +#. `Mathworks <http://www.mathworks.com/help/map/hatano.html>`__ + + + diff --git a/_sources/operations/projections/healpix.rst.txt b/_sources/operations/projections/healpix.rst.txt new file mode 100644 index 00000000..41bc10db --- /dev/null +++ b/_sources/operations/projections/healpix.rst.txt @@ -0,0 +1,77 @@ +.. _healpix: + +******************************************************************************** +HEALPix +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | healpix | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. image:: ../../../images/healpix.png + :scale: 75% + :alt: HEALPix + +The HEALPix projection is area preserving and can be used with a spherical and +ellipsoidal model. It was initially developed for mapping cosmic background +microwave radiation. The image below is the graphical representation of the +mapping and consists of eight isomorphic triangular interrupted map graticules. +The north and south contains four in which straight meridians converge polewards +to a point and unequally spaced horizontal parallels. HEALPix provides a mapping +in which points of equal latitude and equally spaced longitude are mapped to points +of equal latitude and equally spaced longitude with the module of the polar +interruptions. + + +Usage +############################################################################### + +To run a forward HEALPix projection on a unit sphere model, use the following command:: + + proj +proj=healpix +lon_0=0 +a=1 -E <<EOF + 0 0 + EOF + # output + 0 0 0.00 0.00 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. option:: +rot_xy + + .. versionadded:: 6.3.0 + + Rotation of the HEALPix map in degrees. A positive value results in a clockwise + rotation around (x_0, y_0) in the cartesian / projected coordinate space. + + *Defaults to 0.0.* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +Further reading +################################################################################ + +#. `NASA <http://healpix.jpl.nasa.gov/>`_ +#. `Wikipedia <https://en.wikipedia.org/wiki/HEALPix>`_ diff --git a/_sources/operations/projections/igh.rst.txt b/_sources/operations/projections/igh.rst.txt new file mode 100644 index 00000000..5e7df9a9 --- /dev/null +++ b/_sources/operations/projections/igh.rst.txt @@ -0,0 +1,42 @@ +.. _igh: + +******************************************************************************** +Interrupted Goode Homolosine +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | igh | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/igh.png + :width: 500 px + :align: center + :alt: Interrupted Goode Homolosine + + proj-string: ``+proj=igh`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/igh_o.rst.txt b/_sources/operations/projections/igh_o.rst.txt new file mode 100644 index 00000000..2df7223a --- /dev/null +++ b/_sources/operations/projections/igh_o.rst.txt @@ -0,0 +1,42 @@ +.. _igh_o: + +******************************************************************************** +Interrupted Goode Homolosine (Oceanic View) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | igh_o | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/igh_o.png + :width: 500 px + :align: center + :alt: Interrupted Goode Homolosine + + proj-string: ``+proj=igh_o +lon_0=-160`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. A value of +lon_0=-160 is recommended. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/imw_p.rst.txt b/_sources/operations/projections/imw_p.rst.txt new file mode 100644 index 00000000..1dad270e --- /dev/null +++ b/_sources/operations/projections/imw_p.rst.txt @@ -0,0 +1,50 @@ +.. _imw_p: + +******************************************************************************** +International Map of the World Polyconic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoconical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | imw_p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/imw_p.png + :width: 500 px + :align: center + :alt: International Map of the World Polyconic + + proj-string: ``+proj=imw_p +lat_1=30 +lat_2=-40`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/index.rst.txt b/_sources/operations/projections/index.rst.txt new file mode 100644 index 00000000..4f76dab2 --- /dev/null +++ b/_sources/operations/projections/index.rst.txt @@ -0,0 +1,164 @@ +.. _projections: + +================================================================================ +Projections +================================================================================ + +Projections are coordinate operations that are technically conversions but since +projections are so fundamental to PROJ we differentiate them from conversions. + +Projections map the spherical 3D space to a flat 2D space. + +.. toctree:: + :maxdepth: 1 + + adams_hemi + adams_ws1 + adams_ws2 + aea + aeqd + airy + aitoff + alsk + apian + august + bacon + bertin1953 + bipc + boggs + bonne + calcofi + cass + cc + ccon + cea + chamb + collg + col_urban + comill + crast + denoy + eck1 + eck2 + eck3 + eck4 + eck5 + eck6 + eqc + eqdc + eqearth + euler + fahey + fouc + fouc_s + gall + geos + gins8 + gn_sinu + gnom + goode + gs48 + gs50 + guyou + hammer + hatano + healpix + rhealpix + igh + igh_o + imw_p + isea + kav5 + kav7 + krovak + labrd + laea + lagrng + larr + lask + lcc + lcca + leac + lee_os + loxim + lsat + mbt_s + mbt_fps + mbtfpp + mbtfpq + mbtfps + merc + mil_os + mill + misrsom + moll + murd1 + murd2 + murd3 + natearth + natearth2 + nell + nell_h + nicol + nsper + nzmg + ob_tran + ocea + oea + omerc + ortel + ortho + patterson + pconic + peirce_q + poly + putp1 + putp2 + putp3 + putp3p + putp4p + putp5 + putp5p + putp6 + putp6p + qua_aut + qsc + robin + rouss + rpoly + s2 + sch + sinu + somerc + stere + sterea + gstmerc + tcc + tcea + times + tissot + tmerc + tobmerc + tpeqd + tpers + ups + urm5 + urmfps + utm + vandg + vandg2 + vandg3 + vandg4 + vitk1 + wag1 + wag2 + wag3 + wag4 + wag5 + wag6 + wag7 + webmerc + weren + wink1 + wink2 + wintri diff --git a/_sources/operations/projections/isea.rst.txt b/_sources/operations/projections/isea.rst.txt new file mode 100644 index 00000000..73f0af7a --- /dev/null +++ b/_sources/operations/projections/isea.rst.txt @@ -0,0 +1,78 @@ +.. _isea: + +******************************************************************************** +Icosahedral Snyder Equal Area +******************************************************************************** + +Snyder's Icosahedral Equal Area map projections on polyhedral globes for the +dodecahedron and truncated icosahedron offer relatively low scale and +angular distortion. The equations involved are relatively straight-forward, +and for certain instructional tools and databases, the projections are useful +for world maps. The interruptions remain a disadvantage, as with any low-error +projection system applied to the entire globe :cite:`Snyder1992`. + + ++---------------------+----------------------------------------------------------+ +| **Classification** | Polyhedral, equal area | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward, spherical | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | isea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/isea.png + :width: 500 px + :align: center + :alt: Icosahedral Snyder Equal Area + + proj-string: ``+proj=isea`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +orient=<string> + + Can be set to either ``isea`` or ``pole``. See Snyder's Figure 12 for pole orientation :cite:`Snyder1992`. + + *Defaults to isea* + +.. option:: +azi=<value> + + Azimuth. + + *Defaults to 0.0* + +.. option:: +aperture=<value> + + *Defaults to 3.0* + +.. option:: +resolution=<value> + + *Defaults to 4.0* + +.. option:: +mode=<string> + + Can be either ``plane``, ``di``, ``dd`` or ``hex``. + + *Defaults to plane* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/kav5.rst.txt b/_sources/operations/projections/kav5.rst.txt new file mode 100644 index 00000000..0025260b --- /dev/null +++ b/_sources/operations/projections/kav5.rst.txt @@ -0,0 +1,46 @@ +.. _kav5: + +******************************************************************************** +Kavrayskiy V +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | kav5 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/kav5.png + :width: 500 px + :align: center + :alt: Kavrayskiy V + + proj-string: ``+proj=kav5`` + +.. note:: This projection name may also be transliterated as Kavraisky V. + +Created by Soviet cartographer Vladimir V. Kavrayskiy in 1933 :cite:`Snyder1993`. + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Kavrayskiy V projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/kav7.rst.txt b/_sources/operations/projections/kav7.rst.txt new file mode 100644 index 00000000..1808f4ca --- /dev/null +++ b/_sources/operations/projections/kav7.rst.txt @@ -0,0 +1,46 @@ +.. _kav7: + +******************************************************************************** +Kavrayskiy VII +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | kav7 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/kav7.png + :width: 500 px + :align: center + :alt: Kavrayskiy VII + + proj-string: ``+proj=kav7`` + +.. note:: This projection name may also be transliterated as Kavraisky VII. + +Created by Soviet cartographer Vladimir V. Kavrayskiy in 1939 :cite:`Snyder1993`. + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Kavrayskiy VII projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/krovak.rst.txt b/_sources/operations/projections/krovak.rst.txt new file mode 100644 index 00000000..59f66b04 --- /dev/null +++ b/_sources/operations/projections/krovak.rst.txt @@ -0,0 +1,64 @@ +.. _krovak: + +******************************************************************************** +Krovak +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but more accurate around Czechoslovakia | ++---------------------+----------------------------------------------------------+ +| **Alias** | krovak | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/krovak.png + :width: 500 px + :align: center + :alt: Krovak + + proj-string: ``+proj=krovak`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Krovak projection. + + The latitude of pseudo standard parallel is hardcoded to 78.5° and + the ellipsoid to Bessel. + +.. option:: +czech + + Reverse the sign of the output coordinates, as is tradition in the + Czech Republic. + +.. option:: +lon_0=<value> + + Longitude of projection center. + + *Defaults to 24°50' (24.8333333333333)* + +.. option:: +lat_0=<value> + + Latitude of projection center. + + *Defaults to 49.5* + +.. option:: +k_0=<value> + + Scale factor. Determines scale factor used in the projection. + + *Defaults to 0.9999* + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/labrd.rst.txt b/_sources/operations/projections/labrd.rst.txt new file mode 100644 index 00000000..c91e38b7 --- /dev/null +++ b/_sources/operations/projections/labrd.rst.txt @@ -0,0 +1,57 @@ +.. _labrd: + +******************************************************************************** +Laborde +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but more accurate around Madagascar | ++---------------------+----------------------------------------------------------+ +| **Alias** | labrd | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/labrd.png + :width: 500 px + :align: center + :alt: Laborde + + proj-string: ``+proj=labrd +lon_0=40 +lat_0=-10`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +lat_0=<value> + + Latitude of projection center. Must not be zero. + + +Optional +-------------------------------------------------------------------------------- + +.. option:: +azi=<value> + + Azimuth of the central line. + + *Defaults to 0.0* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/laea.rst.txt b/_sources/operations/projections/laea.rst.txt new file mode 100644 index 00000000..5434564c --- /dev/null +++ b/_sources/operations/projections/laea.rst.txt @@ -0,0 +1,46 @@ +.. _laea: + +******************************************************************************** +Lambert Azimuthal Equal Area +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | laea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/laea.png + :width: 500 px + :align: center + :alt: Lambert Azimuthal Equal Area + + proj-string: ``+proj=laea`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/lagrng.rst.txt b/_sources/operations/projections/lagrng.rst.txt new file mode 100644 index 00000000..b96fcd32 --- /dev/null +++ b/_sources/operations/projections/lagrng.rst.txt @@ -0,0 +1,54 @@ +.. _lagrng: + +******************************************************************************** +Lagrange +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lagrng | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lagrng.png + :width: 500 px + :align: center + :alt: Lagrange + + proj-string: ``+proj=lagrng`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +W=<value> + + The factor :option:`+W` is the ratio of the difference in longitude from the + central meridian to the a circular meridian to 90. :option:`+W` must be a + positive value. + + *Defaults to 2.0* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_1.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/larr.rst.txt b/_sources/operations/projections/larr.rst.txt new file mode 100644 index 00000000..edcf146b --- /dev/null +++ b/_sources/operations/projections/larr.rst.txt @@ -0,0 +1,42 @@ +.. _larr: + +******************************************************************************** +Larrivee +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | larr | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/larr.png + :width: 500 px + :align: center + :alt: Larrivee + + proj-string: ``+proj=larr`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Larrivee projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/lask.rst.txt b/_sources/operations/projections/lask.rst.txt new file mode 100644 index 00000000..a4f9a5db --- /dev/null +++ b/_sources/operations/projections/lask.rst.txt @@ -0,0 +1,42 @@ +.. _lask: + +******************************************************************************** +Laskowski +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lask | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lask.png + :width: 500 px + :align: center + :alt: Laskowski + + proj-string: ``+proj=lask`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/lcc.rst.txt b/_sources/operations/projections/lcc.rst.txt new file mode 100644 index 00000000..bf15d76a --- /dev/null +++ b/_sources/operations/projections/lcc.rst.txt @@ -0,0 +1,88 @@ +.. _lcc: + +******************************************************************************** +Lambert Conformal Conic +******************************************************************************** + +A Lambert Conformal Conic projection (LCC) is a conic map projection +used for aeronautical charts, portions of the State Plane Coordinate +System, and many national and regional mapping systems. It is one of +seven projections introduced by Johann Heinrich Lambert in 1772. + +It has several different forms: with one and two standard parallels +(referred to as 1SP and 2SP in EPSG guidance notes). Additionally we +provide "2SP Michigan" form which is very similar to normal 2SP, but +with a scaling factor on the ellipsoid (given as `k_0` parameter). +It is implemented as per EPSG Guidance Note 7-2 (version 54, August +2018, page 25). It is used in a few systems in the EPSG database which +justifies adding this otherwise non-standard projection. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal .| +| | One or two standard parallels (1SP and 2SP). | +| | "LCC 2SP Michigan" form can be used by setting | +| | ``+k_0`` parameter to specify ellipsoid scale. | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Best for regions predominantly east–west in extent and | +| | located in the middle north or south latitudes. | ++---------------------+----------------------------------------------------------+ +| **Alias** | lcc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/lcc.png + :width: 500 px + :align: center + :alt: Lambert Conformal Conic + + proj-string: ``+proj=lcc +lon_0=-90 +lat_1=33 +lat_2=45`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/lat_2.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. option:: +k_0=<value> + + This parameter can represent two different values depending on the + form of the projection. In LCC 1SP it determines the scale factor + at natural origin. In LCC 2SP Michigan it determines the ellipsoid + scale factor. + + *Defaults to 1.0.* + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Lambert_conformal_conic_projection>`_ +#. `Wolfram Mathworld <http://mathworld.wolfram.com/LambertConformalConicProjection.html>`_ +#. `John P. Snyder "Map projections: A working manual" (pp. 104-110) <https://pubs.er.usgs.gov/publication/pp1395>`_ +#. `ArcGIS documentation on "Lambert Conformal Conic" <http://desktop.arcgis.com/en/arcmap/10.3/guide-books/map-projections/lambert-conformal-conic.htm>`_ +#. `EPSG Guidance Note 7-2 (version 54, August 2018, page 25) <http://www.epsg.org/Guidancenotes.aspx>`_ diff --git a/_sources/operations/projections/lcca.rst.txt b/_sources/operations/projections/lcca.rst.txt new file mode 100644 index 00000000..f97c81b4 --- /dev/null +++ b/_sources/operations/projections/lcca.rst.txt @@ -0,0 +1,46 @@ +.. _lcca: + +******************************************************************************** +Lambert Conformal Conic Alternative +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lcca | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lcca.png + :width: 500 px + :align: center + :alt: Lambert Conformal Conic Alternative + + proj-string: ``+proj=lcca +lat_0=35`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/leac.rst.txt b/_sources/operations/projections/leac.rst.txt new file mode 100644 index 00000000..7cc0f2d2 --- /dev/null +++ b/_sources/operations/projections/leac.rst.txt @@ -0,0 +1,53 @@ +.. _leac: + +******************************************************************************** +Lambert Equal Area Conic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | leac | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/leac.png + :width: 500 px + :align: center + :alt: Lambert Equal Area Conic + + proj-string: ``+proj=leac`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Lambert Equal Area Conic + projection. + +.. include:: ../options/lat_1.rst + +.. option:: +south + + Sets the second standard parallel to 90°S. When the flag is off the second + standard parallel is set to 90°N. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/lee_os.rst.txt b/_sources/operations/projections/lee_os.rst.txt new file mode 100644 index 00000000..3f9248ac --- /dev/null +++ b/_sources/operations/projections/lee_os.rst.txt @@ -0,0 +1,40 @@ +.. _lee_os: + +******************************************************************************** +Lee Oblated Stereographic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lee_os | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lee_os.png + :width: 500 px + :align: center + :alt: Lee Oblated Stereographic + + proj-string: ``+proj=lee_os`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/loxim.rst.txt b/_sources/operations/projections/loxim.rst.txt new file mode 100644 index 00000000..9813b6e6 --- /dev/null +++ b/_sources/operations/projections/loxim.rst.txt @@ -0,0 +1,44 @@ +.. _loxim: + +******************************************************************************** +Loximuthal +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | loxim | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/loxim.png + :width: 500 px + :align: center + :alt: Loximuthal + + proj-string: ``+proj=loxim`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Loximuthal projection. + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/lsat.rst.txt b/_sources/operations/projections/lsat.rst.txt new file mode 100644 index 00000000..d7b545a8 --- /dev/null +++ b/_sources/operations/projections/lsat.rst.txt @@ -0,0 +1,58 @@ +.. _lsat: + +******************************************************************************** +Space oblique for LANDSAT +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | lsat | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/lsat.png + :width: 500 px + :align: center + :alt: Space oblique for LANDSAT + + proj-string: ``+proj=lsat +ellps=GRS80 +lat_1=-60 +lat_2=60 +lsat=2 +path=2`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +lsat=<value> + + Landsat satellite used for the projection. Value between 1 and 5. + +.. option:: +path=<value> + + Selected path of satellite. Value between 1 and 253 when :option:`+lsat` is + set to 1,2 or 3, otherwise valid input is between 1 and 233. + + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbt_fps.rst.txt b/_sources/operations/projections/mbt_fps.rst.txt new file mode 100644 index 00000000..614c514a --- /dev/null +++ b/_sources/operations/projections/mbt_fps.rst.txt @@ -0,0 +1,42 @@ +.. _mbt_fps: + +******************************************************************************** +McBryde-Thomas Flat-Pole Sine (No. 2) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbt_fps | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbt_fps.png + :width: 500 px + :align: center + :alt: McBryde-Thomas Flat-Pole Sine (No. 2) + + proj-string: ``+proj=mbt_fps`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbt_s.rst.txt b/_sources/operations/projections/mbt_s.rst.txt new file mode 100644 index 00000000..300c2749 --- /dev/null +++ b/_sources/operations/projections/mbt_s.rst.txt @@ -0,0 +1,43 @@ +.. _mbt_s: + +******************************************************************************** +McBryde-Thomas Flat-Polar Sine (No. 1) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbt_s | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbt_s.png + :width: 500 px + :align: center + :alt: McBryde-Thomas Flat-Polar Sine (No. 1) + + proj-string: ``+proj=mbt_s`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the McBryde-Thomas Flat-Polar Sine + projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbtfpp.rst.txt b/_sources/operations/projections/mbtfpp.rst.txt new file mode 100644 index 00000000..ec83d5f5 --- /dev/null +++ b/_sources/operations/projections/mbtfpp.rst.txt @@ -0,0 +1,42 @@ +.. _mbtfpp: + +******************************************************************************** +McBride-Thomas Flat-Polar Parabolic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbtfpp | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbtfpp.png + :width: 500 px + :align: center + :alt: McBride-Thomas Flat-Polar Parabolic + + proj-string: ``+proj=mbtfpp`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbtfpq.rst.txt b/_sources/operations/projections/mbtfpq.rst.txt new file mode 100644 index 00000000..4ed23e28 --- /dev/null +++ b/_sources/operations/projections/mbtfpq.rst.txt @@ -0,0 +1,42 @@ +.. _mbtfpq: + +******************************************************************************** +McBryde-Thomas Flat-Polar Quartic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbtfpq | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbtfpq.png + :width: 500 px + :align: center + :alt: McBryde-Thomas Flat-Polar Quartic + + proj-string: ``+proj=mbtfpq`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mbtfps.rst.txt b/_sources/operations/projections/mbtfps.rst.txt new file mode 100644 index 00000000..34217e71 --- /dev/null +++ b/_sources/operations/projections/mbtfps.rst.txt @@ -0,0 +1,43 @@ +.. _mbtfps: + +******************************************************************************** +McBryde-Thomas Flat-Polar Sinusoidal +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mbtfps | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mbtfps.png + :width: 500 px + :align: center + :alt: McBryde-Thomas Flat-Polar Sinusoidal + + proj-string: ``+proj=mbtfps`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the McBryde-Thomas Flat-Polar + Sinusoidal projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/merc.rst.txt b/_sources/operations/projections/merc.rst.txt new file mode 100644 index 00000000..6eae9d36 --- /dev/null +++ b/_sources/operations/projections/merc.rst.txt @@ -0,0 +1,197 @@ +.. _merc: + +******************************************************************************** +Mercator +******************************************************************************** + +The Mercator projection is a cylindrical map projection that origins +from the 16th century. It is widely recognized as the first regularly +used map projection. It is a conformal projection in which the equator +projects to a straight line at constant scale. The projection has the +property that a rhumb line, a course of constant heading, projects to a +straight line. This makes it suitable for navigational purposes. + + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+----------------------------------------------------------+ +| **Alias** | merc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/merc.png + :width: 500 px + :align: center + :alt: Mercator + + proj-string: ``+proj=merc`` + +Usage +######## + +Applications should be limited to equatorial regions, but is frequently +used for navigational charts with latitude of true scale (:option:`+lat_ts`) specified within +or near chart's boundaries. +It is considered to be inappropriate for world maps because of the gross +distortions in area; for example the projected area of Greenland is +larger than that of South America, despite the fact that Greenland's +area is :math:`\frac18` that of South America :cite:`Snyder1987`. + + +Example using latitude of true scale:: + + $ echo 56.35 12.32 | proj +proj=merc +lat_ts=56.5 + 3470306.37 759599.90 + +Example using scaling factor:: + + echo 56.35 12.32 | proj +proj=merc +k_0=2 + 12545706.61 2746073.80 + + +Note that :option:`+lat_ts` and :option:`+k_0` are mutually exclusive. +If used together, :option:`+lat_ts` takes precedence over :option:`+k_0`. + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +Mathematical definition +####################### + +Spherical form +************** +For the spherical form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = \cos \phi_{ts} + +Forward projection +================== + +.. math:: + + x = k_0R \lambda; \qquad y = k_0R \psi + +.. math:: + + \psi &= \ln \tan \biggl(\frac{\pi}{4} + \frac{\phi}{2} \biggr)\\ + &= \sinh^{-1}\tan\phi + +The quantity :math:`\psi` is the isometric latitude. + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0R}; \qquad \psi = \frac{y}{k_0R} + +.. math:: + + \phi &= \frac{\pi}{2} - 2 \tan^{-1} \exp(-\psi)\\ + &= \tan^{-1}\sinh\psi + + +Ellipsoidal form +**************** + +For the ellipsoidal form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = m( \phi_{ts} ) + +where + +.. math:: + + m(\phi) = \frac{\cos\phi}{\sqrt{1 - e^2\sin^2\phi}} + +:math:`a\,m(\phi)` is the radius of the circle of latitude :math:`\phi`. + +Forward projection +================== +.. math:: + + x = k_0 a \lambda; \qquad y = k_0 a \psi + +.. math:: + + \psi &= \ln\tan\biggl(\frac\pi4 + \frac{\phi}2\biggr) + -\frac12 e + \ln \biggl(\frac{1 + e \sin\phi}{1 - e \sin\phi}\biggr)\\ + &= \sinh^{-1}\tan\phi - e \tanh^{-1}(e \sin\phi) + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0 a}; \quad \psi = \frac{y}{k_0 a} + +The latitude :math:`\phi` is found by inverting the equation for +:math:`\psi`. This follows the method given by :cite:`Karney2011tm`. +Start by introducing the conformal latitude + +.. math:: + \chi = \tan^{-1}\sinh\psi + +The tangents of the latitudes :math:`\tau = \tan\phi` and :math:`\tau' = +\tan\chi = \sinh\psi` are related by + +.. math:: + \tau' = \tau \sqrt{1 + \sigma^2} - \sigma \sqrt{1 + \tau^2} + +where + +.. math:: + \sigma = \sinh\bigl(e \tanh^{-1}(e \tau/\sqrt{1 + \tau^2}) \bigr) + +This is obtained by taking the :math:`\sinh` of the equation for +:math:`\psi` and using the multiple argument formula. The equation for +:math:`\tau'` can be solved to give :math:`\tau` using Newton's method +using :math:`\tau = \tau'/(1 - e^2)` as an initial guess and with the +needed derivative given by + +.. math:: + \frac{d\tau'}{d\tau} = \frac{1 - e^2}{1 + (1 - e^2)\tau^2} + \sqrt{1 + \tau'^2} \sqrt{1 + \tau^2} + +This converges after no more than 2 iterations. Finally set +:math:`\phi=\tan^{-1}\tau`. + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Mercator_projection>`_ +#. `Wolfram Mathworld <http://mathworld.wolfram.com/MercatorProjection.html>`_ + + diff --git a/_sources/operations/projections/mil_os.rst.txt b/_sources/operations/projections/mil_os.rst.txt new file mode 100644 index 00000000..dbf8488f --- /dev/null +++ b/_sources/operations/projections/mil_os.rst.txt @@ -0,0 +1,40 @@ +.. _mil_os: + +******************************************************************************** +Miller Oblated Stereographic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | mil_os | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mil_os.png + :width: 500 px + :align: center + :alt: Miller Oblated Stereographic + + proj-string: ``+proj=mil_os`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/mill.rst.txt b/_sources/operations/projections/mill.rst.txt new file mode 100644 index 00000000..83447ad5 --- /dev/null +++ b/_sources/operations/projections/mill.rst.txt @@ -0,0 +1,91 @@ +.. _mill: + +******************************************************************************** +Miller Cylindrical +******************************************************************************** + +The Miller cylindrical projection is a modified Mercator projection, proposed by Osborn Maitland Miller in 1942. +The latitude is scaled by a factor of :math:`\frac{4}{5}`, projected according to Mercator, and then the result is multiplied by :math:`\frac{5}{4}` to retain scale along the equator. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Neither conformal nor equal area cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse spherical | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+----------------------------------------------------------+ +| **Alias** | mill | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/mill.png + :width: 500 px + :align: center + :alt: Miller Cylindrical + + proj-string: ``+proj=mill`` + +Usage +######## + +The Miller Cylindrical projection is used for world maps and in several atlases, +including the National Atlas of the United States (USGS, 1970, p. 330-331) :cite:`Snyder1987`. + +Example using Central meridian 90°W:: + + $ echo -100 35 | proj +proj=mill +lon_0=90w + -1113194.91 4061217.24 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Mathematical definition +####################### + +The formulas describing the Miller projection are all taken from :cite:`Snyder1987`. + + +Forward projection +================== + +.. math:: + + x = \lambda + +.. math:: + + y = 1.25 * \ln \left[ \tan \left(\frac{\pi}{4} + 0.4 * \phi \right) \right] + + +Inverse projection +================== + +.. math:: + + \lambda = x + +.. math:: + + \phi = 2.5 * ( \arctan \left[ e^{0.8 * y} \right] - \frac{\pi}{4} ) + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Miller_cylindrical_projection>`_ + diff --git a/_sources/operations/projections/misrsom.rst.txt b/_sources/operations/projections/misrsom.rst.txt new file mode 100644 index 00000000..f04af6b3 --- /dev/null +++ b/_sources/operations/projections/misrsom.rst.txt @@ -0,0 +1,53 @@ +.. _misrsom: + +******************************************************************************** +Space oblique for MISR +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | misrsom | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/misrsom.png + :width: 500 px + :align: center + :alt: Space oblique for MISR + + proj-string: ``+proj=misrsom +path=1`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +path=<value> + + Selected path of satellite. Value between 1 and 233. + + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/moll.rst.txt b/_sources/operations/projections/moll.rst.txt new file mode 100644 index 00000000..e38131d4 --- /dev/null +++ b/_sources/operations/projections/moll.rst.txt @@ -0,0 +1,42 @@ +.. _moll: + +******************************************************************************** +Mollweide +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | moll | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/moll.png + :width: 500 px + :align: center + :alt: Mollweide + + proj-string: ``+proj=moll`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/murd1.rst.txt b/_sources/operations/projections/murd1.rst.txt new file mode 100644 index 00000000..c52de4ce --- /dev/null +++ b/_sources/operations/projections/murd1.rst.txt @@ -0,0 +1,50 @@ +.. _murd1: + +******************************************************************************** +Murdoch I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | murd1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/murd1.png + :width: 500 px + :align: center + :alt: Murdoch I + + proj-string: ``+proj=murd1 +lat_1=30 +lat_2=50`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/murd2.rst.txt b/_sources/operations/projections/murd2.rst.txt new file mode 100644 index 00000000..e9dbb1a6 --- /dev/null +++ b/_sources/operations/projections/murd2.rst.txt @@ -0,0 +1,50 @@ +.. _murd2: + +******************************************************************************** +Murdoch II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | murd2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/murd2.png + :width: 500 px + :align: center + :alt: Murdoch II + + proj-string: ``+proj=murd2 +lat_1=30 +lat_2=50`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/murd3.rst.txt b/_sources/operations/projections/murd3.rst.txt new file mode 100644 index 00000000..194ea31f --- /dev/null +++ b/_sources/operations/projections/murd3.rst.txt @@ -0,0 +1,50 @@ +.. _murd3: + +******************************************************************************** +Murdoch III +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | murd3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/murd3.png + :width: 500 px + :align: center + :alt: Murdoch III + + proj-string: ``+proj=murd3 +lat_1=30 +lat_2=50`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/natearth.rst.txt b/_sources/operations/projections/natearth.rst.txt new file mode 100644 index 00000000..4ed5b638 --- /dev/null +++ b/_sources/operations/projections/natearth.rst.txt @@ -0,0 +1,65 @@ +.. _natearth: + +******************************************************************************** +Natural Earth +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Pseudo cylindrical | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Alias** | natearth | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + + + +.. figure:: ./images/natearth.png + :width: 500 px + :align: center + :alt: Natural Earth + + proj-string: ``+proj=natearth`` + +The Natural Earth projection is intended for making world maps. A distinguishing trait +is its slightly rounded corners fashioned to emulate the spherical shape of Earth. +The meridians (except for the central meridian) bend acutely inward as they approach +the pole lines, giving the projection a hint of three-dimensionality. This bending +also suggests that the meridians converge at the poles instead of truncating at the +top and bottom edges. The distortion characteristics of the Natural Earth projection +compare favorably to other world map projections. + + +Usage +############################################################################### + +The Natural Earth projection has no special options so usage is simple. Here is +an example of an inverse projection on a sphere with a radius of 7500 m:: + + $ echo 3500 -8000 | proj -I +proj=natearth +a=7500 + 37d54'6.091"E 61d23'4.582"S + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. `Wikipedia <https://en.wikipedia.org/wiki/Natural_Earth_projection>`_ diff --git a/_sources/operations/projections/natearth2.rst.txt b/_sources/operations/projections/natearth2.rst.txt new file mode 100644 index 00000000..a5128ea9 --- /dev/null +++ b/_sources/operations/projections/natearth2.rst.txt @@ -0,0 +1,49 @@ +.. _natearth2: + +******************************************************************************** +Natural Earth II +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Pseudo cylindrical | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Alias** | natearth2 | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + + + +.. figure:: ./images/natearth2.png + :width: 500 px + :align: center + :alt: Natural Earth II + + proj-string: ``+proj=natearth2`` + +The Natural Earth II projection is intended for making world maps. At high +latitudes, meridians bend steeply toward short pole lines resulting in a map +with highly rounded corners that resembles an elongated globe. + +See :cite:`Savric2015` + + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nell.rst.txt b/_sources/operations/projections/nell.rst.txt new file mode 100644 index 00000000..2619d0b3 --- /dev/null +++ b/_sources/operations/projections/nell.rst.txt @@ -0,0 +1,42 @@ +.. _nell: + +******************************************************************************** +Nell +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | nell | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/nell.png + :width: 500 px + :align: center + :alt: Nell + + proj-string: ``+proj=nell`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nell_h.rst.txt b/_sources/operations/projections/nell_h.rst.txt new file mode 100644 index 00000000..5b4a45df --- /dev/null +++ b/_sources/operations/projections/nell_h.rst.txt @@ -0,0 +1,42 @@ +.. _nell_h: + +******************************************************************************** +Nell-Hammer +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | nell_h | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/nell_h.png + :width: 500 px + :align: center + :alt: Nell-Hammer + + proj-string: ``+proj=nell_h`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nicol.rst.txt b/_sources/operations/projections/nicol.rst.txt new file mode 100644 index 00000000..0b7f0251 --- /dev/null +++ b/_sources/operations/projections/nicol.rst.txt @@ -0,0 +1,42 @@ +.. _nicol: + +******************************************************************************** +Nicolosi Globular +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoconical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | nicol | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/nicol.png + :width: 500 px + :align: center + :alt: Nicolosi Globular + + proj-string: ``+proj=nicol`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nsper.rst.txt b/_sources/operations/projections/nsper.rst.txt new file mode 100644 index 00000000..d99c7932 --- /dev/null +++ b/_sources/operations/projections/nsper.rst.txt @@ -0,0 +1,53 @@ +.. _nsper: + +******************************************************************************** +Near-sided perspective +******************************************************************************** + +The near-sided perspective projection simulates a view from a height +:math:`h` similar to how a satellite in orbit would see it. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal. Neither conformal nor equal area. | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, although for one hemisphere at a time. | ++---------------------+----------------------------------------------------------+ +| **Alias** | nsper | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/nsper.png + :width: 500 px + :align: center + :alt: Near-sided perspective + + proj-string: ``+proj=nsper +h=3000000 +lat_0=-20 +lon_0=145`` + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. include:: ../options/h.rst + +Optional +------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/nzmg.rst.txt b/_sources/operations/projections/nzmg.rst.txt new file mode 100644 index 00000000..2e367fdf --- /dev/null +++ b/_sources/operations/projections/nzmg.rst.txt @@ -0,0 +1,17 @@ +.. _nzmg: + +******************************************************************************** +New Zealand Map Grid +******************************************************************************** + +.. figure:: ./images/nzmg.png + :width: 500 px + :align: center + :alt: New Zealand Map Grid + + proj-string: ``+proj=nzmg`` + +Parameters +################################################################################ + +.. note:: All standard projection parameters are hard-coded for this projection diff --git a/_sources/operations/projections/ob_tran.rst.txt b/_sources/operations/projections/ob_tran.rst.txt new file mode 100644 index 00000000..2ede2dd6 --- /dev/null +++ b/_sources/operations/projections/ob_tran.rst.txt @@ -0,0 +1,120 @@ +.. _ob_tran: + +******************************************************************************** +General Oblique Transformation +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | ob_tran | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/ob_tran.png + :width: 500 px + :align: center + :alt: General Oblique Transformation + + proj-string: ``+proj=ob_tran +o_proj=mill +o_lon_p=40 +o_lat_p=50 +lon_0=60`` + +Usage +################################################################################ + +All of the projections of spherical library can be used as an +oblique projection by means of the General Oblique Transformation. The user +performs the oblique transformation by selecting the oblique projection +``+proj=ob_tran``, specifying the translation factors, :option:`+o_lat_p`, and +:option:`+o_lon_p`, and the projection to be used, :option:`+o_proj`. In the +example of the Fairgrieve projection, the latitude and longitude of the North pole +of the unrotated geographic CRS, :math:`\alpha` and :math:`\beta` respectively, +expressed in the rotated geographic CRS, are to be placed +at 45°N and 90°W and the :ref:`moll` projection is used. Because the central meridian +of the translated coordinates will follow the :math:`\beta` meridian it is +necessary to translate the translated system so that the Greenwich meridian +will pass through the center of the projection by offsetting the central meridian. + +The final control for this projection is:: + + +proj=ob_tran +o_proj=moll +o_lat_p=45 +o_lon_p=-90 +lon_0=-90 + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +o_proj=<projection> + + Oblique projection. + +In addition to specifying an oblique projection, *how* to rotate the projection +should be specified. This is done in one of three ways: Define a new pole, +rotate the projection about a given point or define a new "equator" spanned by +two points on the sphere. See the details below. + +New pole +................................................................................ + +.. option:: +o_lat_p=<latitude> + + Latitude of the North pole of the unrotated source CRS, expressed in the rotated geographic CRS. + +.. option:: +o_lon_p=<longitude> + + Longitude of the North pole of the unrotated source CRS, expressed in the rotated geographic CRS. + +Rotate about point +................................................................................ + +.. option:: +o_alpha=<value> + + Angle to rotate the projection with. + +.. option:: +o_lon_c=<value> + + Longitude of the point the projection will be rotated about. + +.. option:: +o_lat_c=<value> + + Latitude of the point the projection will be rotated about. + +New "equator" points +................................................................................ + +.. option:: +o_lon_1=<value> + + Longitude of first point. + +.. option:: +o_lat_1=<value> + + Latitude of first point. + +.. option:: +o_lon_2=<value> + + Longitude of second point. + +.. option:: +o_lat_2=<value> + + Latitude of second point. + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/ocea.rst.txt b/_sources/operations/projections/ocea.rst.txt new file mode 100644 index 00000000..480dfd53 --- /dev/null +++ b/_sources/operations/projections/ocea.rst.txt @@ -0,0 +1,82 @@ +.. _ocea: + +******************************************************************************** +Oblique Cylindrical Equal Area +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | ocea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/ocea.png + :width: 500 px + :align: center + :alt: Oblique Cylindrical Equal Area + + proj-string: ``+proj=ocea`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +For the Oblique Cylindrical Equal Area projection a pole of rotation is needed. +The pole can be defined in two ways: By a point and azimuth or by providing to +points that make up the pole. + +Point & azimuth +................................................................................ + +.. option:: +lonc=<value> + + Longitude of rotational pole point. + +.. option:: +alpha=<value> + + Angle of rotational pole. + +Two points +................................................................................ + +.. option:: +lon_1=<value> + + Longitude of first point. + +.. option:: +lat_1=<value> + + Latitude of first point. + +.. option:: +lon_2=<value> + + Longitude of second point. + +.. option:: +lat_2=<value> + + Latitude of second point. + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/oea.rst.txt b/_sources/operations/projections/oea.rst.txt new file mode 100644 index 00000000..a3db1722 --- /dev/null +++ b/_sources/operations/projections/oea.rst.txt @@ -0,0 +1,54 @@ +.. _oea: + +******************************************************************************** +Oblated Equal Area +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | oea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/oea.png + :width: 500 px + :align: center + :alt: Oblated Equal Area + + proj-string: ``+proj=oea +m=1 +n=2`` + +Described in :cite:`Snyder1988`. + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +m=<value> + +.. option:: +n=<value> + +Optional +-------------------------------------------------------------------------------- + +.. option:: +theta=<value> + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/omerc.rst.txt b/_sources/operations/projections/omerc.rst.txt new file mode 100644 index 00000000..cf9a1af1 --- /dev/null +++ b/_sources/operations/projections/omerc.rst.txt @@ -0,0 +1,173 @@ +.. _omerc: + +******************************************************************************** +Oblique Mercator +******************************************************************************** + +The Oblique Mercator projection is a cylindrical map projection that closes the +gap between the Mercator and the Transverse Mercator projections. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but reasonably accurate only within 15 degrees | +| | of the oblique central line | ++---------------------+----------------------------------------------------------+ +| **Alias** | omerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/omerc.png + :width: 500 px + :align: center + :alt: Oblique Mercator + + proj-string: ``+proj=omerc +lat_1=45 +lat_2=55`` + + +Figuratively, the cylinder used for developing the Mercator projection touches +the planet along the Equator, while that of the Transverse Mercator touches the +planet along a meridian, i.e. along a line perpendicular to the Equator. + +The cylinder for the Oblique Mercator, however, touches the planet along a line +at an arbitrary angle with the Equator. Hence, the Oblique Mercator projection +is useful for mapping areas having their greatest extent along a direction that +is neither north-south, nor east-west. + +The Mercator and the Transverse Mercator projections are both limiting forms of +the Oblique Mercator: The Mercator projection is equivalent to an Oblique Mercator +with central line along the Equator, while the Transverse Mercator is equivalent +to an Oblique Mercator with central line along a meridian. + +For the sphere, the construction of the Oblique Mercator projection can be +imagined as "tilting the cylinder of a plain Mercator projection", +so the cylinder, instead of touching the equator, touches an arbitrary great circle +on the sphere. The great circle is defined by the tilt angle of the central line, +hence putting land masses along that great circle near the centre of the map, +where the Equator would go in the plain Mercator case. + +The ellipsoidal case, developed by Hotine, and refined by Snyder :cite:`Snyder1987` +is more complex, involving initial steps projecting from the ellipsoid to another +curved surface, the "aposphere", then projection from the aposphere to the skew +uv-plane, before finally rectifying the skew uv-plane onto the map XY plane. + + +Usage +######## + +The tilt angle (azimuth) of the central line can be given in two different ways. +In the first case, the azimuth is given directly, using the option :option:`+alpha` +and defining the centre of projection using the options :option:`+lonc` and +:option:`+lat_0`. +In the second case, the azimuth is given indirectly by specifying two points on +the central line, using the options +:option:`+lat_1`, :option:`+lon_1`, :option:`+lat_2`, and :option:`+lon_2`. + +Example: Verify that the Mercator projection is a limiting form of the Oblique +Mercator + +:: + + $ echo 12 55 | proj +proj=merc +ellps=GRS80 + 1335833.89 7326837.71 + + $ echo 12 55 | proj +proj=omerc +lonc=0 +alpha=90 +ellps=GRS80 + 1335833.89 7326837.71 + +Example: Second case - indirectly given azimuth + +:: + + $ echo 12 55 | proj +proj=omerc +lon_1=-1 +lat_1=1 +lon_2=0 +lat_2=0 +ellps=GRS80 + 349567.57 6839490.50 + + +Example: An approximation of the Danish "System 34" from :cite:`Rittri2012` + +:: + + $ echo 10.536498003 56.229892362 | proj +proj=omerc +axis=wnu +lonc=9.46 +lat_0=56.13333333 +x_0=-266906.229 +y_0=189617.957 +k=0.9999537 +alpha=-0.76324 +gamma=0 +ellps=GRS80 + 200000.13 199999.89 + +The input coordinate represents the System 34 datum point "Agri Bavnehoj", with coordinates +(200000, 200000) by definition. So at the datum point, the approximation is off by about 17 cm. +This use case represents a datum shift from a cylinder projection on an old, slightly +misaligned datum, to a similar projection on a modern datum. + + +Parameters +################################################################################ + + +Central point and azimuth method +-------------------------------------------------------------------------------- + +.. option:: +alpha=<value> + + Azimuth of centerline clockwise from north at the center point of the line. + If :option:`+gamma` is not given then :option:`+alpha` determines the value of + :option:`+gamma`. + +.. option:: +gamma=<value> + + Azimuth of centerline clockwise from north of the rectified + bearing of centre line. If :option:`+alpha` is not given, then + :option:`+gamma` is used to determine :option:`+alpha`. + +.. option:: +lonc=<value> + + Longitude of the central point. + +.. option:: +lat_0=<value> + + Latitude of the central point. + +Two point method +-------------------------------------------------------------------------------- + +.. option:: +lon_1=<value> + + Longitude of first point. + +.. option:: +lat_1=<value> + + Latitude of first point. + +.. option:: +lon_2=<value> + + Longitude of second point. + +.. option:: +lat_2=<value> + + Latitude of second point. + +Optional +-------------------------------------------------------------------------------- + +.. option:: +no_rot + + No rectification (not "no rotation" as one may well assume). + Do not take the last step from the skew uv-plane to the map + XY plane. + + .. note:: This option is probably only marginally useful, but remains for (mostly) historical reasons. + +.. option:: +no_off + + Do not offset origin to center of projection. + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/ortel.rst.txt b/_sources/operations/projections/ortel.rst.txt new file mode 100644 index 00000000..f6fa5f3c --- /dev/null +++ b/_sources/operations/projections/ortel.rst.txt @@ -0,0 +1,42 @@ +.. _ortel: + +******************************************************************************** +Ortelius Oval +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | ortel | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/ortel.png + :width: 500 px + :align: center + :alt: Ortelius Oval + + proj-string: ``+proj=ortel`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/ortho.rst.txt b/_sources/operations/projections/ortho.rst.txt new file mode 100644 index 00000000..09107c9d --- /dev/null +++ b/_sources/operations/projections/ortho.rst.txt @@ -0,0 +1,57 @@ +.. _ortho: + +******************************************************************************** +Orthographic +******************************************************************************** + +The orthographic projection is a perspective azimuthal projection centered +around a given latitude and longitude. + ++---------------------+--------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global, although only one hemisphere can be seen at a | +| | time | ++---------------------+--------------------------------------------------------+ +| **Alias** | ortho | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + +.. figure:: ./images/ortho.png + :width: 500 px + :align: center + :alt: Orthographic + + proj-string: ``+proj=ortho`` + + +.. note:: Before PROJ 7.2, only the spherical formulation was implemented. If + wanting to replicate PROJ < 7.2 results with newer versions, the + ellipsoid must be forced to a sphere, for example by adding a ``+f=0`` + parameter. + +This projection method corresponds to ``EPSG:9840``. + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/patterson.rst.txt b/_sources/operations/projections/patterson.rst.txt new file mode 100644 index 00000000..b68a14d0 --- /dev/null +++ b/_sources/operations/projections/patterson.rst.txt @@ -0,0 +1,46 @@ +.. _patterson: + +******************************************************************************** +Patterson +******************************************************************************** + +The Patterson projection is a cylindrical map projection designed for +general-purpose mapmaking. + +See :cite:`Patterson2014` + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | patterson | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/patterson.png + :width: 500 px + :align: center + :alt: Patterson + + proj-string: ``+proj=patterson`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/pconic.rst.txt b/_sources/operations/projections/pconic.rst.txt new file mode 100644 index 00000000..8c486151 --- /dev/null +++ b/_sources/operations/projections/pconic.rst.txt @@ -0,0 +1,50 @@ +.. _pconic: + +******************************************************************************** +Perspective Conic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | pconic | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/pconic.png + :width: 500 px + :align: center + :alt: Perspective Conic + + proj-string: ``+proj=pconic +lat_1=25 +lat_2=75`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/peirce_q.rst.txt b/_sources/operations/projections/peirce_q.rst.txt new file mode 100644 index 00000000..57504032 --- /dev/null +++ b/_sources/operations/projections/peirce_q.rst.txt @@ -0,0 +1,119 @@ +.. _peirce_q: + +******************************************************************************** +Peirce Quincuncial +******************************************************************************** + +The Peirce Quincuncial projection is a conformal map projection +that transforms the circle of the northern hemisphere into a square, +and the southern hemisphere split into four triangles arranged +around the square to form a quincunx. The resulting projection +is a regular diamond shape or can be rotated to form a square. +The resulting tile can be infinitely tessellated. Though this implementation +defaults to a central meridian of 0, it is more common to use a central +meridian of around 25 to optimise the distortions. Peirce's original +published map from 1879 used a central meridian of approx -70. +The diamond and square versions can be produced using the +``+shape=diamond`` and ``+shape=square`` options respectively. +This implementation includes an alternative lateral projection +which places hemispheres side-by-side (``+shape=horizontal`` or +``+shape=vertical``). Combined with a general oblique transformation, +this can be used to produced a Grieger Triptychial projection +(see example below). + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | peirce_q | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/peirce_q_square.png + :width: 500 px + :align: center + :alt: Peirce Quincuncial (Square) + + proj-string: ``+proj=peirce_q +lon_0=25 +shape=square`` + +.. figure:: ./images/peirce_q_diamond.png + :width: 500 px + :align: center + :alt: Peirce Quincuncial (Diamond) + + proj-string: ``+proj=peirce_q +lon_0=25 +shape=diamond`` + +.. figure:: ./images/peirce_q_horizontal.png + :width: 500 px + :align: center + :alt: Peirce Quincuncial (Horizontal) + + proj-string: ``+proj=peirce_q +lon_0=25 +shape=horizontal`` + +.. figure:: ./images/grieger_triptychial.png + :width: 500 px + :align: center + :alt: Grieger Triptychial + + proj-string: ``+proj=pipeline +step +proj=ob_tran +o_proj=peirce_q +o_lat_p=-45 +o_lon_p=45 +o_type=horizontal +o_scrollx=-0.25 +step +proj=affine +s11=-1 +s12=0 +s21=0 +s22=-1`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. option:: +shape=square/diamond/horizontal/vertical/nhemisphere/shemisphere + + .. versionadded:: 9.0 + + *Defaults to diamond.* + + .. warning:: This option was wrongly introduced introduced in 8.2.1 with the + ``type`` name, which was inappropriate as it conflicted with + the ``+type=crs`` general hint. + + Indicates the shape of transformation applied to the southern hemisphere: + ``square`` and ``diamond`` represent the traditional quincuncial form suggested + by Peirce with the southern hemisphere divided into 4 triangles and reflected + outward from the northern hemisphere. The ``square`` shape is rotated by 45 + degrees to produce the conventional square presentation. The origin lies at + the centre of the square or diamond. + + By contrast, the ``horizontal`` and ``vertical`` forms reflect the southern + hemisphere laterally across the x or y axis respectively to produce a rectangular + form. The origin lies at the centre of the rectangle. + + The other two types, ``nhemisphere`` and ``shemisphere``, discard latitudes of less + than 0 or more than 0, respectively, to allow single hemispheres to be selected. + The origin lies at the centre of the square or diamond. + +.. option:: +scrollx=<value> + + For ``horizontal`` shape allows a scalar circular scroll of resulting x coordinates + to shift sections of the projection to the other horizontal side of the map. + + *Defaults to 0.0. Must be a scale between -1.0 and 1.0.* + +.. option:: +scrolly=<value> + + For ``vertical`` shape allows a scalar circular scroll of resulting y coordinates + to shift sections of the projection to the other vertical side of the map. + + *Defaults to 0.0. Must be a scale between -1.0 and 1.0.* + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/poly.rst.txt b/_sources/operations/projections/poly.rst.txt new file mode 100644 index 00000000..67815cca --- /dev/null +++ b/_sources/operations/projections/poly.rst.txt @@ -0,0 +1,44 @@ +.. _poly: + +******************************************************************************** +Polyconic (American) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoconical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | poly | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/poly.png + :width: 500 px + :align: center + :alt: Polyconic (American) + + proj-string: ``+proj=poly`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp1.rst.txt b/_sources/operations/projections/putp1.rst.txt new file mode 100644 index 00000000..e621a3c7 --- /dev/null +++ b/_sources/operations/projections/putp1.rst.txt @@ -0,0 +1,42 @@ +.. _putp1: + +******************************************************************************** +Putnins P1 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp1.png + :width: 500 px + :align: center + :alt: Putnins P1 + + proj-string: ``+proj=putp1`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Putnins P1 projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp2.rst.txt b/_sources/operations/projections/putp2.rst.txt new file mode 100644 index 00000000..c0f0648e --- /dev/null +++ b/_sources/operations/projections/putp2.rst.txt @@ -0,0 +1,42 @@ +.. _putp2: + +******************************************************************************** +Putnins P2 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp2.png + :width: 500 px + :align: center + :alt: Putnins P2 + + proj-string: ``+proj=putp2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp3.rst.txt b/_sources/operations/projections/putp3.rst.txt new file mode 100644 index 00000000..17fd4012 --- /dev/null +++ b/_sources/operations/projections/putp3.rst.txt @@ -0,0 +1,42 @@ +.. _putp3: + +******************************************************************************** +Putnins P3 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp3.png + :width: 500 px + :align: center + :alt: Putnins P3 + + proj-string: ``+proj=putp3`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp3p.rst.txt b/_sources/operations/projections/putp3p.rst.txt new file mode 100644 index 00000000..0e3aed3c --- /dev/null +++ b/_sources/operations/projections/putp3p.rst.txt @@ -0,0 +1,42 @@ +.. _putp3p: + +******************************************************************************** +Putnins P3' +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp3p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp3p.png + :width: 500 px + :align: center + :alt: Putnins P3' + + proj-string: ``+proj=putp3p`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp4p.rst.txt b/_sources/operations/projections/putp4p.rst.txt new file mode 100644 index 00000000..895c55e3 --- /dev/null +++ b/_sources/operations/projections/putp4p.rst.txt @@ -0,0 +1,41 @@ +.. _putp4p: + +******************************************************************************** +Putnins P4' +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp4p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/putp4p.png + :width: 500 px + :align: center + :alt: Putnins P4' + + proj-string: ``+proj=putp4p`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp5.rst.txt b/_sources/operations/projections/putp5.rst.txt new file mode 100644 index 00000000..511b570d --- /dev/null +++ b/_sources/operations/projections/putp5.rst.txt @@ -0,0 +1,42 @@ +.. _putp5: + +******************************************************************************** +Putnins P5 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp5 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp5.png + :width: 500 px + :align: center + :alt: Putnins P5 + + proj-string: ``+proj=putp5`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp5p.rst.txt b/_sources/operations/projections/putp5p.rst.txt new file mode 100644 index 00000000..2150057d --- /dev/null +++ b/_sources/operations/projections/putp5p.rst.txt @@ -0,0 +1,42 @@ +.. _putp5p: + +******************************************************************************** +Putnins P5' +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp5p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp5p.png + :width: 500 px + :align: center + :alt: Putnins P5' + + proj-string: ``+proj=putp5p`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp6.rst.txt b/_sources/operations/projections/putp6.rst.txt new file mode 100644 index 00000000..1ef7718f --- /dev/null +++ b/_sources/operations/projections/putp6.rst.txt @@ -0,0 +1,42 @@ +.. _putp6: + +******************************************************************************** +Putnins P6 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp6 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp6.png + :width: 500 px + :align: center + :alt: Putnins P6 + + proj-string: ``+proj=putp6`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/putp6p.rst.txt b/_sources/operations/projections/putp6p.rst.txt new file mode 100644 index 00000000..1976bfd0 --- /dev/null +++ b/_sources/operations/projections/putp6p.rst.txt @@ -0,0 +1,42 @@ +.. _putp6p: + +******************************************************************************** +Putnins P6' +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | putp6p | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/putp6p.png + :width: 500 px + :align: center + :alt: Putnins P6' + + proj-string: ``+proj=putp6p`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/qsc.rst.txt b/_sources/operations/projections/qsc.rst.txt new file mode 100644 index 00000000..d7171fb4 --- /dev/null +++ b/_sources/operations/projections/qsc.rst.txt @@ -0,0 +1,174 @@ +.. _qsc: + +******************************************************************************** +Quadrilateralized Spherical Cube +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | qsc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +The purpose of the Quadrilateralized Spherical Cube (QSC) projection is to project +a sphere surface onto the six sides of a cube: + +.. image:: ../../../images/qsc_concept.jpg + :width: 500 px + :align: center + :alt: Quadrilateralized Spherical Cube + +For this purpose, other alternatives can be used, notably :ref:`gnom` or +:ref:`healpix`. However, QSC projection has the following favorable properties: + +It is an equal-area projection, and at the same time introduces only limited angular +distortions. It treats all cube sides equally, i.e. it does not use different +projections for polar areas and equatorial areas. These properties make QSC +projection a good choice for planetary-scale terrain rendering. Map data can be +organized in quadtree structures for each cube side. See :cite:`LambersKolb2012` for an example. + +The QSC projection was introduced by :cite:`ONeilLaubscher1976`, +building on previous work by :cite:`ChanONeil1975`. For clarity: The +earlier QSC variant described in :cite:`ChanONeil1975` became known as the COBE QSC since it +was used by the NASA Cosmic Background Explorer (COBE) project; it is an approximately +equal-area projection and is not the same as the QSC projection. + +See also :cite:`CalabrettaGreisen2002` Sec. 5.6.2 and 5.6.3 for a description of both and +some analysis. + +In this implementation, the QSC projection projects onto one side of a circumscribed +cube. The cube side is selected by choosing one of the following six projection centers: + ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=0`` | front cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=90`` | right cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=180`` | back cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=-90`` | left cube side | ++-------------------------+--------------------+ +| ``+lat_0=90`` | top cube side | ++-------------------------+--------------------+ +| ``+lat_0=-90`` | bottom cube side | ++-------------------------+--------------------+ + +Furthermore, this implementation allows the projection to be applied to ellipsoids. +A preceding shift to a sphere is performed automatically; see :cite:`LambersKolb2012` for details. + + +Usage +############################################################################### + +The following example uses QSC projection via GDAL to create the six cube side +maps from a world map for the WGS84 ellipsoid:: + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=0" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff frontside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=90" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff rightside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=180" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff backside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=-90" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff leftside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=90 +lon_0=0" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff topside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=-90 +lon_0=0" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff bottomside.tiff + + +Explanation: + +* QSC projection is selected with ``+wktext +proj=qsc``. +* The WGS84 ellipsoid is specified with ``+ellps=WGS84``. +* The cube side is selected with ``+lat_0=... +lon_0=...``. +* The ``-wo`` options are necessary for GDAL to avoid holes in the output maps. +* The ``-te`` option limits the extends of the output map to the major axis diameter + (from -radius to +radius in both x and y direction). These are the dimensions of one side + of the circumscribing cube. + + +The resulting images can be laid out in a grid like below. + + +.. |topside| image:: ../../../images/qsc_topside.jpg + :scale: 50 % + :align: middle + :alt: Top side + +.. |leftside| image:: ../../../images/qsc_leftside.jpg + :scale: 50% + :align: middle + :alt: Left side + +.. |frontside| image:: ../../../images/qsc_frontside.jpg + :scale: 50% + :align: middle + :alt: Front side + +.. |rightside| image:: ../../../images/qsc_rightside.jpg + :scale: 50% + :align: middle + :alt: Right side + +.. |backside| image:: ../../../images/qsc_backside.jpg + :scale: 50% + :align: middle + :alt: Back side + +.. |bottomside| image:: ../../../images/qsc_bottomside.jpg + :scale: 50% + :align: middle + :alt: Bottom side + + ++------------+--------------+-------------+------------+ +| | |topside| | | | ++------------+--------------+-------------+------------+ +| |leftside| | |frontside| | |rightside| | |backside| | ++------------+--------------+-------------+------------+ +| | |bottomside| | | | ++------------+--------------+-------------+------------+ + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. `Wikipedia <https://en.wikipedia.org/wiki/Quadrilateralized_spherical_cube>`_ +#. `NASA <https://lambda.gsfc.nasa.gov/product/cobe/skymap_info_new.cfm>`_ diff --git a/_sources/operations/projections/qua_aut.rst.txt b/_sources/operations/projections/qua_aut.rst.txt new file mode 100644 index 00000000..67a5e5bf --- /dev/null +++ b/_sources/operations/projections/qua_aut.rst.txt @@ -0,0 +1,42 @@ +.. _qua_aut: + +******************************************************************************** +Quartic Authalic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | qua_aut | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/qua_aut.png + :width: 500 px + :align: center + :alt: Quartic Authalic + + proj-string: ``+proj=qua_aut`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Quartic Authalic projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/rhealpix.rst.txt b/_sources/operations/projections/rhealpix.rst.txt new file mode 100644 index 00000000..5a9b99b5 --- /dev/null +++ b/_sources/operations/projections/rhealpix.rst.txt @@ -0,0 +1,75 @@ +.. _rhealpix: + +******************************************************************************** +rHEALPix +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | rhealpix | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. image:: ../../../images/rhealpix.png + :scale: 75% + :alt: rHEALPix + +rHEALPix is a projection based on the HEALPix projection. The implementation of +rHEALPix uses the HEALPix projection. The rHEALPix combines the peaks of the +HEALPix into a square. The square's position can be translated and rotated across +the x-axis which is a novel approach for the rHEALPix projection. The initial +intention of using rHEALPix in the Spatial Computation Engine Science Collaboration +Environment (SCENZGrid). + +Usage +############################################################################### + +To run a rHEALPix projection on a WGS84 ellipsoidal model, use the following +command:: + + proj +proj=rhealpix -f '%.2f' +ellps=WGS84 +south_square=0 +north_square=2 -E << EOF + > 55 12 + > EOF + 55 12 6115727.86 1553840.13 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. option:: +north_square + + Position of the north polar square. Valid inputs are 0--3. + + *Defaults to 0.0.* + +.. option:: +south_square + + Position of the south polar square. Valid inputs are 0--3. + + *Defaults to 0.0.* + + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. `NASA <http://healpix.jpl.nasa.gov/>`_ +#. `Wikipedia <https://en.wikipedia.org/wiki/HEALPix>`_ diff --git a/_sources/operations/projections/robin.rst.txt b/_sources/operations/projections/robin.rst.txt new file mode 100644 index 00000000..5ebdf5e5 --- /dev/null +++ b/_sources/operations/projections/robin.rst.txt @@ -0,0 +1,42 @@ +.. _robin: + +******************************************************************************** +Robinson +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | robin | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/robin.png + :width: 500 px + :align: center + :alt: Robinson + + proj-string: ``+proj=robin`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/rouss.rst.txt b/_sources/operations/projections/rouss.rst.txt new file mode 100644 index 00000000..08fc6e36 --- /dev/null +++ b/_sources/operations/projections/rouss.rst.txt @@ -0,0 +1,44 @@ +.. _rouss: + +******************************************************************************** +Roussilhe Stereographic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | rouss | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/rouss.png + :width: 500 px + :align: center + :alt: Roussilhe Stereographic + + proj-string: ``+proj=rouss`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/rpoly.rst.txt b/_sources/operations/projections/rpoly.rst.txt new file mode 100644 index 00000000..eee66c5e --- /dev/null +++ b/_sources/operations/projections/rpoly.rst.txt @@ -0,0 +1,44 @@ +.. _rpoly: + +******************************************************************************** +Rectangular Polyconic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoconical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | rpoly | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/rpoly.png + :width: 500 px + :align: center + :alt: Rectangular Polyconic + + proj-string: ``+proj=rpoly`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/s2.rst.txt b/_sources/operations/projections/s2.rst.txt new file mode 100644 index 00000000..46ae715e --- /dev/null +++ b/_sources/operations/projections/s2.rst.txt @@ -0,0 +1,120 @@ +.. _s2: + +******************************************************************************** +S2 +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | s2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. versionadded:: 8.2 + +The S2 projection, like the Quadrilateralized Spherical Cube (QSC) projection, projects +a sphere surface onto the six sides of a cube: + +.. image:: ../../../images/qsc_concept.jpg + :width: 500 px + :align: center + :alt: Quadrilateralized Spherical Cube + +S2 was created by Google to represent geographic data on the whole earth. The documentation can be found +at `S2 Geometry <https://s2geometry.io/>`_ It works by first +projecting a point on the sphere to a face of the cube. These are called u,v-coordinates, and they are in [-1,1] x [-1,1]. +This step is followed by a non-linear transformation to normalize the area of rectangles on the sphere. There are three +different choices available for this transformation, meaning that S2 is a family of projections. The final output is in +s,t-coordinates, which are in [0,1] x [0,1]. +See the comments in `S2 Code <https://github.com/google/s2geometry/blob/0c4c460bdfe696da303641771f9def900b3e440f/src/s2/s2coords.h#L226>`_ +for an explanation of the tradeoff between speed and area-preservation. Note that the projection is azimuthal when "none" or +"linear" is selected for the area-normalization, but it is not azimuthal when "quadratic" or "tangent" is chosen. See +S2's `Earthcube page <https://s2geometry.io/resources/earthcube>`_ +to visualize the unfolded cube and the orientation of each face. + +In this implementation, the cube side is selected by choosing one of the following six projection centers: + ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=0`` | front cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=90`` | right cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=180`` | back cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=-90`` | left cube side | ++-------------------------+--------------------+ +| ``+lat_0=90`` | top cube side | ++-------------------------+--------------------+ +| ``+lat_0=-90`` | bottom cube side | ++-------------------------+--------------------+ + +The specific transformation can be chosen with the UVtoST parameter: + ++-------------------------+-----------------------------+ +| ``+UVtoST=linear`` | fastest, no normalization | ++-------------------------+-----------------------------+ +| ``+UVtoST=quadratic`` | fast, good normalization | ++-------------------------+-----------------------------+ +| ``+UVtoST=tangent`` | slowest, best normalization | ++-------------------------+-----------------------------+ +| ``+UVtoST=none`` | returns u,v-coordinates | ++-------------------------+-----------------------------+ + +Furthermore, this implementation allows the projection to be applied to ellipsoids. +A preceding shift to a sphere is performed automatically; see :cite:`LambersKolb2012` for details. +The output of the projection is in s,t-coordinates ([0,1] x [0,1]), so only the +eccentricity of the ellipse is taken into account: the absolute value of the axes does +not affect the output. + + +Usage +############################################################################### + +The following example uses S2 on the right face:: + + echo 90 0 | ../bin/proj +proj=s2 +lat_0=0 +lon_0=90 +ellps=WGS84 +UVtoST=linear + + 0.5 0.5 + +Explanation: + +* S2 projection is selected with ``+proj=s2``. +* The WGS84 ellipsoid is specified with ``+ellps=WGS84``. +* The cube side is selected with ``+lat_0=... +lon_0=...``. +* The normalization transformation is selected with ``+UVtoST=...``. + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. option:: +UVtoST=<value> + + The area-normalization transformation. Choose from {linear, quadratic, tangent, none} + + *Defaults to "quadratic".* + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. `S2's Website <https://s2geometry.io/>`_ diff --git a/_sources/operations/projections/sch.rst.txt b/_sources/operations/projections/sch.rst.txt new file mode 100644 index 00000000..f987d75d --- /dev/null +++ b/_sources/operations/projections/sch.rst.txt @@ -0,0 +1,65 @@ +.. _sch: + +******************************************************************************** +Spherical Cross-track Height +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse. | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Alias** | sch | ++---------------------+--------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+--------------------------------------------------------+ +| **Input type** | 3D coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + + proj-string: ``+proj=sch +plat_0=XX +plon_0=XX +phdg_0=XX`` + +The SCH coordinate system is a sensor aligned coordinate system developed at +JPL (Jet Propulsion Laboratory) for radar mapping missions. + +See :cite:`Hensley2002` + + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. option:: +plat_0=<value> + + Peg latitude (in degree) + +.. option:: +plon_0=<value> + + Peg longitude (in degree) + +.. option:: +phdg_0=<value> + + Peg heading (in degree) + +Optional +------------------------------------------------------------------------------- + +.. option:: +h_0=<value> + + Average height (in metre) + + *Defaults to 0.0.* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst diff --git a/_sources/operations/projections/sinu.rst.txt b/_sources/operations/projections/sinu.rst.txt new file mode 100644 index 00000000..6bd059fb --- /dev/null +++ b/_sources/operations/projections/sinu.rst.txt @@ -0,0 +1,56 @@ +.. _sinu: + +******************************************************************************** +Sinusoidal (Sanson-Flamsteed) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | sinu | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/sinu.png + :width: 500 px + :align: center + :alt: Sinusoidal (Sanson-Flamsteed) + + proj-string: ``+proj=sinu`` + +MacBryde and Thomas developed generalized formulas for several of the +pseudocylindricals with sinusoidal meridians: + +.. math:: + + x = C\lambda(m+cos\theta) / ( m + 1) + +.. math:: + y = C\theta + +.. math:: + + C = \sqrt { (m + 1 ) / n } + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Sinusoidal projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/somerc.rst.txt b/_sources/operations/projections/somerc.rst.txt new file mode 100644 index 00000000..f8530d70 --- /dev/null +++ b/_sources/operations/projections/somerc.rst.txt @@ -0,0 +1,30 @@ +.. _somerc: + +******************************************************************************** +Swiss Oblique Mercator +******************************************************************************** + +.. figure:: ./images/somerc.png + :width: 500 px + :align: center + :alt: Swiss Oblique Mercator + + proj-string: ``+proj=somerc`` + + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/stere.rst.txt b/_sources/operations/projections/stere.rst.txt new file mode 100644 index 00000000..06d77f94 --- /dev/null +++ b/_sources/operations/projections/stere.rst.txt @@ -0,0 +1,56 @@ +.. _stere: + +******************************************************************************** +Stereographic +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | stere | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/stere.png + :width: 500 px + :align: center + :alt: Stereographic + + proj-string: ``+proj=stere +lat_0=90 +lat_ts=75`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_0.rst + +.. option:: +lat_ts=<value> + + Defines the latitude where scale is not distorted. It is only taken into + account for Polar Stereographic formulations (``+lat_0`` = +/- 90 ), and + then defaults to the ``+lat_0`` value. + If set to a value different from +/- 90, it takes precedence over ``+k_0`` + if both options are used together. + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/sterea.rst.txt b/_sources/operations/projections/sterea.rst.txt new file mode 100644 index 00000000..80666d06 --- /dev/null +++ b/_sources/operations/projections/sterea.rst.txt @@ -0,0 +1,46 @@ +.. _sterea: + +******************************************************************************** +Oblique Stereographic Alternative +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | sterea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/sterea.png + :width: 500 px + :align: center + :alt: Oblique Stereographic Alternative + + proj-string: ``+proj=sterea +lat_0=90`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tcc.rst.txt b/_sources/operations/projections/tcc.rst.txt new file mode 100644 index 00000000..3c5fe8eb --- /dev/null +++ b/_sources/operations/projections/tcc.rst.txt @@ -0,0 +1,42 @@ +.. _tcc: + +******************************************************************************** +Transverse Central Cylindrical +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | tcc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/tcc.png + :width: 500 px + :align: center + :alt: Transverse Central Cylindrical + + proj-string: ``+proj=tcc`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tcea.rst.txt b/_sources/operations/projections/tcea.rst.txt new file mode 100644 index 00000000..028e5c32 --- /dev/null +++ b/_sources/operations/projections/tcea.rst.txt @@ -0,0 +1,44 @@ +.. _tcea: + +******************************************************************************** +Transverse Cylindrical Equal Area +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | tcea | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/tcea.png + :width: 500 px + :align: center + :alt: Transverse Cylindrical Equal Area + + proj-string: ``+proj=tcea`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/times.rst.txt b/_sources/operations/projections/times.rst.txt new file mode 100644 index 00000000..33e12148 --- /dev/null +++ b/_sources/operations/projections/times.rst.txt @@ -0,0 +1,43 @@ +.. _times: + +******************************************************************************** +Times +******************************************************************************** + +See :cite:`Snyder1993`, p.213-214. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | times | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/times.png + :width: 500 px + :align: center + :alt: Times + + proj-string: ``+proj=times`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tissot.rst.txt b/_sources/operations/projections/tissot.rst.txt new file mode 100644 index 00000000..814fa637 --- /dev/null +++ b/_sources/operations/projections/tissot.rst.txt @@ -0,0 +1,33 @@ +.. _tissot: + +******************************************************************************** +Tissot +******************************************************************************** + +.. figure:: ./images/tissot.png + :width: 500 px + :align: center + :alt: Tissot + + proj-string: ``+proj=tissot +lat_1=60 +lat_2=65`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tmerc.rst.txt b/_sources/operations/projections/tmerc.rst.txt new file mode 100644 index 00000000..576ad327 --- /dev/null +++ b/_sources/operations/projections/tmerc.rst.txt @@ -0,0 +1,412 @@ +.. _tmerc: + +******************************************************************************** +Transverse Mercator +******************************************************************************** + +The transverse Mercator projection in its various forms is the most widely used projected coordinate system for world topographical and offshore mapping. +It is a conformal projection in which a chosen meridian projects to a +straight line at constant scale. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and ellipsoidal | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, with full accuracy within 3900 km | +| | of the central meridian | ++---------------------+----------------------------------------------------------+ +| **Alias** | tmerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. figure:: ./images/tmerc.png + :width: 500 px + :align: center + :alt: Transverse Mercator + + proj-string: ``+proj=tmerc`` + +Usage +##### + + +Prior to the development of the Universal Transverse Mercator coordinate system, several European nations demonstrated the utility of grid-based conformal maps by mapping their territory during the interwar period. +Calculating the distance between two points on these maps could be performed more easily in the field (using the Pythagorean theorem) than was possible using the trigonometric formulas required under the graticule-based system of latitude and longitude. +In the post-war years, these concepts were extended into the Universal Transverse Mercator/Universal Polar Stereographic (UTM/UPS) coordinate system, which is a global (or universal) system of grid-based maps. + +The following table gives special cases of the Transverse Mercator projection. + ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| Projection Name | Areas | Central meridian | Zone width | Scale Factor | ++=====================================+=====================================================+================================+===========================================+==============+ +| Transverse Mercator | World wide | Various | less than 1000 km | Various | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| Transverse Mercator south oriented | Southern Africa | 2° intervals E of 11°E | 2° | 1.000 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| UTM North hemisphere | World wide equator to 84°N | 6° intervals E & W of 3° E & W | Usually 6°, wider for Norway and Svalbard | 0.9996 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| UTM South hemisphere | World wide north of 80°S to equator | 6° intervals E & W of 3° E & W | Always 6° | 0.9996 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| Gauss-Kruger | Former USSR, Yugoslavia, Germany, S. America, China | Various, according to area | Usually less than 6°, often less than 4° | 1.0000 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ +| Gauss Boaga | Italy | Various, according to area | 6° | 0.9996 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+-------------------------------------------+--------------+ + + + +Example using Gauss-Kruger on Germany area (aka EPSG:31467) :: + + $ echo 9 51 | proj +proj=tmerc +lat_0=0 +lon_0=9 +k_0=1 +x_0=3500000 +y_0=0 +ellps=bessel +units=m + 3500000.00 5651505.56 + +Example using Gauss Boaga on Italy area (EPSG:3004) :: + + $ echo 15 42 | proj +proj=tmerc +lat_0=0 +lon_0=15 +k_0=0.9996 +x_0=2520000 +y_0=0 +ellps=intl +units=m + 2520000.00 4649858.60 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. option:: +approx + + .. versionadded:: 6.0.0 + + Use the Evenden-Snyder algorithm described below under "Legacy + ellipsoidal form". It is faster than the default algorithm, but is + less accurate and diverges beyond 3° from the central meridian. + +.. option:: +algo=auto/evenden_snyder/poder_engsager + + .. versionadded:: 7.1 + + Selects the algorithm to use. The hardcoded value and the one defined in + :ref:`proj-ini` default to ``poder_engsager``; that is the most precise + one. + + When using auto, a heuristics based on the input coordinate to transform + is used to determine if the faster Evenden-Snyder method can be used, for + faster computation, without causing an error greater than 0.1 mm (for an + ellipsoid of the size of Earth) + + Note that :option:`+approx` and :option:`+algo` are mutually exclusive. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/k_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Mathematical definition +####################### + +The formulation given here for the Transverse Mercator projection is due +to Krüger :cite:`Krueger1912` who gave the series expansions accurate to +:math:`n^4`, where :math:`n = (a-b)/(a+b)` is the third flattening. +These series were extended to sixth order by Engsager and Poder in +:cite:`Poder1998` and :cite:`Engsager2007`. This gives full +double-precision accuracy within 3900 km of the central meridian (about +57% of the surface of the earth) :cite:`Karney2011tm`. The error is +less than 0.1 mm within 7000 km of the central meridian (about 89% of +the surface of the earth). + +This formulation consists of three steps: a conformal projection from +the ellipsoid to a sphere, the spherical transverse Mercator +projection, rectifying this projection to give constant scale on the +central meridian. + +The scale on the central meridian is :math:`k_0` and is set by ``+k_0``. + +Option :option:`+lon_0` sets the central meridian; in the formulation +below :math:`\lambda` is the longitude relative to the central meridian. + +Options :option:`+lat_0`, :option:`+x_0`, and :option:`+y_0` serve to +translate the projected coordinates so that at :math:`(\phi, \lambda) = +(\phi_0, \lambda_0)`, the projected coordinates are :math:`(x,y) = +(x_0,y_0)`. To simplify the formulas below, these options are set to +zero (their default values). + +Because the projection is conformal, the formulation is most +conveniently given in terms of complex numbers. In particular, the +unscaled projected coordinates :math:`\eta` (proportional to the +easting, :math:`x`) and :math:`\xi` (proportional to the northing, +:math:`y`) are combined into the single complex quantity :math:`\zeta = +\xi + i\eta`, where :math:`i=\sqrt{-1}`. Then any analytic function +:math:`f(\zeta)` defines a conformal mapping (this follows from the +Cauchy-Riemann conditions). + +Spherical form +************** + +Because the full (ellipsoidal) projection includes the spherical +projection as one of the components, we present the spherical form first +with the coordinates tagged with primes, :math:`\phi'`, +:math:`\lambda'`, :math:`\zeta' = \xi' + i\eta'`, :math:`x'`, +:math:`y'`, so that they can be distinguished from the corresponding +ellipsoidal coordinates (without the primes). The projected coordinates +for the sphere are given by + +.. math:: + + x' = k_0 R \eta';\qquad y' = k_0 R \xi' + +Forward projection +================== + +.. math:: + + \xi' = \tan^{-1}\biggl(\frac{\tan\phi'}{\cos\lambda'}\biggr) + +.. math:: + + \eta' = \sinh^{-1}\biggl(\frac{\sin\lambda'} + {\sqrt{\tan^2\phi' + \cos^2\lambda'}}\biggr) + + +Inverse projection +================== + +.. math:: + + \phi' = \tan^{-1}\biggl(\frac{\sin\xi'} + {\sqrt{\sinh^2\eta' + \cos^2\xi'}}\biggr) + +.. math:: + + \lambda' = \tan^{-1}\biggl(\frac{\sinh\eta'}{\cos\xi'}\biggr) + + +Ellipsoidal form +**************** + +The projected coordinates are given by + +.. math:: + + \zeta = \xi + i\eta;\qquad x = k_0 A \eta;\qquad y = k_0 A \xi + +.. math:: + + A = \frac a{1+n}\biggl(1 + \frac14 n^2 + \frac1{64} n^4 + + \frac1{256}n^6\biggr) + +The series for conversion between ellipsoidal and spherical geographic +coordinates and ellipsoidal and spherical projected coordinates are +given in matrix notation where :math:`\mathbf S(\theta)` and +:math:`\mathbf N` are the row and column vectors of length 6 + +.. math:: + + \mathbf S(\theta) = \begin{pmatrix} + \sin 2\theta & + \sin 4\theta & + \sin 6\theta & + \sin 8\theta & + \sin 10\theta & + \sin 12\theta + \end{pmatrix} + +.. math:: + + \mathbf N = \begin{pmatrix} + n \\ n^2 \\ n^3\\ n^4 \\ n^5 \\ n^6 + \end{pmatrix} + +and :math:`\mathsf C_{\alpha,\beta}` are upper triangular +:math:`6\times6` matrices. + +Relation between geographic coordinates +======================================= + +.. math:: + + \lambda' = \lambda + +.. math:: + + \phi' = \tan^{-1}\sinh\bigl(\sinh^{-1}\tan\phi + - e \tanh^{-1}(e\sin\phi)\bigr) + +Instead of using this analytical formula for :math:`\phi'`, the +conversions between :math:`\phi` and :math:`\phi'` use the series +approximations: + +.. math:: + + \phi' = \phi + \mathbf S(\phi) \cdot \mathsf C_{\chi,\phi} \cdot \mathbf N + +.. math:: + + \phi = \phi' + \mathbf S(\phi') \cdot \mathsf C_{\phi,\chi} \cdot \mathbf N + +.. math:: + + \mathsf C_{\chi,\phi} = \begin{pmatrix} + -2& \frac{2}{3}& \frac{4}{3}& -\frac{82}{45}& \frac{32}{45}& \frac{4642}{4725} \\ + & \frac{5}{3}& -\frac{16}{15}& -\frac{13}{9}& \frac{904}{315}& -\frac{1522}{945} \\ + & & -\frac{26}{15}& \frac{34}{21}& \frac{8}{5}& -\frac{12686}{2835} \\ + & & & \frac{1237}{630}& -\frac{12}{5}& -\frac{24832}{14175} \\ + & & & & -\frac{734}{315}& \frac{109598}{31185} \\ + & & & & & \frac{444337}{155925} \\ + \end{pmatrix} + +.. math:: + + \mathsf C_{\phi,\chi} = \begin{pmatrix} + 2& -\frac{2}{3}& -2& \frac{116}{45}& \frac{26}{45}& -\frac{2854}{675} \\ + & \frac{7}{3}& -\frac{8}{5}& -\frac{227}{45}& \frac{2704}{315}& \frac{2323}{945} \\ + & & \frac{56}{15}& -\frac{136}{35}& -\frac{1262}{105}& \frac{73814}{2835} \\ + & & & \frac{4279}{630}& -\frac{332}{35}& -\frac{399572}{14175} \\ + & & & & \frac{4174}{315}& -\frac{144838}{6237} \\ + & & & & & \frac{601676}{22275} \\ + \end{pmatrix} + +Here :math:`\phi'` is the conformal latitude (sometimes denoted by +:math:`\chi`) and :math:`\mathsf C_{\chi,\phi}` and :math:`\mathsf +C_{\phi,\chi}` are the coefficients in the trigonometric series for +converting between :math:`\phi` and :math:`\chi`. + +Relation between projected coordinates +====================================== + +.. math:: + + \zeta = \zeta' + \mathbf S(\zeta') \cdot \mathsf C_{\mu,\chi} \cdot \mathbf N + +.. math:: + + \zeta' = \zeta + \mathbf S(\zeta) \cdot \mathsf C_{\chi,\mu} \cdot \mathbf N + +.. math:: + + \mathsf C_{\mu,\chi} = \begin{pmatrix} + \frac{1}{2}& -\frac{2}{3}& \frac{5}{16}& \frac{41}{180}& -\frac{127}{288}& \frac{7891}{37800} \\ + & \frac{13}{48}& -\frac{3}{5}& \frac{557}{1440}& \frac{281}{630}& -\frac{1983433}{1935360} \\ + & & \frac{61}{240}& -\frac{103}{140}& \frac{15061}{26880}& \frac{167603}{181440} \\ + & & & \frac{49561}{161280}& -\frac{179}{168}& \frac{6601661}{7257600} \\ + & & & & \frac{34729}{80640}& -\frac{3418889}{1995840} \\ + & & & & & \frac{212378941}{319334400} \\ + \end{pmatrix} + +.. math:: + + \mathsf C_{\chi,\mu} = \begin{pmatrix} + -\frac{1}{2}& \frac{2}{3}& -\frac{37}{96}& \frac{1}{360}& \frac{81}{512}& -\frac{96199}{604800} \\ + & -\frac{1}{48}& -\frac{1}{15}& \frac{437}{1440}& -\frac{46}{105}& \frac{1118711}{3870720} \\ + & & -\frac{17}{480}& \frac{37}{840}& \frac{209}{4480}& -\frac{5569}{90720} \\ + & & & -\frac{4397}{161280}& \frac{11}{504}& \frac{830251}{7257600} \\ + & & & & -\frac{4583}{161280}& \frac{108847}{3991680} \\ + & & & & & -\frac{20648693}{638668800} \\ + \end{pmatrix} + +On the central meridian (:math:`\lambda = \lambda' = 0`), :math:`\zeta' += \phi'` is the conformal latitude :math:`\chi` and :math:`\zeta` plays +the role of the rectifying latitude (sometimes denoted by :math:`\mu`). +:math:`\mathsf C_{\mu,\chi}` and :math:`\mathsf C_{\chi,\mu}` are the +coefficients in the trigonometric series for converting between +:math:`\chi` and :math:`\mu`. + +Legacy ellipsoidal form +*********************** + +The formulas below describe the algorithm used when giving the +:option:`+approx` option. They are originally from :cite:`Snyder1987`, +but here quoted from :cite:`Evenden1995` and :cite:`Evenden2005`. These +are less accurate that the formulation above and are only valid within +about 5 degrees of the central meridian. Here :math:`M(\phi)` is the +meridional distance. + + +Forward projection +================== + +.. math:: + + N = \frac{k_0}{(1 - e^2 \sin^2\phi)^{1/2}} + +.. math:: + + R = \frac{k_0(1-e^2)}{(1-e^2 \sin^2\phi)^{3/2}} + +.. math:: + + t = \tan\phi + +.. math:: + + \eta = \frac{e^2}{1-e^2} \cos^2\phi + +.. math:: + + x &= k_0 \lambda \cos \phi \\ + &+ \frac{k_0 \lambda^3 \cos^3\phi}{3!}(1-t^2+\eta^2) \\ + &+ \frac{k_0 \lambda^5 \cos^5\phi}{5!}(5-18t^2+t^4+14\eta^2-58t^2\eta^2) \\ + &+\frac{k_0 \lambda^7 \cos^7\phi}{7!}(61-479t^2+179t^4-t^6) + +.. math:: + + y &= M(\phi) \\ + &+ \frac{k_0 \lambda^2 \sin\phi \cos \phi}{2!} \\ + &+ \frac{k_0 \lambda^4 \sin\phi \cos^3\phi}{4!}(5-t^2+9\eta^2+4\eta^4) \\ + &+ \frac{k_0 \lambda^6 \sin\phi \cos^5\phi}{6!}(61-58t^2+t^4+270\eta^2-330t^2\eta^2) \\ + &+ \frac{k_0 \lambda^8 \sin\phi \cos^7\phi}{8!}(1385-3111t^2+543t^4-t^6) + +Inverse projection +================== + +.. math:: + + \phi_1 = M^{-1}(y) + +.. math:: + + N_1 = \frac{k_0}{1 - e^2 \sin^2\phi_1)^{1/2}} + +.. math:: + + R_1 = \frac{k_0(1-e^2)}{(1-e^2 \sin^2\phi_1)^{3/2}} + +.. math:: + + t_1 = \tan(\phi_1) + +.. math:: + + \eta_1 = \frac{e^2}{1-e^2} \cos^2\phi_1 + +.. math:: + + \phi &= \phi_1 \\ + &- \frac{t_1 x^2}{2! R_1 N_1} \\ + &+ \frac{t_1 x^4}{4! R_1 N_1^3}(5+3t_1^2+\eta_1^2-4\eta_1^4-9\eta_1^2t_1^2) \\ + &- \frac{t_1 x^6}{6! R_1 N_1^5}(61+90t_1^2+46\eta_1^2+45t_1^4-252t_1^2\eta_1^2) \\ + &+ \frac{t_1 x^8}{8! R_1 N_1^7}(1385+3633t_1^2+4095t_1^4+1575t_1^6) + +.. math:: + + \lambda &= \frac{x}{\cos \phi N_1} \\ + &- \frac{x^3}{3! \cos \phi N_1^3}(1+2t_1^2+\eta_1^2) \\ + &+ \frac{x^5}{5! \cos \phi N_1^5}(5+6\eta_1^2+28t_1^2-3\eta_1^2+8t_1^2\eta_1^2) \\ + &- \frac{x^7}{7! \cos \phi N_1^7}(61+662t_1^2+1320t_1^4+720t_1^6) + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Transverse_Mercator_projection>`_ diff --git a/_sources/operations/projections/tobmerc.rst.txt b/_sources/operations/projections/tobmerc.rst.txt new file mode 100644 index 00000000..7bc5cb95 --- /dev/null +++ b/_sources/operations/projections/tobmerc.rst.txt @@ -0,0 +1,100 @@ +.. _tobmerc: + +******************************************************************************** +Tobler-Mercator +******************************************************************************** + +.. versionadded:: 6.0.0 + +Equal area cylindrical projection with the same latitudinal spacing as +Mercator projection. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical equal area | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical only | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, conventionally truncated at about 80 degrees | +| | north and south | ++---------------------+----------------------------------------------------------+ +| **Alias** | tobmerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/tobmerc.png + :width: 500 px + :align: center + :alt: Tobler-Mercator + + proj-string: ``+proj=tobmerc`` + +Usage +##### + +The inappropriate use of the Mercator projection has declined but still +occasionally occurs. One method of contrasting the Mercator projection is to +present an alternative in the form of an equal area projection. The map +projection derived here is thus not simply a pretty Christmas tree ornament: +it is instead a complement to Mercator's conformal navigation anamorphosis +and can be displayed as an alternative. The equations for the new map +projection preserve the latitudinal stretching of the Mercator while +adjusting the longitudinal spacing. This allows placement of the new map +adjacent to that of Mercator. The surface area, while drastically warped, +maintains the correct magnitude. + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/R.rst + +Mathematical definition +####################### + +The formulas describing the Tobler-Mercator are taken from Waldo Tobler's +article :cite:`Tobler2018` + +Spherical form +************** +For the spherical form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = \cos^2 \phi_{ts} + +Forward projection +================== + +.. math:: + + x = k_0 \lambda + +.. math:: + + y = k_0 \ln \left[ \tan \left(\frac{\pi}{4} + \frac{\phi}{2} \right) \right] + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0} + +.. math:: + + \phi = \frac{\pi}{2} - 2 \arctan \left[ e^{-y/k_0} \right] diff --git a/_sources/operations/projections/tpeqd.rst.txt b/_sources/operations/projections/tpeqd.rst.txt new file mode 100644 index 00000000..fb75a7b1 --- /dev/null +++ b/_sources/operations/projections/tpeqd.rst.txt @@ -0,0 +1,56 @@ +.. _tpeqd: + +******************************************************************************** +Two Point Equidistant +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | tpeqd | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/tpeqd.png + :width: 500 px + :align: center + :alt: Two Point Equidistant + + proj-string: ``+proj=tpeqd +lat_1=60 +lat_2=65`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +lon_1=<value> + + Longitude of first point. + +.. option:: +lat_1=<value> + + Latitude of first point. + +.. option:: +lon_2=<value> + + Longitude of second point. + +.. option:: +lat_2=<value> + + Latitude of second point. + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/tpers.rst.txt b/_sources/operations/projections/tpers.rst.txt new file mode 100644 index 00000000..9dd73805 --- /dev/null +++ b/_sources/operations/projections/tpers.rst.txt @@ -0,0 +1,70 @@ +.. _tpers: + +******************************************************************************** +Tilted perspective +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | tpers | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + + +.. figure:: ./images/tpers.png + :width: 500 px + :align: center + :alt: Tilted perspective + + proj-string: ``+proj=tpers +h=5500000 +lat_0=40`` + +Tilted Perspective is similar to :ref:`nsper` (``nsper``) in that it simulates a +perspective view from a height. Where ``nsper`` projects onto a plane tangent to +the surface, Tilted Perspective orients the plane towards the direction of the +view. Thus, extra parameters specifying azimuth and tilt are required beyond +`nsper``'s ``h``. As with ``nsper``, ``lat_0`` & ``lon_0`` are +also required for satellite position. + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. include:: ../options/h.rst + +Optional +------------------------------------------------------------------------------- + +.. option:: +azi=<value> + + Bearing in degrees away from north. + + *Defaults to 0.0.* + +.. option:: +tilt=<value> + + Angle in degrees away from nadir. + + *Defaults to 0.0.* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/lat_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + diff --git a/_sources/operations/projections/ups.rst.txt b/_sources/operations/projections/ups.rst.txt new file mode 100644 index 00000000..b652b563 --- /dev/null +++ b/_sources/operations/projections/ups.rst.txt @@ -0,0 +1,31 @@ +.. _ups: + +******************************************************************************** +Universal Polar Stereographic +******************************************************************************** + +.. figure:: ./images/ups.png + :width: 500 px + :align: center + :alt: Universal Polar Stereographic + + proj-string: ``+proj=ups`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +south + + South polar aspect. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/urm5.rst.txt b/_sources/operations/projections/urm5.rst.txt new file mode 100644 index 00000000..4d2dd557 --- /dev/null +++ b/_sources/operations/projections/urm5.rst.txt @@ -0,0 +1,41 @@ +.. _urm5: + +******************************************************************************** +Urmaev V +******************************************************************************** + +.. figure:: ./images/urm5.png + :width: 500 px + :align: center + :alt: Urmaev V + + proj-string: ``+proj=urm5 +n=0.9 +alpha=2 +q=4`` + +Parameters +################################################################################ + +Required parameters +-------------------------------------------------------------------------------- +.. option:: +n=<value> + + Set the :math:`n` constant. Value between 0 and 1. + +Optional parameters +-------------------------------------------------------------------------------- +.. option:: +q=<value> + + Set the :math:`q` constant. + +.. option:: +alpha=<value> + + Set the :math:`\alpha` constant. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/urmfps.rst.txt b/_sources/operations/projections/urmfps.rst.txt new file mode 100644 index 00000000..b1f39b28 --- /dev/null +++ b/_sources/operations/projections/urmfps.rst.txt @@ -0,0 +1,29 @@ +.. _urmfps: + +******************************************************************************** +Urmaev Flat-Polar Sinusoidal +******************************************************************************** + +.. figure:: ./images/urmfps.png + :width: 500 px + :align: center + :alt: Urmaev Flat-Polar Sinusoidal + + proj-string: ``+proj=urmfps +n=0.5`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. option:: +n=<value> + + Set the :math:`n` constant. Value between 0 and 1. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/utm.rst.txt b/_sources/operations/projections/utm.rst.txt new file mode 100644 index 00000000..2367cbad --- /dev/null +++ b/_sources/operations/projections/utm.rst.txt @@ -0,0 +1,99 @@ +.. _utm: + +******************************************************************************** +Universal Transverse Mercator (UTM) +******************************************************************************** + +The Universal Transverse Mercator is a system of map projections divided into +sixty zones across the globe, with each zone corresponding to 6 degrees of +longitude. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Transverse cylindrical, conformal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, ellipsoidal only | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Within the used zone, but transformations of coordinates | +| | in adjacent zones can be expected to be accurate as well | ++---------------------+----------------------------------------------------------+ +| **Alias** | utm | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ../../../images/utm_zones.png + :alt: Universal Transverse Mercator (UTM) zones + :figwidth: 100% + :align: center + + UTM zones. + +UTM projections are really the :ref:`Transverse Mercator<tmerc>` +to which specific parameters, such as central meridians, have been applied. +The Earth is divided into 60 zones each generally 6° wide in longitude. +Bounding meridians are evenly divisible by 6°, and zones are +numbered from 1 to 60 proceeding east from the 180th meridian from Greenwich +with minor exceptions :cite:`Snyder1987`. + +Usage +##### + +Convert geodetic coordinate to UTM Zone 32 on the northern hemisphere:: + + $ echo 12 56 | proj +proj=utm +zone=32 + 687071.44 6210141.33 + +Convert geodetic coordinate to UTM Zone 59 on the southern hemisphere:: + + $ echo 174 -44 | proj +proj=utm +zone=59 +south + 740526.32 5123750.87 + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. option:: +zone=<value> + + Select which UTM zone to use. Can be a value between 1-60. + + +Optional +------------------------------------------------------------------------------- + +.. option:: +south + + Add this flag when using the UTM on the southern hemisphere. + +.. option:: +approx + + .. versionadded:: 6.0.0 + + Use faster, less accurate algorithm for the Transverse Mercator. + +.. option:: +algo=auto/evenden_snyder/poder_engsager + + .. versionadded:: 7.1 + + Selects the algorithm to use. The hardcoded value and the one defined in + :ref:`proj-ini` default to ``poder_engsager``, that is the most precise + one. + + When using auto, a heuristics based on the input coordinate to transform + is used to determine if the faster Evenden-Snyder method can be used, for + faster computation, without causing an error greater than 0.1 mm (for an + ellipsoid of the size of Earth) + + Note that :option:`+approx` and :option:`+algo` are mutually exclusive. + +.. include:: ../options/ellps.rst + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>`_ diff --git a/_sources/operations/projections/vandg.rst.txt b/_sources/operations/projections/vandg.rst.txt new file mode 100644 index 00000000..32366534 --- /dev/null +++ b/_sources/operations/projections/vandg.rst.txt @@ -0,0 +1,42 @@ +.. _vandg: + +******************************************************************************** +van der Grinten (I) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vandg | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vandg.png + :width: 500 px + :align: center + :alt: van der Grinten (I) + + proj-string: ``+proj=vandg`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/vandg2.rst.txt b/_sources/operations/projections/vandg2.rst.txt new file mode 100644 index 00000000..dee18774 --- /dev/null +++ b/_sources/operations/projections/vandg2.rst.txt @@ -0,0 +1,42 @@ +.. _vandg2: + +******************************************************************************** +van der Grinten II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vandg2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vandg2.png + :width: 500 px + :align: center + :alt: van der Grinten II + + proj-string: ``+proj=vandg2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/vandg3.rst.txt b/_sources/operations/projections/vandg3.rst.txt new file mode 100644 index 00000000..9f57f320 --- /dev/null +++ b/_sources/operations/projections/vandg3.rst.txt @@ -0,0 +1,42 @@ +.. _vandg3: + +******************************************************************************** +van der Grinten III +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vandg3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vandg3.png + :width: 500 px + :align: center + :alt: van der Grinten III + + proj-string: ``+proj=vandg3`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/vandg4.rst.txt b/_sources/operations/projections/vandg4.rst.txt new file mode 100644 index 00000000..e2215c91 --- /dev/null +++ b/_sources/operations/projections/vandg4.rst.txt @@ -0,0 +1,42 @@ +.. _vandg4: + +******************************************************************************** +van der Grinten IV +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vandg4 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vandg4.png + :width: 500 px + :align: center + :alt: van der Grinten IV + + proj-string: ``+proj=vandg4`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/vitk1.rst.txt b/_sources/operations/projections/vitk1.rst.txt new file mode 100644 index 00000000..c2baf2bf --- /dev/null +++ b/_sources/operations/projections/vitk1.rst.txt @@ -0,0 +1,50 @@ +.. _vitk1: + +******************************************************************************** +Vitkovsky I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | vitk1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/vitk1.png + :width: 500 px + :align: center + :alt: Vitkovsky I + + proj-string: ``+proj=vitk1 +lat_1=45 +lat_2=55`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lat_2.rst + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag1.rst.txt b/_sources/operations/projections/wag1.rst.txt new file mode 100644 index 00000000..72c65ab2 --- /dev/null +++ b/_sources/operations/projections/wag1.rst.txt @@ -0,0 +1,44 @@ +.. _wag1: + +******************************************************************************** +Wagner I (Kavrayskiy VI) +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag1.png + :width: 500 px + :align: center + :alt: Wagner I (Kavrayskiy VI) + + proj-string: ``+proj=wag1`` + +.. note:: This projection name may also be transliterated as Kavraisky VI. + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag2.rst.txt b/_sources/operations/projections/wag2.rst.txt new file mode 100644 index 00000000..60fa7789 --- /dev/null +++ b/_sources/operations/projections/wag2.rst.txt @@ -0,0 +1,50 @@ +.. _wag2: + +******************************************************************************** +Wagner II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag2.png + :width: 500 px + :align: center + :alt: Wagner II + + proj-string: ``+proj=wag2`` + +.. math:: + + x &= 0.92483 \lambda \cos \theta + + y &= 1.38725\theta + + \sin \theta &= 0.88022 \sin(0.8855\phi) + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag3.rst.txt b/_sources/operations/projections/wag3.rst.txt new file mode 100644 index 00000000..6f3dcbb6 --- /dev/null +++ b/_sources/operations/projections/wag3.rst.txt @@ -0,0 +1,50 @@ +.. _wag3: + +******************************************************************************** +Wagner III +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag3 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag3.png + :width: 500 px + :align: center + :alt: Wagner III + + proj-string: ``+proj=wag3`` + +.. math:: + + x &= [\cos\phi_{ts} / \cos ( 2\phi_{ts} / 3)] \lambda \cos (2\phi /3) + + y = \phi + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag4.rst.txt b/_sources/operations/projections/wag4.rst.txt new file mode 100644 index 00000000..a709acfa --- /dev/null +++ b/_sources/operations/projections/wag4.rst.txt @@ -0,0 +1,42 @@ +.. _wag4: + +******************************************************************************** +Wagner IV +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag4 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag4.png + :width: 500 px + :align: center + :alt: Wagner IV + + proj-string: ``+proj=wag4`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag5.rst.txt b/_sources/operations/projections/wag5.rst.txt new file mode 100644 index 00000000..083b5ec6 --- /dev/null +++ b/_sources/operations/projections/wag5.rst.txt @@ -0,0 +1,42 @@ +.. _wag5: + +******************************************************************************** +Wagner V +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag5 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag5.png + :width: 500 px + :align: center + :alt: Wagner V + + proj-string: ``+proj=wag5`` + +Parameters +################################################################################ + +.. note:: All parameters are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag6.rst.txt b/_sources/operations/projections/wag6.rst.txt new file mode 100644 index 00000000..db7c7421 --- /dev/null +++ b/_sources/operations/projections/wag6.rst.txt @@ -0,0 +1,42 @@ +.. _wag6: + +******************************************************************************** +Wagner VI +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag6 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag6.png + :width: 500 px + :align: center + :alt: Wagner VI + + proj-string: ``+proj=wag6`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the Wagner VI projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wag7.rst.txt b/_sources/operations/projections/wag7.rst.txt new file mode 100644 index 00000000..bf99d85b --- /dev/null +++ b/_sources/operations/projections/wag7.rst.txt @@ -0,0 +1,29 @@ +.. _wag7: + +******************************************************************************** +Wagner VII +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wag7 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wag7.png + :width: 500 px + :align: center + :alt: Wagner VII + + proj-string: ``+proj=wag7`` diff --git a/_sources/operations/projections/webmerc.rst.txt b/_sources/operations/projections/webmerc.rst.txt new file mode 100644 index 00000000..55199b24 --- /dev/null +++ b/_sources/operations/projections/webmerc.rst.txt @@ -0,0 +1,100 @@ +.. _webmerc: + +******************************************************************************** +Web Mercator / Pseudo Mercator +******************************************************************************** + +.. versionadded:: 5.1.0 + +The Web Mercator / Pseudo Mercator projection is a cylindrical map projection. +This is a variant of the regular :ref:`merc` projection, except that the computation +is done on a sphere, using the semi-major axis of the ellipsoid. + +From `Wikipedia <https://en.wikipedia.org/wiki/Web_Mercator>`_: + + This projection is widely used by the Web Mercator, Google Web Mercator, + Spherical Mercator, WGS 84 Web Mercator[1] or WGS 84/Pseudo-Mercator is a + variant of the Mercator projection and is the de facto standard for Web + mapping applications. [...] + It is used by virtually all major online map providers [...] + Its official EPSG identifier is EPSG:3857, although others have been used + historically. + + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical (non conformant if used with ellipsoid) | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | webmerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +Usage +######## + +Example:: + + $ echo 2 49 | proj +proj=webmerc +datum=WGS84 + 222638.98 6274861.39 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional, except the ellipsoid + definition, which is WGS84 for the typical use case of EPSG:3857. + In which case, the other parameters are set to their default 0 value. + +.. include:: ../options/ellps.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Mathematical definition +####################### + +The formulas describing the Mercator projection are all taken from G. Evenden's libproj manuals :cite:`Evenden2005`. + +Forward projection +================== + +.. math:: + + x = \lambda + +.. math:: + + y = \ln \left[ \tan \left(\frac{\pi}{4} + \frac{\phi}{2} \right) \right] + + +Inverse projection +================== + +.. math:: + + \lambda = {x} + +.. math:: + + \phi = \frac{\pi}{2} - 2 \arctan \left[ e^{-y} \right] + + + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Web_Mercator>`_ + + + diff --git a/_sources/operations/projections/weren.rst.txt b/_sources/operations/projections/weren.rst.txt new file mode 100644 index 00000000..6c7afdad --- /dev/null +++ b/_sources/operations/projections/weren.rst.txt @@ -0,0 +1,42 @@ +.. _weren: + +******************************************************************************** +Werenskiold I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | weren | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/weren.png + :width: 500 px + :align: center + :alt: Werenskiold I + + proj-string: ``+proj=weren`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wink1.rst.txt b/_sources/operations/projections/wink1.rst.txt new file mode 100644 index 00000000..801bfad2 --- /dev/null +++ b/_sources/operations/projections/wink1.rst.txt @@ -0,0 +1,44 @@ +.. _wink1: + +******************************************************************************** +Winkel I +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wink1 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wink1.png + :width: 500 px + :align: center + :alt: Winkel I + + proj-string: ``+proj=wink1`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wink2.rst.txt b/_sources/operations/projections/wink2.rst.txt new file mode 100644 index 00000000..059a7efa --- /dev/null +++ b/_sources/operations/projections/wink2.rst.txt @@ -0,0 +1,44 @@ +.. _wink2: + +******************************************************************************** +Winkel II +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudocylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wink2 | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wink2.png + :width: 500 px + :align: center + :alt: Winkel II + + proj-string: ``+proj=wink2`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_ts.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/projections/wintri.rst.txt b/_sources/operations/projections/wintri.rst.txt new file mode 100644 index 00000000..8534c92c --- /dev/null +++ b/_sources/operations/projections/wintri.rst.txt @@ -0,0 +1,44 @@ +.. _wintri: + +******************************************************************************** +Winkel Tripel +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Pseudoazimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | wintri | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + +.. figure:: ./images/wintri.png + :width: 500 px + :align: center + :alt: Winkel Tripel + + proj-string: ``+proj=wintri`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for the projection. + +.. include:: ../options/lat_1.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/_sources/operations/transformations/affine.rst.txt b/_sources/operations/transformations/affine.rst.txt new file mode 100644 index 00000000..d2a4e26b --- /dev/null +++ b/_sources/operations/transformations/affine.rst.txt @@ -0,0 +1,123 @@ +.. _affine: + +================================================================================ +Affine transformation +================================================================================ + +.. versionadded:: 6.0.0 + +The affine transformation applies translation and scaling/rotation terms on the +x,y,z coordinates, and translation and scaling on the temporal coordinate. + ++---------------------+----------------------------------------------------------+ +| **Alias** | affine | ++---------------------+----------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+----------------------------------------------------------+ +| **Input type** | XYZT | ++---------------------+----------------------------------------------------------+ +| **output type** | XYZT | ++---------------------+----------------------------------------------------------+ + +By default, the parameters are set for an identity transforms. The transformation +is reversible unless the determinant of the sji matrix is 0, or `tscale` is 0 + + +Parameters +################################################################################ + +Optional +------------------------------------------------------------------------------- + +.. option:: +xoff=<value> + + Offset in X. Default value: 0 + +.. option:: +yoff=<value> + + Offset in Y. Default value: 0 + +.. option:: +zoff=<value> + + Offset in Z. Default value: 0 + +.. option:: +toff=<value> + + Offset in T. Default value: 0 + +.. option:: +s11=<value> + + Rotation/scaling term. Default value: 1 + +.. option:: +s12=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s13=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s21=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s22=<value> + + Rotation/scaling term. Default value: 1 + +.. option:: +s23=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s31=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s32=<value> + + Rotation/scaling term. Default value: 0 + +.. option:: +s33=<value> + + Rotation/scaling term. Default value: 1 + +.. option:: +tscale=<value> + + Time scaling term. Default value: 1 + + + +Mathematical description ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. math:: + :label: formula + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + T \\ + \end{bmatrix}^{dest} = + \begin{bmatrix} + xoff \\ + yoff \\ + zoff \\ + toff \\ + \end{bmatrix} + + \begin{bmatrix} + s11 & s12 & s13 & 0 \\ + s21 & s22 & s23 & 0 \\ + s31 & s32 & s33 & 0 \\ + 0 & 0 & 0 & tscale \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + T \\ + \end{bmatrix}^{source} + \end{align} + + diff --git a/_sources/operations/transformations/defmodel.rst.txt b/_sources/operations/transformations/defmodel.rst.txt new file mode 100644 index 00000000..77906924 --- /dev/null +++ b/_sources/operations/transformations/defmodel.rst.txt @@ -0,0 +1,63 @@ +.. _defmodel: + +================================================================================ +Multi-component time-based deformation model +================================================================================ + +.. versionadded:: 7.1.0 + ++---------------------+--------------------------------------------------------------------+ +| **Alias** | defmodel | ++---------------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic or projected coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++---------------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic or projected coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++---------------------+--------------------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------------------+ +| **Available forms** | Forward and inverse | ++---------------------+--------------------------------------------------------------------+ + +The defmodel transformation can be used to represent most deformation models +currently in use, in particular for areas subject to complex deformation, including +large scale secular crustal deformation near plate boundaries and vertical deformation +due to Glacial Isostatic Adjustment (GIA). These can often be represented by a constant +velocity model. Additionally, many areas suffer episodic deformation events such as +earthquakes and aseismic slow slip event. + +The transformation relies on a "master" JSON file, describing general metadata on +the deformation model, its spatial and temporal extent, and listing spatial +components whose values are stored in :ref:`Geodetic TIFF grids (GTG) <geodetictiffgrids>`. +The valuation of each component is modulated by a time function (constant, step, +reverse step, velocity, piecewise, exponential). + +All details on the content of this JSON file are given in the `Proposal for encoding +of a Deformation Model <https://github.com/linz/deformation-model-format/blob/master/doc/JsonGeotiffDeformationModelFormat_20200501.pdf>`__ + +If input coordinates are given in the geographic domain (resp. projected domain), +the output will also be in the geographic domain (resp. projected domain). +The domain should be the corresponding to the source_crs metadata of the model. + +This transformation is a generalization of the :ref:`Kinematic datum shifting utilizing a deformation model <deformation>` transformation. + +Parameters +------------------------------------------------------------------------------- + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +model=<filename> + + Filename to the JSON master file for the deformation model. + + +Example +------------------------------------------------------------------------------- + +Transforming a point with the LINZ NZGD2000 deformation model: + +:: + + echo 166.7133850980 -44.5105886020 293.3700 2007.689 | cct +proj=defmodel +model=nzgd2000-20180701.json diff --git a/_sources/operations/transformations/deformation.rst.txt b/_sources/operations/transformations/deformation.rst.txt new file mode 100644 index 00000000..84b87949 --- /dev/null +++ b/_sources/operations/transformations/deformation.rst.txt @@ -0,0 +1,229 @@ +.. _deformation: + +================================================================================ +Kinematic datum shifting utilizing a deformation model +================================================================================ + +.. versionadded:: 5.0.0 + +Perform datum shifts means of a deformation/velocity model. + ++-----------------+--------------------------------------------------------------------+ +| **Alias** | deformation | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+--------------------------------------------------------------------+ +| **Domain** | 4D | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates | ++-----------------+--------------------------------------------------------------------+ + + +The deformation operation is used to adjust coordinates for intraplate deformations. +Usually the transformation parameters for regional plate-fixed reference frames such as +the ETRS89 does not take intraplate deformation into account. It is assumed that +tectonic plate of the region is rigid. Often times this is true, but near the plate +boundary and in areas with post-glacial uplift the assumption breaks. Intraplate +deformations can be modelled and then applied to the coordinates so that +they represent the physical world better. In PROJ this is done with the deformation +operation. + +The horizontal grid is stored in CTable2 format and the vertical grid is stored in the +GTX format. Both grids are expected to contain grid-values in units of +mm/year. GDAL both reads and writes both file formats. Using GDAL for +construction of new grids is recommended. + +Starting with PROJ 7.0, use of a GeoTIFF format is recommended to store both +the horizontal and vertical velocities. + +More complex deformations can be done with the :ref:`Multi-component time-based deformation model <defmodel>` transformation. + +Example +------------------------------------------------------------------------------- + +In :cite:`Hakli2016` coordinate transformation including a deformation model is described. +The paper describes how coordinates from the global ITRFxx frames are transformed to the +local Nordic realisations of ETRS89. Scandinavia is an area with significant post-glacial +rebound. The deformations from the post-glacial uplift is not accounted for in the +official ETRS89 transformations so in order to get accurate transformations in the Nordic +countries it is necessary to apply the deformation model. The transformation from ITRF2008 +to the Danish realisation of ETRS89 is in PROJ described as:: + + + proj = pipeline ellps = GRS80 + # ITRF2008@t_obs -> ITRF2000@t_obs + step init = ITRF2008:ITRF2000 + # ITRF2000@t_obs -> ETRF2000@t_obs + step proj=helmert t_epoch = 2000.0 convention=position_vector + x = 0.054 rx = 0.000891 drx = 8.1e-05 + y = 0.051 ry = 0.00539 dry = 0.00049 + z = -0.048 rz = -0.008712 drz = -0.000792 + # ETRF2000@t_obs -> NKG_ETRF00@2000.0 + step proj = deformation t_epoch = 2000.0 + grids = ./eur_nkg_nkgrf03vel_realigned.tif + inv + # NKG_ETRF@2000.0 -> ETRF92@2000.0 + step proj=helmert convention=position_vector s = -0.009420e + x = 0.03863 rx = 0.00617753 + y = 0.147 ry = 5.064e-05 + z = 0.02776 rz = 4.729e-05 + # ETRF92@2000.0 -> ETRF92@1994.704 + step proj = deformation dt = -5.296 + grids = ./eur_nkg_nkgrf03vel_realigned.tif + +From this we can see that the transformation from ITRF2008 to the Danish realisation of +ETRS89 is a combination of Helmert transformations and adjustments with a deformation +model. The first use of the deformation operation is:: + + proj = deformation t_epoch = 2000.0 grids = ./eur_nkg_nkgrf03vel_realigned.tif + +Here we set the central epoch of the transformation, 2000.0. The observation epoch +is expected as part of the input coordinate tuple. The deformation model is +described by two grids, specified with :option:`+xy_grids` and :option:`+z_grids`. +The first is the horizontal part of the model and the second is the vertical +component. + +Parameters +------------------------------------------------------------------------------- + +.. option:: +xy_grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an ``@`` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids for the horizontal component of a deformation model is expected to be + in CTable2 format. + + .. note:: :option:`+xy_grids` is mutually exclusive with :option:`+grids` + +.. option:: +z_grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an `@` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids for the vertical component of a deformation model is expected to be + in either GTX format. + + .. note:: :option:`+z_grids` is mutually exclusive with :option:`+grids` + +.. option:: +grids=<list> + + .. versionadded:: 7.0.0 + + Comma-separated list of grids to load. If a grid is prefixed by an `@` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids should be in GeoTIFF format with the first 3 components being + respectively the easting, northing and up velocities in mm/year. + Setting the Description and Unit Type GDAL band metadata items is strongly + recommended, so that gdalinfo reports: + + :: + + Band 1 Block=... Type=Float32, ColorInterp=Gray + Description = east_velocity + Unit Type: mm/year + Band 2 Block=... Type=Float32, ColorInterp=Undefined + Description = north_velocity + Unit Type: mm/year + Band 3 Block=... Type=Float32, ColorInterp=Undefined + Description = up_velocity + Unit Type: mm/year + + .. note:: :option:`+grids` is mutually exclusive with :option:`+xy_grids` + and :option:`+z_grids` + +.. option:: +t_epoch=<value> + + Central epoch of transformation given in decimalyears. Will be used in + conjunction with the observation time from the input coordinate to + determine :math:`dt` as used in eq. :eq:`apply_velocity` below. + + .. note:: :option:`+t_epoch` is mutually exclusive with :option:`+dt` + +.. option:: +dt=<value> + + .. versionadded:: 6.0.0 + + :math:`dt` as used in eq. :eq:`apply_velocity` below. Is useful when + no observation time is available in the input coordinate or when + a deformation for a specific timespan needs to be applied in a + transformation. :math:`dt` is given in units of decimalyears. + + .. note:: :option:`+dt` is mutually exclusive with :option:`+t_epoch` + +Mathematical description +------------------------------------------------------------------------------- + +Mathematically speaking, application of a deformation model is simple. The deformation model is +represented as a grid of velocities in three dimensions. Coordinate corrections are +applied in cartesian space. For a given coordinate, :math:`(X, Y, Z)`, velocities +:math:`(V_X, V_Y, V_Z)` can be interpolated from the gridded model. The time span +between :math:`t_{obs}` and :math:`t_c` determine the magnitude of the coordinate +correction as seen in eq. :eq:`apply_velocity` below. + +.. math:: + :label: apply_velocity + + \begin{align} + \begin{pmatrix} + X \\ + Y \\ + Z \\ + \end{pmatrix}_B = + \begin{pmatrix} + X \\ + Y \\ + Z \\ + \end{pmatrix}_A + + (t_{obs} - t_c) + \begin{pmatrix} + V_X \\ + V_Y \\ + V_Z \\ + \end{pmatrix} + \end{align} + +Corrections are done in cartesian space. + +Coordinates of the gridded model are in ENU (east, north, up) space because it +would otherwise require an enormous 3 dimensional grid to handle the corrections +in cartesian space. Keeping the correction in lat/long space reduces the +complexity of the grid significantly. Consequently though, the input coordinates +needs to be converted to lat/long space when searching for corrections in the +grid. This is done with the :ref:`cart<cart>` operation. The converted grid +corrections can then be applied to the input coordinates in cartesian space. The +conversion from ENU space to cartesian space is done in the following way: + +.. math:: + :label: enu2xyz + + \begin{align} + \begin{pmatrix} + X \\ + Y \\ + Z \\ + \end{pmatrix} = + \begin{pmatrix} + -\sin\phi \cos\lambda N - \sin\lambda E + \cos\phi \cos\lambda U \\ + -\sin\phi \sin\lambda N + \sin\lambda E + \cos\phi \sin\lambda U \\ + \cos\phi N + \sin\phi U \\ + \end{pmatrix} + \end{align} + +where :math:`\phi` and :math:`\lambda` are the latitude and longitude of the coordinate +that is searched for in the grid. :math:`(E, N, U)` are the grid values in ENU-space and +:math:`(X, Y, Z)` are the corrections converted to cartesian space. + + +See also +----------------------------------------------------------------------------- + +#. :ref:`Behavioural changes from version 5 to 6<differences_deformation>` diff --git a/_sources/operations/transformations/geogoffset.rst.txt b/_sources/operations/transformations/geogoffset.rst.txt new file mode 100644 index 00000000..6ca4f64c --- /dev/null +++ b/_sources/operations/transformations/geogoffset.rst.txt @@ -0,0 +1,70 @@ +.. _geogoffset: + +================================================================================ +Geographic offsets +================================================================================ + +.. versionadded:: 6.0.0 + +The Geographic offsets transformation adds an offset to the geographic longitude, +latitude coordinates, and an offset to the ellipsoidal height. + ++---------------------+----------------------------------------------------------+ +| **Alias** | geogoffset | ++---------------------+----------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical) | ++---------------------+----------------------------------------------------------+ +| **output type** | Geodetic coordinates (horizontal), meters (vertical) | ++---------------------+----------------------------------------------------------+ + +This method is normally only used when low accuracy is tolerated. It is documented +as coordinate operation method code 9619 (for geographic 2D) and 9660 (for +geographic 3D) in the EPSG dataset (:cite:`IOGP2018`) + +It can also be used to implement the method Geographic2D with Height Offsets +(code 9618) by noting that the input vertical component is a gravity-related +height and the output vertical component is the ellipsoid height (dh being +the geoid undulation). + +It can also be used to implement the method Vertical offset (code 9616) + +The reverse transformation simply consists in subtracting the offsets. + +This method is a conveniency wrapper for the more general :ref:`affine`. + +Examples +############################################################################### + +Geographic offset from the old Greek geographic 2D CRS to the newer GGRS87 CRS:: + + proj=geogoffset dlon=0.28 dlat=-5.86 + +Conversion from Tokyo + JSLD69 height to WGS 84:: + + proj=geogoffset dlon=-13.97 dlat=7.94 dh=26.9 + +Conversion from Baltic 1977 height to Black Sea height:: + + proj=geogoffset dh=0.4 + + +Parameters +################################################################################ + +Optional +------------------------------------------------------------------------------- + +.. option:: +dlon=<value> + + Offset in longitude, expressed in arc-second, to add. + +.. option:: +dlat=<value> + + Offset in latitude, expressed in arc-second, to add. + +.. option:: +dh=<value> + + Offset in height, expressed in meter, to add. + diff --git a/_sources/operations/transformations/helmert.rst.txt b/_sources/operations/transformations/helmert.rst.txt new file mode 100644 index 00000000..c0f6934f --- /dev/null +++ b/_sources/operations/transformations/helmert.rst.txt @@ -0,0 +1,482 @@ +.. _helmert: + +================================================================================ +Helmert transform +================================================================================ + +.. versionadded:: 5.0.0 + +The Helmert transformation changes coordinates from one reference frame to +another by means of 3-, 4-and 7-parameter shifts, or one of their 6-, 8- and +14-parameter kinematic counterparts. + + ++-----------------+-------------------------------------------------------------------+ +| **Alias** | helmert | ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 2D, 3D and 4D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ + +The Helmert transform, in all its various incarnations, is used to perform reference +frame shifts. The transformation operates in cartesian space. It can be used to transform +planar coordinates from one datum to another, transform 3D cartesian +coordinates from one static reference frame to another or it can be used to do fully +kinematic transformations from global reference frames to local static frames. + +All of the parameters described in the table above are marked as optional. This is true +as long as at least one parameter is defined in the setup of the transformation. +The behavior of the transformation depends on which parameters are used in the setup. +For instance, if a rate of change parameter is specified a kinematic version of the +transformation is used. + +The kinematic transformations require an observation time of the coordinate, as well +as a central epoch for the transformation. The latter is usually documented +alongside the rest of the transformation parameters for a given transformation. +The central epoch is controlled with the parameter `t_epoch`. The observation +time is given as part of the coordinate when using PROJ's 4D-functionality. + +Examples ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert: + +:: + + proj=helmert convention=coordinate_frame x=-9597.3572 y=.6112 s=0.304794780637 theta=-1.244048 + +Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters: + +:: + + proj=helmert convention=coordinate_frame x=0.67678 y=0.65495 z=-0.52827 + rx=-0.022742 ry=0.012667 rz=0.022704 s=-0.01070 + +Transformation from `ITRF2000` to `ITRF93` using 15 parameters: + +:: + + proj=helmert convention=position_vector + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + rx=-0.00039 ry=0.00080 rz=-0.00114 + drx=-0.00011 dry=-0.00019 drz=0.00007 + t_epoch=1988.0 + +Parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. note:: + + All parameters are optional but at least one should be used, otherwise the + operation will return the coordinates unchanged. + +.. option:: +convention=coordinate_frame/position_vector + + .. versionadded:: 5.2.0 + + Indicates the convention to express the rotational terms when a 3D-Helmert / + 7-parameter more transform is involved. As soon as a rotational parameter + is specified (one of ``rx``, ``ry``, ``rz``, ``drx``, ``dry``, ``drz``), + ``convention`` is required. + + The two conventions are equally popular and a frequent source of confusion. + The coordinate frame convention is also described as an clockwise + rotation of the coordinate frame. It corresponds to EPSG method code + 1032 (in the geocentric domain) or 9607 (in the geographic domain) + The position vector convention is also described as an anticlockwise + (counter-clockwise) rotation of the coordinate frame. + It corresponds to as EPSG method code 1033 (in the geocentric domain) or + 9606 (in the geographic domain). + + This parameter is ignored when only a 3-parameter + (translation terms only: ``x``, ``y``, ``z``) , 4-parameter (3-parameter + and ``theta``) or 6-parameter (3-parameter and their derivative terms) + is used. + + The result obtained with parameters specified in a given convention + can be obtained in the other convention by negating the rotational parameters + (``rx``, ``ry``, ``rz``, ``drx``, ``dry``, ``drz``) + + .. note:: This parameter obsoletes ``transpose`` which was present in + PROJ 5.0 and 5.1, and is forbidden starting with PROJ 5.2 + +.. option:: +x=<value> + + Translation of the x-axis given in meters. + +.. option:: +y=<value> + + Translation of the y-axis given in meters. + +.. option:: +z=<value> + + Translation of the z-axis given in meters. + +.. option:: +s=<value> + + Scale factor given in ppm. + +.. option:: +rx=<value> + + X-axis rotation in the 3D Helmert given arc seconds. + + +.. option:: +ry=<value> + + Y-axis rotation in the 3D Helmert given in arc seconds. + +.. option:: +rz=<value> + + Z-axis rotation in the 3D Helmert given in arc seconds. + + +.. option:: +theta=<value> + + Rotation angle in the 2D Helmert given in arc seconds. + +.. option:: +dx=<value> + + Translation rate of the x-axis given in m/year. + +.. option:: +dy=<value> + + Translation rate of the y-axis given in m/year. + +.. option:: +dz=<value> + + Translation rate of the z-axis given in m/year. + +.. option:: +ds=<value> + + Scale rate factor given in ppm/year. + +.. option:: +drx=<value> + + Rotation rate of the x-axis given in arc seconds/year. + +.. option:: +dry=<value> + + Rotation rate of the y-axis given in arc seconds/year. + +.. option:: +drz=<value> + + Rotation rate of the y-axis given in arc seconds/year. + +.. option:: +t_epoch=<value> + + Central epoch of transformation given in decimalyear. Only used + spatiotemporal transformations. + +.. option:: +exact + + Use exact transformation equations. + + See :eq:`rot_exact` + +.. option:: +transpose + + .. deprecated:: 5.2.0 (removed) + + Transpose rotation matrix and follow the **Position Vector** rotation + convention. If :option:`+transpose` is not added the **Coordinate Frame** + rotation convention is used. + + + +Mathematical description ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In the notation used below, :math:`\hat{P}` is the rate of change of a given transformation +parameter :math:`P`. :math:`\dot{P}` is the kinematically adjusted version of :math:`P`, +described by + +.. math:: + :label: propagation + + \dot{P}= P + \hat{P}\left(t - t_{central}\right) + +where :math:`t` is the observation time of the coordinate and :math:`t_{central}` is +the central epoch of the transformation. Equation :eq:`propagation` can be used to +propagate all transformation parameters in time. + +Superscripts of vectors denote the reference frame the coordinates in the vector belong to. + + +2D Helmert +------------------------------------------------------------------------------- + +The simplest version of the Helmert transform is the 2D case. In the 2-dimensional +case only the horizontal coordinates are changed. The coordinates can be +translated, rotated and scale. Translation is controlled with the `x` and `y` +parameters. The rotation is determined by `theta` and the scale is controlled with +the `s` parameters. + +.. note:: + + The scaling parameter `s` is unitless for the 2D Helmert, as opposed to the + 3D version where the scaling parameter is given in units of ppm. + +Mathematically the 2D Helmert is described as: + +.. math:: + :label: 4param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + \end{bmatrix} + + s + \begin{bmatrix} + \hphantom{-}\cos \theta & \sin \theta \\ + -\sin \theta & \cos \theta \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + + +:eq:`4param` can be extended to a time-varying kinematic version by +adjusting the parameters with :eq:`propagation` to :eq:`4param`, which yields +the kinematic 2D Helmert transform: + +.. math:: + :label: 8param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \end{bmatrix} + + s(t) + \begin{bmatrix} + \hphantom{-}\cos \dot{\theta} & \sin \dot{\theta} \\ + -\sin\ \dot{\theta} & \cos \dot{\theta} \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + +All parameters in :eq:`8param` are determined by the use of :eq:`propagation`, +which applies the rate of change to each individual parameter for a given +timespan between :math:`t` and :math:`t_{central}`. + + +3D Helmert +------------------------------------------------------------------------------- + +The general form of the 3D Helmert is + +.. math:: + :label: general-helmert + + + \begin{align} + V^B = T + \left(1 + s \times 10^{-6}\right) \mathbf{R} V^A + \end{align} + +Where :math:`T` is a vector consisting of the three translation parameters, :math:`s` +is the scaling factor and :math:`\mathbf{R}` is a rotation matrix. :math:`V^A` and +:math:`V^B` are coordinate vectors, with :math:`V^A` being the input coordinate and +:math:`V^B` is the output coordinate. + +In the *Position Vector* convention, we define :math:`R_x = radians \left( rx \right)`, +:math:`R_z = radians \left( ry \right)` and :math:`R_z = radians \left( rz \right)` + +In the *Coordinate Frame* convention, :math:`R_x = - radians \left( rx \right)`, +:math:`R_z = - radians \left( ry \right)` and :math:`R_z = - radians \left( rz \right)` + +The rotation matrix is composed of three rotation matrices, one for each axis. + +.. math:: + + \begin{align} + \mathbf{R}_X &= \begin{bmatrix} 1 & 0 & 0\\ 0 & \cos R_x & -\sin R_x \\ 0 & \sin R_x & \cos R_x \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Y &= \begin{bmatrix} \cos R_y & 0 & \sin R_y\\ 0 & 1 & 0\\ -\sin R_y & 0 & \cos R_y \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Z &= \begin{bmatrix} \cos R_z & -\sin R_z & 0\\ \sin R_z & \cos R_z & 0\\ 0 & 0 & 1 \end{bmatrix} + \end{align} + +The three rotation matrices can be combined in one: + +.. math:: + + \begin{align} + \mathbf{R} = \mathbf{R_X} \mathbf{R_Y} \mathbf{R_Y} + \end{align} + + +For :math:`\mathbf{R}`, this yields: + +.. math:: + :label: rot_exact + + \begin{bmatrix} + \cos R_y \cos R_z & -\cos R_x \sin R_z + & \sin R_x \sin R_z + \\ + & \sin R_x \sin R_y \cos R_z & \cos R_x \sin R_y \cos R_z \\ + \cos R_y\sin R_z & \cos R_x \cos R_z + & - \sin R_x \cos R_z + \\ + & \sin R_x \sin R_y \sin R_z & \cos R_x \sin R_y \sin R_z \\ + -\sin R_y & \sin R_x \cos R_y & \cos R_x \cos R_y \\ + \end{bmatrix} + + +Using the small angle approximation the rotation matrix can be simplified to + +.. math:: + :label: rot_approx + + \begin{align} \mathbf{R} = + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \end{align} + +Which allow us to express the most common version of the Helmert transform, +using the approximated rotation matrix: + + +.. math:: + :label: 7param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \left(1 + s \times 10^{-6}\right) + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +If the rotation matrix is transposed, or the sign of the rotation terms negated, +the rotational part of the transformation is effectively reversed. +This is what happens when switching between the 2 conventions ``position_vector`` +and ``coordinate_frame`` + +Applying :eq:`propagation` we get the kinematic version of the approximated +3D Helmert: + +.. math:: + :label: 14param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \left(1 + \dot{s} \times 10^{-6}\right) + \begin{bmatrix} + 1 & -\dot{R_z} & \dot{R_y} \\ + \dot{R_z} & 1 & -\dot{R_x} \\ + -\dot{R_y} & \dot{R_x} & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + + + + +The Helmert transformation can be applied without using the rotation parameters, +in which case it becomes a simple translation of the origin of the coordinate +system. When using the Helmert in this version equation :eq:`general-helmert` +simplifies to: + +.. math:: + :label: 3param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +That after application of :eq:`propagation` has the following kinematic +counterpart: + +.. math:: + :label: 6param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} diff --git a/_sources/operations/transformations/hgridshift.rst.txt b/_sources/operations/transformations/hgridshift.rst.txt new file mode 100644 index 00000000..d27059e9 --- /dev/null +++ b/_sources/operations/transformations/hgridshift.rst.txt @@ -0,0 +1,118 @@ +.. _hgridshift: + +================================================================================ +Horizontal grid shift +================================================================================ + +.. versionadded:: 5.0.0 + +Change of horizontal datum by grid shift. + ++-----------------+--------------------------------------------------------------------+ +| **Alias** | hgridshift | ++-----------------+--------------------------------------------------------------------+ +| **Domain** | 2D, 3D and 4D | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++-----------------+--------------------------------------------------------------------+ + +The horizontal grid shift is done by offsetting the planar input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid:: + + +proj=hgridshift +grids=nzgr2kgrid0005.gsb + + +More than one grid can be loaded at the same time, for instance in case the +dataset needs to be transformed spans several countries. In this example grids +of the continental US, Alaska and Canada is loaded at the same time:: + + +proj=hgridshift +grids=@conus,@alaska,@ntv2_0.gsb,@ntv_can.dat + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ search path. The list of grids is prioritized so that +grids in the start of the list takes precedence over the grids in the back of the +list. + +PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections. Details +about all three formats can be found in the GDAL documentation and/or driver source +code. GDAL reads and writes all three formats. Using GDAL for construction of +new grids is recommended. + + +Temporal gridshifting +################################################################################ +.. versionadded:: 5.1.0 + +By initializing the horizontal gridshift operation with a central epoch, it can be +used as a step function applying the grid offsets only if a coordinate is +transformed from an epoch before grids central epoch to an epoch after. This is +handy in transformations where it is necessary to handle deformations caused by +seismic activity. + +The central epoch of the grid is controlled with :option:`+t_epoch` and the final +epoch of the coordinate is set with :option:`+t_final`. The observation epoch of +the coordinate is part of the coordinate tuple. + +Suppose we want to model the deformation of the 2008 earthquake in Iceland in +a transformation of data from 2005 to 2009:: + + echo 63.992 -21.014 10.0 2005.0 | cct +proj=hgridshift +grids=iceland2008.gsb +t_epoch=2008.4071 +t_final=2009.0 + 63.9920021 -21.0140013 10.0 2005.0 + +.. note:: + The timestamp of the resulting coordinate is still 2005.0. The observation + time is always kept unchanged as it would otherwise be impossible to do the + inverse transformation. + +Temporal gridshifting is especially powerful in transformation pipelines where +several gridshifts can be chained together, effectively acting as a series of +step functions that can be applied to a coordinate that is propagated through +time. In the following example we establish a pipeline that allows transformation +of coordinates from any given epoch up until the current date, applying only +those gridshifts that have central epochs between the observation epoch and +the final epoch:: + + +proj=pipeline +t_final=now + +step +proj=hgridshift +grids=earthquake_1.gsb +t_epoch=2010.421 + +step +proj=hgridshift +grids=earthquake_2.gsb +t_epoch=2013.853 + +step +proj=hgridshift +grids=earthquake_3.gsb +t_epoch=2017.713 + +.. note:: + The special epoch *now* is used when specifying the final epoch with + :option:`+t_final`. This results in coordinates being transformed to the + current date. Additionally, :option:`+t_final` is used as a + :ref:`global pipeline parameter<global-pipeline-parameter>`, which means + that it is applied to all the steps in the pipeline. + +In the above transformation, a coordinate with observation epoch 2009.32 would +be subject to all three gridshift steps in the pipeline. A coordinate with +observation epoch 2014.12 would only by offset by the last step in the pipeline. + + +Parameters +################################################################################ + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an `@` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids are expected to be in CTable2, NTv1 or NTv2 format. + +Optional ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. include:: ../options/t_epoch.rst +.. versionadded:: 5.1.0 +.. include:: ../options/t_final.rst +.. versionadded:: 5.1.0 + diff --git a/_sources/operations/transformations/horner.rst.txt b/_sources/operations/transformations/horner.rst.txt new file mode 100644 index 00000000..ad09e8ab --- /dev/null +++ b/_sources/operations/transformations/horner.rst.txt @@ -0,0 +1,213 @@ +.. _horner: + +================================================================================ +Horner polynomial evaluation +================================================================================ + +.. versionadded:: 5.0.0 + ++-----------------+-------------------------------------------------------------------+ +| **Alias** | horner | ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 2D and 3D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Geodetic and projected coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Geodetic and projected coordinates | ++-----------------+-------------------------------------------------------------------+ + +The Horner polynomial evaluation scheme is used for transformations between reference +frames where one or both are inhomogeneous or internally distorted. This will typically +be reference frames created before the introduction of space geodetic techniques such +as GPS. + +Horner polynomials, or Multiple Regression Equations as they are also known as, have +their strength in being able to create complicated mappings between coordinate +reference frames while still being lightweight in both computational cost and disk +space used. + +PROJ implements two versions of the Horner evaluation scheme: Real and complex +polynomial evaluation. Below both are briefly described. For more details consult +:cite:`Ruffhead2016` and :cite:`IOGP2018`. + +The polynomial evaluation in real number space is defined by the following equations: + +.. math:: + :label: real_poly + + \Delta X = \sum_{i,j} u_{i,j} U^i V^j + + \Delta Y = \sum_{i,j} v_{i,j} U^i V^j + +where + +.. math:: + :label: UV + + U = X_{in} - X_{origin} + + V = Y_{in} - Y_{origin} + +and :math:`u_{i,j}` and :math:`v_{i,j}` are coefficients that make up +the polynomial. + +The final coordinates are determined as + +.. math:: + :label: xy_out + + X_{out} = X_{in} + \Delta X + + Y_{out} = Y_{in} + \Delta Y + +The inverse transform is the same as the above but requires a different set of +coefficients. + +Evaluation of the complex polynomials are defined by the following equations: + +.. math:: + :label: complex_poly + + \Delta X + i \Delta Y = \sum_{j=1}^n (c_{2j-1} + i c_{2j}) (U + i V)^j + +Where :math:`n` is the degree of the polynomial. :math:`U` and :math:`V` are +defined as in :eq:`UV` and the resulting coordinates are again determined +by :eq:`xy_out`. + +Examples +################################################################################ + +Mapping between Danish TC32 and ETRS89/UTM zone 32 using polynomials in real +number space:: + + +proj=horner + +ellps=intl + +range=500000 + +fwd_origin=877605.269066,6125810.306769 + +inv_origin=877605.760036,6125811.281773 + +deg=4 + +fwd_v=6.1258112678e+06,9.9999971567e-01,1.5372750011e-10,5.9300860915e-15,2.2609497633e-19,4.3188227445e-05,2.8225130416e-10,7.8740007114e-16,-1.7453997279e-19,1.6877465415e-10,-1.1234649773e-14,-1.7042333358e-18,-7.9303467953e-15,-5.2906832535e-19,3.9984284847e-19 + +fwd_u=8.7760574982e+05,9.9999752475e-01,2.8817299305e-10,5.5641310680e-15,-1.5544700949e-18,-4.1357045890e-05,4.2106213519e-11,2.8525551629e-14,-1.9107771273e-18,3.3615590093e-10,2.4380247154e-14,-2.0241230315e-18,1.2429019719e-15,5.3886155968e-19,-1.0167505000e-18 + +inv_v=6.1258103208e+06,1.0000002826e+00,-1.5372762184e-10,-5.9304261011e-15,-2.2612705361e-19,-4.3188331419e-05,-2.8225549995e-10,-7.8529116371e-16,1.7476576773e-19,-1.6875687989e-10,1.1236475299e-14,1.7042518057e-18,7.9300735257e-15,5.2881862699e-19,-3.9990736798e-19 + +inv_u=8.7760527928e+05,1.0000024735e+00,-2.8817540032e-10,-5.5627059451e-15,1.5543637570e-18,4.1357152105e-05,-4.2114813612e-11,-2.8523713454e-14,1.9109017837e-18,-3.3616407783e-10,-2.4382678126e-14,2.0245020199e-18,-1.2441377565e-15,-5.3885232238e-19,1.0167203661e-18 + + +Mapping between Danish System Storebælt and ETRS89/UTM zone 32 using complex +polynomials:: + + +proj=horner + +ellps=intl + +range=500000 + +fwd_origin=4.94690026817276e+05,6.13342113183056e+06 + +inv_origin=6.19480258923588e+05,6.13258568148837e+06 + +deg=3 + +fwd_c=6.13258562111350e+06,6.19480105709997e+05,9.99378966275206e-01,-2.82153291753490e-02,-2.27089979140026e-10,-1.77019590701470e-09,1.08522286274070e-14,2.11430298751604e-15 + +inv_c=6.13342118787027e+06,4.94690181709311e+05,9.99824464710368e-01,2.82279070814774e-02,7.66123542220864e-11,1.78425334628927e-09,-1.05584823306400e-14,-3.32554258683744e-15 + +Parameters +################################################################################ + +Setting up Horner polynomials requires many coefficients being explicitly +written, even for polynomials of low degree. For this reason it is recommended +to store the polynomial definitions in an :ref:`init file <init_files>` for +easier writing and reuse. + +Required +------------------------------------------------------------------------------- + +Below is a list of required parameters that can be set for the Horner polynomial +transformation. As stated above, the transformation takes to forms, either using +real or complex polynomials. These are divided into separate sections below. +Parameters from the two sections are mutually exclusive, that is parameters +describing real and complex polynomials can't be mixed. + +.. include:: ../options/ellps.rst + +.. option:: +deg=<value> + + Degree of polynomial + +.. option:: +fwd_origin=<northing,easting> + + Coordinate of origin for the forward mapping + +.. option:: +inv_origin=<northing,easting> + + Coordinate of origin for the inverse mapping + +Real polynomials +.............................................................................. + +The following parameters has to be set if the transformation consists of +polynomials in real space. Each parameter takes a comma-separated list of +coefficients. The number of coefficients is governed by the degree, :math:`d`, +of the polynomial: + +.. math:: + + N = \frac{(d + 1)(d + 2)}{2} + +.. option:: +fwd_u=<u_11,u_12,...,u_ij,..,u_mn> + + Coefficients for the forward transformation i.e. latitude to northing + as described in :eq:`real_poly`. + +.. option:: +fwd_v=<v_11,v_12,...,v_ij,..,v_mn> + + Coefficients for the forward transformation i.e. longitude to easting + as described in :eq:`real_poly`. + +.. option:: +inv_u=<u_11,u_12,...,u_ij,..,u_mn> + + Coefficients for the inverse transformation i.e. latitude to northing + as described in :eq:`real_poly`. + +.. option:: +inv_v=<v_11,v_12,...,v_ij,..,v_mn> + + Coefficients for the inverse transformation i.e. longitude to easting + as described in :eq:`real_poly`. + + + +Complex polynomials +.............................................................................. + +The following parameters has to be set if the transformation consists of +polynomials in complex space. Each parameter takes a comma-separated list of +coefficients. The number of coefficients is governed by the degree, :math:`d`, +of the polynomial: + +.. math:: + + N = 2d + 2 + +.. option:: +fwd_c=<c_1,c_2,...,c_N> + + Coefficients for the complex forward transformation + as described in :eq:`complex_poly`. + +.. option:: +inv_c=<c_1,c_2,...,c_N> + + Coefficients for the complex inverse transformation + as described in :eq:`complex_poly`. + +Optional +------------------------------------------------------------------------------- + +.. option:: +range=<value> + + Radius of the region of validity. + +.. option:: +uneg + + Express latitude as southing. Only applies for complex polynomials. + +.. option:: +vneg + + Express longitude as westing. Only applies for complex polynomials. + + +Further reading +################################################################################ + +#. `Wikipedia <https://en.wikipedia.org/wiki/Horner%27s_method>`_ diff --git a/_sources/operations/transformations/index.rst.txt b/_sources/operations/transformations/index.rst.txt new file mode 100644 index 00000000..a413b8f6 --- /dev/null +++ b/_sources/operations/transformations/index.rst.txt @@ -0,0 +1,24 @@ +.. _transformation_list: + +================================================================================ +Transformations +================================================================================ + +Transformations coordinate operation in which the two coordinate reference +systems are based on different datums. + +.. toctree:: + :maxdepth: 1 + + affine + defmodel + deformation + geogoffset + helmert + horner + molodensky + molobadekas + hgridshift + tinshift + vgridshift + xyzgridshift diff --git a/_sources/operations/transformations/molobadekas.rst.txt b/_sources/operations/transformations/molobadekas.rst.txt new file mode 100644 index 00000000..b7d638bf --- /dev/null +++ b/_sources/operations/transformations/molobadekas.rst.txt @@ -0,0 +1,147 @@ +.. _molobadekas: + +================================================================================ +Molodensky-Badekas transform +================================================================================ + +.. versionadded:: 6.0.0 + +The Molodensky-Badekas transformation changes coordinates from one reference frame to +another by means of a 10-parameter shift. + +.. note:: + + It should not be confused with the :ref:`Molodensky` transform which + operates directly in the geodetic coordinates. Molodensky-Badekas can rather + be seen as a variation of :ref:`Helmert` + ++-----------------+-------------------------------------------------------------------+ +| **Alias** | molobadekas | ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 3D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ + +The Molodensky-Badekas transformation is a variation of the :ref:`Helmert` where +the rotational terms are not directly applied to the ECEF coordinates, but on +cartesian coordinates relative to a reference point (usually close to Earth surface, +and to the area of use of the transformation). When ``px`` = ``py`` = ``pz`` = 0, +this is equivalent to a 7-parameter Helmert transformation. + +Example ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Transforming coordinates from La Canoa to REGVEN: + +:: + + proj=molobadekas convention=coordinate_frame + x=-270.933 y=115.599 z=-360.226 rx=-5.266 ry=-1.238 rz=2.381 + s=-5.109 px=2464351.59 py=-5783466.61 pz=974809.81 + + +Parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. note:: + + All parameters (except convention) are optional but at least one should be + used, otherwise the operation will return the coordinates unchanged. + +.. option:: +convention=coordinate_frame/position_vector + + Indicates the convention to express the rotational terms when a 3D-Helmert / + 7-parameter more transform is involved. + + The two conventions are equally popular and a frequent source of confusion. + The coordinate frame convention is also described as an clockwise + rotation of the coordinate frame. It corresponds to EPSG method code + 1034 (in the geocentric domain) or 9636 (in the geographic domain) + The position vector convention is also described as an anticlockwise + (counter-clockwise) rotation of the coordinate frame. + It corresponds to as EPSG method code 1061 (in the geocentric domain) or + 1063 (in the geographic domain). + + The result obtained with parameters specified in a given convention + can be obtained in the other convention by negating the rotational parameters + (``rx``, ``ry``, ``rz``) + +.. option:: +x=<value> + + Translation of the x-axis given in meters. + +.. option:: +y=<value> + + Translation of the y-axis given in meters. + +.. option:: +z=<value> + + Translation of the z-axis given in meters. + +.. option:: +s=<value> + + Scale factor given in ppm. + +.. option:: +rx=<value> + + X-axis rotation given arc seconds. + +.. option:: +ry=<value> + + Y-axis rotation given in arc seconds. + +.. option:: +rz=<value> + + Z-axis rotation given in arc seconds. + +.. option:: +px=<value> + + Coordinate along the x-axis of the reference point given in meters. + +.. option:: +py=<value> + + Coordinate along the y-axis of the reference point given in meters. + +.. option:: +pz=<value> + + Coordinate along the z-axis of the reference point given in meters. + +Mathematical description ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +In the *Position Vector* convention, we define :math:`R_x = radians \left( rx \right)`, +:math:`R_z = radians \left( ry \right)` and :math:`R_z = radians \left( rz \right)` + +In the *Coordinate Frame* convention, :math:`R_x = - radians \left( rx \right)`, +:math:`R_z = - radians \left( ry \right)` and :math:`R_z = - radians \left( rz \right)` + +.. math:: + :label: 10param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^{output} = + \begin{bmatrix} + T_x + P_x\\ + T_y + P_y\\ + T_z + P_z\\ + \end{bmatrix} + + \left(1 + s \times 10^{-6}\right) + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X^{input} - P_x\\ + Y^{input} - P_y\\ + Z^{input} - P_z\\ + \end{bmatrix} + \end{align} diff --git a/_sources/operations/transformations/molodensky.rst.txt b/_sources/operations/transformations/molodensky.rst.txt new file mode 100644 index 00000000..df0b00a2 --- /dev/null +++ b/_sources/operations/transformations/molodensky.rst.txt @@ -0,0 +1,96 @@ +.. _molodensky: + +================================================================================ +Molodensky transform +================================================================================ + +.. versionadded:: 5.0.0 + +The Molodensky transformation resembles a :ref:`Helmert` with zero +rotations and a scale of unity, but converts directly from geodetic coordinates to +geodetic coordinates, without the intermediate shifts to and from cartesian +geocentric coordinates, associated with the Helmert transformation. +The Molodensky transformation is simple to implement and to parametrize, requiring +only the 3 shifts between the input and output frame, and the corresponding +differences between the semimajor axes and flattening parameters of the reference +ellipsoids. Due to its algorithmic simplicity, it was popular prior to the +ubiquity of digital computers. Today, it is mostly interesting for historical +reasons, but nevertheless indispensable due to the large amount of data that has +already been transformed that way :cite:`EversKnudsen2017`. + ++---------------------+----------------------------------------------------------+ +| **Alias** | molodensky | ++---------------------+----------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical) | ++---------------------+----------------------------------------------------------+ +| **output type** | Geodetic coordinates (horizontal), meters (vertical) | ++---------------------+----------------------------------------------------------+ + +The Molodensky transform can be used to perform a datum shift from coordinate +:math:`(\phi_1, \lambda_1, h_1)` to :math:`(\phi_2, \lambda_2, h_2)` where the two +coordinates are referenced to different ellipsoids. This is based on three +assumptions: + + 1. The cartesian axes, :math:`X, Y, Z`, of the two ellipsoids are parallel. + 2. The offset, :math:`\delta X, \delta Y, \delta Z`, between the two ellipsoid + are known. + 3. The characteristics of the two ellipsoids, expressed as the difference in + semimajor axis (:math:`\delta a`) and flattening (:math:`\delta f`), are known. + +The Molodensky transform is mostly used for transforming between old systems +dating back to the time before computers. The advantage of the Molodensky transform +is that it is fairly simple to compute by hand. The ease of computation come at the +cost of limited accuracy. + +A derivation of the mathematical formulas for the Molodensky transform can be found +in :cite:`Deakin2004`. + + +Examples +############################################################################### + +The abridged Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 abridged + +The same transformation using the standard Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 + + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. option:: +da=<value> + + Difference in semimajor axis of the defining ellipsoids. + +.. option:: +df=<value> + + Difference in flattening of the defining ellipsoids. + +.. option:: +dx=<value> + + Offset of the X-axes of the defining ellipsoids. + +.. option:: +dy=<value> + + Offset of the Y-axes of the defining ellipsoids. + +.. option:: +dz=<value> + + Offset of the Z-axes of the defining ellipsoids. + +.. include:: ../options/ellps.rst + +Optional +------------------------------------------------------------------------------- + +.. option:: +abridged + + Use the abridged version of the Molodensky transform. diff --git a/_sources/operations/transformations/tinshift.rst.txt b/_sources/operations/transformations/tinshift.rst.txt new file mode 100644 index 00000000..2135266b --- /dev/null +++ b/_sources/operations/transformations/tinshift.rst.txt @@ -0,0 +1,215 @@ +.. _tinshift: + +================================================================================ +Triangulated Irregular Network based transformation +================================================================================ + +.. versionadded:: 7.2.0 + ++---------------------+--------------------------------------------------------------------+ +| **Alias** | tinshift | ++---------------------+--------------------------------------------------------------------+ +| **Input type** | Projected or geographic coordinates (horizontal), meters (vertical)| ++---------------------+--------------------------------------------------------------------+ +| **Output type** | Projected or geographic coordinates (horizontal), meters (vertical)| ++---------------------+--------------------------------------------------------------------+ +| **Domain** | 2D or 3D | ++---------------------+--------------------------------------------------------------------+ +| **Available forms** | Forward and inverse | ++---------------------+--------------------------------------------------------------------+ + + +The ``tinshift`` transformation takes one mandatory +argument, ``file``, that points to a JSON file, which contains the +triangulation and associated metadata. Input and output coordinates must be +geographic or projected coordinates. +Depending on the content of the JSON file, horizontal, vertical or both +components of the coordinates may be transformed. + +The transformation is invertible, with the same computational complexity than +the forward transformation. + +Parameters +------------------------------------------------------------------------------- + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +file=<filename> + + Filename to the JSON file for the TIN. + + +Example +------------------------------------------------------------------------------- + +Transforming a point with the Finland EPSG:2393 ("KKJ / Finland Uniform +Coordinate System") projected CRS to EPSG:3067 ("ETRS89 / TM35FIN(E,N)") + +:: + + $ echo 3210000.0000 6700000.0000 0 2020 | cct +proj=tinshift +file=./triangulation_kkj.json + + 209948.3217 6697187.0009 0.0000 2020 + + +Algorithm ++++++++++ + +Internally, ``tinshift`` ingest the whole file into memory. It is considered that +triangulation should be small enough for that. + +When a point is transformed, one must find the triangle into which it falls into. +Instead of iterating over all triangles, we build a in-memory quadtree to speed-up +the identification of candidates triangles. + +To determine if a point falls into a triangle, one computes its 3 +`barycentric coordinates <https://en.wikipedia.org/wiki/Barycentric_coordinate_system#Conversion_between_barycentric_and_Cartesian_coordinates>`_ +from its projected coordinates, :math:`\lambda_i` for :math:`i=1,2,3`. +They are real values (in the [0,1] range for a point inside the triangle), +giving the weight of each of the 3 vertices of the triangles. + +Once those weights are known, interpolating the target horizontal +coordinate is a matter of doing the linear combination of those weights with +the target horizontal coordinates at the 3 vertices of the triangle (:math:`Xt_i` and :math:`Yt_i`): + +.. math:: + + X_{target} = Xt_1 * \lambda_1 + Xt_2 * \lambda_2 + Xt_3 * \lambda_3 + + Y_{target} = Yt_1 * \lambda_1 + Yt_2 * \lambda_2 + Yt_3 * \lambda_3 + +This interpolation is exact at the vertices of the triangulation, and has linear properties +inside each triangle. It is completely equivalent to other formulations of +triangular interpolation, such as + +.. math:: + + X_{target} = A + X_{source} * B + Y_{source} * C + + Y_{target} = D + X_{source} * E + Y_{source} * F + +where the A, B, C, D, E, F constants (for a given triangle) are found by solving +the 2 systems of 3 linear equations, constraint by the source and target coordinate pairs +of the 3 vertices of the triangle: + +.. math:: + + Xt_i = A + Xs_i * B + Ys_i * C + + Yt_i = D + Xs_i * E + Ys_i * F + +Similarly for a vertical coordinate transformation, where :math:`Zoff_i` is the vertical +offset at each vertex of the triangle: + +.. math:: + + Z_{target} = Z_{source} + Zoff_1 * \lambda_1 + Zoff_2 * \lambda_2 + Zoff_3 * \lambda_3 + +Constraints on the triangulation +++++++++++++++++++++++++++++++++ + +No check is done on the consistence of the triangulation. It is highly +recommended that triangles do not overlap each other (when considering the +source coordinates or the forward transformation, or the target coordinates for +the inverse transformation), otherwise which triangle will be selected is +unspecified. Besides that, the triangulation does not need to have particular +properties (like being a Delaunay triangulation) + +File format ++++++++++++ + +The triangulation is stored in a text-based format, using JSON as a serialization. + +Below a minimal example, from the KKJ to ETRS89 transformation, with just a +single triangle: + +.. literalinclude:: ../../../../data/tests/tinshift_crs_implicit.json + :language: json + + +So after the generic metadata, we define the input and output CRS (informative +only), and that the transformation affects horizontal components of +coordinates. We name the columns of the ``vertices`` and ``triangles`` arrays. +We defined the source and target coordinates of each vertex, and define a +triangle by referring to the index of its vertices in the ``vertices`` array. + +More formally, the specific items for the triangulation file are: + +input_crs + String identifying the CRS of source coordinates + in the vertices. Typically ``EPSG:XXXX``. If the transformation is for vertical + component, this should be the code for a compound CRS (can be EPSG:XXXX+YYYY + where XXXX is the code of the horizontal CRS and YYYY the code of the vertical CRS). + For example, for the KKJ->ETRS89 transformation, this is EPSG:2393 + (``KKJ / Finland Uniform Coordinate System``). The input coordinates are assumed + to be passed in the "normalized for visualisation" / "GIS friendly" order, + that is longitude, latitude for geographic coordinates and + easting, northing for projected coordinates. + + +output_crs + String identifying the CRS of target coordinates in the vertices. + Typically ``EPSG:XXXX``. If the transformation is for vertical component, + this should be the code for a compound CRS (can be EPSG:XXXX+YYYY where + XXXX is the code of the horizontal CRS and YYYY the code of the vertical CRS). + For example, for the KKJ->ETRS89 transformation, this is EPSG:3067 + (\"ETRS89 / TM35FIN(E,N)\"). The output coordinates will be returned in + the "normalized for visualisation" / "GIS friendly" order, + that is longitude, latitude for geographic coordinates and + easting, northing for projected coordinates. + + +transformed_components + Array which may contain one or two strings: "horizontal" when horizontal + components of the coordinates are transformed and/or "vertical" when the + vertical component is transformed. + + +fallback_strategy + String identifying how to treat points that do not fall into any of the + specified triangles. This item is available for ``format_version`` >= 1.1. + Possible values are ``none``, ``nearest_side`` and ``nearest_centroid``. The + default is ``none`` and signifies, that points that fall outside the + specified triangles are not transformed. This is also the behaviour for + ``format_version`` before 1.1. If ``fallback_strategy`` is set to + ``nearest_side``, then points that do not fall into any triangle are + transformed according to the triangle closest to them by euclidean distance. + If ``fallback_strategy`` is set to ``nearest_centroid``, then points that do + not fall into any triangle are transformed according to the triangle with the + closest centroid (intersection of its medians). + + +vertices_columns + Specify the name of the columns of the rows in the ``vertices`` + array. There must be exactly as many elements in ``vertices_columns`` as in a + row of ``vertices``. The following names have a special meaning: ``source_x``, + ``source_y``, ``target_x``, ``target_y``, ``source_z``, ``target_z`` and + ``offset_z``. ``source_x`` and ``source_y`` are compulsory. + ``source_x`` is for the source longitude (in degree) or easting. + ``source_y`` is for the source latitude (in degree) or northing. + ``target_x`` and ``target_y`` are compulsory when ``horizontal`` is specified + in ``transformed_components``. (``source_z`` and ``target_z``) or + ``offset_z`` are compulsory when ``vertical`` is specified in ``transformed_components`` + + +triangles_columns + Specify the name of the columns of the rows in the + ``triangles`` array. There must be exactly as many elements in ``triangles_columns`` + as in a row of ``triangles``. The following names have a special meaning: + ``idx_vertex1``, ``idx_vertex2``, ``idx_vertex3``. They are compulsory. + + +vertices + An array whose items are themselves arrays with as many columns as + described in ``vertices_columns``. + + +triangles + An array whose items are themselves arrays with as many columns as + described in ``triangles_columns``. + The value of the ``idx_vertexN`` columns must be indices + (between 0 and len(``vertices``-1) of items of the ``vertices`` array. + +A `JSON schema <https://proj.org/schemas/triangulation.schema.json>`_ is available +for this file format. diff --git a/_sources/operations/transformations/vgridshift.rst.txt b/_sources/operations/transformations/vgridshift.rst.txt new file mode 100644 index 00000000..5a31ae8f --- /dev/null +++ b/_sources/operations/transformations/vgridshift.rst.txt @@ -0,0 +1,133 @@ +.. _vgridshift: + +================================================================================ +Vertical grid shift +================================================================================ + +.. versionadded:: 5.0.0 + +Change Vertical datum change by grid shift + ++-----------------+--------------------------------------------------------------------+ +| **Alias** | vgridshift | ++-----------------+--------------------------------------------------------------------+ +| **Domain** | 3D and 4D | ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates (horizontal), meters (vertical), | +| | decimalyear (temporal) | ++-----------------+--------------------------------------------------------------------+ + +The vertical grid shift is done by offsetting the vertical input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid. Here we change the vertical +reference from the ellipsoid to the global geoid model, EGM96:: + + +proj=vgridshift +grids=egm96_15.gtx + + +More than one grid can be loaded at the same time, for instance in the case where +a better geoid model than the global is available for a certain area. Here the +gridshift is set up so that the local DVR90 geoid model takes precedence over +the global model:: + + +proj=vgridshift +grids=@dvr90.gtx,egm96_15.gtx + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ search path. The list of grids is prioritized so that +grids in the start of the list takes precedence over the grids in the back of the +list. + +PROJ supports the GTX file format for vertical grid corrections. Details +about all the format can be found in the GDAL documentation. GDAL both reads and +writes the format. Using GDAL for construction of new grids is recommended. + +Temporal gridshifting +################################################################################ +.. versionadded:: 5.1.0 + +By initializing the vertical gridshift operation with a central epoch, it can be +used as a step function applying the grid offsets only if a coordinate is +transformed from an epoch before grids central epoch to an epoch after. This is +handy in transformations where it is necessary to handle deformations caused by +seismic activity. + +The central epoch of the grid is controlled with :option:`+t_epoch` and the final +epoch of the coordinate is set with :option:`+t_final`. The observation epoch of +the coordinate is part of the coordinate tuple. + +Suppose we want to model the deformation of the 2008 earthquake in Iceland in +a transformation of data from 2005 to 2009:: + + echo 63.992 -21.014 10.0 2005.0 | cct +proj=vgridshift +grids=iceland2008.gtx +t_epoch=2008.4071 +t_final=2009.0 + 63.992 -21.014 10.11 2005.0 + +.. note:: + The timestamp of the resulting coordinate is still 2005.0. The observation + time is always kept unchanged as it would otherwise be impossible to do the + inverse transformation. + +Temporal gridshifting is especially powerful in transformation pipelines where +several gridshifts can be chained together, effectively acting as a series of +step functions that can be applied to a coordinate that is propagated through +time. In the following example we establish a pipeline that allows transformation +of coordinates from any given epoch up until the current date, applying only +those gridshifts that have central epochs between the observation epoch and +the final epoch:: + + +proj=pipeline +t_final=now + +step +proj=vgridshift +grids=earthquake_1.gtx +t_epoch=2010.421 + +step +proj=vgridshift +grids=earthquake_2.gtx +t_epoch=2013.853 + +step +proj=vgridshift +grids=earthquake_3.gtx +t_epoch=2017.713 + +.. note:: + The special epoch *now* is used when specifying the final epoch with + :option:`+t_final`. This results in coordinates being transformed to the + current date. Additionally, :option:`+t_final` is used as a + :ref:`global pipeline parameter<global-pipeline-parameter>`, which means + that it is applied to all the steps in the pipeline. + +In the above transformation, a coordinate with observation epoch 2009.32 would +be subject to all three gridshift steps in the pipeline. A coordinate with +observation epoch 2014.12 would only by offset by the last step in the pipeline. + +Parameters +################################################################################ + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an `@` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids are expected to be in GTX format. + +Optional ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. include:: ../options/t_epoch.rst +.. versionadded:: 5.1.0 +.. include:: ../options/t_final.rst +.. versionadded:: 5.1.0 + +.. option:: +multiplier=<value> + + Specify the multiplier to apply to the grid value in the forward transformation + direction, such that: + + .. math:: + :label: multiplier_formula + + Z_{target} = Z_{source} + multiplier \times gridvalue + + The multiplier can be used to control whether the gridvalue should be added + or subtracted, and if unit conversion must be done (the multiplied gridvalue + must be expressed in metre). + + Note that the default is `-1.0` for historical reasons. +.. versionadded:: 5.2.0 diff --git a/_sources/operations/transformations/xyzgridshift.rst.txt b/_sources/operations/transformations/xyzgridshift.rst.txt new file mode 100644 index 00000000..e76b3a63 --- /dev/null +++ b/_sources/operations/transformations/xyzgridshift.rst.txt @@ -0,0 +1,93 @@ +.. _xyzgridshift: + +================================================================================ +Geocentric grid shift +================================================================================ + +.. versionadded:: 7.0.0 + +Geocentric translation using a grid shift + ++-----------------+-------------------------------------------------------------------+ +| **Alias** | xyzgridshift | ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 3D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates | ++-----------------+-------------------------------------------------------------------+ + +Perform a geocentric translation by bilinear interpolation of dx, dy, dz +translation values from a grid. The grid is referenced against either the +2D geographic CRS corresponding to the input (or sometimes output) CRS. + +This method is described (in French) in :cite:`NTF_88` +and as EPSG operation method code 9655 in :cite:`IOGP2018` (§2.4.4.1.1 +France geocentric interpolation). + +The translation in the grids are added to the input coordinates in the forward direction, +and subtracted in the reverse direction. +By default (if ``grid_ref=input_crs``), in the forward direction, the input coordinates +are converted to their geographic equivalent to directly read and interpolate from +the grid. In the reverse direction, an iterative method is used to be able to find +the grid locations to read. +If ``grid_ref=output_crs`` is used, then the reverse strategy is applied: iterative +method in the forward direction, and direct read in the reverse direction. + +Example +------------------------------------------------------------------------------- + +NTF to RGF93 transformation using :file:`gr3df97a.tif` grid + +:: + + +proj=pipeline + +step +proj=push +v_3 + +step +proj=cart +ellps=clrk80ign + +step +proj=xyzgridshift +grids=gr3df97a.tif +grid_ref=output_crs +ellps=GRS80 + +step +proj=cart +ellps=GRS80 +inv + +step +proj=pop +v_3 + +Parameters +################################################################################ + +The ellipsoid parameters should be the ones consistent with ``grid_ref``. +They are used to perform a geocentric to geographic conversion to find the +translation parameters. + + +Required ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. include:: ../options/ellps.rst + +.. option:: +grids=<list> + + Comma-separated list of grids to load. If a grid is prefixed by an ``@`` the + grid is considered optional and PROJ will the not complain if the grid is + not available. + + Grids are expected to be in GeoTIFF format. If no metadata is provided, + the first, second and third samples are assumed to be the geocentric + translation along X, Y and Z axis respectively, in metres. + +Optional ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +grid_ref=input_crs/output_crs + + Specify in which CRS the grid is referenced to. The default value is + input_crs. That is the grid is referenced in the geographic CRS corresponding + to the input geocentric CRS. + + If output_crs is specified, the grid is referenced in the geographic CRS corresponding + to the output geocentric CRS. This is for example the case for the French + :file:`gr3df97a.tif` grid converting from NTF to RGF93, but referenced against RGF93. + Thus in the forward direction (NTF->RGF93), an iterative method is used to find + the appropriate shift. + +.. option:: +multiplier=<value> + + Specify the multiplier to apply to the grid values. Defaults to 1.0 + |