From 410ad2d07515a734d04bf4c44c694fd5b548f1a2 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 22:31:55 +0100 Subject: Restructure coordinate operations docs --- .../usage/operations/conversions/axisswap.rst | 39 +++++++ docs/source/usage/operations/conversions/cart.rst | 24 +++++ docs/source/usage/operations/conversions/index.rst | 18 ++++ .../source/usage/operations/conversions/latlon.rst | 6 ++ .../source/usage/operations/conversions/lonlat.rst | 6 ++ .../usage/operations/conversions/unitconvert.rst | 112 +++++++++++++++++++++ docs/source/usage/operations/index.rst | 13 ++- docs/source/usage/operations/projections/index.rst | 7 +- .../source/usage/operations/projections/latlon.rst | 6 -- .../source/usage/operations/projections/lonlat.rst | 6 -- .../usage/operations/transformations/axisswap.rst | 39 ------- .../usage/operations/transformations/cart.rst | 24 ----- .../usage/operations/transformations/index.rst | 6 +- .../operations/transformations/unitconvert.rst | 112 --------------------- 14 files changed, 221 insertions(+), 197 deletions(-) create mode 100644 docs/source/usage/operations/conversions/axisswap.rst create mode 100644 docs/source/usage/operations/conversions/cart.rst create mode 100644 docs/source/usage/operations/conversions/index.rst create mode 100644 docs/source/usage/operations/conversions/latlon.rst create mode 100644 docs/source/usage/operations/conversions/lonlat.rst create mode 100644 docs/source/usage/operations/conversions/unitconvert.rst delete mode 100644 docs/source/usage/operations/projections/latlon.rst delete mode 100644 docs/source/usage/operations/projections/lonlat.rst delete mode 100644 docs/source/usage/operations/transformations/axisswap.rst delete mode 100644 docs/source/usage/operations/transformations/cart.rst delete mode 100644 docs/source/usage/operations/transformations/unitconvert.rst (limited to 'docs/source/usage') diff --git a/docs/source/usage/operations/conversions/axisswap.rst b/docs/source/usage/operations/conversions/axisswap.rst new file mode 100644 index 00000000..ddaad075 --- /dev/null +++ b/docs/source/usage/operations/conversions/axisswap.rst @@ -0,0 +1,39 @@ +.. _axisswap: + +================================================================================ +Axis swap +================================================================================ + +Change the order and sign of 2,3 or 4 axes. + ++--------------+---------------------------------------------------------------+ +| **Options** | ++--------------+---------------------------------------------------------------+ +| `+order` | Ordered comma-separated list of axis, e.g. `+order=2,1,3,4` | ++--------------+---------------------------------------------------------------+ + + +Each of the possible four axes are numbered with 1-4, such that the first input axis +is 1, the second is 2 and so on. The output ordering is controlled by a list of the +input axes re-ordered to the new mapping. + +Examples +################################################################################ + +Reversing the order of the axes:: + + +proj=axisswap +order=4,3,2,1 + +Swapping the first two axes (x and y):: + + +proj=axisswap +order=2,1,3,4 + +The direction, or sign, of an axis can be changed by adding a minus in +front of the axis-number:: + + +proj=axisswap +order=1,-2,3,4 + +It is only necessary to specify the axes that are affected by the swap +operation:: + + +proj=axisswap +order=2,1 diff --git a/docs/source/usage/operations/conversions/cart.rst b/docs/source/usage/operations/conversions/cart.rst new file mode 100644 index 00000000..0c3c7c23 --- /dev/null +++ b/docs/source/usage/operations/conversions/cart.rst @@ -0,0 +1,24 @@ +.. _cart: + +================================================================================ +Cartesian to geodetic conversion +================================================================================ + +Convert geodetic coordinates to cartesian coordinates. + ++--------------+--------------------------------------------------------------------+ +| **Options** | ++--------------+--------------------------------------------------------------------+ +| `+ellps` | Ellipsoid of the input coordinates. If used together with the | +| |  ellipsoid parameters below, ``+ellps`` is overwritten. | ++--------------+--------------------------------------------------------------------+ +| `+a` | Semi-major radius of ellipsoid axis. | ++--------------+--------------------------------------------------------------------+ +| `+b` | Semi-minor radius of ellipsoid axis. | ++--------------+--------------------------------------------------------------------+ +| `+es` | Eccentricity of ellipsoid. | ++--------------+--------------------------------------------------------------------+ +| `+f` | Flattening of ellipsoid. | ++--------------+--------------------------------------------------------------------+ + + diff --git a/docs/source/usage/operations/conversions/index.rst b/docs/source/usage/operations/conversions/index.rst new file mode 100644 index 00000000..54324ec4 --- /dev/null +++ b/docs/source/usage/operations/conversions/index.rst @@ -0,0 +1,18 @@ +.. _conversions_list: + +================================================================================ +Conversions +================================================================================ + +Conversions are coordinate operations in which both coordinate reference systems +are based on the same datum. In PROJ.4 projections are differentiated from +conversions. + +.. toctree:: + :maxdepth: 1 + + axisswap + cart + lonlat + latlon + unitconvert diff --git a/docs/source/usage/operations/conversions/latlon.rst b/docs/source/usage/operations/conversions/latlon.rst new file mode 100644 index 00000000..6712fa7b --- /dev/null +++ b/docs/source/usage/operations/conversions/latlon.rst @@ -0,0 +1,6 @@ +.. _latlon: + +******************************************************************************** +Lat/long (Geodetic alias) +******************************************************************************** + diff --git a/docs/source/usage/operations/conversions/lonlat.rst b/docs/source/usage/operations/conversions/lonlat.rst new file mode 100644 index 00000000..589cc813 --- /dev/null +++ b/docs/source/usage/operations/conversions/lonlat.rst @@ -0,0 +1,6 @@ +.. _lonlat: + +******************************************************************************** +Lat/long (Geodetic) +******************************************************************************** + diff --git a/docs/source/usage/operations/conversions/unitconvert.rst b/docs/source/usage/operations/conversions/unitconvert.rst new file mode 100644 index 00000000..ad848207 --- /dev/null +++ b/docs/source/usage/operations/conversions/unitconvert.rst @@ -0,0 +1,112 @@ +.. _unitconvert: + +================================================================================ +Unit conversion +================================================================================ + +Convert between various distance and time units. + ++--------------+--------------------------------------------------------------------+ +| **Options** | ++--------------+--------------------------------------------------------------------+ +| `+xy_in` | Input unit of the horizontal components. | ++--------------+--------------------------------------------------------------------+ +| `+xy_out` | Output unit of the horizontal components. | ++--------------+--------------------------------------------------------------------+ +| `+z_in` | Input unit of the vertical component. | ++--------------+--------------------------------------------------------------------+ +| `+z_out` | Output unit of the vertical component. | ++--------------+--------------------------------------------------------------------+ +| `+t_in` | Input unit of the time component. | ++--------------+--------------------------------------------------------------------+ +| `+t_out` | Output unit of the time component. | ++--------------+--------------------------------------------------------------------+ + +There are many examples of coordinate reference systems that are expressed in +other units than the meter. There are also many cases where temporal data +has to be translated to different units. The `unitconvert` operation takes care +of that. + +Many North American systems are defined with coordinates in feet. For example +in Vermont:: + + +proj=pipeline + +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k=0.999964286 +x_0=500000.00001016 +y_0=0 + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +Often when working with GNNS data the timestamps are presented in GPS-weeks, +but when the data transformed with the `helmert` operation timestamps are +expected to be in units of decimalyears. This can be fixed with `unitconvert`:: + + +proj=pipeline + +step +proj=unitconvert +t_in=gpsweek +t_out=decimalyear + +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ... + + +Distance units +############################################################################### + +In the table below all distance units supported by PROJ.4 is listed. +The same list can also be produced on the command line with `proj` or `cs2cs`, +by adding the `-lu` flag when calling the utility. + ++----------+---------------------------------+ +| Label | Name | ++----------+---------------------------------+ +| km | Kilometer | ++----------+---------------------------------+ +| m | Meter | ++----------+---------------------------------+ +| dm | Decimeter | ++----------+---------------------------------+ +| cm | Centimeter | ++----------+---------------------------------+ +| mm | Millimeter | ++----------+---------------------------------+ +| kmi | International Nautical Mile | ++----------+---------------------------------+ +| in | International Inch | ++----------+---------------------------------+ +| ft | International Foot | ++----------+---------------------------------+ +| yd | International Yard | ++----------+---------------------------------+ +| mi | International Statute Mile | ++----------+---------------------------------+ +| fath | International Fathom | ++----------+---------------------------------+ +| ch | International Chain | ++----------+---------------------------------+ +| link | International Link | ++----------+---------------------------------+ +| us-in | U.S. Surveyor's Inch | ++----------+---------------------------------+ +| us-ft | U.S. Surveyor's Foot | ++----------+---------------------------------+ +| us-yd | U.S. Surveyor's Yard | ++----------+---------------------------------+ +| us-ch | U.S. Surveyor's Chain | ++----------+---------------------------------+ +| us-mi | U.S. Surveyor's Statute Mile | ++----------+---------------------------------+ +| ind-yd | Indian Yard | ++----------+---------------------------------+ +| ind-ft | Indian Foot | ++----------+---------------------------------+ +| ind-ch | Indian Chain | ++----------+---------------------------------+ + + +Time units +############################################################################### + +In the table below all time units supported by PROJ.4 is listed. + ++--------------+-----------------------------+ +| mjd | Modfied Julian date | ++--------------+-----------------------------+ +| decimalyear | Decimal year | ++--------------+-----------------------------+ +| gps_week | GPS Week | ++--------------+-----------------------------+ + diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst index 21200c93..baae0e0a 100644 --- a/docs/source/usage/operations/index.rst +++ b/docs/source/usage/operations/index.rst @@ -4,15 +4,18 @@ Coordinate operations ================================================================================ -Coordinate operations in PROJ.4 are divided into two groups: -Projections and transformations. -Projections are purely cartographic mappings of the sphere onto the plane whereas -transformations are mostly geodetic operations concerned with changes in -reference frames. +Coordinate operations in PROJ.4 are divided into three groups: +Projections, conversions and transformations. +Projections are purely cartographic mappings of the sphere onto the plane. +Technically projections are conversions (according to ISO standards), though in +PROJ.4 projections are distinguished from conversions. Conversions are coordinate +operations that do not exert a change in reference frame. Operations that do +exert a change in reference frame are called transformations. .. toctree:: :maxdepth: 1 projections/index + conversions/index transformations/index diff --git a/docs/source/usage/operations/projections/index.rst b/docs/source/usage/operations/projections/index.rst index 5ccf0045..f7eb0c67 100644 --- a/docs/source/usage/operations/projections/index.rst +++ b/docs/source/usage/operations/projections/index.rst @@ -4,6 +4,11 @@ Projections ================================================================================ +Projections are coordinate operations that are technically conversions but since +projections are so fundamental to PROJ.4 we differentiate them from conversions. + +Projections map the spherical 3D space to a flat 2D space. + .. toctree:: :maxdepth: 1 @@ -62,8 +67,6 @@ Projections lagrng larr lask - lonlat - latlon lcc lcca leac diff --git a/docs/source/usage/operations/projections/latlon.rst b/docs/source/usage/operations/projections/latlon.rst deleted file mode 100644 index 6712fa7b..00000000 --- a/docs/source/usage/operations/projections/latlon.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _latlon: - -******************************************************************************** -Lat/long (Geodetic alias) -******************************************************************************** - diff --git a/docs/source/usage/operations/projections/lonlat.rst b/docs/source/usage/operations/projections/lonlat.rst deleted file mode 100644 index 589cc813..00000000 --- a/docs/source/usage/operations/projections/lonlat.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _lonlat: - -******************************************************************************** -Lat/long (Geodetic) -******************************************************************************** - diff --git a/docs/source/usage/operations/transformations/axisswap.rst b/docs/source/usage/operations/transformations/axisswap.rst deleted file mode 100644 index ddaad075..00000000 --- a/docs/source/usage/operations/transformations/axisswap.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _axisswap: - -================================================================================ -Axis swap -================================================================================ - -Change the order and sign of 2,3 or 4 axes. - -+--------------+---------------------------------------------------------------+ -| **Options** | -+--------------+---------------------------------------------------------------+ -| `+order` | Ordered comma-separated list of axis, e.g. `+order=2,1,3,4` | -+--------------+---------------------------------------------------------------+ - - -Each of the possible four axes are numbered with 1-4, such that the first input axis -is 1, the second is 2 and so on. The output ordering is controlled by a list of the -input axes re-ordered to the new mapping. - -Examples -################################################################################ - -Reversing the order of the axes:: - - +proj=axisswap +order=4,3,2,1 - -Swapping the first two axes (x and y):: - - +proj=axisswap +order=2,1,3,4 - -The direction, or sign, of an axis can be changed by adding a minus in -front of the axis-number:: - - +proj=axisswap +order=1,-2,3,4 - -It is only necessary to specify the axes that are affected by the swap -operation:: - - +proj=axisswap +order=2,1 diff --git a/docs/source/usage/operations/transformations/cart.rst b/docs/source/usage/operations/transformations/cart.rst deleted file mode 100644 index 0c3c7c23..00000000 --- a/docs/source/usage/operations/transformations/cart.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _cart: - -================================================================================ -Cartesian to geodetic conversion -================================================================================ - -Convert geodetic coordinates to cartesian coordinates. - -+--------------+--------------------------------------------------------------------+ -| **Options** | -+--------------+--------------------------------------------------------------------+ -| `+ellps` | Ellipsoid of the input coordinates. If used together with the | -| |  ellipsoid parameters below, ``+ellps`` is overwritten. | -+--------------+--------------------------------------------------------------------+ -| `+a` | Semi-major radius of ellipsoid axis. | -+--------------+--------------------------------------------------------------------+ -| `+b` | Semi-minor radius of ellipsoid axis. | -+--------------+--------------------------------------------------------------------+ -| `+es` | Eccentricity of ellipsoid. | -+--------------+--------------------------------------------------------------------+ -| `+f` | Flattening of ellipsoid. | -+--------------+--------------------------------------------------------------------+ - - diff --git a/docs/source/usage/operations/transformations/index.rst b/docs/source/usage/operations/transformations/index.rst index 2966ed0d..112d9220 100644 --- a/docs/source/usage/operations/transformations/index.rst +++ b/docs/source/usage/operations/transformations/index.rst @@ -4,13 +4,13 @@ Transformations ================================================================================ +Transformations coordinate operation in which the two coordinate reference +systems are based on different datums. + .. toctree:: :maxdepth: 1 - axisswap - cart helmert molodensky hgridshift vgridshift - unitconvert diff --git a/docs/source/usage/operations/transformations/unitconvert.rst b/docs/source/usage/operations/transformations/unitconvert.rst deleted file mode 100644 index ad848207..00000000 --- a/docs/source/usage/operations/transformations/unitconvert.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _unitconvert: - -================================================================================ -Unit conversion -================================================================================ - -Convert between various distance and time units. - -+--------------+--------------------------------------------------------------------+ -| **Options** | -+--------------+--------------------------------------------------------------------+ -| `+xy_in` | Input unit of the horizontal components. | -+--------------+--------------------------------------------------------------------+ -| `+xy_out` | Output unit of the horizontal components. | -+--------------+--------------------------------------------------------------------+ -| `+z_in` | Input unit of the vertical component. | -+--------------+--------------------------------------------------------------------+ -| `+z_out` | Output unit of the vertical component. | -+--------------+--------------------------------------------------------------------+ -| `+t_in` | Input unit of the time component. | -+--------------+--------------------------------------------------------------------+ -| `+t_out` | Output unit of the time component. | -+--------------+--------------------------------------------------------------------+ - -There are many examples of coordinate reference systems that are expressed in -other units than the meter. There are also many cases where temporal data -has to be translated to different units. The `unitconvert` operation takes care -of that. - -Many North American systems are defined with coordinates in feet. For example -in Vermont:: - - +proj=pipeline - +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k=0.999964286 +x_0=500000.00001016 +y_0=0 - +step +proj=unitconvert +xy_in=m +xy_out=us-ft - -Often when working with GNNS data the timestamps are presented in GPS-weeks, -but when the data transformed with the `helmert` operation timestamps are -expected to be in units of decimalyears. This can be fixed with `unitconvert`:: - - +proj=pipeline - +step +proj=unitconvert +t_in=gpsweek +t_out=decimalyear - +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ... - - -Distance units -############################################################################### - -In the table below all distance units supported by PROJ.4 is listed. -The same list can also be produced on the command line with `proj` or `cs2cs`, -by adding the `-lu` flag when calling the utility. - -+----------+---------------------------------+ -| Label | Name | -+----------+---------------------------------+ -| km | Kilometer | -+----------+---------------------------------+ -| m | Meter | -+----------+---------------------------------+ -| dm | Decimeter | -+----------+---------------------------------+ -| cm | Centimeter | -+----------+---------------------------------+ -| mm | Millimeter | -+----------+---------------------------------+ -| kmi | International Nautical Mile | -+----------+---------------------------------+ -| in | International Inch | -+----------+---------------------------------+ -| ft | International Foot | -+----------+---------------------------------+ -| yd | International Yard | -+----------+---------------------------------+ -| mi | International Statute Mile | -+----------+---------------------------------+ -| fath | International Fathom | -+----------+---------------------------------+ -| ch | International Chain | -+----------+---------------------------------+ -| link | International Link | -+----------+---------------------------------+ -| us-in | U.S. Surveyor's Inch | -+----------+---------------------------------+ -| us-ft | U.S. Surveyor's Foot | -+----------+---------------------------------+ -| us-yd | U.S. Surveyor's Yard | -+----------+---------------------------------+ -| us-ch | U.S. Surveyor's Chain | -+----------+---------------------------------+ -| us-mi | U.S. Surveyor's Statute Mile | -+----------+---------------------------------+ -| ind-yd | Indian Yard | -+----------+---------------------------------+ -| ind-ft | Indian Foot | -+----------+---------------------------------+ -| ind-ch | Indian Chain | -+----------+---------------------------------+ - - -Time units -############################################################################### - -In the table below all time units supported by PROJ.4 is listed. - -+--------------+-----------------------------+ -| mjd | Modfied Julian date | -+--------------+-----------------------------+ -| decimalyear | Decimal year | -+--------------+-----------------------------+ -| gps_week | GPS Week | -+--------------+-----------------------------+ - -- cgit v1.2.3