diff options
Diffstat (limited to 'docs/source/usage')
294 files changed, 5125 insertions, 0 deletions
diff --git a/docs/source/usage/apps/cs2cs.rst b/docs/source/usage/apps/cs2cs.rst new file mode 100644 index 00000000..675379ef --- /dev/null +++ b/docs/source/usage/apps/cs2cs.rst @@ -0,0 +1,143 @@ +.. _cs2cs: + +================================================================================ +cs2cs +================================================================================ + + +``cs2cs`` performs transformation between the source and destination cartographic coordinate system +on a set of input points. The coordinate system transformation can include translation between +projected and geographic coordinates as well as the application of datum shifts. + + +Synopsis +******** + +:: + + cs2cs [ -eEfIlrstvwW [ args ] ] [ +opts[=arg] ] [ +to [+opts[=arg]] ] file[s] + +Description +*********** +The following control parameters can appear in any order: + +:: + + -I method to specify inverse translation, convert from +to coordinate system to the + primary coordinate system defined. + + -ta A specifies a character employed as the first character to denote a control line + to be passed through without processing. This option applicable to ascii input + only. (# is the default value). + + -e string + String is an arbitrary string to be output if an error is detected during data + transformations. The default value is: *\t*. Note that if the -b, -i or -o + options are employed, an error is returned as HUGE_VAL value for both + return values. + + -E causes the input coordinates to be copied to the output line prior to printing the + converted values. + + -l[p|P|=|e|u|d]id + List projection identifiers with -l, -lp or -lP (expanded) that can be selected + with +proj. -l=id gives expanded description of projection id. List + ellipsoid identifiers with -le, that can be selected with +ellps,-lu list of + cartesian to meter conversion factors that can be selected with +units or -ld + list of datums that can be selected with +datum. + + -r This options reverses the order of the expected input from longitude-latitude or + x-y to latitude-longitude or y-x. + + -s This options reverses the order of the output from x-y or longitude-latitude to + y-x or latitude-longitude. + + -f format + Format is a printf format string to control the form of the output values. For + inverse projections, the output will be in degrees when this option is employed. + If a format is specified for inverse projection the output data will be in deci- + mal degrees. The default format is "%.2f" for forward projection and DMS for + inverse. + + -[w|W]n + N is the number of significant fractional digits to employ for seconds output (when + the option is not specified, -w3 is assumed). When -W is employed the fields + will be constant width and with leading zeroes. + + -v causes a listing of cartographic control parameters tested for and used by the + program to be printed prior to input data. + +The ``+args`` run-line arguments are associated with cartographic parameters. Usage varies with +projection and for a complete description consult the `projection pages <../projections/index.html>`_ + +The cs2cs program requires two coordinate system +definitions. The first (or primary is defined +based on all projection parameters not appearing +after the +to argument. All projection parameters +appearing after the ``+to`` argument are considered +the definition of the second coordinate +system. If there is no second coordinate system +defined, a geographic coordinate system based on +the datum and ellipsoid of the source coordinate +system is assumed. Note that the source and +destination coordinate system can both be projections, +both be geographic, or one of each and +may have the same or different datums. + +Additional projection control parameters may be +contained in two auxiliary control files: the +first is optionally referenced with the +``+init=file:id`` and the second is always processed +after the name of the projection has been established +from either the run-line or the contents +of ``+init`` file. The environment parameter +PROJ_LIB establishes the default directory for a +file reference without an absolute path. This +is also used for supporting files like datum +shift files. + +One or more files (processed in left to right +order) specify the source of data to be transformed. +A - will specify the location of processing standard input. +If no files are specified, the input is assumed to be from stdin. +For input data the two data values must be in +the first two white space separated fields and +when both input and output are ASCII all trailing +portions of the input line are appended to +the output line. + +Input geographic data (longitude and latitude) +must be in DMS or decimal degrees format and +input cartesian data must be in units consistent +with the ellipsoid major axis or sphere radius +units. Output geographic coordinates will normally +be in DMS format (use ``-f %.12f`` for decimal +degrees with 12 decimal places), while projected +(cartesian) coordinates will be in linear +(meter, feet) units. + + +Example +******* +The following script + +:: + + cs2cs +proj=latlong +datum=NAD83 + +to +proj=utm +zone=10 +datum=NAD27 + -r <<EOF + 45d15'33.1" 111.5W + 45d15.551666667N -111d30 + +45.25919444444 111d30'000w + EOF + +will transform the input NAD83 geographic coordinates into NAD27 +coordinates in the UTM projection with zone 10 selected. The geographic +values of this example are equivalent and meant as examples of various forms of DMS input. +The x-y output data will appear as three lines of: + +:: + + 1402285.99 5076292.42 0.000 + + diff --git a/docs/source/usage/apps/geod.rst b/docs/source/usage/apps/geod.rst new file mode 100644 index 00000000..e7056121 --- /dev/null +++ b/docs/source/usage/apps/geod.rst @@ -0,0 +1,168 @@ +.. _geod: + +================================================================================ +geod +================================================================================ + +``geod`` (direct) and ``invgeod`` (inverse) perform geodesic ("Great +Circle") computations for determining latitude, longitude and +back azimuth of a terminus point given a initial point latitude, +longitude, azimuth and distance (direct) or the forward +and back azimuths and distance between an initial and terminus +point latitudes and longitudes (inverse). The results are +accurate to round off for :math:`|f| < 1/50`, where f is flattening. + + +``invgeod`` may not be available on all platforms; in this case +call geod with the -I option. + + + +Synopsis +******** + +:: + + geod +ellps=<ellipse> [ -afFIlptwW [ args ] ] [ +args ] file[s] + + invgeod +ellps=<ellipse> [ -afFIlptwW [ args ] ] [ +args ] file[s] + +Description +*********** +The following command-line options can appear in any order: + +:: + + -I Specifies that the inverse geodesic computation is to be + performed. May be used with execution of geod as an + alternative to invgeod execution. + + -a Latitude and longitudes of the initial and terminal + points, forward and back azimuths and distance are output. + + -ta A specifies a character employed as the first character + to denote a control line to be passed through without + processing. + + -le Gives a listing of all the ellipsoids that may be + selected with the +ellps= option. + + -lu Gives a listing of all the units that may be selected + with the +units= option. + + -[f|F] format + Format is a printf format string to control the output + form of the geographic coordinate values (f) or distance + value (F). The default mode is DMS for geographic + coordinates and "%.3f" for distance. + + -[w|W]n + N is the number of significant fractional digits to + employ for seconds output (when the option is not + specified, -w3 is assumed). When -W is employed the fields + will be constant width with leading zeroes. + + -p This option causes the azimuthal values to be output as + unsigned DMS numbers between 0 and 360 degrees. Also + note -f. + +The ``+args`` command-line options are associated with geodetic +parameters for specifying the ellipsoidal or sphere to use. +See ``proj`` `documentation <proj.html>`_ for full list of these parameters and +controls. The options are processed in left to right order +from the command line. Reentry of an option is ignored with +the first occurrence assumed to be the desired value. + +One or more files (processed in left to right order) specify +the source of data to be transformed. A - will specify the +location of processing standard input. If no files are specified, +the input is assumed to be from stdin. + +For direct determinations input data must be in latitude, longitude, +azimuth and distance order and output will be latitude, +longitude and back azimuth of the terminus point. Latitude, +longitude of the initial and terminus point are input for the +inverse mode and respective forward and back azimuth from the +initial and terminus points are output along with the distance +between the points. + +Input geographic coordinates (latitude and longitude) and +azimuthal data must be in decimal degrees or DMS format and +input distance data must be in units consistent with the ellipsoid +major axis or sphere radius units. The latitude must lie +in the range [-90d,90d]. Output geographic coordinates will be +in DMS (if the -f switch is not employed) to 0.001" with trailing, +zero-valued minute-second fields deleted. Output distance +data will be in the same units as the ellipsoid or sphere +radius. + +The Earth's ellipsoidal figure may be selected in the same manner +as program ``proj`` by using ``+ellps=``, ``+a=``, ``+es=``, etc. + +Geod may also be used to determine intermediate points along +either a geodesic line between two points or along an arc of +specified distance from a geographic point. In both cases an +initial point must be specified with ``+lat_1=lat`` and ``+lon_1=lon`` +parameters and either a terminus point ``+lat_2=lat`` and +``+lon_2=lon`` or a distance and azimuth from the initial point +with ``+S=distance`` and ``+A=azimuth`` must be specified. + +If points along a geodesic are to be determined then either +``+n_S=integer`` specifying the number of intermediate points +and/or ``+del_S=distance`` specifying the incremental distance +between points must be specified. + +To determine points along an arc equidistant from the initial +point both ``+del_A=angle`` and ``+n_A=integer`` must be specified +which determine the respective angular increments and number of +points to be determined. + +Examples +******** + +The following script determines the geodesic azimuths and distance in U.S. +statute miles from Boston, MA, to Portland, OR: + +:: + + geod +ellps=clrk66 <<EOF -I +units=us-mi + 42d15'N 71d07'W 45d31'N 123d41'W + EOF + +which gives the results: + +:: + + -66d31'50.141" 75d39'13.083" 2587.504 + +where the first two values are the azimuth from Boston to Portland, +the back azimuth from Portland to Boston followed by the distance. + +An example of forward geodesic use is to use the Boston location +and determine Portland's location by azimuth and distance: + +:: + + geod +ellps=clrk66 <<EOF +units=us-mi + 42d15'N 71d07'W -66d31'50.141" 2587.504 + EOF + +which gives: + +:: + + 45d31'0.003"N 123d40'59.985"W 75d39'13.094" + +.. note:: + Lack of precision in the distance value compromises the + precision of the Portland location. + +Further reading +*************** + +#. `GeographicLib <https://geographiclib.sourceforge.io>`_. + +#. C. F. F. Karney, `Algorithms for Geodesics <https://doi.org/10.1007/s00190-012-0578-z>`_, J. Geodesy **87**\ (1), 43–55 (2013); + `addenda <https://geographiclib.sourceforge.io/geod-addenda.html>`_. + +#. `A geodesic bibliography <https://geographiclib.sourceforge.io/geodesic-papers/biblio.html>`_. diff --git a/docs/source/usage/apps/index.rst b/docs/source/usage/apps/index.rst new file mode 100644 index 00000000..0d818682 --- /dev/null +++ b/docs/source/usage/apps/index.rst @@ -0,0 +1,20 @@ +.. _apps: + +================================================================================ +Applications +================================================================================ + +Bundled with PROJ comes a set of small command line utilities. The +``proj`` program is limited to converting between geographic and projection +coordinates within one datum. The ``cs2cs`` program operates similarly, but +allows translation between any pair of definable coordinate systems, including +support for basic datum translation. The ``geod`` program provides the ability +to do geodesic (great circle) computations. + +.. toctree:: + :maxdepth: 1 + + proj + cs2cs + geod + diff --git a/docs/source/usage/apps/proj.rst b/docs/source/usage/apps/proj.rst new file mode 100644 index 00000000..6227047f --- /dev/null +++ b/docs/source/usage/apps/proj.rst @@ -0,0 +1,164 @@ +.. _proj: + +================================================================================ +proj +================================================================================ + + +.. Index:: proj + +``proj`` and ``invproj`` perform respective forward and inverse transformation of cartographic data to +or from cartesian data with a wide range of selectable projection functions. + + +Synopsis +******** +:: + + proj [ -bcCeEfiIlmorsStTvVwW [ args ] ] [ +args ] file[s] + invproj [ -bcCeEfiIlmorsStTwW [ args ] ] [ +args ] file[s] + + +Description +*********** +The following control parameters can appear in any order + +:: + + -b Special option for binary coordinate data input and output through standard input + and standard output. Data is assumed to be in system type double floating point + words. This option is to be used when proj is a son process and allows bypassing + formatting operations. + + -i Selects binary input only (see -b option). + + -C Check. Invoke all built in self tests and report. Get more verbose report by + preceding with the -V option). + + -I alternate method to specify inverse projection. Redundant when used with invproj. + + -o Selects binary output only (see -b option). + + -ta A specifies a character employed as the first character to denote a control line + to be passed through without processing. This option applicable to ascii input + only. (# is the default value). + + -e string + String is an arbitrary string to be output if an error is detected during data + transformations. The default value is: *\t*. Note that if the -b, -i or -o + options are employed, an error is returned as HUGE_VAL value for both return values. + + -E causes the input coordinates to be copied to the output line prior to printing the + converted values. + + + -l[p|P|=|e|u|d]id + List projection identifiers with -l, -lp or -lP (expanded) that can be selected + with +proj. -l=id gives expanded description of projection id. List + ellipsoid identifiers with -le, that can be selected with +ellps, -lu list of + cartesian to meter conversion factors that can be selected with +units or -ld + list of datums that can be selected with +datum. + + -r This options reverses the order of the expected input from longitude-latitude or + x-y to latitude-longitude or y-x. + + -s This options reverses the order of the output from x-y or longitude-latitude to + y-x or latitude-longitude. + + -S Causes estimation of meridional and parallel scale factors, area scale factor and + angular distortion, and maximum and minimum scale factors to be listed between <> + for each input point. For conformal projections meridional and parallel scales + factors will be equal and angular distortion zero. Equal area projections will + have an area factor of 1. + + -m mult + The cartesian data may be scaled by the mult parameter. When processing data in + a forward projection mode the cartesian output values are multiplied by mult + otherwise the input cartesian values are divided by mult before inverse projection. + If the first two characters of mult are 1/ or 1: then the reciprocal value of mult + is employed. + + -f format + Format is a printf format string to control the form of the output values. For + inverse projections, the output will be in degrees when this option is employed. + The default format is "%.2f" for forward projection and DMS for inverse. + + -[w|W]n + N is the number of significant fractional digits to employ for seconds output (when + the option is not specified, -w3 is assumed). When -W is employed the fields + will be constant width and with leading zeroes. + + -v causes a listing of cartographic control parameters tested for and used by the + program to be printed prior to input data. Should not be used with the -T + option. + + -V This option causes an expanded annotated listing of the characteristics of the + projected point. -v is implied with this option. + + -T ulow,uhi,vlow,vhi,res[,umax,vmax] + This option creates a set of bivariate Chebyshev polynomial coefficients that + approximate the selected cartographic projection on stdout. The values low and + hi denote the range of the input where the u or v prefixes apply to respective + longitude-x or latitude-y depending upon whether a forward or inverse projection + is selected. Res is an integer number specifying the power of 10 precision of + the approximation. For example, a res of -3 specifies an approximation with an + accuracy better than .001. Umax, and vmax specify maximum degree of the polynomials + (default: 15). + + +The ``+args`` run-line arguments are associated with cartographic parameters. Usage varies with +projection and for a complete description consult the `projection pages <../projections/index.html>`_ + +Additional projection control parameters may be +contained in two auxiliary control files: the +first is optionally referenced with the +``+init=file:id`` and the second is always processed +after the name of the projection has been established +from either the run-line or the contents +of +init file. The environment parameter +``PROJ_LIB`` establishes the default directory for a +file reference without an absolute path. This +is also used for supporting files like datum +shift files. + +One or more files (processed in left to right +order) specify the source of data to be transformed. +A - will specify the location of processing +standard input. If no files are specified, +the input is assumed to be from stdin. +For ASCII input data the two data values must be +in the first two white space separated fields +and when both input and output are ASCII all +trailing portions of the input line are appended +to the output line. + +Input geographic data (longitude and latitude) +must be in DMS format and input cartesian data +must be in units consistent with the ellipsoid +major axis or sphere radius units. Output +geographic coordinates will be in DMS (if the -w +switch is not employed) and precise to 0.001" +with trailing, zero-valued minute-second fields +deleted. + +Example +******* +The following script + +:: + + proj +proj=utm +lon_0=112w +ellps=clrk66 + -r <<EOF + 45d15'33.1" 111.5W + 45d15.551666667N -111d30 + +45.25919444444 111d30'000w + EOF + +will perform UTM forward projection with a standard +UTM central meridian nearest longitude +112W. The geographic values of this example are +equivalent and meant as examples of various +forms of DMS input. The x-y output data will +appear as three lines of:: + + 460769.27 5011648.45 diff --git a/docs/source/usage/environmentvars.rst b/docs/source/usage/environmentvars.rst new file mode 100644 index 00000000..0d5d06a8 --- /dev/null +++ b/docs/source/usage/environmentvars.rst @@ -0,0 +1,43 @@ +.. _environmentvars: + +================================================================================ +Environment variables +================================================================================ + +PROJ can be crontrolled by setting environment variables. Most users will +have a use for the :envvar:`PROJ_LIB`. + +On UNIX systems environment variables can be set for a shell-session with:: + + $ export VAR="some variable" + +or it can be set for just one command line call:: + + $ VAR="some variable" ./cmd + +Environment variables on UNIX are usually removed with the ``unset`` command:: + + $ unset VAR + +On windows systems environment variables can be set in the command line with:: + + > set VAR="some variable" + +```VAR`` will be available for the entire session, unless it is unset. This is +done by setting the variable with no content:: + + > set VAR= + +.. envvar:: PROJ_LIB + + The location of PROJ :doc:`resource files<resource_files>`. + It is only possible to specify a single library in :envvar:`PROJ_LIB`; e.g. it + does not behave like PATH. PROJ is hardcoded to look for resource files + in other locations as well, amongst those are the users home directory, + ``/usr/share/proj`` and the current folder. + +.. envvar:: PROJ_DEBUG + + Set the debug level of PROJ. The default debug level is zero, which results + in no debug output when using PROJ. A number from 1-3, whit 3 being the most + verbose setting. diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst new file mode 100644 index 00000000..d59296d0 --- /dev/null +++ b/docs/source/usage/index.rst @@ -0,0 +1,22 @@ +.. _usage: + +================================================================================ +Using PROJ +================================================================================ + +The main purpose of PROJ is to transform coordinates from one coordinate +reference system to another. This can be achieved either with the included +command line applications or the C API that is a part of the software package. + + +.. toctree:: + :maxdepth: 1 + + quickstart + apps/index + projections + transformation + resource_files + environmentvars + operations/index + diff --git a/docs/source/usage/operations/conversions/axisswap.rst b/docs/source/usage/operations/conversions/axisswap.rst new file mode 100644 index 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..af27e2fd --- /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 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..73e517bd --- /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 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 is listed. + ++--------------+-----------------------------+ +| mjd | Modfied Julian date | ++--------------+-----------------------------+ +| decimalyear | Decimal year | ++--------------+-----------------------------+ +| gps_week | GPS Week | ++--------------+-----------------------------+ + diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst new file mode 100644 index 00000000..87bfdc40 --- /dev/null +++ b/docs/source/usage/operations/index.rst @@ -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 + diff --git a/docs/source/usage/operations/pipeline.rst b/docs/source/usage/operations/pipeline.rst new file mode 100644 index 00000000..18637712 --- /dev/null +++ b/docs/source/usage/operations/pipeline.rst @@ -0,0 +1,98 @@ +.. _pipeline: + +================================================================================ +The pipeline operator +================================================================================ + +Construct complex operations by daisy-chaining operations in a sequential pipeline. + ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Any. | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Any. | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `step` | Separate each step in a pipeline. | ++-----------------+--------------------------------------------------------------------+ +| `inv` | Invert a step in a pipeline. | ++-----------------+--------------------------------------------------------------------+ + +.. 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 occurence of `+step`. This means that the GRS80 ellipsoid is used +in both steps, since any parameter stated before the first occurence 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. + +**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 + + diff --git a/docs/source/usage/operations/projections/aeqd.rst b/docs/source/usage/operations/projections/aeqd.rst new file mode 100644 index 00000000..32165e49 --- /dev/null +++ b/docs/source/usage/operations/projections/aeqd.rst @@ -0,0 +1,22 @@ +.. _aeqd: + +******************************************************************************** +Azimuthal Equidistant +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+guam` | Use Guam elliptical formulas. Defaults to false. | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/aeqd.png + :scale: 50% + :alt: Azimuthal Equidistant + diff --git a/docs/source/usage/operations/projections/airy.rst b/docs/source/usage/operations/projections/airy.rst new file mode 100644 index 00000000..d2730592 --- /dev/null +++ b/docs/source/usage/operations/projections/airy.rst @@ -0,0 +1,26 @@ +.. _airy: + +******************************************************************************** +Airy +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_b` | | ++---------------------+----------------------------------------------------------+ +| `+no_cut` | Do not cut at hemisphere limit | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/airy.png + :scale: 50% + :alt: Airy + diff --git a/docs/source/usage/operations/projections/aitoff.rst b/docs/source/usage/operations/projections/aitoff.rst new file mode 100644 index 00000000..4d681468 --- /dev/null +++ b/docs/source/usage/operations/projections/aitoff.rst @@ -0,0 +1,10 @@ +.. _aitoff: + +******************************************************************************** +Aitoff +******************************************************************************** + +.. image:: ./images/aitoff.png + :scale: 50% + :alt: Aitoff + diff --git a/docs/source/usage/operations/projections/alsk.rst b/docs/source/usage/operations/projections/alsk.rst new file mode 100644 index 00000000..f7a7a0ef --- /dev/null +++ b/docs/source/usage/operations/projections/alsk.rst @@ -0,0 +1,10 @@ +.. _alsk: + +******************************************************************************** +Mod. Stererographics of Alaska +******************************************************************************** + +.. image:: ./images/alsk.png + :scale: 50% + :alt: Mod. Stererographics of Alaska + diff --git a/docs/source/usage/operations/projections/apian.rst b/docs/source/usage/operations/projections/apian.rst new file mode 100644 index 00000000..add501ea --- /dev/null +++ b/docs/source/usage/operations/projections/apian.rst @@ -0,0 +1,10 @@ +.. _apian: + +******************************************************************************** +Apian Globular I +******************************************************************************** + +.. image:: ./images/apian.png + :scale: 50% + :alt: Apian Globular I + diff --git a/docs/source/usage/operations/projections/august.rst b/docs/source/usage/operations/projections/august.rst new file mode 100644 index 00000000..e2ad3516 --- /dev/null +++ b/docs/source/usage/operations/projections/august.rst @@ -0,0 +1,10 @@ +.. _august: + +******************************************************************************** +August Epicycloidal +******************************************************************************** + +.. image:: ./images/august.png + :scale: 50% + :alt: August Epicycloidal + diff --git a/docs/source/usage/operations/projections/bacon.rst b/docs/source/usage/operations/projections/bacon.rst new file mode 100644 index 00000000..a87ea7d8 --- /dev/null +++ b/docs/source/usage/operations/projections/bacon.rst @@ -0,0 +1,10 @@ +.. _bacon: + +******************************************************************************** +Bacon Globular +******************************************************************************** + +.. image:: ./images/bacon.png + :scale: 50% + :alt: Bacon Globular + diff --git a/docs/source/usage/operations/projections/bipc.rst b/docs/source/usage/operations/projections/bipc.rst new file mode 100644 index 00000000..7045f04a --- /dev/null +++ b/docs/source/usage/operations/projections/bipc.rst @@ -0,0 +1,10 @@ +.. _bipc: + +******************************************************************************** +Bipolar conic of western hemisphere +******************************************************************************** + +.. image:: ./images/bipc.png + :scale: 50% + :alt: Bipolar conic of western hemisphere + diff --git a/docs/source/usage/operations/projections/boggs.rst b/docs/source/usage/operations/projections/boggs.rst new file mode 100644 index 00000000..1dd7d19f --- /dev/null +++ b/docs/source/usage/operations/projections/boggs.rst @@ -0,0 +1,10 @@ +.. _boggs: + +******************************************************************************** +Boggs Eumorphic +******************************************************************************** + +.. image:: ./images/boggs.png + :scale: 50% + :alt: Boggs Eumorphic + diff --git a/docs/source/usage/operations/projections/bonne.rst b/docs/source/usage/operations/projections/bonne.rst new file mode 100644 index 00000000..ef87d7c9 --- /dev/null +++ b/docs/source/usage/operations/projections/bonne.rst @@ -0,0 +1,10 @@ +.. _bonne: + +******************************************************************************** +Bonne (Werner lat_1=90) +******************************************************************************** + +.. image:: ./images/bonne.png + :scale: 50% + :alt: Bonne (Werner lat_1=90) + diff --git a/docs/source/usage/operations/projections/calcofi.rst b/docs/source/usage/operations/projections/calcofi.rst new file mode 100644 index 00000000..650416c1 --- /dev/null +++ b/docs/source/usage/operations/projections/calcofi.rst @@ -0,0 +1,95 @@ +.. _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 elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Only valid for the west coast of USA and Mexico | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Frank Warmerdam | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `No special options for this projection` | ++---------------------+----------------------------------------------------------+ + + +.. image:: ../../../../images/calcofi.png + :scale: 50% + :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 + +Mathematical definition +################################################################################ + +The algorithm used to make conversions is described in [EberHewitt1979]_ with +a few corrections reported in [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/docs/source/usage/operations/projections/cass.rst b/docs/source/usage/operations/projections/cass.rst new file mode 100644 index 00000000..4111a2ee --- /dev/null +++ b/docs/source/usage/operations/projections/cass.rst @@ -0,0 +1,145 @@ +.. _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 Elliptical | ++---------------------+-------------------------------------------------------------------------+ +| **Defined area** | Global, but best used near the central meridian with long, narrow areas | ++---------------------+-------------------------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+-------------------------------------------------------------------------+ +| **Options** | ++---------------------+-------------------------------------------------------------------------+ +| `+lat_0` | Latitude of origin (Default to 0) | ++---------------------+-------------------------------------------------------------------------+ + +.. image:: ./images/cass.png + :scale: 50% + :alt: Cassini + +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 [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 +no_defs + 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 +datum=potsdam +units=m +no_defs + 31343.05 7932.76 + + +Mathematical definition +####################### + +The formulas describing the Cassini projection are taken from Snyder's [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)) + +Elliptical 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>`_ +#. [Snyder1987]_ +#. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas <http://www.ihsenergy.com/epsg/guid7.pdf>`_ diff --git a/docs/source/usage/operations/projections/cc.rst b/docs/source/usage/operations/projections/cc.rst new file mode 100644 index 00000000..5b30e6c6 --- /dev/null +++ b/docs/source/usage/operations/projections/cc.rst @@ -0,0 +1,10 @@ +.. _cc: + +******************************************************************************** +Central Cylindrical +******************************************************************************** + +.. image:: ./images/cc.png + :scale: 50% + :alt: Central Cylindrical + diff --git a/docs/source/usage/operations/projections/ccon.rst b/docs/source/usage/operations/projections/ccon.rst new file mode 100644 index 00000000..8a858e38 --- /dev/null +++ b/docs/source/usage/operations/projections/ccon.rst @@ -0,0 +1,127 @@ +.. _ccon: + +******************************************************************************** +Central Conic +******************************************************************************** + +This is central (centrographic) projection on cone tangent at ``lat_0`` latitude, +identical with ``conic()`` projection from ``mapproj`` R package. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the standard parallel | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Lukasz Komsta | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_1` | Latitude of standard parallel. | ++---------------------+----------------------------------------------------------+ + +.. image:: ./images/ccon.png + :scale: 50% + :alt: Central Conic + + +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 [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 +lat_0=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000 + +For more information see [Komsta2016]_ and [Verey2017]_. + + +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 +datum=WGS84 +no_defs + 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 +datum=WGS84 +no_defs +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/docs/source/usage/operations/projections/cea.rst b/docs/source/usage/operations/projections/cea.rst new file mode 100644 index 00000000..20ebc285 --- /dev/null +++ b/docs/source/usage/operations/projections/cea.rst @@ -0,0 +1,10 @@ +.. _cea: + +******************************************************************************** +Equal Area Cylindrical +******************************************************************************** + +.. image:: ./images/cea.png + :scale: 50% + :alt: Equal Area Cylindrical + diff --git a/docs/source/usage/operations/projections/chamb.rst b/docs/source/usage/operations/projections/chamb.rst new file mode 100644 index 00000000..2ec9bffe --- /dev/null +++ b/docs/source/usage/operations/projections/chamb.rst @@ -0,0 +1,10 @@ +.. _chamb: + +******************************************************************************** +Chamberlin Trimetric +******************************************************************************** + +.. image:: ./images/chamb.png + :scale: 50% + :alt: Chamberlin Trimetric + diff --git a/docs/source/usage/operations/projections/collg.rst b/docs/source/usage/operations/projections/collg.rst new file mode 100644 index 00000000..aa16182a --- /dev/null +++ b/docs/source/usage/operations/projections/collg.rst @@ -0,0 +1,10 @@ +.. _collg: + +******************************************************************************** +Collignon +******************************************************************************** + +.. image:: ./images/collg.png + :scale: 50% + :alt: Collignon + diff --git a/docs/source/usage/operations/projections/crast.rst b/docs/source/usage/operations/projections/crast.rst new file mode 100644 index 00000000..9d17f274 --- /dev/null +++ b/docs/source/usage/operations/projections/crast.rst @@ -0,0 +1,10 @@ +.. _crast: + +******************************************************************************** +Craster Parabolic (Putnins P4) +******************************************************************************** + +.. image:: ./images/crast.png + :scale: 50% + :alt: Craster Parabolic (Putnins P4) + diff --git a/docs/source/usage/operations/projections/denoy.rst b/docs/source/usage/operations/projections/denoy.rst new file mode 100644 index 00000000..a885ab0e --- /dev/null +++ b/docs/source/usage/operations/projections/denoy.rst @@ -0,0 +1,10 @@ +.. _denoy: + +******************************************************************************** +Denoyer Semi-Elliptical +******************************************************************************** + +.. image:: ./images/denoy.png + :scale: 50% + :alt: Denoyer Semi-Elliptical + diff --git a/docs/source/usage/operations/projections/eck1.rst b/docs/source/usage/operations/projections/eck1.rst new file mode 100644 index 00000000..841533ec --- /dev/null +++ b/docs/source/usage/operations/projections/eck1.rst @@ -0,0 +1,18 @@ +.. _eck1: + +******************************************************************************** +Eckert I +******************************************************************************** + +.. image:: ./images/eck1.png + :scale: 50% + :alt: Eckert I + + +.. math:: + + x &= 2 \sqrt{2/3\pi} \lambda (1- |\phi|/\pi) + + y &= 2 \sqrt{2/3\pi}\phi + + diff --git a/docs/source/usage/operations/projections/eck2.rst b/docs/source/usage/operations/projections/eck2.rst new file mode 100644 index 00000000..b1bd3179 --- /dev/null +++ b/docs/source/usage/operations/projections/eck2.rst @@ -0,0 +1,10 @@ +.. _eck2: + +******************************************************************************** +Eckert II +******************************************************************************** + +.. image:: ./images/eck2.png + :scale: 50% + :alt: Eckert II + diff --git a/docs/source/usage/operations/projections/eck3.rst b/docs/source/usage/operations/projections/eck3.rst new file mode 100644 index 00000000..ecacc32d --- /dev/null +++ b/docs/source/usage/operations/projections/eck3.rst @@ -0,0 +1,10 @@ +.. _eck3: + +******************************************************************************** +Eckert III +******************************************************************************** + +.. image:: ./images/eck3.png + :scale: 50% + :alt: Eckert III + diff --git a/docs/source/usage/operations/projections/eck4.rst b/docs/source/usage/operations/projections/eck4.rst new file mode 100644 index 00000000..3fc6a9fd --- /dev/null +++ b/docs/source/usage/operations/projections/eck4.rst @@ -0,0 +1,19 @@ +.. _eck4: + +******************************************************************************** +Eckert IV +******************************************************************************** + +.. image:: ./images/eck4.png + :scale: 50% + :alt: Eckert IV + + +.. math:: + + x = \lambda(1+cos\phi) / \sqrt{ 2 + \pi } + +.. math:: + y = 2 \phi / \sqrt { 2 + \pi } + + diff --git a/docs/source/usage/operations/projections/eck5.rst b/docs/source/usage/operations/projections/eck5.rst new file mode 100644 index 00000000..1442d99d --- /dev/null +++ b/docs/source/usage/operations/projections/eck5.rst @@ -0,0 +1,10 @@ +.. _eck5: + +******************************************************************************** +Eckert V +******************************************************************************** + +.. image:: ./images/eck5.png + :scale: 50% + :alt: Eckert V + diff --git a/docs/source/usage/operations/projections/eck6.rst b/docs/source/usage/operations/projections/eck6.rst new file mode 100644 index 00000000..caeaefa6 --- /dev/null +++ b/docs/source/usage/operations/projections/eck6.rst @@ -0,0 +1,10 @@ +.. _eck6: + +******************************************************************************** +Eckert VI +******************************************************************************** + +.. image:: ./images/eck6.png + :scale: 50% + :alt: Eckert VI + diff --git a/docs/source/usage/operations/projections/eqc.rst b/docs/source/usage/operations/projections/eqc.rst new file mode 100644 index 00000000..be431977 --- /dev/null +++ b/docs/source/usage/operations/projections/eqc.rst @@ -0,0 +1,110 @@ +.. _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 | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_ts` | Latitude of true scale. Defaults to 0.0 | ++---------------------+----------------------------------------------------------+ +| `+lat_0` | Center of the map : latitude of origin | ++---------------------+----------------------------------------------------------+ + +.. image:: ./images/eqc.png + :scale: 50% + :alt: Equidistant Cylindrical (Plate Carrée) + +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 +datum=WGS84 +units=m +no_defs + 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 +lat_0=90w + -8483684.61 13358338.90 + + +Mathematical definition +####################### + +The formulas describing the Equidistant Cylindrical projection are all taken from Snyder's [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/docs/source/usage/operations/projections/eqdc.rst b/docs/source/usage/operations/projections/eqdc.rst new file mode 100644 index 00000000..3ee5999d --- /dev/null +++ b/docs/source/usage/operations/projections/eqdc.rst @@ -0,0 +1,10 @@ +.. _eqdc: + +******************************************************************************** +Equidistant Conic +******************************************************************************** + +.. image:: ./images/eqdc.png + :scale: 50% + :alt: Equidistant Conic + diff --git a/docs/source/usage/operations/projections/etmerc.rst b/docs/source/usage/operations/projections/etmerc.rst new file mode 100644 index 00000000..b7f89032 --- /dev/null +++ b/docs/source/usage/operations/projections/etmerc.rst @@ -0,0 +1,10 @@ +.. _etmerc: + +******************************************************************************** +Extended Transverse Mercator +******************************************************************************** + +.. image:: ./images/etmerc.png + :scale: 50% + :alt: Extended Transverse Mercator + diff --git a/docs/source/usage/operations/projections/euler.rst b/docs/source/usage/operations/projections/euler.rst new file mode 100644 index 00000000..e495063f --- /dev/null +++ b/docs/source/usage/operations/projections/euler.rst @@ -0,0 +1,10 @@ +.. _euler: + +******************************************************************************** +Euler +******************************************************************************** + +.. image:: ./images/euler.png + :scale: 50% + :alt: Euler + diff --git a/docs/source/usage/operations/projections/fahey.rst b/docs/source/usage/operations/projections/fahey.rst new file mode 100644 index 00000000..2e09337f --- /dev/null +++ b/docs/source/usage/operations/projections/fahey.rst @@ -0,0 +1,10 @@ +.. _fahey: + +******************************************************************************** +Fahey +******************************************************************************** + +.. image:: ./images/fahey.png + :scale: 50% + :alt: Fahey + diff --git a/docs/source/usage/operations/projections/fouc.rst b/docs/source/usage/operations/projections/fouc.rst new file mode 100644 index 00000000..7467dcb1 --- /dev/null +++ b/docs/source/usage/operations/projections/fouc.rst @@ -0,0 +1,10 @@ +.. _fouc: + +******************************************************************************** +Foucaut +******************************************************************************** + +.. image:: ./images/fouc.png + :scale: 50% + :alt: Foucaut + diff --git a/docs/source/usage/operations/projections/fouc_s.rst b/docs/source/usage/operations/projections/fouc_s.rst new file mode 100644 index 00000000..ac353adb --- /dev/null +++ b/docs/source/usage/operations/projections/fouc_s.rst @@ -0,0 +1,25 @@ +.. _fouc_s: + +******************************************************************************** +Foucaut Sinusoidal +******************************************************************************** + +.. image:: ./images/fouc_s.png + :scale: 50% + :alt: Foucaut Sinusoidal + + +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` diff --git a/docs/source/usage/operations/projections/gall.rst b/docs/source/usage/operations/projections/gall.rst new file mode 100644 index 00000000..b9120d9f --- /dev/null +++ b/docs/source/usage/operations/projections/gall.rst @@ -0,0 +1,84 @@ +.. _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 | ++---------------------+--------------------------------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+--------------------------------------------------------------------------------+ +| **Options** | No special options for this projection | ++---------------------+--------------------------------------------------------------------------------+ + + +.. image:: ./images/gall.png + :scale: 50% + :alt: Gall (Gall Stereographic) + +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. + + +Example using Gall Stereographical :: + + $ echo 9 51 | proj +proj=gall +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs + 708432.90 5193386.36 + +Example using Gall Stereographical (Central meridian 90°W) :: + + $ echo 9 51 | proj +proj=gall +lon_0=90w +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs + 7792761.91 5193386.36 + +Mathematical definition +####################### + +The formulas describing the Gall Stereographical are all taken from Snyder's [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/docs/source/usage/operations/projections/geos.rst b/docs/source/usage/operations/projections/geos.rst new file mode 100644 index 00000000..670985ae --- /dev/null +++ b/docs/source/usage/operations/projections/geos.rst @@ -0,0 +1,72 @@ +.. _geos: + +******************************************************************************** +Geostationary Satellite View +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden and Martin Raspaud | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+h` | Satellite height above earth. Required. | ++---------------------+----------------------------------------------------------+ +| `+sweep` | Sweep angle axis of the viewing instrument. | +| | Valid options are ``x`` and ``y``. Defaults to ``y``. | ++---------------------+----------------------------------------------------------+ +| `+lon_0` | Subsatellite longitude point. | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/geos.png + :scale: 50% + :alt: Geostationary Satellite View + +The geos projection pictures how a geostationary satellite scans the earth at regular +scanning angle intervals. + + +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 + :scale: 50% + :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 x, and +GOES should take sweep as y. diff --git a/docs/source/usage/operations/projections/gins8.rst b/docs/source/usage/operations/projections/gins8.rst new file mode 100644 index 00000000..f6adb092 --- /dev/null +++ b/docs/source/usage/operations/projections/gins8.rst @@ -0,0 +1,10 @@ +.. _gins8: + +******************************************************************************** +Ginsburg VIII (TsNIIGAiK) +******************************************************************************** + +.. image:: ./images/gins8.png + :scale: 50% + :alt: Ginsburg VIII (TsNIIGAiK) + diff --git a/docs/source/usage/operations/projections/gn_sinu.rst b/docs/source/usage/operations/projections/gn_sinu.rst new file mode 100644 index 00000000..c1017c27 --- /dev/null +++ b/docs/source/usage/operations/projections/gn_sinu.rst @@ -0,0 +1,10 @@ +.. _gn_sinu: + +******************************************************************************** +General Sinusoidal Series +******************************************************************************** + +.. image:: ./images/gn_sinu.png + :scale: 50% + :alt: General Sinusoidal Series + diff --git a/docs/source/usage/operations/projections/gnom.rst b/docs/source/usage/operations/projections/gnom.rst new file mode 100644 index 00000000..08d0db5f --- /dev/null +++ b/docs/source/usage/operations/projections/gnom.rst @@ -0,0 +1,10 @@ +.. _gnom: + +******************************************************************************** +Gnomonic +******************************************************************************** + +.. image:: ./images/gnom.png + :scale: 50% + :alt: Gnomonic + diff --git a/docs/source/usage/operations/projections/goode.rst b/docs/source/usage/operations/projections/goode.rst new file mode 100644 index 00000000..c4590bf2 --- /dev/null +++ b/docs/source/usage/operations/projections/goode.rst @@ -0,0 +1,10 @@ +.. _goode: + +******************************************************************************** +Goode Homolosine +******************************************************************************** + +.. image:: ./images/goode.png + :scale: 50% + :alt: Goode Homolosine + diff --git a/docs/source/usage/operations/projections/gs48.rst b/docs/source/usage/operations/projections/gs48.rst new file mode 100644 index 00000000..bdaa367c --- /dev/null +++ b/docs/source/usage/operations/projections/gs48.rst @@ -0,0 +1,10 @@ +.. _gs48: + +******************************************************************************** +Mod. Stererographics of 48 U.S. +******************************************************************************** + +.. image:: ./images/gs48.png + :scale: 50% + :alt: Mod. Stererographics of 48 U.S. + diff --git a/docs/source/usage/operations/projections/gs50.rst b/docs/source/usage/operations/projections/gs50.rst new file mode 100644 index 00000000..0d4b7e81 --- /dev/null +++ b/docs/source/usage/operations/projections/gs50.rst @@ -0,0 +1,10 @@ +.. _gs50: + +******************************************************************************** +Mod. Stererographics of 50 U.S. +******************************************************************************** + +.. image:: ./images/gs50.png + :scale: 50% + :alt: Mod. Stererographics of 50 U.S. + diff --git a/docs/source/usage/operations/projections/gstmerc.rst b/docs/source/usage/operations/projections/gstmerc.rst new file mode 100644 index 00000000..fc587ab0 --- /dev/null +++ b/docs/source/usage/operations/projections/gstmerc.rst @@ -0,0 +1,10 @@ +.. _gstmerc: + +******************************************************************************** +Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) +******************************************************************************** + +.. image:: ./images/gstmerc.png + :scale: 50% + :alt: Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) + diff --git a/docs/source/usage/operations/projections/hammer.rst b/docs/source/usage/operations/projections/hammer.rst new file mode 100644 index 00000000..e795b91b --- /dev/null +++ b/docs/source/usage/operations/projections/hammer.rst @@ -0,0 +1,10 @@ +.. _hammer: + +******************************************************************************** +Hammer & Eckert-Greifendorff +******************************************************************************** + +.. image:: ./images/hammer.png + :scale: 50% + :alt: Hammer & Eckert-Greifendorff + diff --git a/docs/source/usage/operations/projections/hatano.rst b/docs/source/usage/operations/projections/hatano.rst new file mode 100644 index 00000000..5d0c63b7 --- /dev/null +++ b/docs/source/usage/operations/projections/hatano.rst @@ -0,0 +1,70 @@ +.. _hatano: + +******************************************************************************** +Hatano Asymmetrical Equal Area +******************************************************************************** + + + + ++---------------------+----------------------------------------------------------+ +| **Classification** | :term:`Pseudocylindrical Projection` | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best between standard parallels | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_1` | Standard Parallel 1 | ++---------------------+----------------------------------------------------------+ +| `+lat_2` | Standard Parallel 2 | ++---------------------+----------------------------------------------------------+ +| `+sym` | Symmetric form used instead of asymmetric | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/hatano.png + :scale: 50% + :alt: Hatano Asymmetrical Equal Area + + + +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_p` :math:`C_p` +==================================== ================== =================== +if ``+sym`` or :math:`\phi > 0` 1.75859 2.67595 +if not ``+sym`` and :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/docs/source/usage/operations/projections/healpix.rst b/docs/source/usage/operations/projections/healpix.rst new file mode 100644 index 00000000..20815d76 --- /dev/null +++ b/docs/source/usage/operations/projections/healpix.rst @@ -0,0 +1,55 @@ +.. _healpix: + +******************************************************************************** +HEALPix +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Mixed | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Alex Raichev and Michael Speth | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `No special options for this projection` | ++---------------------+----------------------------------------------------------+ + +.. 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 + +Further reading +################################################################################ + +#. `NASA <http://healpix.jpl.nasa.gov/>`_ +#. `Wikipedia <https://en.wikipedia.org/wiki/HEALPix>`_ + + + + + diff --git a/docs/source/usage/operations/projections/igh.rst b/docs/source/usage/operations/projections/igh.rst new file mode 100644 index 00000000..d74e1362 --- /dev/null +++ b/docs/source/usage/operations/projections/igh.rst @@ -0,0 +1,10 @@ +.. _igh: + +******************************************************************************** +Interrupted Goode Homolosine +******************************************************************************** + +.. image:: ./images/igh.png + :scale: 50% + :alt: Interrupted Goode Homolosine + diff --git a/docs/source/usage/operations/projections/images/aea.png b/docs/source/usage/operations/projections/images/aea.png Binary files differnew file mode 100644 index 00000000..7fdd4ece --- /dev/null +++ b/docs/source/usage/operations/projections/images/aea.png diff --git a/docs/source/usage/operations/projections/images/aeqd.png b/docs/source/usage/operations/projections/images/aeqd.png Binary files differnew file mode 100644 index 00000000..8e45b2c0 --- /dev/null +++ b/docs/source/usage/operations/projections/images/aeqd.png diff --git a/docs/source/usage/operations/projections/images/airy.png b/docs/source/usage/operations/projections/images/airy.png Binary files differnew file mode 100644 index 00000000..a441e317 --- /dev/null +++ b/docs/source/usage/operations/projections/images/airy.png diff --git a/docs/source/usage/operations/projections/images/aitoff.png b/docs/source/usage/operations/projections/images/aitoff.png Binary files differnew file mode 100644 index 00000000..3449dcd5 --- /dev/null +++ b/docs/source/usage/operations/projections/images/aitoff.png diff --git a/docs/source/usage/operations/projections/images/alsk.png b/docs/source/usage/operations/projections/images/alsk.png Binary files differnew file mode 100644 index 00000000..6f6e2014 --- /dev/null +++ b/docs/source/usage/operations/projections/images/alsk.png diff --git a/docs/source/usage/operations/projections/images/apian.png b/docs/source/usage/operations/projections/images/apian.png Binary files differnew file mode 100644 index 00000000..95857ae3 --- /dev/null +++ b/docs/source/usage/operations/projections/images/apian.png diff --git a/docs/source/usage/operations/projections/images/august.png b/docs/source/usage/operations/projections/images/august.png Binary files differnew file mode 100644 index 00000000..9d9fece6 --- /dev/null +++ b/docs/source/usage/operations/projections/images/august.png diff --git a/docs/source/usage/operations/projections/images/bacon.png b/docs/source/usage/operations/projections/images/bacon.png Binary files differnew file mode 100644 index 00000000..62deae63 --- /dev/null +++ b/docs/source/usage/operations/projections/images/bacon.png diff --git a/docs/source/usage/operations/projections/images/bipc.png b/docs/source/usage/operations/projections/images/bipc.png Binary files differnew file mode 100644 index 00000000..7b8ab39c --- /dev/null +++ b/docs/source/usage/operations/projections/images/bipc.png diff --git a/docs/source/usage/operations/projections/images/boggs.png b/docs/source/usage/operations/projections/images/boggs.png Binary files differnew file mode 100644 index 00000000..42dd4c13 --- /dev/null +++ b/docs/source/usage/operations/projections/images/boggs.png diff --git a/docs/source/usage/operations/projections/images/bonne.png b/docs/source/usage/operations/projections/images/bonne.png Binary files differnew file mode 100644 index 00000000..12f93217 --- /dev/null +++ b/docs/source/usage/operations/projections/images/bonne.png diff --git a/docs/source/usage/operations/projections/images/calcofi.png b/docs/source/usage/operations/projections/images/calcofi.png Binary files differnew file mode 100644 index 00000000..2fd405ac --- /dev/null +++ b/docs/source/usage/operations/projections/images/calcofi.png diff --git a/docs/source/usage/operations/projections/images/cass.png b/docs/source/usage/operations/projections/images/cass.png Binary files differnew file mode 100644 index 00000000..e44c46af --- /dev/null +++ b/docs/source/usage/operations/projections/images/cass.png diff --git a/docs/source/usage/operations/projections/images/cc.png b/docs/source/usage/operations/projections/images/cc.png Binary files differnew file mode 100644 index 00000000..3beaedfd --- /dev/null +++ b/docs/source/usage/operations/projections/images/cc.png diff --git a/docs/source/usage/operations/projections/images/ccon.png b/docs/source/usage/operations/projections/images/ccon.png Binary files differnew file mode 100644 index 00000000..ccc0ec9e --- /dev/null +++ b/docs/source/usage/operations/projections/images/ccon.png diff --git a/docs/source/usage/operations/projections/images/cea.png b/docs/source/usage/operations/projections/images/cea.png Binary files differnew file mode 100644 index 00000000..eca2319d --- /dev/null +++ b/docs/source/usage/operations/projections/images/cea.png diff --git a/docs/source/usage/operations/projections/images/chamb.png b/docs/source/usage/operations/projections/images/chamb.png Binary files differnew file mode 100644 index 00000000..a87e6c68 --- /dev/null +++ b/docs/source/usage/operations/projections/images/chamb.png diff --git a/docs/source/usage/operations/projections/images/collg.png b/docs/source/usage/operations/projections/images/collg.png Binary files differnew file mode 100644 index 00000000..851201da --- /dev/null +++ b/docs/source/usage/operations/projections/images/collg.png diff --git a/docs/source/usage/operations/projections/images/comill.png b/docs/source/usage/operations/projections/images/comill.png Binary files differnew file mode 100644 index 00000000..725a0118 --- /dev/null +++ b/docs/source/usage/operations/projections/images/comill.png diff --git a/docs/source/usage/operations/projections/images/crast.png b/docs/source/usage/operations/projections/images/crast.png Binary files differnew file mode 100644 index 00000000..abd4d32a --- /dev/null +++ b/docs/source/usage/operations/projections/images/crast.png diff --git a/docs/source/usage/operations/projections/images/denoy.png b/docs/source/usage/operations/projections/images/denoy.png Binary files differnew file mode 100644 index 00000000..2871cf84 --- /dev/null +++ b/docs/source/usage/operations/projections/images/denoy.png diff --git a/docs/source/usage/operations/projections/images/eck1.png b/docs/source/usage/operations/projections/images/eck1.png Binary files differnew file mode 100644 index 00000000..b892d39e --- /dev/null +++ b/docs/source/usage/operations/projections/images/eck1.png diff --git a/docs/source/usage/operations/projections/images/eck2.png b/docs/source/usage/operations/projections/images/eck2.png Binary files differnew file mode 100644 index 00000000..ff011598 --- /dev/null +++ b/docs/source/usage/operations/projections/images/eck2.png diff --git a/docs/source/usage/operations/projections/images/eck3.png b/docs/source/usage/operations/projections/images/eck3.png Binary files differnew file mode 100644 index 00000000..f828eed0 --- /dev/null +++ b/docs/source/usage/operations/projections/images/eck3.png diff --git a/docs/source/usage/operations/projections/images/eck4.png b/docs/source/usage/operations/projections/images/eck4.png Binary files differnew file mode 100644 index 00000000..d7ff87bb --- /dev/null +++ b/docs/source/usage/operations/projections/images/eck4.png diff --git a/docs/source/usage/operations/projections/images/eck5.png b/docs/source/usage/operations/projections/images/eck5.png Binary files differnew file mode 100644 index 00000000..3df303c6 --- /dev/null +++ b/docs/source/usage/operations/projections/images/eck5.png diff --git a/docs/source/usage/operations/projections/images/eck6.png b/docs/source/usage/operations/projections/images/eck6.png Binary files differnew file mode 100644 index 00000000..d22f4956 --- /dev/null +++ b/docs/source/usage/operations/projections/images/eck6.png diff --git a/docs/source/usage/operations/projections/images/eqc.png b/docs/source/usage/operations/projections/images/eqc.png Binary files differnew file mode 100644 index 00000000..b2d8ba23 --- /dev/null +++ b/docs/source/usage/operations/projections/images/eqc.png diff --git a/docs/source/usage/operations/projections/images/eqdc.png b/docs/source/usage/operations/projections/images/eqdc.png Binary files differnew file mode 100644 index 00000000..f2330a8e --- /dev/null +++ b/docs/source/usage/operations/projections/images/eqdc.png diff --git a/docs/source/usage/operations/projections/images/etmerc.png b/docs/source/usage/operations/projections/images/etmerc.png Binary files differnew file mode 100644 index 00000000..8e6bb39b --- /dev/null +++ b/docs/source/usage/operations/projections/images/etmerc.png diff --git a/docs/source/usage/operations/projections/images/euler.png b/docs/source/usage/operations/projections/images/euler.png Binary files differnew file mode 100644 index 00000000..c9c6e4c8 --- /dev/null +++ b/docs/source/usage/operations/projections/images/euler.png diff --git a/docs/source/usage/operations/projections/images/fahey.png b/docs/source/usage/operations/projections/images/fahey.png Binary files differnew file mode 100644 index 00000000..8b870b8a --- /dev/null +++ b/docs/source/usage/operations/projections/images/fahey.png diff --git a/docs/source/usage/operations/projections/images/fouc.png b/docs/source/usage/operations/projections/images/fouc.png Binary files differnew file mode 100644 index 00000000..6d33216b --- /dev/null +++ b/docs/source/usage/operations/projections/images/fouc.png diff --git a/docs/source/usage/operations/projections/images/fouc_s.png b/docs/source/usage/operations/projections/images/fouc_s.png Binary files differnew file mode 100644 index 00000000..401f5ee4 --- /dev/null +++ b/docs/source/usage/operations/projections/images/fouc_s.png diff --git a/docs/source/usage/operations/projections/images/gall.png b/docs/source/usage/operations/projections/images/gall.png Binary files differnew file mode 100644 index 00000000..819b5d12 --- /dev/null +++ b/docs/source/usage/operations/projections/images/gall.png diff --git a/docs/source/usage/operations/projections/images/geos.png b/docs/source/usage/operations/projections/images/geos.png Binary files differnew file mode 100644 index 00000000..e44fa41b --- /dev/null +++ b/docs/source/usage/operations/projections/images/geos.png diff --git a/docs/source/usage/operations/projections/images/gins8.png b/docs/source/usage/operations/projections/images/gins8.png Binary files differnew file mode 100644 index 00000000..12fbae93 --- /dev/null +++ b/docs/source/usage/operations/projections/images/gins8.png diff --git a/docs/source/usage/operations/projections/images/gn_sinu.png b/docs/source/usage/operations/projections/images/gn_sinu.png Binary files differnew file mode 100644 index 00000000..f02e119e --- /dev/null +++ b/docs/source/usage/operations/projections/images/gn_sinu.png diff --git a/docs/source/usage/operations/projections/images/gnom.png b/docs/source/usage/operations/projections/images/gnom.png Binary files differnew file mode 100644 index 00000000..c079d31a --- /dev/null +++ b/docs/source/usage/operations/projections/images/gnom.png diff --git a/docs/source/usage/operations/projections/images/goode.png b/docs/source/usage/operations/projections/images/goode.png Binary files differnew file mode 100644 index 00000000..7001e8d2 --- /dev/null +++ b/docs/source/usage/operations/projections/images/goode.png diff --git a/docs/source/usage/operations/projections/images/gs48.png b/docs/source/usage/operations/projections/images/gs48.png Binary files differnew file mode 100644 index 00000000..574e368f --- /dev/null +++ b/docs/source/usage/operations/projections/images/gs48.png diff --git a/docs/source/usage/operations/projections/images/gs50.png b/docs/source/usage/operations/projections/images/gs50.png Binary files differnew file mode 100644 index 00000000..7244b160 --- /dev/null +++ b/docs/source/usage/operations/projections/images/gs50.png diff --git a/docs/source/usage/operations/projections/images/gstmerc.png b/docs/source/usage/operations/projections/images/gstmerc.png Binary files differnew file mode 100644 index 00000000..d553ea60 --- /dev/null +++ b/docs/source/usage/operations/projections/images/gstmerc.png diff --git a/docs/source/usage/operations/projections/images/hammer.png b/docs/source/usage/operations/projections/images/hammer.png Binary files differnew file mode 100644 index 00000000..83848479 --- /dev/null +++ b/docs/source/usage/operations/projections/images/hammer.png diff --git a/docs/source/usage/operations/projections/images/hatano.png b/docs/source/usage/operations/projections/images/hatano.png Binary files differnew file mode 100644 index 00000000..b3f47377 --- /dev/null +++ b/docs/source/usage/operations/projections/images/hatano.png diff --git a/docs/source/usage/operations/projections/images/healpix.png b/docs/source/usage/operations/projections/images/healpix.png Binary files differnew file mode 100644 index 00000000..c58a155c --- /dev/null +++ b/docs/source/usage/operations/projections/images/healpix.png diff --git a/docs/source/usage/operations/projections/images/igh.png b/docs/source/usage/operations/projections/images/igh.png Binary files differnew file mode 100644 index 00000000..36336eec --- /dev/null +++ b/docs/source/usage/operations/projections/images/igh.png diff --git a/docs/source/usage/operations/projections/images/imw_p.png b/docs/source/usage/operations/projections/images/imw_p.png Binary files differnew file mode 100644 index 00000000..74cfe81b --- /dev/null +++ b/docs/source/usage/operations/projections/images/imw_p.png diff --git a/docs/source/usage/operations/projections/images/isea.png b/docs/source/usage/operations/projections/images/isea.png Binary files differnew file mode 100644 index 00000000..23cfbf74 --- /dev/null +++ b/docs/source/usage/operations/projections/images/isea.png diff --git a/docs/source/usage/operations/projections/images/kav5.png b/docs/source/usage/operations/projections/images/kav5.png Binary files differnew file mode 100644 index 00000000..d5c45400 --- /dev/null +++ b/docs/source/usage/operations/projections/images/kav5.png diff --git a/docs/source/usage/operations/projections/images/kav7.png b/docs/source/usage/operations/projections/images/kav7.png Binary files differnew file mode 100644 index 00000000..50d7e6e6 --- /dev/null +++ b/docs/source/usage/operations/projections/images/kav7.png diff --git a/docs/source/usage/operations/projections/images/krovak.png b/docs/source/usage/operations/projections/images/krovak.png Binary files differnew file mode 100644 index 00000000..d0d69547 --- /dev/null +++ b/docs/source/usage/operations/projections/images/krovak.png diff --git a/docs/source/usage/operations/projections/images/labrd.png b/docs/source/usage/operations/projections/images/labrd.png Binary files differnew file mode 100644 index 00000000..e4a174c0 --- /dev/null +++ b/docs/source/usage/operations/projections/images/labrd.png diff --git a/docs/source/usage/operations/projections/images/laea.png b/docs/source/usage/operations/projections/images/laea.png Binary files differnew file mode 100644 index 00000000..f52c7c1f --- /dev/null +++ b/docs/source/usage/operations/projections/images/laea.png diff --git a/docs/source/usage/operations/projections/images/lagrng.png b/docs/source/usage/operations/projections/images/lagrng.png Binary files differnew file mode 100644 index 00000000..e48210bb --- /dev/null +++ b/docs/source/usage/operations/projections/images/lagrng.png diff --git a/docs/source/usage/operations/projections/images/larr.png b/docs/source/usage/operations/projections/images/larr.png Binary files differnew file mode 100644 index 00000000..967b91d2 --- /dev/null +++ b/docs/source/usage/operations/projections/images/larr.png diff --git a/docs/source/usage/operations/projections/images/lask.png b/docs/source/usage/operations/projections/images/lask.png Binary files differnew file mode 100644 index 00000000..dff0e8fa --- /dev/null +++ b/docs/source/usage/operations/projections/images/lask.png diff --git a/docs/source/usage/operations/projections/images/lcc.png b/docs/source/usage/operations/projections/images/lcc.png Binary files differnew file mode 100644 index 00000000..4714b74e --- /dev/null +++ b/docs/source/usage/operations/projections/images/lcc.png diff --git a/docs/source/usage/operations/projections/images/lcca.png b/docs/source/usage/operations/projections/images/lcca.png Binary files differnew file mode 100644 index 00000000..0c404670 --- /dev/null +++ b/docs/source/usage/operations/projections/images/lcca.png diff --git a/docs/source/usage/operations/projections/images/leac.png b/docs/source/usage/operations/projections/images/leac.png Binary files differnew file mode 100644 index 00000000..1f57d192 --- /dev/null +++ b/docs/source/usage/operations/projections/images/leac.png diff --git a/docs/source/usage/operations/projections/images/lee_os.png b/docs/source/usage/operations/projections/images/lee_os.png Binary files differnew file mode 100644 index 00000000..3e258393 --- /dev/null +++ b/docs/source/usage/operations/projections/images/lee_os.png diff --git a/docs/source/usage/operations/projections/images/loxim.png b/docs/source/usage/operations/projections/images/loxim.png Binary files differnew file mode 100644 index 00000000..a03ba94e --- /dev/null +++ b/docs/source/usage/operations/projections/images/loxim.png diff --git a/docs/source/usage/operations/projections/images/lsat.png b/docs/source/usage/operations/projections/images/lsat.png Binary files differnew file mode 100644 index 00000000..ec608544 --- /dev/null +++ b/docs/source/usage/operations/projections/images/lsat.png diff --git a/docs/source/usage/operations/projections/images/mbt_fps.png b/docs/source/usage/operations/projections/images/mbt_fps.png Binary files differnew file mode 100644 index 00000000..e97cd21e --- /dev/null +++ b/docs/source/usage/operations/projections/images/mbt_fps.png diff --git a/docs/source/usage/operations/projections/images/mbt_s.png b/docs/source/usage/operations/projections/images/mbt_s.png Binary files differnew file mode 100644 index 00000000..4432e83b --- /dev/null +++ b/docs/source/usage/operations/projections/images/mbt_s.png diff --git a/docs/source/usage/operations/projections/images/mbtfpp.png b/docs/source/usage/operations/projections/images/mbtfpp.png Binary files differnew file mode 100644 index 00000000..3d0c4fb5 --- /dev/null +++ b/docs/source/usage/operations/projections/images/mbtfpp.png diff --git a/docs/source/usage/operations/projections/images/mbtfpq.png b/docs/source/usage/operations/projections/images/mbtfpq.png Binary files differnew file mode 100644 index 00000000..b31c52ce --- /dev/null +++ b/docs/source/usage/operations/projections/images/mbtfpq.png diff --git a/docs/source/usage/operations/projections/images/mbtfps.png b/docs/source/usage/operations/projections/images/mbtfps.png Binary files differnew file mode 100644 index 00000000..83891be6 --- /dev/null +++ b/docs/source/usage/operations/projections/images/mbtfps.png diff --git a/docs/source/usage/operations/projections/images/merc.png b/docs/source/usage/operations/projections/images/merc.png Binary files differnew file mode 100644 index 00000000..8202789e --- /dev/null +++ b/docs/source/usage/operations/projections/images/merc.png diff --git a/docs/source/usage/operations/projections/images/mil_os.png b/docs/source/usage/operations/projections/images/mil_os.png Binary files differnew file mode 100644 index 00000000..3316d317 --- /dev/null +++ b/docs/source/usage/operations/projections/images/mil_os.png diff --git a/docs/source/usage/operations/projections/images/mill.png b/docs/source/usage/operations/projections/images/mill.png Binary files differnew file mode 100644 index 00000000..f62e517c --- /dev/null +++ b/docs/source/usage/operations/projections/images/mill.png diff --git a/docs/source/usage/operations/projections/images/misrsom.png b/docs/source/usage/operations/projections/images/misrsom.png Binary files differnew file mode 100644 index 00000000..493baff3 --- /dev/null +++ b/docs/source/usage/operations/projections/images/misrsom.png diff --git a/docs/source/usage/operations/projections/images/moll.png b/docs/source/usage/operations/projections/images/moll.png Binary files differnew file mode 100644 index 00000000..5d599579 --- /dev/null +++ b/docs/source/usage/operations/projections/images/moll.png diff --git a/docs/source/usage/operations/projections/images/murd1.png b/docs/source/usage/operations/projections/images/murd1.png Binary files differnew file mode 100644 index 00000000..34d628c5 --- /dev/null +++ b/docs/source/usage/operations/projections/images/murd1.png diff --git a/docs/source/usage/operations/projections/images/murd2.png b/docs/source/usage/operations/projections/images/murd2.png Binary files differnew file mode 100644 index 00000000..b3fdabdd --- /dev/null +++ b/docs/source/usage/operations/projections/images/murd2.png diff --git a/docs/source/usage/operations/projections/images/murd3.png b/docs/source/usage/operations/projections/images/murd3.png Binary files differnew file mode 100644 index 00000000..354b009c --- /dev/null +++ b/docs/source/usage/operations/projections/images/murd3.png diff --git a/docs/source/usage/operations/projections/images/natearth.png b/docs/source/usage/operations/projections/images/natearth.png Binary files differnew file mode 100644 index 00000000..0e182a0b --- /dev/null +++ b/docs/source/usage/operations/projections/images/natearth.png diff --git a/docs/source/usage/operations/projections/images/natearth2.png b/docs/source/usage/operations/projections/images/natearth2.png Binary files differnew file mode 100644 index 00000000..3757646c --- /dev/null +++ b/docs/source/usage/operations/projections/images/natearth2.png diff --git a/docs/source/usage/operations/projections/images/nell.png b/docs/source/usage/operations/projections/images/nell.png Binary files differnew file mode 100644 index 00000000..c0dbdcac --- /dev/null +++ b/docs/source/usage/operations/projections/images/nell.png diff --git a/docs/source/usage/operations/projections/images/nell_h.png b/docs/source/usage/operations/projections/images/nell_h.png Binary files differnew file mode 100644 index 00000000..a5a27076 --- /dev/null +++ b/docs/source/usage/operations/projections/images/nell_h.png diff --git a/docs/source/usage/operations/projections/images/nicol.png b/docs/source/usage/operations/projections/images/nicol.png Binary files differnew file mode 100644 index 00000000..711db115 --- /dev/null +++ b/docs/source/usage/operations/projections/images/nicol.png diff --git a/docs/source/usage/operations/projections/images/nsper.png b/docs/source/usage/operations/projections/images/nsper.png Binary files differnew file mode 100644 index 00000000..06f210a1 --- /dev/null +++ b/docs/source/usage/operations/projections/images/nsper.png diff --git a/docs/source/usage/operations/projections/images/nzmg.png b/docs/source/usage/operations/projections/images/nzmg.png Binary files differnew file mode 100644 index 00000000..3625f331 --- /dev/null +++ b/docs/source/usage/operations/projections/images/nzmg.png diff --git a/docs/source/usage/operations/projections/images/ob_tran.png b/docs/source/usage/operations/projections/images/ob_tran.png Binary files differnew file mode 100644 index 00000000..9b1e0d44 --- /dev/null +++ b/docs/source/usage/operations/projections/images/ob_tran.png diff --git a/docs/source/usage/operations/projections/images/ocea.png b/docs/source/usage/operations/projections/images/ocea.png Binary files differnew file mode 100644 index 00000000..41a5a813 --- /dev/null +++ b/docs/source/usage/operations/projections/images/ocea.png diff --git a/docs/source/usage/operations/projections/images/oea.png b/docs/source/usage/operations/projections/images/oea.png Binary files differnew file mode 100644 index 00000000..601ead55 --- /dev/null +++ b/docs/source/usage/operations/projections/images/oea.png diff --git a/docs/source/usage/operations/projections/images/omerc.png b/docs/source/usage/operations/projections/images/omerc.png Binary files differnew file mode 100644 index 00000000..50a3d2b7 --- /dev/null +++ b/docs/source/usage/operations/projections/images/omerc.png diff --git a/docs/source/usage/operations/projections/images/ortel.png b/docs/source/usage/operations/projections/images/ortel.png Binary files differnew file mode 100644 index 00000000..c6a5bf4f --- /dev/null +++ b/docs/source/usage/operations/projections/images/ortel.png diff --git a/docs/source/usage/operations/projections/images/ortho.png b/docs/source/usage/operations/projections/images/ortho.png Binary files differnew file mode 100644 index 00000000..e8b0b9b2 --- /dev/null +++ b/docs/source/usage/operations/projections/images/ortho.png diff --git a/docs/source/usage/operations/projections/images/patterson.png b/docs/source/usage/operations/projections/images/patterson.png Binary files differnew file mode 100644 index 00000000..f8014249 --- /dev/null +++ b/docs/source/usage/operations/projections/images/patterson.png diff --git a/docs/source/usage/operations/projections/images/pconic.png b/docs/source/usage/operations/projections/images/pconic.png Binary files differnew file mode 100644 index 00000000..7d7f9f92 --- /dev/null +++ b/docs/source/usage/operations/projections/images/pconic.png diff --git a/docs/source/usage/operations/projections/images/poly.png b/docs/source/usage/operations/projections/images/poly.png Binary files differnew file mode 100644 index 00000000..ccf25529 --- /dev/null +++ b/docs/source/usage/operations/projections/images/poly.png diff --git a/docs/source/usage/operations/projections/images/putp1.png b/docs/source/usage/operations/projections/images/putp1.png Binary files differnew file mode 100644 index 00000000..c81f574c --- /dev/null +++ b/docs/source/usage/operations/projections/images/putp1.png diff --git a/docs/source/usage/operations/projections/images/putp2.png b/docs/source/usage/operations/projections/images/putp2.png Binary files differnew file mode 100644 index 00000000..377a027c --- /dev/null +++ b/docs/source/usage/operations/projections/images/putp2.png diff --git a/docs/source/usage/operations/projections/images/putp3.png b/docs/source/usage/operations/projections/images/putp3.png Binary files differnew file mode 100644 index 00000000..08692ca1 --- /dev/null +++ b/docs/source/usage/operations/projections/images/putp3.png diff --git a/docs/source/usage/operations/projections/images/putp3p.png b/docs/source/usage/operations/projections/images/putp3p.png Binary files differnew file mode 100644 index 00000000..9e42319c --- /dev/null +++ b/docs/source/usage/operations/projections/images/putp3p.png diff --git a/docs/source/usage/operations/projections/images/putp4p.png b/docs/source/usage/operations/projections/images/putp4p.png Binary files differnew file mode 100644 index 00000000..43cb10c6 --- /dev/null +++ b/docs/source/usage/operations/projections/images/putp4p.png diff --git a/docs/source/usage/operations/projections/images/putp5.png b/docs/source/usage/operations/projections/images/putp5.png Binary files differnew file mode 100644 index 00000000..4e45de6d --- /dev/null +++ b/docs/source/usage/operations/projections/images/putp5.png diff --git a/docs/source/usage/operations/projections/images/putp5p.png b/docs/source/usage/operations/projections/images/putp5p.png Binary files differnew file mode 100644 index 00000000..76dcb767 --- /dev/null +++ b/docs/source/usage/operations/projections/images/putp5p.png diff --git a/docs/source/usage/operations/projections/images/putp6.png b/docs/source/usage/operations/projections/images/putp6.png Binary files differnew file mode 100644 index 00000000..c73585ee --- /dev/null +++ b/docs/source/usage/operations/projections/images/putp6.png diff --git a/docs/source/usage/operations/projections/images/putp6p.png b/docs/source/usage/operations/projections/images/putp6p.png Binary files differnew file mode 100644 index 00000000..d64c2c20 --- /dev/null +++ b/docs/source/usage/operations/projections/images/putp6p.png diff --git a/docs/source/usage/operations/projections/images/qsc.png b/docs/source/usage/operations/projections/images/qsc.png Binary files differnew file mode 100644 index 00000000..5824cf64 --- /dev/null +++ b/docs/source/usage/operations/projections/images/qsc.png diff --git a/docs/source/usage/operations/projections/images/qua_aut.png b/docs/source/usage/operations/projections/images/qua_aut.png Binary files differnew file mode 100644 index 00000000..6bc2d811 --- /dev/null +++ b/docs/source/usage/operations/projections/images/qua_aut.png diff --git a/docs/source/usage/operations/projections/images/rhealpix.png b/docs/source/usage/operations/projections/images/rhealpix.png Binary files differnew file mode 100644 index 00000000..dc1c344a --- /dev/null +++ b/docs/source/usage/operations/projections/images/rhealpix.png diff --git a/docs/source/usage/operations/projections/images/robin.png b/docs/source/usage/operations/projections/images/robin.png Binary files differnew file mode 100644 index 00000000..42a49da2 --- /dev/null +++ b/docs/source/usage/operations/projections/images/robin.png diff --git a/docs/source/usage/operations/projections/images/rouss.png b/docs/source/usage/operations/projections/images/rouss.png Binary files differnew file mode 100644 index 00000000..2eca0fed --- /dev/null +++ b/docs/source/usage/operations/projections/images/rouss.png diff --git a/docs/source/usage/operations/projections/images/rpoly.png b/docs/source/usage/operations/projections/images/rpoly.png Binary files differnew file mode 100644 index 00000000..343127c1 --- /dev/null +++ b/docs/source/usage/operations/projections/images/rpoly.png diff --git a/docs/source/usage/operations/projections/images/sinu.png b/docs/source/usage/operations/projections/images/sinu.png Binary files differnew file mode 100644 index 00000000..9bef143a --- /dev/null +++ b/docs/source/usage/operations/projections/images/sinu.png diff --git a/docs/source/usage/operations/projections/images/somerc.png b/docs/source/usage/operations/projections/images/somerc.png Binary files differnew file mode 100644 index 00000000..1248e6ea --- /dev/null +++ b/docs/source/usage/operations/projections/images/somerc.png diff --git a/docs/source/usage/operations/projections/images/stere.png b/docs/source/usage/operations/projections/images/stere.png Binary files differnew file mode 100644 index 00000000..840050f0 --- /dev/null +++ b/docs/source/usage/operations/projections/images/stere.png diff --git a/docs/source/usage/operations/projections/images/sterea.png b/docs/source/usage/operations/projections/images/sterea.png Binary files differnew file mode 100644 index 00000000..d2aad552 --- /dev/null +++ b/docs/source/usage/operations/projections/images/sterea.png diff --git a/docs/source/usage/operations/projections/images/tcc.png b/docs/source/usage/operations/projections/images/tcc.png Binary files differnew file mode 100644 index 00000000..f968f62d --- /dev/null +++ b/docs/source/usage/operations/projections/images/tcc.png diff --git a/docs/source/usage/operations/projections/images/tcea.png b/docs/source/usage/operations/projections/images/tcea.png Binary files differnew file mode 100644 index 00000000..44212bd8 --- /dev/null +++ b/docs/source/usage/operations/projections/images/tcea.png diff --git a/docs/source/usage/operations/projections/images/tissot.png b/docs/source/usage/operations/projections/images/tissot.png Binary files differnew file mode 100644 index 00000000..2f785477 --- /dev/null +++ b/docs/source/usage/operations/projections/images/tissot.png diff --git a/docs/source/usage/operations/projections/images/tmerc.png b/docs/source/usage/operations/projections/images/tmerc.png Binary files differnew file mode 100644 index 00000000..b206c502 --- /dev/null +++ b/docs/source/usage/operations/projections/images/tmerc.png diff --git a/docs/source/usage/operations/projections/images/tpeqd.png b/docs/source/usage/operations/projections/images/tpeqd.png Binary files differnew file mode 100644 index 00000000..50291b68 --- /dev/null +++ b/docs/source/usage/operations/projections/images/tpeqd.png diff --git a/docs/source/usage/operations/projections/images/tpers.png b/docs/source/usage/operations/projections/images/tpers.png Binary files differnew file mode 100644 index 00000000..480f6dce --- /dev/null +++ b/docs/source/usage/operations/projections/images/tpers.png diff --git a/docs/source/usage/operations/projections/images/ups.png b/docs/source/usage/operations/projections/images/ups.png Binary files differnew file mode 100644 index 00000000..354b64ac --- /dev/null +++ b/docs/source/usage/operations/projections/images/ups.png diff --git a/docs/source/usage/operations/projections/images/urm5.png b/docs/source/usage/operations/projections/images/urm5.png Binary files differnew file mode 100644 index 00000000..088671c9 --- /dev/null +++ b/docs/source/usage/operations/projections/images/urm5.png diff --git a/docs/source/usage/operations/projections/images/urmfps.png b/docs/source/usage/operations/projections/images/urmfps.png Binary files differnew file mode 100644 index 00000000..86432790 --- /dev/null +++ b/docs/source/usage/operations/projections/images/urmfps.png diff --git a/docs/source/usage/operations/projections/images/utm.png b/docs/source/usage/operations/projections/images/utm.png Binary files differnew file mode 100644 index 00000000..3dcd5ee0 --- /dev/null +++ b/docs/source/usage/operations/projections/images/utm.png diff --git a/docs/source/usage/operations/projections/images/vandg.png b/docs/source/usage/operations/projections/images/vandg.png Binary files differnew file mode 100644 index 00000000..46fe2346 --- /dev/null +++ b/docs/source/usage/operations/projections/images/vandg.png diff --git a/docs/source/usage/operations/projections/images/vandg2.png b/docs/source/usage/operations/projections/images/vandg2.png Binary files differnew file mode 100644 index 00000000..597b5ae1 --- /dev/null +++ b/docs/source/usage/operations/projections/images/vandg2.png diff --git a/docs/source/usage/operations/projections/images/vandg3.png b/docs/source/usage/operations/projections/images/vandg3.png Binary files differnew file mode 100644 index 00000000..36d1ad04 --- /dev/null +++ b/docs/source/usage/operations/projections/images/vandg3.png diff --git a/docs/source/usage/operations/projections/images/vandg4.png b/docs/source/usage/operations/projections/images/vandg4.png Binary files differnew file mode 100644 index 00000000..163c1558 --- /dev/null +++ b/docs/source/usage/operations/projections/images/vandg4.png diff --git a/docs/source/usage/operations/projections/images/vitk1.png b/docs/source/usage/operations/projections/images/vitk1.png Binary files differnew file mode 100644 index 00000000..31034b3a --- /dev/null +++ b/docs/source/usage/operations/projections/images/vitk1.png diff --git a/docs/source/usage/operations/projections/images/wag1.png b/docs/source/usage/operations/projections/images/wag1.png Binary files differnew file mode 100644 index 00000000..a2bc8adc --- /dev/null +++ b/docs/source/usage/operations/projections/images/wag1.png diff --git a/docs/source/usage/operations/projections/images/wag2.png b/docs/source/usage/operations/projections/images/wag2.png Binary files differnew file mode 100644 index 00000000..b4abb48c --- /dev/null +++ b/docs/source/usage/operations/projections/images/wag2.png diff --git a/docs/source/usage/operations/projections/images/wag3.png b/docs/source/usage/operations/projections/images/wag3.png Binary files differnew file mode 100644 index 00000000..a2053815 --- /dev/null +++ b/docs/source/usage/operations/projections/images/wag3.png diff --git a/docs/source/usage/operations/projections/images/wag4.png b/docs/source/usage/operations/projections/images/wag4.png Binary files differnew file mode 100644 index 00000000..7d1c50b3 --- /dev/null +++ b/docs/source/usage/operations/projections/images/wag4.png diff --git a/docs/source/usage/operations/projections/images/wag5.png b/docs/source/usage/operations/projections/images/wag5.png Binary files differnew file mode 100644 index 00000000..487f6022 --- /dev/null +++ b/docs/source/usage/operations/projections/images/wag5.png diff --git a/docs/source/usage/operations/projections/images/wag6.png b/docs/source/usage/operations/projections/images/wag6.png Binary files differnew file mode 100644 index 00000000..dd49e8d0 --- /dev/null +++ b/docs/source/usage/operations/projections/images/wag6.png diff --git a/docs/source/usage/operations/projections/images/wag7.png b/docs/source/usage/operations/projections/images/wag7.png Binary files differnew file mode 100644 index 00000000..b9682755 --- /dev/null +++ b/docs/source/usage/operations/projections/images/wag7.png diff --git a/docs/source/usage/operations/projections/images/weren.png b/docs/source/usage/operations/projections/images/weren.png Binary files differnew file mode 100644 index 00000000..7deb132f --- /dev/null +++ b/docs/source/usage/operations/projections/images/weren.png diff --git a/docs/source/usage/operations/projections/images/wink1.png b/docs/source/usage/operations/projections/images/wink1.png Binary files differnew file mode 100644 index 00000000..6cbf48ae --- /dev/null +++ b/docs/source/usage/operations/projections/images/wink1.png diff --git a/docs/source/usage/operations/projections/images/wink2.png b/docs/source/usage/operations/projections/images/wink2.png Binary files differnew file mode 100644 index 00000000..21a23634 --- /dev/null +++ b/docs/source/usage/operations/projections/images/wink2.png diff --git a/docs/source/usage/operations/projections/images/wintri.png b/docs/source/usage/operations/projections/images/wintri.png Binary files differnew file mode 100644 index 00000000..54a0a85a --- /dev/null +++ b/docs/source/usage/operations/projections/images/wintri.png diff --git a/docs/source/usage/operations/projections/imw_p.rst b/docs/source/usage/operations/projections/imw_p.rst new file mode 100644 index 00000000..1fd3ded0 --- /dev/null +++ b/docs/source/usage/operations/projections/imw_p.rst @@ -0,0 +1,10 @@ +.. _imw_p: + +******************************************************************************** +International Map of the World Polyconic +******************************************************************************** + +.. image:: ./images/imw_p.png + :scale: 50% + :alt: International Map of the World Polyconic + diff --git a/docs/source/usage/operations/projections/index.rst b/docs/source/usage/operations/projections/index.rst new file mode 100644 index 00000000..904dc9e6 --- /dev/null +++ b/docs/source/usage/operations/projections/index.rst @@ -0,0 +1,146 @@ +.. _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 + + aeqd + airy + aitoff + alsk + apian + august + bacon + bipc + boggs + bonne + calcofi + cass + cc + ccon + cea + chamb + collg + crast + denoy + eck1 + eck2 + eck3 + eck4 + eck5 + eck6 + eqc + eqdc + euler + etmerc + fahey + fouc + fouc_s + gall + geos + gins8 + gn_sinu + gnom + goode + gs48 + gs50 + hammer + hatano + healpix + rhealpix + igh + 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 + moll + murd1 + murd2 + murd3 + natearth + nell + nell_h + nicol + nsper + nzmg + ob_tran + ocea + oea + omerc + ortel + ortho + pconic + poly + putp1 + putp2 + putp3 + putp3p + putp4p + putp5 + putp5p + putp6 + putp6p + qua_aut + qsc + robin + rouss + rpoly + sinu + somerc + stere + sterea + gstmerc + tcc + tcea + tissot + tmerc + tpeqd + tpers + ups + urm5 + urmfps + utm + vandg + vandg2 + vandg3 + vandg4 + vitk1 + wag1 + wag2 + wag3 + wag4 + wag5 + wag6 + wag7 + weren + wink1 + wink2 + wintri diff --git a/docs/source/usage/operations/projections/isea.rst b/docs/source/usage/operations/projections/isea.rst new file mode 100644 index 00000000..1b6457af --- /dev/null +++ b/docs/source/usage/operations/projections/isea.rst @@ -0,0 +1,10 @@ +.. _isea: + +******************************************************************************** +Icosahedral Snyder Equal Area +******************************************************************************** + +.. image:: ./images/isea.png + :scale: 50% + :alt: Icosahedral Snyder Equal Area + diff --git a/docs/source/usage/operations/projections/kav5.rst b/docs/source/usage/operations/projections/kav5.rst new file mode 100644 index 00000000..2ec5d1c1 --- /dev/null +++ b/docs/source/usage/operations/projections/kav5.rst @@ -0,0 +1,10 @@ +.. _kav5: + +******************************************************************************** +Kavraisky V +******************************************************************************** + +.. image:: ./images/kav5.png + :scale: 50% + :alt: Kavraisky V + diff --git a/docs/source/usage/operations/projections/kav7.rst b/docs/source/usage/operations/projections/kav7.rst new file mode 100644 index 00000000..8371e6ea --- /dev/null +++ b/docs/source/usage/operations/projections/kav7.rst @@ -0,0 +1,10 @@ +.. _kav7: + +******************************************************************************** +Kavraisky VII +******************************************************************************** + +.. image:: ./images/kav7.png + :scale: 50% + :alt: Kavraisky VII + diff --git a/docs/source/usage/operations/projections/krovak.rst b/docs/source/usage/operations/projections/krovak.rst new file mode 100644 index 00000000..6c774825 --- /dev/null +++ b/docs/source/usage/operations/projections/krovak.rst @@ -0,0 +1,10 @@ +.. _krovak: + +******************************************************************************** +Krovak +******************************************************************************** + +.. image:: ./images/krovak.png + :scale: 50% + :alt: Krovak + diff --git a/docs/source/usage/operations/projections/labrd.rst b/docs/source/usage/operations/projections/labrd.rst new file mode 100644 index 00000000..5be58db5 --- /dev/null +++ b/docs/source/usage/operations/projections/labrd.rst @@ -0,0 +1,10 @@ +.. _labrd: + +******************************************************************************** +Laborde +******************************************************************************** + +.. image:: ./images/labrd.png + :scale: 50% + :alt: Laborde + diff --git a/docs/source/usage/operations/projections/laea.rst b/docs/source/usage/operations/projections/laea.rst new file mode 100644 index 00000000..2377f294 --- /dev/null +++ b/docs/source/usage/operations/projections/laea.rst @@ -0,0 +1,10 @@ +.. _laea: + +******************************************************************************** +Lambert Azimuthal Equal Area +******************************************************************************** + +.. image:: ./images/laea.png + :scale: 50% + :alt: Lambert Azimuthal Equal Area + diff --git a/docs/source/usage/operations/projections/lagrng.rst b/docs/source/usage/operations/projections/lagrng.rst new file mode 100644 index 00000000..de9e5640 --- /dev/null +++ b/docs/source/usage/operations/projections/lagrng.rst @@ -0,0 +1,10 @@ +.. _lagrng: + +******************************************************************************** +Lagrange +******************************************************************************** + +.. image:: ./images/lagrng.png + :scale: 50% + :alt: Lagrange + diff --git a/docs/source/usage/operations/projections/larr.rst b/docs/source/usage/operations/projections/larr.rst new file mode 100644 index 00000000..9529f83f --- /dev/null +++ b/docs/source/usage/operations/projections/larr.rst @@ -0,0 +1,10 @@ +.. _larr: + +******************************************************************************** +Larrivee +******************************************************************************** + +.. image:: ./images/larr.png + :scale: 50% + :alt: Larrivee + diff --git a/docs/source/usage/operations/projections/lask.rst b/docs/source/usage/operations/projections/lask.rst new file mode 100644 index 00000000..d34dc8a0 --- /dev/null +++ b/docs/source/usage/operations/projections/lask.rst @@ -0,0 +1,10 @@ +.. _lask: + +******************************************************************************** +Laskowski +******************************************************************************** + +.. image:: ./images/lask.png + :scale: 50% + :alt: Laskowski + diff --git a/docs/source/usage/operations/projections/lcc.rst b/docs/source/usage/operations/projections/lcc.rst new file mode 100644 index 00000000..a3075e76 --- /dev/null +++ b/docs/source/usage/operations/projections/lcc.rst @@ -0,0 +1,10 @@ +.. _lcc: + +******************************************************************************** +Lambert Conformal Conic +******************************************************************************** + +.. image:: ./images/lcc.png + :scale: 50% + :alt: Lambert Conformal Conic + diff --git a/docs/source/usage/operations/projections/lcca.rst b/docs/source/usage/operations/projections/lcca.rst new file mode 100644 index 00000000..ca87e67e --- /dev/null +++ b/docs/source/usage/operations/projections/lcca.rst @@ -0,0 +1,10 @@ +.. _lcca: + +******************************************************************************** +Lambert Conformal Conic Alternative +******************************************************************************** + +.. image:: ./images/lcca.png + :scale: 50% + :alt: Lambert Conformal Conic Alternative + diff --git a/docs/source/usage/operations/projections/leac.rst b/docs/source/usage/operations/projections/leac.rst new file mode 100644 index 00000000..2957798e --- /dev/null +++ b/docs/source/usage/operations/projections/leac.rst @@ -0,0 +1,10 @@ +.. _leac: + +******************************************************************************** +Lambert Equal Area Conic +******************************************************************************** + +.. image:: ./images/leac.png + :scale: 50% + :alt: Lambert Equal Area Conic + diff --git a/docs/source/usage/operations/projections/lee_os.rst b/docs/source/usage/operations/projections/lee_os.rst new file mode 100644 index 00000000..711dc754 --- /dev/null +++ b/docs/source/usage/operations/projections/lee_os.rst @@ -0,0 +1,10 @@ +.. _lee_os: + +******************************************************************************** +Lee Oblated Stereographic +******************************************************************************** + +.. image:: ./images/lee_os.png + :scale: 50% + :alt: Lee Oblated Stereographic + diff --git a/docs/source/usage/operations/projections/loxim.rst b/docs/source/usage/operations/projections/loxim.rst new file mode 100644 index 00000000..e50ba472 --- /dev/null +++ b/docs/source/usage/operations/projections/loxim.rst @@ -0,0 +1,10 @@ +.. _loxim: + +******************************************************************************** +Loximuthal +******************************************************************************** + +.. image:: ./images/loxim.png + :scale: 50% + :alt: Loximuthal + diff --git a/docs/source/usage/operations/projections/lsat.rst b/docs/source/usage/operations/projections/lsat.rst new file mode 100644 index 00000000..fb64bdb2 --- /dev/null +++ b/docs/source/usage/operations/projections/lsat.rst @@ -0,0 +1,10 @@ +.. _lsat: + +******************************************************************************** +Space oblique for LANDSAT +******************************************************************************** + +.. image:: ./images/lsat.png + :scale: 50% + :alt: Space oblique for LANDSAT + diff --git a/docs/source/usage/operations/projections/mbt_fps.rst b/docs/source/usage/operations/projections/mbt_fps.rst new file mode 100644 index 00000000..55ebcf6c --- /dev/null +++ b/docs/source/usage/operations/projections/mbt_fps.rst @@ -0,0 +1,10 @@ +.. _mbt_fps: + +******************************************************************************** +McBryde-Thomas Flat-Pole Sine (No. 2) +******************************************************************************** + +.. image:: ./images/mbt_fps.png + :scale: 50% + :alt: McBryde-Thomas Flat-Pole Sine (No. 2) + diff --git a/docs/source/usage/operations/projections/mbt_s.rst b/docs/source/usage/operations/projections/mbt_s.rst new file mode 100644 index 00000000..9a355ec8 --- /dev/null +++ b/docs/source/usage/operations/projections/mbt_s.rst @@ -0,0 +1,10 @@ +.. _mbt_s: + +******************************************************************************** +McBryde-Thomas Flat-Polar Sine (No. 1) +******************************************************************************** + +.. image:: ./images/mbt_s.png + :scale: 50% + :alt: McBryde-Thomas Flat-Polar Sine (No. 1) + diff --git a/docs/source/usage/operations/projections/mbtfpp.rst b/docs/source/usage/operations/projections/mbtfpp.rst new file mode 100644 index 00000000..9be309d9 --- /dev/null +++ b/docs/source/usage/operations/projections/mbtfpp.rst @@ -0,0 +1,10 @@ +.. _mbtfpp: + +******************************************************************************** +McBride-Thomas Flat-Polar Parabolic +******************************************************************************** + +.. image:: ./images/mbtfpp.png + :scale: 50% + :alt: McBride-Thomas Flat-Polar Parabolic + diff --git a/docs/source/usage/operations/projections/mbtfpq.rst b/docs/source/usage/operations/projections/mbtfpq.rst new file mode 100644 index 00000000..295e814d --- /dev/null +++ b/docs/source/usage/operations/projections/mbtfpq.rst @@ -0,0 +1,10 @@ +.. _mbtfpq: + +******************************************************************************** +McBryde-Thomas Flat-Polar Quartic +******************************************************************************** + +.. image:: ./images/mbtfpq.png + :scale: 50% + :alt: McBryde-Thomas Flat-Polar Quartic + diff --git a/docs/source/usage/operations/projections/mbtfps.rst b/docs/source/usage/operations/projections/mbtfps.rst new file mode 100644 index 00000000..b9365361 --- /dev/null +++ b/docs/source/usage/operations/projections/mbtfps.rst @@ -0,0 +1,10 @@ +.. _mbtfps: + +******************************************************************************** +McBryde-Thomas Flat-Polar Sinusoidal +******************************************************************************** + +.. image:: ./images/mbtfps.png + :scale: 50% + :alt: McBryde-Thomas Flat-Polar Sinusoidal + diff --git a/docs/source/usage/operations/projections/merc.rst b/docs/source/usage/operations/projections/merc.rst new file mode 100644 index 00000000..8895abc8 --- /dev/null +++ b/docs/source/usage/operations/projections/merc.rst @@ -0,0 +1,140 @@ +.. _merc: + +******************************************************************************** +Mercator +******************************************************************************** + +The Mercator projection is a cylindrical map projection that origins from the 15th +century. It is widely recognized as the first regularly used map projection. +The projection is conformal which makes it suitable for navigational purposes. + + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_ts` | Latitude of true scale. Defaults to 0.0 | ++---------------------+----------------------------------------------------------+ +| `+k_0` | Scaling factor. Defaults to 1.0 | ++---------------------+----------------------------------------------------------+ + + + +.. image:: ./images/merc.png + :scale: 50% + :alt: Mercator + + +Usage +######## + +Applications should be limited to equatorial regions, but is frequently +used for navigational charts with latitude of true scale (``+lat_ts``) specified within +or near chart's boundaries. +Often inappropriately used for world maps since the regions near the poles +cannot be shown [Evenden1995]_. + + +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 ``+lat_ts`` and ``+k_0`` are mutually exclusive. +If used together, ``+lat_ts`` takes precedence over ``+k_0``. + +Mathematical definition +####################### + +The formulas describing the Mercator projection are all taken from G. Evenden's libproj manuals [Evenden2005]_. + +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_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] + + +Elliptical form +*************** + +For the elliptical form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = m\left( \phi_ts \right) + +where :math:`m\left(\phi\right)` is the parallel radius at latitude :math:`\phi`. + +We also use the Isometric Latitude kernel function :math:`t()`. + +.. note:: + m() and t() should be described properly on a separate page about the theory of projections on the ellipsoid. + +Forward projection +================== +.. math:: + + x = k_0 \lambda + +.. math:: + + y = k_0 \ln t \left( \phi \right) + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0} + +.. math:: + + \phi = t^{-1}\left[ e^{ -y/k_0 } \right] + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Mercator_projection>`_ +#. `Wolfram Mathworld <http://mathworld.wolfram.com/MercatorProjection.html>`_ + + diff --git a/docs/source/usage/operations/projections/mil_os.rst b/docs/source/usage/operations/projections/mil_os.rst new file mode 100644 index 00000000..5547e43c --- /dev/null +++ b/docs/source/usage/operations/projections/mil_os.rst @@ -0,0 +1,10 @@ +.. _mil_os: + +******************************************************************************** +Miller Oblated Stereographic +******************************************************************************** + +.. image:: ./images/mil_os.png + :scale: 50% + :alt: Miller Oblated Stereographic + diff --git a/docs/source/usage/operations/projections/mill.rst b/docs/source/usage/operations/projections/mill.rst new file mode 100644 index 00000000..eb9c2092 --- /dev/null +++ b/docs/source/usage/operations/projections/mill.rst @@ -0,0 +1,72 @@ +.. _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 | ++---------------------+--------------------------------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+--------------------------------------------------------------------------------+ +| **Options** | ++---------------------+--------------------------------------------------------------------------------+ +| `+lat_0` | Latitude of origin (Default to 0) | ++---------------------+--------------------------------------------------------------------------------+ + +.. image:: ./images/mill.png + :scale: 50% + :alt: Miller Cylindrical + +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) [Snyder1987]_. + +Example using Central meridian 90°W:: + + $ echo -100 35 | proj +proj=mill +lon_0=90w + -1113194.91 4061217.24 + +Mathematical definition +####################### + +The formulas describing the Miller projection are all taken from Snyder's manuals [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/docs/source/usage/operations/projections/moll.rst b/docs/source/usage/operations/projections/moll.rst new file mode 100644 index 00000000..1bd3d005 --- /dev/null +++ b/docs/source/usage/operations/projections/moll.rst @@ -0,0 +1,10 @@ +.. _moll: + +******************************************************************************** +Mollweide +******************************************************************************** + +.. image:: ./images/moll.png + :scale: 50% + :alt: Mollweide + diff --git a/docs/source/usage/operations/projections/murd1.rst b/docs/source/usage/operations/projections/murd1.rst new file mode 100644 index 00000000..71cbf155 --- /dev/null +++ b/docs/source/usage/operations/projections/murd1.rst @@ -0,0 +1,10 @@ +.. _murd1: + +******************************************************************************** +Murdoch I +******************************************************************************** + +.. image:: ./images/murd1.png + :scale: 50% + :alt: Murdoch I + diff --git a/docs/source/usage/operations/projections/murd2.rst b/docs/source/usage/operations/projections/murd2.rst new file mode 100644 index 00000000..b55cde35 --- /dev/null +++ b/docs/source/usage/operations/projections/murd2.rst @@ -0,0 +1,10 @@ +.. _murd2: + +******************************************************************************** +Murdoch II +******************************************************************************** + +.. image:: ./images/murd2.png + :scale: 50% + :alt: Murdoch II + diff --git a/docs/source/usage/operations/projections/murd3.rst b/docs/source/usage/operations/projections/murd3.rst new file mode 100644 index 00000000..70cc9276 --- /dev/null +++ b/docs/source/usage/operations/projections/murd3.rst @@ -0,0 +1,10 @@ +.. _murd3: + +******************************************************************************** +Murdoch III +******************************************************************************** + +.. image:: ./images/murd3.png + :scale: 50% + :alt: Murdoch III + diff --git a/docs/source/usage/operations/projections/natearth.rst b/docs/source/usage/operations/projections/natearth.rst new file mode 100644 index 00000000..57dd96db --- /dev/null +++ b/docs/source/usage/operations/projections/natearth.rst @@ -0,0 +1,47 @@ +.. _natearth: + +******************************************************************************** +Natural Earth +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Pseudo cylindrical | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Implemented by** | Bernhard Jenny | ++---------------------+--------------------------------------------------------+ +| **Options** | ++---------------------+--------------------------------------------------------+ +| `No special options for this projection` | ++---------------------+--------------------------------------------------------+ + +.. image:: ./images/natearth.png + :scale: 50% + :alt: Natural Earth + + +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 + + +Further reading +################################################################################ + +#. `Wikipedia <https://en.wikipedia.org/wiki/Natural_Earth_projection>`_ diff --git a/docs/source/usage/operations/projections/nell.rst b/docs/source/usage/operations/projections/nell.rst new file mode 100644 index 00000000..c6a3771c --- /dev/null +++ b/docs/source/usage/operations/projections/nell.rst @@ -0,0 +1,10 @@ +.. _nell: + +******************************************************************************** +Nell +******************************************************************************** + +.. image:: ./images/nell.png + :scale: 50% + :alt: Nell + diff --git a/docs/source/usage/operations/projections/nell_h.rst b/docs/source/usage/operations/projections/nell_h.rst new file mode 100644 index 00000000..6a3b26ba --- /dev/null +++ b/docs/source/usage/operations/projections/nell_h.rst @@ -0,0 +1,10 @@ +.. _nell_h: + +******************************************************************************** +Nell-Hammer +******************************************************************************** + +.. image:: ./images/nell_h.png + :scale: 50% + :alt: Nell-Hammer + diff --git a/docs/source/usage/operations/projections/nicol.rst b/docs/source/usage/operations/projections/nicol.rst new file mode 100644 index 00000000..995cedb5 --- /dev/null +++ b/docs/source/usage/operations/projections/nicol.rst @@ -0,0 +1,10 @@ +.. _nicol: + +******************************************************************************** +Nicolosi Globular +******************************************************************************** + +.. image:: ./images/nicol.png + :scale: 50% + :alt: Nicolosi Globular + diff --git a/docs/source/usage/operations/projections/nsper.rst b/docs/source/usage/operations/projections/nsper.rst new file mode 100644 index 00000000..4a8651fc --- /dev/null +++ b/docs/source/usage/operations/projections/nsper.rst @@ -0,0 +1,10 @@ +.. _nsper: + +******************************************************************************** +Near-sided perspective +******************************************************************************** + +.. image:: ./images/nsper.png + :scale: 50% + :alt: Near-sided perspective + diff --git a/docs/source/usage/operations/projections/nzmg.rst b/docs/source/usage/operations/projections/nzmg.rst new file mode 100644 index 00000000..926655d8 --- /dev/null +++ b/docs/source/usage/operations/projections/nzmg.rst @@ -0,0 +1,10 @@ +.. _nzmg: + +******************************************************************************** +New Zealand Map Grid +******************************************************************************** + +.. image:: ./images/nzmg.png + :scale: 50% + :alt: New Zealand Map Grid + diff --git a/docs/source/usage/operations/projections/ob_tran.rst b/docs/source/usage/operations/projections/ob_tran.rst new file mode 100644 index 00000000..3c996336 --- /dev/null +++ b/docs/source/usage/operations/projections/ob_tran.rst @@ -0,0 +1,10 @@ +.. _ob_tran: + +******************************************************************************** +General Oblique Transformation +******************************************************************************** + +.. image:: ./images/ob_tran.png + :scale: 50% + :alt: General Oblique Transformation + diff --git a/docs/source/usage/operations/projections/ocea.rst b/docs/source/usage/operations/projections/ocea.rst new file mode 100644 index 00000000..40005d9e --- /dev/null +++ b/docs/source/usage/operations/projections/ocea.rst @@ -0,0 +1,10 @@ +.. _ocea: + +******************************************************************************** +Oblique Cylindrical Equal Area +******************************************************************************** + +.. image:: ./images/ocea.png + :scale: 50% + :alt: Oblique Cylindrical Equal Area + diff --git a/docs/source/usage/operations/projections/oea.rst b/docs/source/usage/operations/projections/oea.rst new file mode 100644 index 00000000..379dc157 --- /dev/null +++ b/docs/source/usage/operations/projections/oea.rst @@ -0,0 +1,10 @@ +.. _oea: + +******************************************************************************** +Oblated Equal Area +******************************************************************************** + +.. image:: ./images/oea.png + :scale: 50% + :alt: Oblated Equal Area + diff --git a/docs/source/usage/operations/projections/omerc.rst b/docs/source/usage/operations/projections/omerc.rst new file mode 100644 index 00000000..114b9fa3 --- /dev/null +++ b/docs/source/usage/operations/projections/omerc.rst @@ -0,0 +1,10 @@ +.. _omerc: + +******************************************************************************** +Oblique Mercator +******************************************************************************** + +.. image:: ./images/omerc.png + :scale: 50% + :alt: Oblique Mercator + diff --git a/docs/source/usage/operations/projections/ortel.rst b/docs/source/usage/operations/projections/ortel.rst new file mode 100644 index 00000000..03f132ef --- /dev/null +++ b/docs/source/usage/operations/projections/ortel.rst @@ -0,0 +1,10 @@ +.. _ortel: + +******************************************************************************** +Ortelius Oval +******************************************************************************** + +.. image:: ./images/ortel.png + :scale: 50% + :alt: Ortelius Oval + diff --git a/docs/source/usage/operations/projections/ortho.rst b/docs/source/usage/operations/projections/ortho.rst new file mode 100644 index 00000000..131dbfc7 --- /dev/null +++ b/docs/source/usage/operations/projections/ortho.rst @@ -0,0 +1,10 @@ +.. _ortho: + +******************************************************************************** +Orthographic +******************************************************************************** + +.. image:: ./images/ortho.png + :scale: 50% + :alt: Orthographic + diff --git a/docs/source/usage/operations/projections/pconic.rst b/docs/source/usage/operations/projections/pconic.rst new file mode 100644 index 00000000..6bc0018e --- /dev/null +++ b/docs/source/usage/operations/projections/pconic.rst @@ -0,0 +1,10 @@ +.. _pconic: + +******************************************************************************** +Perspective Conic +******************************************************************************** + +.. image:: ./images/pconic.png + :scale: 50% + :alt: Perspective Conic + diff --git a/docs/source/usage/operations/projections/poly.rst b/docs/source/usage/operations/projections/poly.rst new file mode 100644 index 00000000..e252feb5 --- /dev/null +++ b/docs/source/usage/operations/projections/poly.rst @@ -0,0 +1,10 @@ +.. _poly: + +******************************************************************************** +Polyconic (American) +******************************************************************************** + +.. image:: ./images/poly.png + :scale: 50% + :alt: Polyconic (American) + diff --git a/docs/source/usage/operations/projections/putp1.rst b/docs/source/usage/operations/projections/putp1.rst new file mode 100644 index 00000000..68971a46 --- /dev/null +++ b/docs/source/usage/operations/projections/putp1.rst @@ -0,0 +1,10 @@ +.. _putp1: + +******************************************************************************** +Putnins P1 +******************************************************************************** + +.. image:: ./images/putp1.png + :scale: 50% + :alt: Putnins P1 + diff --git a/docs/source/usage/operations/projections/putp2.rst b/docs/source/usage/operations/projections/putp2.rst new file mode 100644 index 00000000..01ea8073 --- /dev/null +++ b/docs/source/usage/operations/projections/putp2.rst @@ -0,0 +1,10 @@ +.. _putp2: + +******************************************************************************** +Putnins P2 +******************************************************************************** + +.. image:: ./images/putp2.png + :scale: 50% + :alt: Putnins P2 + diff --git a/docs/source/usage/operations/projections/putp3.rst b/docs/source/usage/operations/projections/putp3.rst new file mode 100644 index 00000000..3aa6b9e6 --- /dev/null +++ b/docs/source/usage/operations/projections/putp3.rst @@ -0,0 +1,10 @@ +.. _putp3: + +******************************************************************************** +Putnins P3 +******************************************************************************** + +.. image:: ./images/putp3.png + :scale: 50% + :alt: Putnins P3 + diff --git a/docs/source/usage/operations/projections/putp3p.rst b/docs/source/usage/operations/projections/putp3p.rst new file mode 100644 index 00000000..5b87512e --- /dev/null +++ b/docs/source/usage/operations/projections/putp3p.rst @@ -0,0 +1,10 @@ +.. _putp3p: + +******************************************************************************** +Putnins P3' +******************************************************************************** + +.. image:: ./images/putp3p.png + :scale: 50% + :alt: Putnins P3' + diff --git a/docs/source/usage/operations/projections/putp4p.rst b/docs/source/usage/operations/projections/putp4p.rst new file mode 100644 index 00000000..b211ad9b --- /dev/null +++ b/docs/source/usage/operations/projections/putp4p.rst @@ -0,0 +1,10 @@ +.. _putp4p: + +******************************************************************************** +Putnins P4' +******************************************************************************** + +.. image:: ./images/putp4p.png + :scale: 50% + :alt: Putnins P4' + diff --git a/docs/source/usage/operations/projections/putp5.rst b/docs/source/usage/operations/projections/putp5.rst new file mode 100644 index 00000000..5b60a961 --- /dev/null +++ b/docs/source/usage/operations/projections/putp5.rst @@ -0,0 +1,10 @@ +.. _putp5: + +******************************************************************************** +Putnins P5 +******************************************************************************** + +.. image:: ./images/putp5.png + :scale: 50% + :alt: Putnins P5 + diff --git a/docs/source/usage/operations/projections/putp5p.rst b/docs/source/usage/operations/projections/putp5p.rst new file mode 100644 index 00000000..f586b889 --- /dev/null +++ b/docs/source/usage/operations/projections/putp5p.rst @@ -0,0 +1,10 @@ +.. _putp5p: + +******************************************************************************** +Putnins P5' +******************************************************************************** + +.. image:: ./images/putp5p.png + :scale: 50% + :alt: Putnins P5' + diff --git a/docs/source/usage/operations/projections/putp6.rst b/docs/source/usage/operations/projections/putp6.rst new file mode 100644 index 00000000..94683ace --- /dev/null +++ b/docs/source/usage/operations/projections/putp6.rst @@ -0,0 +1,10 @@ +.. _putp6: + +******************************************************************************** +Putnins P6 +******************************************************************************** + +.. image:: ./images/putp6.png + :scale: 50% + :alt: Putnins P6 + diff --git a/docs/source/usage/operations/projections/putp6p.rst b/docs/source/usage/operations/projections/putp6p.rst new file mode 100644 index 00000000..8c3add71 --- /dev/null +++ b/docs/source/usage/operations/projections/putp6p.rst @@ -0,0 +1,10 @@ +.. _putp6p: + +******************************************************************************** +Putnins P6' +******************************************************************************** + +.. image:: ./images/putp6p.png + :scale: 50% + :alt: Putnins P6' + diff --git a/docs/source/usage/operations/projections/qsc.rst b/docs/source/usage/operations/projections/qsc.rst new file mode 100644 index 00000000..e3af2cee --- /dev/null +++ b/docs/source/usage/operations/projections/qsc.rst @@ -0,0 +1,158 @@ +.. _qsc: + +******************************************************************************** +Quadrilateralized Spherical Cube +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Martin Lambers | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_0` | Latitude (in degrees) of the view position. | ++---------------------+----------------------------------------------------------+ +| `+lon_0` | Longitude (in degrees) of the view position. | ++---------------------+----------------------------------------------------------+ + +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 + :scale: 50% + :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 [LambersKolb2012]_ for an example. + +The QSC projection was introduced by [ONeilLaubscher1976]_, +building on previous work by [ChanONeil1975]_. For clarity: The +earlier QSC variant described in [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 [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 [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| | | | ++------------+--------------+-------------+------------+ + +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/docs/source/usage/operations/projections/qua_aut.rst b/docs/source/usage/operations/projections/qua_aut.rst new file mode 100644 index 00000000..d3a0aece --- /dev/null +++ b/docs/source/usage/operations/projections/qua_aut.rst @@ -0,0 +1,10 @@ +.. _qua_aut: + +******************************************************************************** +Quartic Authalic +******************************************************************************** + +.. image:: ./images/qua_aut.png + :scale: 50% + :alt: Quartic Authalic + diff --git a/docs/source/usage/operations/projections/rhealpix.rst b/docs/source/usage/operations/projections/rhealpix.rst new file mode 100644 index 00000000..b8ed4f5f --- /dev/null +++ b/docs/source/usage/operations/projections/rhealpix.rst @@ -0,0 +1,51 @@ +.. _rhealpix: + +******************************************************************************** +rHEALPix +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Mixed | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Alex Raichev and Michael Speth | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+north_square` | Position of the north polar square. | +| | Valid inputs are 0--3. Defaults to 0. | ++---------------------+----------------------------------------------------------+ +| `+south_square` | Position of the south polar square. | +| | Valid inputs are 0--3. Defaults to 0. | ++---------------------+----------------------------------------------------------+ + +.. 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 + + +Further reading +################################################################################ + +#. `NASA <http://healpix.jpl.nasa.gov/>`_ +#. `Wikipedia <https://en.wikipedia.org/wiki/HEALPix>`_ diff --git a/docs/source/usage/operations/projections/robin.rst b/docs/source/usage/operations/projections/robin.rst new file mode 100644 index 00000000..3e58be46 --- /dev/null +++ b/docs/source/usage/operations/projections/robin.rst @@ -0,0 +1,10 @@ +.. _robin: + +******************************************************************************** +Robinson +******************************************************************************** + +.. image:: ./images/robin.png + :scale: 50% + :alt: Robinson + diff --git a/docs/source/usage/operations/projections/rouss.rst b/docs/source/usage/operations/projections/rouss.rst new file mode 100644 index 00000000..e27fb1cf --- /dev/null +++ b/docs/source/usage/operations/projections/rouss.rst @@ -0,0 +1,10 @@ +.. _rouss: + +******************************************************************************** +Roussilhe Stereographic +******************************************************************************** + +.. image:: ./images/rouss.png + :scale: 50% + :alt: Roussilhe Stereographic + diff --git a/docs/source/usage/operations/projections/rpoly.rst b/docs/source/usage/operations/projections/rpoly.rst new file mode 100644 index 00000000..80e0d640 --- /dev/null +++ b/docs/source/usage/operations/projections/rpoly.rst @@ -0,0 +1,10 @@ +.. _rpoly: + +******************************************************************************** +Rectangular Polyconic +******************************************************************************** + +.. image:: ./images/rpoly.png + :scale: 50% + :alt: Rectangular Polyconic + diff --git a/docs/source/usage/operations/projections/sinu.rst b/docs/source/usage/operations/projections/sinu.rst new file mode 100644 index 00000000..a7ebd232 --- /dev/null +++ b/docs/source/usage/operations/projections/sinu.rst @@ -0,0 +1,24 @@ +.. _sinu: + +******************************************************************************** +Sinusoidal (Sanson-Flamsteed) +******************************************************************************** + +.. image:: ./images/sinu.png + :scale: 50% + :alt: Sinusoidal (Sanson-Flamsteed) + +MacBryde and Thomas developed generalized formulas for sever 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 } + diff --git a/docs/source/usage/operations/projections/somerc.rst b/docs/source/usage/operations/projections/somerc.rst new file mode 100644 index 00000000..c572622b --- /dev/null +++ b/docs/source/usage/operations/projections/somerc.rst @@ -0,0 +1,10 @@ +.. _somerc: + +******************************************************************************** +Swiss. Obl. Mercator +******************************************************************************** + +.. image:: ./images/somerc.png + :scale: 50% + :alt: Swiss. Obl. Mercator + diff --git a/docs/source/usage/operations/projections/stere.rst b/docs/source/usage/operations/projections/stere.rst new file mode 100644 index 00000000..d4958ec9 --- /dev/null +++ b/docs/source/usage/operations/projections/stere.rst @@ -0,0 +1,10 @@ +.. _stere: + +******************************************************************************** +Stereographic +******************************************************************************** + +.. image:: ./images/stere.png + :scale: 50% + :alt: Stereographic + diff --git a/docs/source/usage/operations/projections/sterea.rst b/docs/source/usage/operations/projections/sterea.rst new file mode 100644 index 00000000..4f2f8727 --- /dev/null +++ b/docs/source/usage/operations/projections/sterea.rst @@ -0,0 +1,10 @@ +.. _sterea: + +******************************************************************************** +Oblique Stereographic Alternative +******************************************************************************** + +.. image:: ./images/sterea.png + :scale: 50% + :alt: Oblique Stereographic Alternative + diff --git a/docs/source/usage/operations/projections/tcc.rst b/docs/source/usage/operations/projections/tcc.rst new file mode 100644 index 00000000..586dd3b8 --- /dev/null +++ b/docs/source/usage/operations/projections/tcc.rst @@ -0,0 +1,10 @@ +.. _tcc: + +******************************************************************************** +Transverse Central Cylindrical +******************************************************************************** + +.. image:: ./images/tcc.png + :scale: 50% + :alt: Transverse Central Cylindrical + diff --git a/docs/source/usage/operations/projections/tcea.rst b/docs/source/usage/operations/projections/tcea.rst new file mode 100644 index 00000000..cf5549a3 --- /dev/null +++ b/docs/source/usage/operations/projections/tcea.rst @@ -0,0 +1,10 @@ +.. _tcea: + +******************************************************************************** +Transverse Cylindrical Equal Area +******************************************************************************** + +.. image:: ./images/tcea.png + :scale: 50% + :alt: Transverse Cylindrical Equal Area + diff --git a/docs/source/usage/operations/projections/tissot.rst b/docs/source/usage/operations/projections/tissot.rst new file mode 100644 index 00000000..7ec1a741 --- /dev/null +++ b/docs/source/usage/operations/projections/tissot.rst @@ -0,0 +1,10 @@ +.. _tissot: + +******************************************************************************** +Tissot +******************************************************************************** + +.. image:: ./images/tissot.png + :scale: 50% + :alt: Tissot + diff --git a/docs/source/usage/operations/projections/tmerc.rst b/docs/source/usage/operations/projections/tmerc.rst new file mode 100644 index 00000000..1fc0cd7e --- /dev/null +++ b/docs/source/usage/operations/projections/tmerc.rst @@ -0,0 +1,197 @@ +.. _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. + ++---------------------+--------------------------------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+--------------------------------------------------------------------------------+ +| **Available forms** | Forward and inverse, Spherical and Elliptical | ++---------------------+--------------------------------------------------------------------------------+ +| **Defined area** | Global, but reasonably accurate only within 15 degrees of the central meridian | ++---------------------+--------------------------------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+--------------------------------------------------------------------------------+ +| **Options** | ++---------------------+--------------------------------------------------------------------------------+ +| `+lat_0` | Latitude of origin (Default to 0) | ++---------------------+--------------------------------------------------------------------------------+ +| `+k0` | Scale factor at natural origin (Default to 1) | ++---------------------+--------------------------------------------------------------------------------+ + + +.. image:: ./images/tmerc.png + :scale: 50% + :alt: Transverse Mercator + +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 6° | 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 | Always 6° | 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=1 +x_0=3500000 +y_0=0 +ellps=bessel +datum=potsdam +units=m +no_defs + 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.9996 +x_0=2520000 +y_0=0 +ellps=intl +units=m +no_defs + 2520000.00 4649858.60 + +Mathematical definition +####################### + +The formulas describing the Transverse Mercator are all taken from Evenden's [Evenden2005]_. + +:math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``. + +:math:`k_0` is the scale factor at the natural origin (on the central meridian). It can be set with ``+k_0``. + +:math:`M(\phi)` is the meridional distance. + +Spherical form +************** + +Forward projection +================== + +.. math:: + + B = \cos \phi \sin \lambda + +.. math:: + + x = \frac{k_0}{2} \ln(\frac{1+B}{1-B}) + +.. math:: + + y = k_0 ( \arctan(\frac{\tan(\phi)}{\cos \lambda}) - \phi_0) + + +Inverse projection +================== + +.. math:: + + D = \frac{y}{k_0} + \phi_0 + +.. math:: + + x' = \frac{x}{k_0} + +.. math:: + + \phi = \arcsin(\frac{\sin D}{\cosh x'}) + +.. math:: + + \lambda = \arctan(\frac{\sinh x'}{\cos D}) + + +Elliptical form +*************** + +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/Universal_Transverse_Mercator_coordinate_system>`_ +#. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas <http://www.ihsenergy.com/epsg/guid7.pdf>`_ diff --git a/docs/source/usage/operations/projections/tpeqd.rst b/docs/source/usage/operations/projections/tpeqd.rst new file mode 100644 index 00000000..e6d7ef29 --- /dev/null +++ b/docs/source/usage/operations/projections/tpeqd.rst @@ -0,0 +1,10 @@ +.. _tpeqd: + +******************************************************************************** +Two Point Equidistant +******************************************************************************** + +.. image:: ./images/tpeqd.png + :scale: 50% + :alt: Two Point Equidistant + diff --git a/docs/source/usage/operations/projections/tpers.rst b/docs/source/usage/operations/projections/tpers.rst new file mode 100644 index 00000000..345a5faa --- /dev/null +++ b/docs/source/usage/operations/projections/tpers.rst @@ -0,0 +1,39 @@ +.. _tpers: + +******************************************************************************** +Tilted perspective +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+h` | Height (in meters) above the surface. Required. | ++---------------------+----------------------------------------------------------+ +| `+azi` | Bearing (in degrees) from due north. | ++---------------------+----------------------------------------------------------+ +| `+tilt` | Angle (in degrees) away from nadir. | ++---------------------+----------------------------------------------------------+ +| `+lat_0` | Latitude (in degrees) of the view position. | ++---------------------+----------------------------------------------------------+ +| `+lon_0` | Longitude (in degrees) of the view position. | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/tpers.png + :scale: 50% + :alt: Tilted perspective + + +Tilted Perspective is similar to :ref:`nsper` (``nsper``) in that it simulates a +perspective view from a hight. Where ``nsper`` projects onto a plane tangent to +the surface, Tilted Perspective orients the plane towards the direction of the +view. Thus, extra parameters azi and tilt are required beyond `nsper``'s ``h``. +As with ``nsper``, ``lat_0`` & ``lon_0`` are also required +for satellite position. diff --git a/docs/source/usage/operations/projections/ups.rst b/docs/source/usage/operations/projections/ups.rst new file mode 100644 index 00000000..7a9ab50b --- /dev/null +++ b/docs/source/usage/operations/projections/ups.rst @@ -0,0 +1,10 @@ +.. _ups: + +******************************************************************************** +Universal Polar Stereographic +******************************************************************************** + +.. image:: ./images/ups.png + :scale: 50% + :alt: Universal Polar Stereographic + diff --git a/docs/source/usage/operations/projections/urm5.rst b/docs/source/usage/operations/projections/urm5.rst new file mode 100644 index 00000000..91d06308 --- /dev/null +++ b/docs/source/usage/operations/projections/urm5.rst @@ -0,0 +1,10 @@ +.. _urm5: + +******************************************************************************** +Urmaev V +******************************************************************************** + +.. image:: ./images/urm5.png + :scale: 50% + :alt: Urmaev V + diff --git a/docs/source/usage/operations/projections/urmfps.rst b/docs/source/usage/operations/projections/urmfps.rst new file mode 100644 index 00000000..515ced84 --- /dev/null +++ b/docs/source/usage/operations/projections/urmfps.rst @@ -0,0 +1,10 @@ +.. _urmfps: + +******************************************************************************** +Urmaev Flat-Polar Sinusoidal +******************************************************************************** + +.. image:: ./images/urmfps.png + :scale: 50% + :alt: Urmaev Flat-Polar Sinusoidal + diff --git a/docs/source/usage/operations/projections/utm.rst b/docs/source/usage/operations/projections/utm.rst new file mode 100644 index 00000000..7fb66cb8 --- /dev/null +++ b/docs/source/usage/operations/projections/utm.rst @@ -0,0 +1,10 @@ +.. _utm: + +******************************************************************************** +Universal Transverse Mercator (UTM) +******************************************************************************** + +.. image:: ./images/utm.png + :scale: 50% + :alt: Universal Transverse Mercator (UTM) + diff --git a/docs/source/usage/operations/projections/vandg.rst b/docs/source/usage/operations/projections/vandg.rst new file mode 100644 index 00000000..cdc772bb --- /dev/null +++ b/docs/source/usage/operations/projections/vandg.rst @@ -0,0 +1,10 @@ +.. _vandg: + +******************************************************************************** +van der Grinten (I) +******************************************************************************** + +.. image:: ./images/vandg.png + :scale: 50% + :alt: van der Grinten (I) + diff --git a/docs/source/usage/operations/projections/vandg2.rst b/docs/source/usage/operations/projections/vandg2.rst new file mode 100644 index 00000000..556929e2 --- /dev/null +++ b/docs/source/usage/operations/projections/vandg2.rst @@ -0,0 +1,10 @@ +.. _vandg2: + +******************************************************************************** +van der Grinten II +******************************************************************************** + +.. image:: ./images/vandg2.png + :scale: 50% + :alt: van der Grinten II + diff --git a/docs/source/usage/operations/projections/vandg3.rst b/docs/source/usage/operations/projections/vandg3.rst new file mode 100644 index 00000000..d767c4d5 --- /dev/null +++ b/docs/source/usage/operations/projections/vandg3.rst @@ -0,0 +1,10 @@ +.. _vandg3: + +******************************************************************************** +van der Grinten III +******************************************************************************** + +.. image:: ./images/vandg3.png + :scale: 50% + :alt: van der Grinten III + diff --git a/docs/source/usage/operations/projections/vandg4.rst b/docs/source/usage/operations/projections/vandg4.rst new file mode 100644 index 00000000..097ba1d8 --- /dev/null +++ b/docs/source/usage/operations/projections/vandg4.rst @@ -0,0 +1,10 @@ +.. _vandg4: + +******************************************************************************** +van der Grinten IV +******************************************************************************** + +.. image:: ./images/vandg4.png + :scale: 50% + :alt: van der Grinten IV + diff --git a/docs/source/usage/operations/projections/vitk1.rst b/docs/source/usage/operations/projections/vitk1.rst new file mode 100644 index 00000000..b9081547 --- /dev/null +++ b/docs/source/usage/operations/projections/vitk1.rst @@ -0,0 +1,10 @@ +.. _vitk1: + +******************************************************************************** +Vitkovsky I +******************************************************************************** + +.. image:: ./images/vitk1.png + :scale: 50% + :alt: Vitkovsky I + diff --git a/docs/source/usage/operations/projections/wag1.rst b/docs/source/usage/operations/projections/wag1.rst new file mode 100644 index 00000000..dd1ed39e --- /dev/null +++ b/docs/source/usage/operations/projections/wag1.rst @@ -0,0 +1,10 @@ +.. _wag1: + +******************************************************************************** +Wagner I (Kavraisky VI) +******************************************************************************** + +.. image:: ./images/wag1.png + :scale: 50% + :alt: Wagner I (Kavraisky VI) + diff --git a/docs/source/usage/operations/projections/wag2.rst b/docs/source/usage/operations/projections/wag2.rst new file mode 100644 index 00000000..9c7b0edc --- /dev/null +++ b/docs/source/usage/operations/projections/wag2.rst @@ -0,0 +1,18 @@ +.. _wag2: + +******************************************************************************** +Wagner II +******************************************************************************** + +.. image:: ./images/wag2.png + :scale: 50% + :alt: Wagner II + + +.. math:: + + x &= 0.92483 \lambda \cos \theta + + y &= 1.38725\theta + + \sin \theta &= 0.88022 \sin(0.8855\phi) diff --git a/docs/source/usage/operations/projections/wag3.rst b/docs/source/usage/operations/projections/wag3.rst new file mode 100644 index 00000000..fb70a0a6 --- /dev/null +++ b/docs/source/usage/operations/projections/wag3.rst @@ -0,0 +1,16 @@ +.. _wag3: + +******************************************************************************** +Wagner III +******************************************************************************** + +.. image:: ./images/wag3.png + :scale: 50% + :alt: Wagner III + + +.. math:: + + x &= [\cos\phi_{ts} / \cos ( 2\phi_{ts} / 3)] \lambda \cos (2\phi /3) + + y = \phi diff --git a/docs/source/usage/operations/projections/wag4.rst b/docs/source/usage/operations/projections/wag4.rst new file mode 100644 index 00000000..7b8dac96 --- /dev/null +++ b/docs/source/usage/operations/projections/wag4.rst @@ -0,0 +1,10 @@ +.. _wag4: + +******************************************************************************** +Wagner IV +******************************************************************************** + +.. image:: ./images/wag4.png + :scale: 50% + :alt: Wagner IV + diff --git a/docs/source/usage/operations/projections/wag5.rst b/docs/source/usage/operations/projections/wag5.rst new file mode 100644 index 00000000..f880290b --- /dev/null +++ b/docs/source/usage/operations/projections/wag5.rst @@ -0,0 +1,10 @@ +.. _wag5: + +******************************************************************************** +Wagner V +******************************************************************************** + +.. image:: ./images/wag5.png + :scale: 50% + :alt: Wagner V + diff --git a/docs/source/usage/operations/projections/wag6.rst b/docs/source/usage/operations/projections/wag6.rst new file mode 100644 index 00000000..f74749a5 --- /dev/null +++ b/docs/source/usage/operations/projections/wag6.rst @@ -0,0 +1,10 @@ +.. _wag6: + +******************************************************************************** +Wagner VI +******************************************************************************** + +.. image:: ./images/wag6.png + :scale: 50% + :alt: Wagner VI + diff --git a/docs/source/usage/operations/projections/wag7.rst b/docs/source/usage/operations/projections/wag7.rst new file mode 100644 index 00000000..be1401b8 --- /dev/null +++ b/docs/source/usage/operations/projections/wag7.rst @@ -0,0 +1,10 @@ +.. _wag7: + +******************************************************************************** +Wagner VII +******************************************************************************** + +.. image:: ./images/wag7.png + :scale: 50% + :alt: Wagner VII + diff --git a/docs/source/usage/operations/projections/weren.rst b/docs/source/usage/operations/projections/weren.rst new file mode 100644 index 00000000..de7c5abf --- /dev/null +++ b/docs/source/usage/operations/projections/weren.rst @@ -0,0 +1,10 @@ +.. _weren: + +******************************************************************************** +Werenskiold I +******************************************************************************** + +.. image:: ./images/weren.png + :scale: 50% + :alt: Werenskiold I + diff --git a/docs/source/usage/operations/projections/wink1.rst b/docs/source/usage/operations/projections/wink1.rst new file mode 100644 index 00000000..00346765 --- /dev/null +++ b/docs/source/usage/operations/projections/wink1.rst @@ -0,0 +1,10 @@ +.. _wink1: + +******************************************************************************** +Winkel I +******************************************************************************** + +.. image:: ./images/wink1.png + :scale: 50% + :alt: Winkel I + diff --git a/docs/source/usage/operations/projections/wink2.rst b/docs/source/usage/operations/projections/wink2.rst new file mode 100644 index 00000000..7e9b48a7 --- /dev/null +++ b/docs/source/usage/operations/projections/wink2.rst @@ -0,0 +1,10 @@ +.. _wink2: + +******************************************************************************** +Winkel II +******************************************************************************** + +.. image:: ./images/wink2.png + :scale: 50% + :alt: Winkel II + diff --git a/docs/source/usage/operations/projections/wintri.rst b/docs/source/usage/operations/projections/wintri.rst new file mode 100644 index 00000000..bfd5032f --- /dev/null +++ b/docs/source/usage/operations/projections/wintri.rst @@ -0,0 +1,10 @@ +.. _wintri: + +******************************************************************************** +Winkel Tripel +******************************************************************************** + +.. image:: ./images/wintri.png + :scale: 50% + :alt: Winkel Tripel + diff --git a/docs/source/usage/operations/transformations/deformation.rst b/docs/source/usage/operations/transformations/deformation.rst new file mode 100644 index 00000000..2489f18e --- /dev/null +++ b/docs/source/usage/operations/transformations/deformation.rst @@ -0,0 +1,148 @@ +.. _deformation: + +================================================================================ +Kinematic datum shifting utilizing a deformation model +================================================================================ + +Perform datum shifts means of a deformation/velocity model. + ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `xy_grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ +| `z_grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ +| `t_epoch` | Central epoch of transformation. [decimalyear]. Only used in | +| | spatiotemporal transformations. | ++-----------------+--------------------------------------------------------------------+ +| `t_obs` | Observation time of coordinate(s). Mostly useful in 2D and 3D | +| | transformations. [decimalyear]. *Optional*. | ++-----------------+--------------------------------------------------------------------+ + +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. Tntraplate +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. +Details about the formats can be found in the GDAL documentation. GDAL both reads and +writes both file formats. Using GDAL for construction of new grids is recommended. + +Example +------------------------------------------------------------------------------- + +In [Häkli2016]_ 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 ERTS89. Scandinavia is an area with significant post-glacial +rebound. The deformations from the post-glacial uplift is not accounted for in the +offcial ETRS89 transformations so in order to get accurate transformations in the Nordic +countries it is necesarry 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 transpose + 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 + xy_grids = ./nkgrf03vel_realigned_xy.ct2 + z_grids = ./nkgrf03vel_realigned_z.gtx + # NKG_ETRF@2000.0 -> ETRF92@2000.0 + step proj=helmert transpose 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 t_epoch = 1994.704 t_obs = 2000.0 + xy_grids = ./nkgrf03vel_realigned_xy.ct2 + z_grids = ./nkgrf03vel_realigned_z.gtx + +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 + xy_grids = ./nkgrf03vel_realigned_xy.ct2 + z_grids = ./nkgrf03vel_realigned_z.gtx + +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 *xy_grids* and *z_grids*. The first is +the horizontal part of the model and the second is the vertical component. + +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_c` and :math:`t_{obs}` determine the magnitude of the coordinate +correcton 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_c - t_{obs}) + \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. Consequentyly though, the input coordinates needs to be converted to +lat/long space when searching for corrections in the grid. This is done with *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. diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst new file mode 100644 index 00000000..03e5db15 --- /dev/null +++ b/docs/source/usage/operations/transformations/helmert.rst @@ -0,0 +1,388 @@ +.. _helmert: + +================================================================================ +Helmert transform +================================================================================ + +The Helmert transformation changes coordinates from one reference frame to +anoether by means of 3-, 4-and 7-parameter shifts, or one of their 6-, 8- and +14-parameter kinematic counterparts. + ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Options** | ++----------------+--------------------------------------------------------------------+ +| `x` | Translation of the x-axis [m]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `y` | Translation of the y-axis [m]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `z` | Translation of the z-axis. [m]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `s` | Scale factor [ppm]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `rx` | X-axis rotation in the 3D Helmert [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `ry` | Y-axis rotatoin in the 3D Helmert [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `rz` | Z-axis rotation in the 3D Helmert [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `theta` | Rotation angle in the 2D Helmert. [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dx` | Translation rate of the x-axis. [m/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dy` | Translation rate of the y-axis. [m/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dz` | Translation rate of the z-axis. [m/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `ds` | Scale rate factor [ppm/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `drx` | Rotation rate of the x-axis [arc seconds/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dry` | Rotation rate of the y-axis [arc seconds/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `drz` | Rotation rate of the y-axis [arc seconds/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `t_epoch` | Central epoch of transformation. [decimalyear]. Only used in | +| | spatiotemporal transformations. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `t_obs` | Observation time of coordinate(s). Mostly useful in 2D and 3D | +| | transformations. [decimalyear]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `exact` | Use exact transformation equations. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `transpose` | Transpose rotation matrix. *Optional*. | ++----------------+--------------------------------------------------------------------+ + +The Helmert transform, in all it's various incarnations, is used to perform reference +frame shifts. The transformation operates in cartesian space. It can be used to transform +planar coordinates from one datum to another, transform 3D cartesian +coordinates from one static reference frame to another or it can be used to do fully +kinematic transformations from global reference frames to local static frames. + +All of the parameters described in the table above are marked as optional. This is true +as long as at least one parameter is defined in the setup of the transformation. +The behaviour of the transformation depends on which parameters are used in the setup. +For instance, if a rate of change paramater is specified a kinematic version of the +transformation is used. + +The kinematic transformations require an observation time of the coordinate, as well +as a central epoch for the transformation. The latter is usually documented +alongside the rest of the transformation parameters for a given transformation. +The central eopch is controlled with the parameter `t_epoch`. The observation +time can either by stated as part of the coordinate when using PROJ's +4D-functionality or it can be controlled in the transformation setup by the +parameter `t_obs`. When `t_obs` is specified, all transformed coordinates are +treated as if they have the same observation time. + +Examples ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert: + +:: + + proj=helmert ellps=GRS80 x=-9597.3572 y=.6112 + s=0.304794780637 theta=-1.244048 + +Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters: + +:: + + proj=helmert ellps=GRS80 x=0.67678 y=0.65495 z=-0.52827 + rx=-0.022742 ry=0.012667 rz=0.022704 s=-0.01070 + +Transformation from `ITRF2000@2017.0` to `ITRF93@2017.0` using 15 parameters: + +:: + + proj=helmert ellps=GRS80 + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + rx=-0.00039 ry=0.00080 rz=-0.00114 + drx=-0.00011 dry=-0.00019 drz=0.00007 + epoch=1988.0 tobs=2017.0 transpose + +Mathematical description ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In the notation used below, :math:`\hat{P}` is the rate of change of a given transformation +parameter :math:`P`. :math:`\dot{P}` is the kinematically adjusted version of :math:`P`, +described by + +.. math:: + :label: propagation + + \dot{P}= P + \hat{P}\left(t - t_{central}\right) + +where :math:`t` is the observation time of the coordinate and :math:`t_{central}` is +the central epoch of the transformation. Equation :eq:`propagation` can be used to +propagate all transformation parameters in time. + +Superscripts of vectors denote the reference frame the coordinates in the vector belong to. + + +2D Helmert +------------------------------------------------------------------------------- + +The simplest version of the Helmert transform is the 2D case. In the 2-dimensional +case only the horizontal coordinates are changed. The coordinates can be +translated, rotated and scale. Translation is controlled with the `x` and `y` +parameters. The rotation is determined by `theta` and the scale is controlled with +the `s` paramaters. + +.. note:: + + The scaling parameter `s` is unitless for the 2D Helmert, as opposed to the + 3D version where the scaling parameter is given in units of ppm. + +Mathematically the 2D Helmert is described as: + +.. math:: + :label: 4param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + \end{bmatrix} + + s + \begin{bmatrix} + \hphantom{-}\cos \theta & \sin \theta \\ + -\sin \theta & \cos \theta \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + + +:eq:`4param` can be extended to a time-varying kinematic version by +adjusting the parameters with :eq:`propagation` to :eq:`4param`, which yields +the kinematic 2D Helmert transform: + +.. math:: + :label: 8param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \end{bmatrix} + + s(t) + \begin{bmatrix} + \hphantom{-}\cos \dot{\theta} & \sin \dot{\theta} \\ + -\sin\ \dot{\theta} & \cos \dot{\theta} \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + +All parameters in :eq:`8param` are determined by the use of :eq:`propagation`, +which applies the rate of change to each individual parameter for a given +timespan between :math:`t` and :math:`t_{central}`. + + +3D Helmert +------------------------------------------------------------------------------- + +The general form of the 3D Helmert is + +.. math:: + :label: general-helmert + + + \begin{align} + V^B = T + \left(1 + s \times 10^{-6}\right) \mathbf{R} V^A + \end{align} + +Where :math:`T` is a vector consisting of the three translation parameters, :math:`s` +is the scaling factor and :math:`\mathbf{R}` is a rotation matrix. :math:`V^A` and +:math:`V^B` are coordinate vectors, with :math:`V^A` being the input coordinate and +:math:`V^B` is the output coordinate. + +The rotation matrix is composed of three rotation matrices, one for each axis: + +.. math:: + + \begin{align} + \mathbf{R}_X &= \begin{bmatrix} 1 & 0 & 0\\ 0 & \cos\phi & -\sin\phi\\ 0 & \sin\phi & \cos\phi \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Y &= \begin{bmatrix} \cos\theta & 0 & \sin\theta\\ 0 & 1 & 0\\ -\sin\theta & 0 & \cos\theta \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Z &= \begin{bmatrix} \cos\psi & -\sin\psi & 0\\ \sin\psi & \cos\psi & 0\\ 0 & 0 & 1 \end{bmatrix} + \end{align} + +The three rotation matrices can be combined in one: + +.. math:: + + \begin{align} + \mathbf{R} = \mathbf{R_X} \mathbf{R_Y} \mathbf{R_Y} + \end{align} + +For :math:`\mathbf{R}`, this yields: + +.. math:: + :label: rot_exact + + \begin{bmatrix} + \cos\theta \cos\psi & -\cos\phi \sin\psi + \sin\phi \sin\theta \cos\psi & \sin\phi \sin\psi + \cos\phi \sin\theta \cos\psi \\ + \cos\theta\sin\psi & \cos\phi \cos\psi + \sin\phi \sin\theta \sin\psi & - \sin\phi \cos\psi + \cos\phi \sin\theta \sin\psi \\ + -\sin\theta & \sin\phi \cos\theta & \cos\phi \cos\theta \\ + \end{bmatrix} + + +Using the small angle approxition the rotation matrix can be simplified to + +.. math:: + :label: rot_approx + + \begin{align} \mathbf{R} = + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \end{align} + +Which allow us to express the most common version of the Helmert transform, +using the approximated rotation matrix: + + +.. math:: + :label: 7param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \left(1 + s \times 10^{-6}\right) + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +If the rotation matrix is transposed the transformation is effectively reversed. +This is cause for some confusion since there is no correct way of defining the +rotation matrix. Two conventions exists and they seem to be equally popular. +In PROJ the rotation matrix can be transposed by adding the `transpose` flag in +the transformation setup. + +Applying :eq:`propagation` we get the kinematic version of the approximated +3D Helmert: + +.. math:: + :label: 14param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \left(1 + \dot{s} \times 10^{-6}\right) + \begin{bmatrix} + 1 & -\dot{R_z} & \dot{R_y} \\ + \dot{R_z} & 1 & -\dot{R_x} \\ + -\dot{R_y} & \dot{R_x} & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + + + + +The Helmert transformation can be applied without using the rotation parameters, +in which case it becomes a simlpe translation of the origin of the coordinate +system. When using the Helmert in this version equation :eq:`general-helmert` +simplies to: + +.. math:: + :label: 3param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +That after application of :eq:`propagation` has the following kinematic +countpart: + +.. math:: + :label: 6param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} diff --git a/docs/source/usage/operations/transformations/hgridshift.rst b/docs/source/usage/operations/transformations/hgridshift.rst new file mode 100644 index 00000000..7f3c9895 --- /dev/null +++ b/docs/source/usage/operations/transformations/hgridshift.rst @@ -0,0 +1,39 @@ +.. _hgridshift: + +================================================================================ +Horizontal grid shift +================================================================================ + +Change of horizontal datum by grid shift. + ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `+grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ + +The horizontal grid shift is done by offsetting the planar input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid:: + + +hgridshift +grids=nzgr2kgrid0005.gsb + + +More than one grid can be loaded at the same time, for instance in case the +dataset needs to be transformed spans several countries. In this example grids +of the continental US, Alaska and Canada is loaded at the same time:: + + +hgridshift +grids=@conus,@alaska,@ntv2_0.gsb,@ntv_can.dat + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ search path. The list of grids is prioritized so that +grids in the start of the list takes presedence over the grids in the back of the +list. + +PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections. Details +about all three formats can be found in the GDAL documentation. GDAL reads and +writes all three formats. Using GDAL for construction of new grids is recommended. diff --git a/docs/source/usage/operations/transformations/index.rst b/docs/source/usage/operations/transformations/index.rst new file mode 100644 index 00000000..5112ffa2 --- /dev/null +++ b/docs/source/usage/operations/transformations/index.rst @@ -0,0 +1,17 @@ +.. _transformation_list: + +================================================================================ +Transformations +================================================================================ + +Transformations coordinate operation in which the two coordinate reference +systems are based on different datums. + +.. toctree:: + :maxdepth: 1 + + deformation + helmert + molodensky + hgridshift + vgridshift diff --git a/docs/source/usage/operations/transformations/molodensky.rst b/docs/source/usage/operations/transformations/molodensky.rst new file mode 100644 index 00000000..d4ff3e79 --- /dev/null +++ b/docs/source/usage/operations/transformations/molodensky.rst @@ -0,0 +1,74 @@ +.. _molodensky: + +================================================================================ +Molodensky transform +================================================================================ + +The Molodensky transformation resembles a :ref:`Helmert` with zero +rotations and a scale of unity, but converts directly from geodetic coordinates to +geodetic coordinates, without the intermediate shifts to and from cartesian +geocentric coordinates, associated with the Helmert transformation. +The Molodensky transformation is simple to implement and to parameterize, requiring +only the 3 shifts between the input and output frame, and the corresponding +differences between the semimajor axes and flattening parameters of the reference +ellipsoids. Due to its algorithmic simplicity, it was popular prior to the +ubiquity of digital computers. Today, it is mostly interesting for historical +reasons, but nevertheless indispensable due to the large amount of data that has +already been transformed that way [EversKnudsen2017]_. + ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates. | ++---------------------+----------------------------------------------------------+ +| **Output type** | Geodetic coordinates. | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+da` | Difference in semimajor axis of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+df` | Difference in flattening of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+dx` | Offset of the X-axes of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+dy` | Offset of the Y-axes of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+dz` | Offset of the Z-axes of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+ellps` | Ellipsoid definition of source coordinates. | +| | Any specification can be used (e.g. `+a`, `+rf`, etc). | +| | If not specified, default ellipsoid is used. | ++---------------------+----------------------------------------------------------+ +| `+abridged` | Use the abridged version of the Molodensky transform. | +| | Optional. | ++---------------------+----------------------------------------------------------+ + +The Molodensky transform can be used to perform a datum shift from coordinate +:math:`(\phi_1, \lambda_1, h_1)` to :math:`(\phi_2, \lambda_2, h_2)` where the two +coordinates are referenced to different ellipsoids. This is based on three +assumptions: + + 1. The cartesian axes, :math:`X, Y, Z`, of the two ellipsoids are parallel. + 2. The offset, :math:`\delta X, \delta Y, \delta Z`, between the two ellipsoid + are known. + 3. The characteristics of the two ellipsoids, expressed as the difference in + semimajor axis (:math:`\delta a`) and flattening (:math:`\delta f`), are known. + +The Molodensky transform is mostly used for transforming between old systems +dating back to the time before computers. The advantage of the Molodensky transform +is that it is fairly simple to compute by hand. The ease of computation come at the +cost of limited accuracy. + +A derivation of the mathematical formulas for the Molodensky transform can be found +in [Deakin2004]_. + + +Examples +############################################################################### + +The abridged Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 abridged + +The same transformation using the standard Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 + diff --git a/docs/source/usage/operations/transformations/vgridshift.rst b/docs/source/usage/operations/transformations/vgridshift.rst new file mode 100644 index 00000000..e9f78310 --- /dev/null +++ b/docs/source/usage/operations/transformations/vgridshift.rst @@ -0,0 +1,41 @@ +.. _vgridshift: + +================================================================================ +Vertical grid shift +================================================================================ + +Change Vertical datum change by grid shift + ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical). | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates (horizontal), meters (vertical). | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `+grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ + +The vertical grid shift is done by offsetting the vertical input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid. Here we change the vertical +reference from the ellipsoid to the global geoid model, EGM96:: + + +vgridshift +grids=egm96_16.gtx + + +More than one grid can be loaded at the same time, for instance in the case where +a better geoid model than the global is available for a certain area. Here the +gridshift is set up so that the local DVR90 geoid model takes presedence over +the global model:: + + +vgridshift +grids=@dvr90.gtx,egm96_16.gtx + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ search path. The list of grids is prioritized so that +grids in the start of the list takes presedence over the grids in the back of the +list. + +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. diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst new file mode 100644 index 00000000..645c1eb1 --- /dev/null +++ b/docs/source/usage/projections.rst @@ -0,0 +1,164 @@ +.. _projections_intro: + +================================================================================ +Cartographic projection +================================================================================ + +The foundation of PROJ is the large number of +:doc:`projections<operations/projections/index>` available in the library. This section +is devoted to the generic parameters that can be used on any projection in the +PROJ library. + +Below is a list of PROJ parameters which can be applied to most coordinate +system definitions. This table does not attempt to describe the parameters +particular to particular projection types. These can be found on the pages +documenting the individual :doc:`projections<operations/projections/index>`. + + ========== ================================================================ + Parameter Description + ========== ================================================================ + +a Semimajor radius of the ellipsoid axis + +axis Axis orientation + +b Semiminor radius of the ellipsoid axis + +ellps Ellipsoid name (see ``proj -le``) + +k Scaling factor (deprecated) + +k_0 Scaling factor + +lat_0 Latitude of origin + +lon_0 Central meridian + +lon_wrap Center longitude to use for wrapping (see below) + +no_defs Don't use the /usr/share/proj/proj_def.dat defaults file + +over Allow longitude output outside -180 to 180 range, disables + wrapping (see below) + +pm Alternate prime meridian (typically a city name, see below) + +proj Projection name (see ``proj -l``) + +units meters, US survey feet, etc. + +vunits vertical units. + +x_0 False easting + +y_0 False northing + ========== ================================================================ + +In the sections below most of the parameters are explained in details. + +Units ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Horizontal units can be specified using the ``+units`` keyword with a symbolic +name for a unit (ie. ``us-ft``). Alternatively the translation to meters can be +specified with the ``+to_meter`` keyword (ie. 0.304800609601219 for US feet). The +``-lu`` argument to ``cs2cs`` or ``proj`` can be used to list symbolic unit names. +The default unit for projected coordinates is the meter. +A few special projections deviate from this behaviour, most notably the +latlong pseudo-projection that returns degrees. + +Vertical (Z) units can be specified using the ``+vunits`` keyword with a +symbolic name for a unit (ie. ``us-ft``). Alternatively the translation to +meters can be specified with the ``+vto_meter`` keyword (ie. 0.304800609601219 +for US feet). The ``-lu`` argument to ``cs2cs`` or ``proj`` can be used to list +symbolic unit names. If no vertical units are specified, the vertical units will +default to be the same as the horizontal coordinates. + +.. note:: + ``proj`` do not handle vertical units at all and hence the ``+vto_meter`` + argument will be ignored. + +Scaling of output units can be done by applying the ``+k_0`` argument. The +returned coordinates are scaled by the value assigned with the ``+k_0`` +parameter. + +False Easting/Northing ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Virtually all coordinate systems allow for the presence of a false easting +(``+x_0``) and northing (``+y_0``). Note that these values are always expressed in +meters even if the coordinate system is some other units. Some coordinate +systems (such as UTM) have implicit false easting and northing values. + +Longitude Wrapping ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +By default PROJ wraps output longitudes in the range -180 to 180. The ``+over`` +switch can be used to disable the default wrapping which is done at a low level +in ``pj_inv()``. This is particularly useful with projections like the +:doc:`equidistant cylindrical<operations/projections/eqc>` +where it would be desirable for X values past -20000000 (roughly) to continue +past -180 instead of wrapping to +180. + +The ``+lon_wrap`` option can be used to provide an alternative means of doing +longitude wrapping within ``pj_transform()``. The argument to this option is a +center longitude. So ``+lon_wrap=180`` means wrap longitudes in the range 0 to +360. Note that ``+over`` does **not** disable ``+lon_wrap``. + +Prime Meridian ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +A prime meridian may be declared indicating the offset between the prime +meridian of the declared coordinate system and that of greenwich. A prime +meridian is clared using the "pm" parameter, and may be assigned a symbolic +name, or the longitude of the alternative prime meridian relative to greenwich. + +Currently prime meridian declarations are only utilized by the +``pj_transform()`` API call, not the ``pj_inv()`` and ``pj_fwd()`` calls. +Consequently the user utility ``cs2cs`` does honour prime meridians but the +``proj`` user utility ignores them. + +The following predeclared prime meridian names are supported. These can be +listed using with ``cs2cs -lm``. + + =========== ================ + Meridian Longitude + =========== ================ + greenwich 0dE + lisbon 9d07'54.862"W + paris 2d20'14.025"E + bogota 74d04'51.3"E + madrid 3d41'16.48"W + rome 12d27'8.4"E + bern 7d26'22.5"E + jakarta 106d48'27.79"E + ferro 17d40'W + brussels 4d22'4.71"E + stockholm 18d3'29.8"E + athens 23d42'58.815"E + oslo 10d43'22.5"E + =========== ================ + +Example of use. The location ``long=0``, ``lat=0`` in the greenwich based lat/long +coordinates is translated to lat/long coordinates with Madrid as the prime +meridian. + +:: + + cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid + 0 0 <i>(input)</i> + 3d41'16.48"E 0dN 0.000 <i>(output)</i> + + +Axis orientation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Starting in PROJ 4.8.0, the +axis argument can be used to control the axis +orientation of the coordinate system. The default orientation is "easting, +northing, up" but directions can be flipped, or axes flipped using combinations +of the axes in the +axis switch. The values are: + +* "e" - Easting +* "w" - Westing +* "n" - Northing +* "s" - Southing +* "u" - Up +* "d" - Down + +They can be combined in +axis in forms like: + +* ``+axis=enu`` - the default easting, northing, elevation. +* ``+axis=neu`` - northing, easting, up - useful for "lat/long" geographic + coordinates, or south orientated transverse mercator. +* ``+axis=wnu`` - westing, northing, up - some planetary coordinate systems + have "west positive" coordinate systems + +.. note:: + + The ``+axis`` argument does not work with the ``proj`` command line + utility. + + diff --git a/docs/source/usage/quickstart.rst b/docs/source/usage/quickstart.rst new file mode 100644 index 00000000..2cf66122 --- /dev/null +++ b/docs/source/usage/quickstart.rst @@ -0,0 +1,68 @@ +.. _quickstart: + +================================================================================ +Quick start +================================================================================ + +Coordinate transformations are defined by, what in PROJ terminology is +known as, "proj-strings". A proj-string describes any transformation regardless of +how simple or complicated it might be. The simplest case is projection of geodetic +coordinates. This section focuses on the simpler cases and introduces the basic +anatomy of the proj-string. The complex cases are discussed in +:doc:`transformation`. + +A proj-strings holds the parameters of a given coordinate transformation, e.g. + +:: + + +proj=merc +lat_ts=56.5 +ellps=GRS80 + +I.e. a proj-string consists of a projection specifier, ``+proj``, a number of +parameters that applies to the projection and, if needed, a description of a +datum shift. In the example above geodetic coordinates are transformed to +projected space with the :doc:`Mercator projection<operations/projections/merc>` with +the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every +projection in PROJ is identified by a shorthand such as ``merc`` in the above +example. + +By using the above projection definition as parameters for the command line +utility ``proj`` we can convert the geodetic coordinates to projected space: + +:: + + $ proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + +If called as above ``proj`` will be in interactive mode, letting you type the +input data manually and getting a responce presented on screen. ``proj`` +works as any UNIX filter though, which means that you can also pipe data to +the utility, for instance by using the ``echo`` command: + +:: + + $ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + 3399483.80 752085.60 + + +PROJ also comes bundled with the ``cs2cs`` utility which is used to transform +from onecoordinate reference system to another. Say we want to convert +the above Mercator coordinates to UTM, we can do that with ``cs2cs``: + +:: + + $ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to +proj=utm +zone=32 + 6103992.36 1924052.47 0.00 + +Notice the ``+to`` parameter that seperates the source and destination +projection definitions. + +If you happen to know the EPSG identifiers for the two cordinates reference +systems you are transforming between you can use those with ``cs2cs``: + +:: + + $ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832 + 231950.54 1920310.71 0.00 + +In the above example we transform geodetic coordinates in the WGS84 reference +frame to UTM zone 32N coordinates in the ETRS89 reference frame. +UTM coordinates diff --git a/docs/source/usage/resource_files.rst b/docs/source/usage/resource_files.rst new file mode 100644 index 00000000..7a1dea8b --- /dev/null +++ b/docs/source/usage/resource_files.rst @@ -0,0 +1,121 @@ +.. _resource_files: + +================================================================================ +Resource files +================================================================================ + +A number of files containing preconfigured transformations and default parameters +for certain projections are bundled with the PROJ distribution. Init files +contains preconfigured proj-strings for various coordinate reference systems +and the defaults file contains default values for parameters of select +projections. + +Init files +------------------------------------------------------------------------------- + +Init files are used for preconfiguring proj-strings for often used +transformations, such as those found in the EPSG database. Most init files contain +transformations from a given coordinate reference system to WGS84. This makes +it easy to transformations between any two coordinate reference systems with +``cs2cs``. Init files can however contain any proj-string and don't necesarily +have to follow the *cs2cs* paradigm where WGS84 is used as a pivot datum. The +ITRF init file is a good example of that. + +A number of init files come pre-bundled with PROJ but it is also possible to +add your own custom init files. PROJ looks for the init files in the directoty +listed in the ``PROJ_LIB`` environment variable. + +The format of init files made up of a identifier in angled brackets and a +proj-string: + +:: + + <3819> +proj=longlat +ellps=bessel + +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs <> + +The above example is the first entry from the ``epsg`` init file. So, this is the +coordinate reference system with ID 3819 in the EPSG database. Comments can be +inserted by prefixing them with a "#". With version 4.10.0 a new special metadata +entry is now accepted in init files. It can be parsed with a function from the public +API. The metadata entry in the epsg init file looks like this at the time of writing: + +:: + +<metadata> +version=9.0.0 +origin=EPSG +lastupdate=2017-01-10 + +Pre-configured proj-strings from init files are used in the following way: + +:: + + $ cs2cs -v +proj=latlong +to +init=epsg:3819 + # ---- From Coordinate System ---- + #Lat/long (Geodetic alias) + # + # +proj=latlong +ellps=WGS84 + # ---- To Coordinate System ---- + #Lat/long (Geodetic alias) + # + # +init=epsg:3819 +proj=longlat +ellps=bessel + # +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs + +It is possible to override parameters when using ``+init``. Just add the parameter +to the proj-string alongside the ``+init`` parameter. For instance by overriding +the ellipsoid as in the following example + +:: + + +init=epsg:25832 +ellps=intl + +where the Hayford ellipsoid is used instead of the predefined GRS80 ellipsoid. +It is also possible to add additional parameters not specified in the init file, +for instance by adding an obervation epoch when transforming from ITRF2000 to +ITRF2005: + +:: + + +init=ITRF2000:ITRF2005 +tobs=2010.5 + +which then expands to + +:: + + +proj=helmert +x=-0.0001 +y=0.0008 +z=0.0058 +s=-0.0004 + +dx=0.0002 +dy=-0.0001 +dz=0.0018 +ds=-0.000008 + +epoch=2000.0 +transpose + +tobs=2010.5 + +Below is a list of the init files that are packaged with PROJ. + + ======== ================================================================ + Name Description + ======== ================================================================ + esri Auto-generated mapping from Esri projection index. Not + maintained any more + epsg EPSG database + GL27 Great Lakes Grids + IGNF French coordinate systems supplied by the IGNF + ITRF2000 Full set of transformation parameters between ITRF2000 and other + ITRF's + ITRF2008 Full set of transformation parameters between ITRF2008 and other + ITRF's + ITRF2014 Full set of transformation parameters between ITRF2014 and other + ITRF's + nad27 State plane coordinate systems, North American Datum 1927 + nad83 State plane coordinate systems, North American Datum 1983 + ======== ================================================================ + + +Defaults file +------------------------------------------------------------------------------- + +The ``proj_def.dat`` file supplies default parameters for PROJ. It uses the same +syntax as the init files described above. The identifiers in the defaults file +describe to what the parameters should apply. If the ``<general>`` identifier is +used, then all parameters in that section applies for all proj-strings. Otherwise +the identifier is connected to a specific projection. With the defaults file +supplied with PROJ the default ellipsoid is set to WGS84 (for all proj-strings). +Apart from that only the Albers Equal Area, +:doc:`Lambert Conic Conformal<operations/projections/lcc>` and the +:doc:`Lagrange<operations/projections/lagrng>` projections have default parameters. +Defaults can be ignored by adding the ``+no_def`` parameter to a proj-string. + diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst new file mode 100644 index 00000000..2f5ee880 --- /dev/null +++ b/docs/source/usage/transformation.rst @@ -0,0 +1,314 @@ +.. _transformation: + +================================================================================ +Geodetic transformation +================================================================================ + +PROJ can do everything from the most simple projection to very complex +transformations across many reference frames. While originally developed as a +tool for cartographic projections, PROJ has over time evolved into a powerfull +generic coordinate transformation engine that makes it possible to do both +large scale cartographic projections as well as coordinate transformation at a +geodetic high precision level. This chapter delves into the details of how +geodetec transformations of varying complexity can be performed. + +In PROJ, two frameworks for geodetic transformations exists, the *cs2cs* +framework and the *transformation pipelines* framework. The first is the original, +and limited, framework for doing geodetic transforms in PROJ The latter is a +newer addition that aims to be a more complete transformation framework. Both are +described in the sections below. Large portions of the text are based on +[EversKnudsen2017]_. + +Before describing the details of the two frameworks, let us first remark that +most cases of geodetic transformations can be expressed as a series of elementary +operations, the output of one operation being the input of the next. E.g. when +going from UTM zone 32, datum ED50, to UTM zone 32, datum ETRS89, one must, in the +simplest case, go through 5 steps: + +1. Back-project the UTM coordinates to geographic coordinates +2. Convert the geographic coordinates to 3D cartesian geocentric coordinates +3. Apply a Helmert transformation from ED50 to ETRS89 +4. Convert back from cartesian to geographic coordinates +5. Finally project the geographic coordinates to UTM zone 32 planar coordinates. + + +Transformation pipelines ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The homology between the above steps and a Unix shell style pipeline is evident. +It is there the main architectural inspiration behind the transformation pipeline +framework. The pipeline framework is realized by utilizing a special "projection", +that takes as its user supplied arguments, a series of elementary operations, +which it strings together in order to implement the full transformation needed. +Additionally, a number of elementary geodetic operations, including Helmert +transformations, general high order polynomial shifts and the Molodensky +transformation are available as part of the pipeline framework. +In anticipation of upcoming support for full time-varying transformations, we +also introduce a 4D spatiotemporal data type, and a programming interface +(API) for handling this. + +The Molodensky transformation converts directly from geodetic coordinates +in one datum, to geodetic coordinates in another datum, while the (typically more +accurate) Helmert transformation converts from 3D cartesian to 3D cartesian +coordinates. So when using the Helmert transformation one typically needs to do an +initial conversion from geodetic to cartesian coordinates, and a final conversion +the other way round, to arrive at the desired result. Fortunately, this three-step +compound transformation has the attractive characteristic that each step depends +only on the output of the immediately preceding step. Hence, we can build a +geodetic-to-geodetic Helmert transformation by tying together the outputs and inputs +of 3 steps (geodetic-to-cartesian → Helmert → cartesian-to-geodetic), pipeline style. +The pipeline driver, makes this kind of chained transformations possible. +The implementation is compact, consisting of just one pseudo-projection, called +``pipeline``, which takes as its arguments strings of elementary projections +(note: "projection" is the, slightly misleading, PROJ term used for any kind of +transformation). +The pipeline pseudo projection is supplemented by a number of elementary +transformations, all in all providing a framework for building high accuracy +solutions for a wide spectrum of geodetic tasks. + + +As a first example, let us take a look at the iconic +*geodetic → Cartesian → Helmert → geodetic* case (steps 2 to 4 in the example in +the itroduction). In PROJ it can be implemented as + +:: + + proj=pipeline + step proj=cart ellps=intl + step proj=helmert + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + +The pipeline can be expanded at both ends to accommodate whatever coordinate type +is needed for input and output: In the example below, we transform from the +deprecated Danish System 45, a 2D system with some tension in the original defining +network, to UTM zone 33, ETRS89. The tension is reduced using a polynomial +transformation (the init=./s45b... step, s45b.pol is a file containing the +polynomial coefficients), taking the S45 coordinates to a technical coordinate +system (TC32), defined to represent "UTM zone 32 coordinates, as they would look if +the Helmert transformation between ED50 and ETRS89 was perfect". The TC32 +coordinates are then converted back to geodetic(ED50) coordinates, using an +inverse UTM projection, further to cartesian(ED50), then to cartesian(ETRS89), +using the relevant Helmert transformation, and back to geodetic(ETRS89), before +finally being projected onto the UTM zone 33, ETRS89 system. All in all a 6 step +pipeline, implementing a transformation with centimeter level accuracy from a +deprecated system with decimeter level tensions. + +:: + + proj=pipeline + step init=./s45b.pol:s45b_tc32 + step proj=utm inv ellps=intl zone=32 + step proj=cart ellps=intl + step proj=helmert + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + step proj=utm ellps=GRS80 zone=33 + +With the pipeline framework spatiotemporal transformation is possible. This is +possible by leveraging the time dimension in PROJ that enables 4D coordinates +(three spatial components and one temporal component) to be passed through a +transformation pipeline. In the example below a transformation from ITRF93 to +ITRF2000 is defined. The temporal component is given as GPS weeks in the input +data, but the 14-parameter Helmert transform expects temporal units in decimalyears. +Hence the first step in the pipeline is the unitconvert pseudo-projection that makes +sure the correct units are passed along to the Helmert transform. +Most parameters of the Helmert transform are taken from [AltamimiEtAl2002]_, +except the epoch which is the epoch of the transformation. The default setting is to +use “coordinate frame” convention of the Helmert transform, but “position vector” +convention can also be used. The last step in the pipeline is converting the +coordinate timestamps back to GPS weeks. + +:: + + proj=pipeline + step proj=unitconvert t_in=gps_week t_out=decimalyear + step proj=helmert + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + rx=0.00039 ry=-0.00080 rz=0.00114 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + drx=0.00011 dry=0.00019 drz=-0.00007 + epoch=1988.0 + step proj=unitconvert t_in=decimalyear t_out=gps_week + + +cs2cs paradigm ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + ============ ============================================================== + Parameter Description + ============ ============================================================== + +datum Datum name (see ``proj -ld``) + +geoidgrids Filename of GTX grid file to use for vertical datum transforms + +nadgrids Filename of NTv2 grid file to use for datum transforms + +towgs84 3 or 7 term datum transform parameters + +to_meter Multiplier to convert map units to 1.0m + +vto_meter Vertical conversion to meters + ============ ============================================================== + +The *cs2cs* framework delivers a subset of the geodetic transformations available +with the *pipeline* framework. Coordinate transformations done in this framework +are transformed in a two-step process with WGS84 as a pivot datum That is, the +input coordinates are transformed to WGS84 geodetic coordinates and then transformed +from WGS84 coordinates to the specified output coordinate reference system, by +utilizing either the Helmert transform, datum shift grids or a combination of both. +Datum shifts can be described in a proj-string with the parameters ``+towgs84``, +``+nadgrids`` and ``+geoidgrids``. +An inverse transform exists for all three and is applied if +specified in the input proj-string. The most common is ``+towgs84``, which is used to +define a 3- or 7-parameter Helmert shift from the input reference frame to WGS84. +Exactly which realization of WGS84 is not specified, hence a fair amount of +uncertainty is introduced in this step of the transformation. With the +nadgrids +parameter a non-lineaer planar correction derived from interpolation in a +correction grid can be applied. Originally this was implemented as a means to +transform coordinates between the american datums NAD27 and NAD83, but corrections +can be applied for any datum for which a correction grid exists. The inverse +transform for the horizontal grid shift is "dumb", in the sense that the +correction grid is applied verbatim without taking into account that the inverse +operation is non-linear. Similar to the horizontal grid correction, ``+geoidgrids`` +can be used to perform grid corrections in the vertical component. +Both grid correction methods allow inclusion of more than one grid in the same +transformation + +In contrast to the *transformation pipeline* framework, transformations with the +*cs2cs* framework are expressed as two separate proj-strings. One proj-string *to* +WGS84 and one *from* WGS84. Together they form the mapping from the source +coordinate reference system to the destination coordinate reference system. +When used with the ``cs2cs`` the source and destination CRS's are separated by the +special ``+to`` parameter. + +The following example demonstrates converting from the Greek GGRS87 datum +to WGS84 with the ``+towgs84`` parameter. + +:: + + cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62 + +to +proj=latlong +datum=WGS84 + 20 35 + 20d0'5.467"E 35d0'9.575"N 8.570 + +The EPSG database provides this example for transforming from WGS72 to WGS84 +using an approximated 7 parameter transformation. + +:: + + cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \ + +to +proj=latlong +datum=WGS84 + 4 55 + 4d0'0.554"E 55d0'0.09"N 3.223 + + +Grid Based Datum Adjustments ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In many places (notably North America and Austrialia) national geodetic +organizations provide grid shift files for converting between different datums, +such as NAD27 to NAD83. These grid shift files include a shift to be applied +at each grid location. Actually grid shifts are normally computed based on an +interpolation between the containing four grid points. + +PROJ supports use of grid files for shifting between various reference frames. +The grid shift table formats are ctable (the binary format produced by the PROJ +``nad2bin`` program), NTv1 (the old Canadian format), and NTv2 (``.gsb`` - the new +Canadian and Australian format). + +The text in this section is based on the *cs2cs* framework. Gridshifting is off +course also possible with the *pipeline* framework. The major difference between the +two is that the *cs2cs* framework is limited to grid mappings to WGS84, whereas with +*transformation pipelines* it is possible to perform grid shifts between any two +reference frames, as long as a grid exists. + +Use of grid shifts with ``cs2cs`` is specified using the ``+nadgrids`` +keyword in a coordinate system definition. For example: + +:: + + % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'2.952"W 50d0'0.111"N 0.000 + +In this case the ``/usr/local/share/proj/ntv1_can.dat`` grid shift file was +loaded, and used to get a grid shift value for the selected point. + +It is possible to list multiple grid shift files, in which case each will be +tried in turn till one is found that contains the point being transformed. + +:: + + cs2cs +proj=latlong +ellps=clrk66 \ + +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + + +Skipping Missing Grids +................................................................................ + +The special prefix ``@`` may be prefixed to a grid to make it optional. If it +not found, the search will continue to the next grid. Normally any grid not +found will cause an error. For instance, the following would use the +``ntv2_0.gsb`` file if available (see :ref:`nonfreegrids`), otherwise it would +fallback to using the ``ntv1_can.dat`` file. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + +The null Grid +................................................................................ + +A special ``null`` grid shift file is shift with releases after 4.4.6 (not +inclusive). This file provides a zero shift for the whole world. It may be +listed at the end of a nadgrids file list if you want a zero shift to be +applied to points outside the valid region of all the other grids. Normally if +no grid is found that contains the point to be transformed an error will occur. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 45 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + -111 55 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + 111dW 55dN 0.000 + +For more information see the chapter on :ref:`Grids`. + +Caveats +................................................................................ + +* Where grids overlap (such as conus and ntv1_can.dat for instance) the first + found for a point will be used regardless of whether it is appropriate or + not. So, for instance, ``+nadgrids=ntv1_can.dat``,conus would result in + the Canadian data being used for some areas in the northern United States + even though the conus data is the approved data to use for the area. + Careful selection of files and file order is necessary. In some cases + border spanning datasets may need to be pre-segmented into Canadian and + American points so they can be properly grid shifted +* There are additional grids for shifting between NAD83 and various HPGN + versions of the NAD83 datum. Use of these haven't been tried recently so + you may encounter problems. The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla + are examples of high precision grid shifts. Take care! +* Additional detail on the grid shift being applied can be found by setting + the PROJ_DEBUG environment variable to a value. This will result in output + to stderr on what grid is used to shift points, the bounds of the various + grids loaded and so forth +* The *cs2cs* framework always assumes that grids contain a shift **to** NAD83 (essentially + WGS84). Other types of grids can be used with the *pipeline* framework. |
