diff options
Diffstat (limited to 'usage')
| -rw-r--r-- | usage/differences.html | 281 | ||||
| -rw-r--r-- | usage/ellipsoids.html | 343 | ||||
| -rw-r--r-- | usage/environmentvars.html | 239 | ||||
| -rw-r--r-- | usage/index.html | 152 | ||||
| -rw-r--r-- | usage/network.html | 237 | ||||
| -rw-r--r-- | usage/projections.html | 366 | ||||
| -rw-r--r-- | usage/quickstart.html | 188 | ||||
| -rw-r--r-- | usage/transformation.html | 477 |
8 files changed, 2283 insertions, 0 deletions
diff --git a/usage/differences.html b/usage/differences.html new file mode 100644 index 00000000..590fa7ac --- /dev/null +++ b/usage/differences.html @@ -0,0 +1,281 @@ +<!DOCTYPE html> +<html class="writer-html5" lang="en" > +<head> + <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Known differences between versions — PROJ 9.0.0 documentation</title> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> + <link rel="shortcut icon" href="../_static/favicon.png"/> + <link rel="canonical" href="https://proj.orgusage/differences.html"/> + <!--[if lt IE 9]> + <script src="../_static/js/html5shiv.min.js"></script> + <![endif]--> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + <script async="async" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script> + <script src="../_static/js/theme.js"></script> + <link rel="author" title="About these documents" href="../about.html" /> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Network capabilities" href="network.html" /> + <link rel="prev" title="Environment variables" href="environmentvars.html" /> +</head> + +<body class="wy-body-for-nav"> + <div class="wy-grid-for-nav"> + <nav data-toggle="wy-nav-shift" class="wy-nav-side"> + <div class="wy-side-scroll"> + <div class="wy-side-nav-search" style="background: #353130" > + <a href="../index.html"> + <img src="../_static/logo.png" class="logo" alt="Logo"/> + </a> + <div class="version"> + 9.0.0 + </div> +<div role="search"> + <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> + <input type="text" name="q" placeholder="Search docs" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> + </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li> +<li class="toctree-l1"><a class="reference internal" href="../news.html">News</a></li> +<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a></li> +<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">Using PROJ</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick start</a></li> +<li class="toctree-l2"><a class="reference internal" href="projections.html">Cartographic projection</a></li> +<li class="toctree-l2"><a class="reference internal" href="transformation.html">Geodetic transformation</a></li> +<li class="toctree-l2"><a class="reference internal" href="ellipsoids.html">Ellipsoids</a></li> +<li class="toctree-l2"><a class="reference internal" href="environmentvars.html">Environment variables</a></li> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Known differences between versions</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#version-4-6-0">Version 4.6.0</a></li> +<li class="toctree-l3"><a class="reference internal" href="#version-5-0-0">Version 5.0.0</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#longitude-wrapping-when-using-custom-central-meridian">Longitude wrapping when using custom central meridian</a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="#version-6-0-0">Version 6.0.0</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#removal-of-proj-def-dat">Removal of <code class="file docutils literal notranslate"><span class="pre">proj_def.dat</span></code></a></li> +<li class="toctree-l4"><a class="reference internal" href="#changes-to-deformation">Changes to <span class="xref std std-ref">deformation</span></a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="#version-6-3-0">Version 6.3.0</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#projinfo">projinfo</a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="#version-7-0-0">Version 7.0.0</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#proj">proj</a></li> +<li class="toctree-l4"><a class="reference internal" href="#cs2cs">cs2cs</a></li> +<li class="toctree-l4"><a class="reference internal" href="#utf-8-adoption">UTF-8 adoption</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="network.html">Network capabilities</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../apps/index.html">Applications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operations/index.html">Coordinate operations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../resource_files.html">Resource files</a></li> +<li class="toctree-l1"><a class="reference internal" href="../geodesic.html">Geodesic calculations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../specifications/index.html">Specifications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../community/index.html">Community</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li> +<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> +<li class="toctree-l1"><a class="reference internal" href="../zreferences.html">References</a></li> +</ul> + + </div> + </div> + </nav> + + <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #353130" > + <i data-toggle="wy-nav-top" class="fa fa-bars"></i> + <a href="../index.html">PROJ</a> + </nav> + + <div class="wy-nav-content"> + <div class="rst-content"> + <div role="navigation" aria-label="Page navigation"> + <ul class="wy-breadcrumbs"> + <li><a href="../index.html" class="icon icon-home"></a> »</li> + <li><a href="index.html">Using PROJ</a> »</li> + <li>Known differences between versions</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/usage/differences.rst" class="fa fa-github"> Edit on GitHub</a> + </li> + </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation"> + <a href="environmentvars.html" class="btn btn-neutral float-left" title="Environment variables" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="network.html" class="btn btn-neutral float-right" title="Network capabilities" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + <hr/> +</div> + <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> + <div itemprop="articleBody"> + + <section id="known-differences-between-versions"> +<span id="differences"></span><h1>Known differences between versions<a class="headerlink" href="#known-differences-between-versions" title="Permalink to this headline">¶</a></h1> +<p>Once in a while, a new version of PROJ causes changes in the existing behavior. +In this section we track deliberate changes to PROJ that break from previous +behavior. Most times that will be caused by a bug fix. Unfortunately, some bugs +have existed for so long that their faulty behavior is relied upon by software +that uses PROJ.</p> +<p>Behavioural changes caused by new bugs are not tracked here, as they should be +fixed in later versions of PROJ.</p> +<section id="version-4-6-0"> +<h2>Version 4.6.0<a class="headerlink" href="#version-4-6-0" title="Permalink to this headline">¶</a></h2> +<p>The default datum application behavior changed with the 4.6.0 release. PROJ +will now only apply a datum shift if both the source and destination coordinate +system have valid datum shift information.</p> +<p>The PROJ 4.6.0 Release Notes states</p> +<blockquote> +<div><p>MAJOR: Rework <code class="xref c c-func docutils literal notranslate"><span class="pre">pj_transform()</span></code> to avoid applying ellipsoid to ellipsoid +transformations as a datum shift when no datum info is available.</p> +</div></blockquote> +</section> +<section id="version-5-0-0"> +<h2>Version 5.0.0<a class="headerlink" href="#version-5-0-0" title="Permalink to this headline">¶</a></h2> +<section id="longitude-wrapping-when-using-custom-central-meridian"> +<h3>Longitude wrapping when using custom central meridian<a class="headerlink" href="#longitude-wrapping-when-using-custom-central-meridian" title="Permalink to this headline">¶</a></h3> +<p>By default PROJ wraps output longitudes in the range -180 to 180. Previous to +PROJ 5, this was handled incorrectly when a custom central meridian was set with +<a class="reference internal" href="../operations/projections/wintri.html#cmdoption-arg-lon_0"><code class="xref std std-option docutils literal notranslate"><span class="pre">+lon_0</span></code></a>. This caused a change in sign on the resulting easting as seen +below:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ proj +proj=merc +lon_0=110 +-70 0 +-20037508.34 0.00 +290 0 +20037508.34 0.00 +</pre></div> +</div> +<p>From PROJ 5 on onwards, the same input now results in same coordinates, as seen +from the example below where PROJ 5 is used:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ proj +proj=merc +lon_0=110 +-70 0 +-20037508.34 0.00 +290 0 +-20037508.34 0.00 +</pre></div> +</div> +<p>The change is made on the basis that <span class="math notranslate nohighlight">\(\lambda=290^{\circ}\)</span> is a full +rotation of the circle larger than <span class="math notranslate nohighlight">\(\lambda=-70^{\circ}\)</span> and hence +should return the same output for both.</p> +<p>Adding the <code class="docutils literal notranslate"><span class="pre">+over</span></code> flag to the projection definition provides +the old behavior.</p> +</section> +</section> +<section id="version-6-0-0"> +<h2>Version 6.0.0<a class="headerlink" href="#version-6-0-0" title="Permalink to this headline">¶</a></h2> +<section id="removal-of-proj-def-dat"> +<h3>Removal of <code class="file docutils literal notranslate"><span class="pre">proj_def.dat</span></code><a class="headerlink" href="#removal-of-proj-def-dat" title="Permalink to this headline">¶</a></h3> +<p>Before PROJ 6, the <code class="file docutils literal notranslate"><span class="pre">proj_def.dat</span></code> was used to provide general and per-projection +parameters, when <code class="docutils literal notranslate"><span class="pre">+no_defs</span></code> was not specified. It has now been removed. In case, +no ellipsoid or datum specification is provided in the PROJ string, the +default ellipsoid is GRS80 (was WGS84 in previous PROJ versions).</p> +</section> +<section id="changes-to-deformation"> +<h3>Changes to <a class="reference internal" href="../operations/transformations/deformation.html#deformation"><span class="std std-ref">deformation</span></a><a class="headerlink" href="#changes-to-deformation" title="Permalink to this headline">¶</a></h3> +<section id="reversed-order-of-operation"> +<span id="differences-deformation"></span><h4>Reversed order of operation<a class="headerlink" href="#reversed-order-of-operation" title="Permalink to this headline">¶</a></h4> +<p>In the initial version of the of <a class="reference internal" href="../operations/transformations/deformation.html#deformation"><span class="std std-ref">deformation</span></a> operation +the time span between <span class="math notranslate nohighlight">\(t_{obs}\)</span> and <span class="math notranslate nohighlight">\(t_c\)</span> was determined by the +expression</p> +<div class="math notranslate nohighlight"> +\[dt = t_c - t_{obs}\]</div> +<p>With version 6.0.0 this has been reversed in order to behave similarly to +the <a class="reference internal" href="../operations/transformations/helmert.html#helmert"><span class="std std-ref">Helmert operation</span></a>, which determines time differences as</p> +<div class="math notranslate nohighlight"> +\[dt = t_{obs} - t_c\]</div> +<p>Effectively this means that the direction of the operation has been reversed, +so that what in PROJ 5 was a forward operation is now an inverse operation and +vice versa.</p> +<p>Pipelines written for PROJ 5 can be migrated to PROJ 6 by adding <a class="reference internal" href="../operations/pipeline.html#cmdoption-arg-inv"><code class="xref std std-option docutils literal notranslate"><span class="pre">+inv</span></code></a> +to forward steps involving the deformation operation. Similarly +<a class="reference internal" href="../operations/pipeline.html#cmdoption-arg-inv"><code class="xref std std-option docutils literal notranslate"><span class="pre">+inv</span></code></a> should be removed from inverse steps to be compatible with +PROJ 6.</p> +</section> +<section id="removed-t-obs-parameter"> +<h4>Removed <code class="docutils literal notranslate"><span class="pre">+t_obs</span></code> parameter<a class="headerlink" href="#removed-t-obs-parameter" title="Permalink to this headline">¶</a></h4> +<p>The <code class="docutils literal notranslate"><span class="pre">+t_obs</span></code> parameter was confusing for users since it effectively +overwrote the observation time in input coordinates. To make it more clear +what is the operation is doing, users are now required to directly specify +the time span for which they wish to apply a given deformation. The parameter +<a class="reference internal" href="../operations/transformations/deformation.html#cmdoption-arg-dt"><code class="xref std std-option docutils literal notranslate"><span class="pre">+dt</span></code></a> has been added for that purpose. The new parameter is mutually +exclusive with <a class="reference internal" href="../operations/transformations/vgridshift.html#cmdoption-arg-t_epoch"><code class="xref std std-option docutils literal notranslate"><span class="pre">+t_epoch</span></code></a>. <a class="reference internal" href="../operations/transformations/deformation.html#cmdoption-arg-dt"><code class="xref std std-option docutils literal notranslate"><span class="pre">+dt</span></code></a> is used when deformation +for a set amount of time is needed and <a class="reference internal" href="../operations/transformations/vgridshift.html#cmdoption-arg-t_epoch"><code class="xref std std-option docutils literal notranslate"><span class="pre">+t_epoch</span></code></a> is used (in +conjunction with the observation time of the input coordinate) when +deformation from a specific epoch to the observation time is needed.</p> +</section> +</section> +</section> +<section id="version-6-3-0"> +<h2>Version 6.3.0<a class="headerlink" href="#version-6-3-0" title="Permalink to this headline">¶</a></h2> +<section id="projinfo"> +<h3>projinfo<a class="headerlink" href="#projinfo" title="Permalink to this headline">¶</a></h3> +<p>Before PROJ 6.3.0, WKT1:GDAL was implicitly calling <code class="docutils literal notranslate"><span class="pre">--boundcrs-to-wgs84</span></code>, to +add a <code class="docutils literal notranslate"><span class="pre">TOWGS84[]</span></code> node in some cases. This is no longer the case.</p> +</section> +</section> +<section id="version-7-0-0"> +<h2>Version 7.0.0<a class="headerlink" href="#version-7-0-0" title="Permalink to this headline">¶</a></h2> +<section id="proj"> +<h3>proj<a class="headerlink" href="#proj" title="Permalink to this headline">¶</a></h3> +<p>Removed <code class="docutils literal notranslate"><span class="pre">-ld</span></code> option from application, since it promoted use of deprecated +parameters like <code class="docutils literal notranslate"><span class="pre">+towgs</span></code> and <code class="docutils literal notranslate"><span class="pre">+datum</span></code>.</p> +</section> +<section id="cs2cs"> +<h3>cs2cs<a class="headerlink" href="#cs2cs" title="Permalink to this headline">¶</a></h3> +<p>Removed <code class="docutils literal notranslate"><span class="pre">-ld</span></code> option from application, since it promoted use of deprecated +parameters like <code class="docutils literal notranslate"><span class="pre">+towgs</span></code> and <code class="docutils literal notranslate"><span class="pre">+datum</span></code>.</p> +</section> +<section id="utf-8-adoption"> +<h3>UTF-8 adoption<a class="headerlink" href="#utf-8-adoption" title="Permalink to this headline">¶</a></h3> +<p>The value of all path, filenames passed to PROJ through function calls, PROJ +strings or environment variables should be encoded in UTF-8.</p> +</section> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="environmentvars.html" class="btn btn-neutral float-left" title="Environment variables" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="network.html" class="btn btn-neutral float-right" title="Network capabilities" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + + <hr/> + + <div role="contentinfo"> + <p>© Copyright 1983-2022. + <span class="lastupdated">Last updated on 22 Mar 2022. + </span></p> + </div> + + Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a + <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> + provided by <a href="https://readthedocs.org">Read the Docs</a>. + + +</footer> + </div> + </div> + </section> + </div> + <script> + jQuery(function () { + SphinxRtdTheme.Navigation.enable(true); + }); + </script> + +</body> +</html>
\ No newline at end of file diff --git a/usage/ellipsoids.html b/usage/ellipsoids.html new file mode 100644 index 00000000..afa8a63f --- /dev/null +++ b/usage/ellipsoids.html @@ -0,0 +1,343 @@ +<!DOCTYPE html> +<html class="writer-html5" lang="en" > +<head> + <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Ellipsoids — PROJ 9.0.0 documentation</title> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> + <link rel="shortcut icon" href="../_static/favicon.png"/> + <link rel="canonical" href="https://proj.orgusage/ellipsoids.html"/> + <!--[if lt IE 9]> + <script src="../_static/js/html5shiv.min.js"></script> + <![endif]--> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + <script async="async" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script> + <script src="../_static/js/theme.js"></script> + <link rel="author" title="About these documents" href="../about.html" /> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Environment variables" href="environmentvars.html" /> + <link rel="prev" title="Geodetic transformation" href="transformation.html" /> +</head> + +<body class="wy-body-for-nav"> + <div class="wy-grid-for-nav"> + <nav data-toggle="wy-nav-shift" class="wy-nav-side"> + <div class="wy-side-scroll"> + <div class="wy-side-nav-search" style="background: #353130" > + <a href="../index.html"> + <img src="../_static/logo.png" class="logo" alt="Logo"/> + </a> + <div class="version"> + 9.0.0 + </div> +<div role="search"> + <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> + <input type="text" name="q" placeholder="Search docs" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> + </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li> +<li class="toctree-l1"><a class="reference internal" href="../news.html">News</a></li> +<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a></li> +<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">Using PROJ</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick start</a></li> +<li class="toctree-l2"><a class="reference internal" href="projections.html">Cartographic projection</a></li> +<li class="toctree-l2"><a class="reference internal" href="transformation.html">Geodetic transformation</a></li> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Ellipsoids</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#ellipsoid-size-parameters">Ellipsoid size parameters</a></li> +<li class="toctree-l3"><a class="reference internal" href="#ellipsoid-shape-parameters">Ellipsoid shape parameters</a></li> +<li class="toctree-l3"><a class="reference internal" href="#ellipsoid-spherification-parameters">Ellipsoid spherification parameters</a></li> +<li class="toctree-l3"><a class="reference internal" href="#built-in-ellipsoid-definitions">Built-in ellipsoid definitions</a></li> +<li class="toctree-l3"><a class="reference internal" href="#transformation-examples">Transformation examples</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="environmentvars.html">Environment variables</a></li> +<li class="toctree-l2"><a class="reference internal" href="differences.html">Known differences between versions</a></li> +<li class="toctree-l2"><a class="reference internal" href="network.html">Network capabilities</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../apps/index.html">Applications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operations/index.html">Coordinate operations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../resource_files.html">Resource files</a></li> +<li class="toctree-l1"><a class="reference internal" href="../geodesic.html">Geodesic calculations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../specifications/index.html">Specifications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../community/index.html">Community</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li> +<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> +<li class="toctree-l1"><a class="reference internal" href="../zreferences.html">References</a></li> +</ul> + + </div> + </div> + </nav> + + <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #353130" > + <i data-toggle="wy-nav-top" class="fa fa-bars"></i> + <a href="../index.html">PROJ</a> + </nav> + + <div class="wy-nav-content"> + <div class="rst-content"> + <div role="navigation" aria-label="Page navigation"> + <ul class="wy-breadcrumbs"> + <li><a href="../index.html" class="icon icon-home"></a> »</li> + <li><a href="index.html">Using PROJ</a> »</li> + <li>Ellipsoids</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/usage/ellipsoids.rst" class="fa fa-github"> Edit on GitHub</a> + </li> + </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation"> + <a href="transformation.html" class="btn btn-neutral float-left" title="Geodetic transformation" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="environmentvars.html" class="btn btn-neutral float-right" title="Environment variables" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + <hr/> +</div> + <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> + <div itemprop="articleBody"> + + <section id="ellipsoids"> +<span id="id1"></span><h1>Ellipsoids<a class="headerlink" href="#ellipsoids" title="Permalink to this headline">¶</a></h1> +<p>An ellipsoid is a mathematically defined surface which approximates the <em>geoid</em>: +the surface of the Earth’s gravity field, which is approximately the same as +mean sea level.</p> +<figure class="align-center" id="id5"> +<a class="reference internal image-reference" href="../_images/general_ellipsoid.png"><img alt="Global and local fitting of the ellipsoid" src="../_images/general_ellipsoid.png" style="width: 500px;" /></a> +<figcaption> +<p><span class="caption-text">Global and local fitting of the ellipsoid</span><a class="headerlink" href="#id5" title="Permalink to this image">¶</a></p> +</figcaption> +</figure> +<p>A complete ellipsoid definition comprises a size (primary) and a shape (secondary) +parameter.</p> +<section id="ellipsoid-size-parameters"> +<span id="id2"></span><h2>Ellipsoid size parameters<a class="headerlink" href="#ellipsoid-size-parameters" title="Permalink to this headline">¶</a></h2> +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-R"> +<span id="cmdoption-arg-r"></span><span class="sig-name descname"><span class="pre">+R</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-R" title="Permalink to this definition">¶</a></dt> +<dd><p>Radius of the sphere, <span class="math notranslate nohighlight">\(R\)</span>.</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-a"> +<span class="sig-name descname"><span class="pre">+a</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-a" title="Permalink to this definition">¶</a></dt> +<dd><p>Semi-major axis of the ellipsoid, <span class="math notranslate nohighlight">\(a\)</span>.</p> +</dd></dl> + +</section> +<section id="ellipsoid-shape-parameters"> +<span id="id3"></span><h2>Ellipsoid shape parameters<a class="headerlink" href="#ellipsoid-shape-parameters" title="Permalink to this headline">¶</a></h2> +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-rf"> +<span class="sig-name descname"><span class="pre">+rf</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-rf" title="Permalink to this definition">¶</a></dt> +<dd><p>Reverse flattening of the ellipsoid, <span class="math notranslate nohighlight">\(1/f\)</span>.</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-f"> +<span class="sig-name descname"><span class="pre">+f</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-f" title="Permalink to this definition">¶</a></dt> +<dd><p>Flattening of the ellipsoid, <span class="math notranslate nohighlight">\(f\)</span>.</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-es"> +<span class="sig-name descname"><span class="pre">+es</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-es" title="Permalink to this definition">¶</a></dt> +<dd><p>Eccentricity squared, <span class="math notranslate nohighlight">\(e^2\)</span>.</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-e"> +<span class="sig-name descname"><span class="pre">+e</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-e" title="Permalink to this definition">¶</a></dt> +<dd><p>Eccentricity, <span class="math notranslate nohighlight">\(e\)</span>.</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-b"> +<span class="sig-name descname"><span class="pre">+b</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-b" title="Permalink to this definition">¶</a></dt> +<dd><p>Semi-minor axis, <span class="math notranslate nohighlight">\(b\)</span>.</p> +</dd></dl> + +<p>The ellipsoid definition may be augmented with a spherification flag, turning +the ellipsoid into a sphere with features defined by the ellipsoid.</p> +</section> +<section id="ellipsoid-spherification-parameters"> +<span id="id4"></span><h2>Ellipsoid spherification parameters<a class="headerlink" href="#ellipsoid-spherification-parameters" title="Permalink to this headline">¶</a></h2> +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-R_A"> +<span id="cmdoption-arg-r-a"></span><span class="sig-name descname"><span class="pre">+R_A</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-R_A" title="Permalink to this definition">¶</a></dt> +<dd><p>A sphere with the same surface area as the ellipsoid.</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-R_V"> +<span id="cmdoption-arg-r-v"></span><span class="sig-name descname"><span class="pre">+R_V</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-R_V" title="Permalink to this definition">¶</a></dt> +<dd><p>A sphere with the same volume as the ellipsoid.</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-R_a"> +<span class="sig-name descname"><span class="pre">+R_a</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-R_a" title="Permalink to this definition">¶</a></dt> +<dd><p>A sphere with <span class="math notranslate nohighlight">\(R = (a + b)/2\)</span> (arithmetic mean).</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-R_g"> +<span id="cmdoption-arg-r-g"></span><span class="sig-name descname"><span class="pre">+R_g</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-R_g" title="Permalink to this definition">¶</a></dt> +<dd><p>A sphere with <span class="math notranslate nohighlight">\(R = \sqrt{ab}\)</span> (geometric mean).</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-R_h"> +<span id="cmdoption-arg-r-h"></span><span class="sig-name descname"><span class="pre">+R_h</span></span><span class="sig-prename descclassname"><span class="pre">=<value></span></span><a class="headerlink" href="#cmdoption-arg-R_h" title="Permalink to this definition">¶</a></dt> +<dd><p>A sphere with <span class="math notranslate nohighlight">\(R = 2ab/(a+b)\)</span> (harmonic mean).</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-R_lat_a"> +<span id="cmdoption-arg-r-lat-a"></span><span class="sig-name descname"><span class="pre">+R_lat_a</span></span><span class="sig-prename descclassname"><span class="pre">=<phi></span></span><a class="headerlink" href="#cmdoption-arg-R_lat_a" title="Permalink to this definition">¶</a></dt> +<dd><p>A sphere with <span class="math notranslate nohighlight">\(R\)</span> being the arithmetic mean of the corresponding +ellipsoid at latitude <span class="math notranslate nohighlight">\(\phi\)</span>.</p> +</dd></dl> + +<dl class="std option"> +<dt class="sig sig-object std" id="cmdoption-arg-R_lat_g"> +<span id="cmdoption-arg-r-lat-g"></span><span class="sig-name descname"><span class="pre">+R_lat_g</span></span><span class="sig-prename descclassname"><span class="pre">=<phi></span></span><a class="headerlink" href="#cmdoption-arg-R_lat_g" title="Permalink to this definition">¶</a></dt> +<dd><p>A sphere with <span class="math notranslate nohighlight">\(R\)</span> being the geometric mean of the corresponding +ellipsoid at latitude <span class="math notranslate nohighlight">\(\phi\)</span>.</p> +</dd></dl> + +<p>If <a class="reference internal" href="#cmdoption-arg-R"><code class="xref std std-option docutils literal notranslate"><span class="pre">+R</span></code></a> is given as size parameter, any shape and spherification +parameters given are ignored.</p> +</section> +<section id="built-in-ellipsoid-definitions"> +<span id="ellipsoid-definitions"></span><h2>Built-in ellipsoid definitions<a class="headerlink" href="#built-in-ellipsoid-definitions" title="Permalink to this headline">¶</a></h2> +<p>The <code class="docutils literal notranslate"><span class="pre">ellps=xxx</span></code> parameter provides both size and shape for a number of +built-in ellipsoid definitions.</p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 16%" /> +<col style="width: 45%" /> +<col style="width: 38%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>ellps</p></th> +<th class="head"><p>Parameters</p></th> +<th class="head"><p>Datum name</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>GRS80</p></td> +<td><p>a=6378137.0 rf=298.257222101</p></td> +<td><p>GRS 1980(IUGG, 1980)</p></td> +</tr> +<tr class="row-odd"><td><p>airy</p></td> +<td><p>a=6377563.396 b=6356256.910</p></td> +<td><p>Airy 1830</p></td> +</tr> +<tr class="row-even"><td><p>bessel</p></td> +<td><p>a=6377397.155 rf=299.1528128</p></td> +<td><p>Bessel 1841</p></td> +</tr> +<tr class="row-odd"><td><p>clrk66</p></td> +<td><p>a=6378206.4 b=6356583.8</p></td> +<td><p>Clarke 1866</p></td> +</tr> +<tr class="row-even"><td><p>intl</p></td> +<td><p>a=6378388.0 rf=297.</p></td> +<td><p>International 1909 (Hayford)</p></td> +</tr> +<tr class="row-odd"><td><p>WGS60</p></td> +<td><p>a=6378165.0 rf=298.3</p></td> +<td><p>WGS 60</p></td> +</tr> +<tr class="row-even"><td><p>WGS66</p></td> +<td><p>a=6378145.0 rf=298.25</p></td> +<td><p>WGS 66</p></td> +</tr> +<tr class="row-odd"><td><p>WGS72</p></td> +<td><p>a=6378135.0 rf=298.26</p></td> +<td><p>WGS 72</p></td> +</tr> +<tr class="row-even"><td><p>WGS84</p></td> +<td><p>a=6378137.0 rf=298.257223563</p></td> +<td><p>WGS 84</p></td> +</tr> +<tr class="row-odd"><td><p>sphere</p></td> +<td><p>a=6370997.0 b=6370997.0</p></td> +<td><p>Normal Sphere (r=6370997)</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p>If size and shape are given as <code class="docutils literal notranslate"><span class="pre">ellps=xxx</span></code>, later shape and size parameters +are are taken into account as modifiers for the built-in ellipsoid definition.</p> +<p>While this may seem strange, it is in accordance with historical PROJ +behavior. It can e.g. be used to define coordinates on the ellipsoid +scaled to unit semimajor axis by specifying <code class="docutils literal notranslate"><span class="pre">+ellps=xxx</span> <span class="pre">+a=1</span></code></p> +</section> +<section id="transformation-examples"> +<span id="ellipsoid-transformation-examples"></span><h2>Transformation examples<a class="headerlink" href="#transformation-examples" title="Permalink to this headline">¶</a></h2> +<p>Spherical earth with radius 7000km:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>proj=laton R=7000000 +</pre></div> +</div> +<p>Using the GRS80 ellipsoid:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>proj=laton ellps=GRS80 +</pre></div> +</div> +<p>Expressing ellipsoid by semi-major axis and reverse flattening (<span class="math notranslate nohighlight">\(1/f\)</span>):</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>proj=laton a=6378137.0 rf=298.25 +</pre></div> +</div> +<p>Spherical earth based on volume of ellipsoid</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>proj=laton a=6378137.0 rf=298.25 +R_V +</pre></div> +</div> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="transformation.html" class="btn btn-neutral float-left" title="Geodetic transformation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="environmentvars.html" class="btn btn-neutral float-right" title="Environment variables" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + + <hr/> + + <div role="contentinfo"> + <p>© Copyright 1983-2022. + <span class="lastupdated">Last updated on 22 Mar 2022. + </span></p> + </div> + + Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a + <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> + provided by <a href="https://readthedocs.org">Read the Docs</a>. + + +</footer> + </div> + </div> + </section> + </div> + <script> + jQuery(function () { + SphinxRtdTheme.Navigation.enable(true); + }); + </script> + +</body> +</html>
\ No newline at end of file diff --git a/usage/environmentvars.html b/usage/environmentvars.html new file mode 100644 index 00000000..57327597 --- /dev/null +++ b/usage/environmentvars.html @@ -0,0 +1,239 @@ +<!DOCTYPE html> +<html class="writer-html5" lang="en" > +<head> + <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Environment variables — PROJ 9.0.0 documentation</title> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> + <link rel="shortcut icon" href="../_static/favicon.png"/> + <link rel="canonical" href="https://proj.orgusage/environmentvars.html"/> + <!--[if lt IE 9]> + <script src="../_static/js/html5shiv.min.js"></script> + <![endif]--> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + <script src="../_static/js/theme.js"></script> + <link rel="author" title="About these documents" href="../about.html" /> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Known differences between versions" href="differences.html" /> + <link rel="prev" title="Ellipsoids" href="ellipsoids.html" /> +</head> + +<body class="wy-body-for-nav"> + <div class="wy-grid-for-nav"> + <nav data-toggle="wy-nav-shift" class="wy-nav-side"> + <div class="wy-side-scroll"> + <div class="wy-side-nav-search" style="background: #353130" > + <a href="../index.html"> + <img src="../_static/logo.png" class="logo" alt="Logo"/> + </a> + <div class="version"> + 9.0.0 + </div> +<div role="search"> + <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> + <input type="text" name="q" placeholder="Search docs" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> + </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li> +<li class="toctree-l1"><a class="reference internal" href="../news.html">News</a></li> +<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a></li> +<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">Using PROJ</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick start</a></li> +<li class="toctree-l2"><a class="reference internal" href="projections.html">Cartographic projection</a></li> +<li class="toctree-l2"><a class="reference internal" href="transformation.html">Geodetic transformation</a></li> +<li class="toctree-l2"><a class="reference internal" href="ellipsoids.html">Ellipsoids</a></li> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Environment variables</a></li> +<li class="toctree-l2"><a class="reference internal" href="differences.html">Known differences between versions</a></li> +<li class="toctree-l2"><a class="reference internal" href="network.html">Network capabilities</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../apps/index.html">Applications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operations/index.html">Coordinate operations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../resource_files.html">Resource files</a></li> +<li class="toctree-l1"><a class="reference internal" href="../geodesic.html">Geodesic calculations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../specifications/index.html">Specifications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../community/index.html">Community</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li> +<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> +<li class="toctree-l1"><a class="reference internal" href="../zreferences.html">References</a></li> +</ul> + + </div> + </div> + </nav> + + <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #353130" > + <i data-toggle="wy-nav-top" class="fa fa-bars"></i> + <a href="../index.html">PROJ</a> + </nav> + + <div class="wy-nav-content"> + <div class="rst-content"> + <div role="navigation" aria-label="Page navigation"> + <ul class="wy-breadcrumbs"> + <li><a href="../index.html" class="icon icon-home"></a> »</li> + <li><a href="index.html">Using PROJ</a> »</li> + <li>Environment variables</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/usage/environmentvars.rst" class="fa fa-github"> Edit on GitHub</a> + </li> + </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation"> + <a href="ellipsoids.html" class="btn btn-neutral float-left" title="Ellipsoids" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="differences.html" class="btn btn-neutral float-right" title="Known differences between versions" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + <hr/> +</div> + <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> + <div itemprop="articleBody"> + + <section id="environment-variables"> +<span id="environmentvars"></span><h1>Environment variables<a class="headerlink" href="#environment-variables" title="Permalink to this headline">¶</a></h1> +<p>PROJ can be controlled by setting environment variables. Most users will +have a use for the <span class="target" id="index-0"></span><a class="reference internal" href="#envvar-PROJ_LIB"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PROJ_LIB</span></code></a>.</p> +<p>On UNIX systems environment variables can be set for a shell-session with:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ export VAR="some variable" +</pre></div> +</div> +<p>or it can be set for just one command line call:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ VAR="some variable" ./cmd +</pre></div> +</div> +<p>Environment variables on UNIX are usually removed with the <code class="docutils literal notranslate"><span class="pre">unset</span></code> command:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ unset VAR +</pre></div> +</div> +<p>On windows systems environment variables can be set in the command line with:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>> set VAR="some variable" +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">VAR</span></code> will be available for the entire session, unless it is unset. This is +done by setting the variable with no content:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>> set VAR= +</pre></div> +</div> +<dl class="std envvar"> +<dt class="sig sig-object std" id="envvar-PROJ_LIB"> +<span class="sig-name descname"><span class="pre">PROJ_LIB</span></span><a class="headerlink" href="#envvar-PROJ_LIB" title="Permalink to this definition">¶</a></dt> +<dd><p>The location of PROJ <a class="reference internal" href="../resource_files.html"><span class="doc">resource files</span></a>.</p> +<p>Starting with PROJ 6, multiple directories can be specified. On Unix, they +should be separated by the colon (:) character. on Windows, by the semi-colon (;) +character.</p> +<p>PROJ is hardcoded to look for resource files +in other locations as well, amongst those are the +installation directory (usually <code class="docutils literal notranslate"><span class="pre">share/proj</span></code> under the PROJ +installation root) and the current folder.</p> +<p>You can also set the location of the resource files using +<code class="xref py py-func docutils literal notranslate"><span class="pre">proj_context_set_search_paths()</span></code> in the <code class="file docutils literal notranslate"><span class="pre">proj.h</span></code> API header.</p> +</dd></dl> + +<div class="versionchanged"> +<p><span class="versionmodified changed">Changed in version 6.1.0: </span>Starting with PROJ version 6.1.0, the paths set by +<code class="xref py py-func docutils literal notranslate"><span class="pre">proj_context_set_search_paths()</span></code> will have priority over the +<span class="target" id="index-1"></span><a class="reference internal" href="#envvar-PROJ_LIB"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PROJ_LIB</span></code></a> to allow for multiple versions of PROJ +resource files on your system without conflicting.</p> +</div> +<dl class="std envvar"> +<dt class="sig sig-object std" id="envvar-PROJ_AUX_DB"> +<span class="sig-name descname"><span class="pre">PROJ_AUX_DB</span></span><a class="headerlink" href="#envvar-PROJ_AUX_DB" title="Permalink to this definition">¶</a></dt> +<dd><div class="versionadded"> +<p><span class="versionmodified added">New in version 8.1.0.</span></p> +</div> +<p>To set the path to one or several auxiliary SQLite3 databases of structure +identical to the main <code class="file docutils literal notranslate"><span class="pre">proj.db</span></code> database and that can contain additional +object (CRS, transformation, …) definitions. If several paths are +provided, they must be separated by the colon (:) character on Unix, and +on Windows, by the semi-colon (;) character.</p> +</dd></dl> + +<dl class="std envvar"> +<dt class="sig sig-object std" id="envvar-PROJ_DEBUG"> +<span class="sig-name descname"><span class="pre">PROJ_DEBUG</span></span><a class="headerlink" href="#envvar-PROJ_DEBUG" title="Permalink to this definition">¶</a></dt> +<dd><p>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, with 3 being the most +verbose setting.</p> +</dd></dl> + +<dl class="std envvar"> +<dt class="sig sig-object std" id="envvar-PROJ_NETWORK"> +<span class="sig-name descname"><span class="pre">PROJ_NETWORK</span></span><a class="headerlink" href="#envvar-PROJ_NETWORK" title="Permalink to this definition">¶</a></dt> +<dd><div class="versionadded"> +<p><span class="versionmodified added">New in version 7.0.0.</span></p> +</div> +<p>If set to ON, enable the capability to use remote grids stored on CDN +(Content Delivery Network) storage, when grids are not available locally. +Alternatively, the <a class="reference internal" href="../development/reference/functions.html#c.proj_context_set_enable_network" title="proj_context_set_enable_network"><code class="xref c c-func docutils literal notranslate"><span class="pre">proj_context_set_enable_network()</span></code></a> function can +be used.</p> +</dd></dl> + +<dl class="std envvar"> +<dt class="sig sig-object std" id="envvar-PROJ_NETWORK_ENDPOINT"> +<span class="sig-name descname"><span class="pre">PROJ_NETWORK_ENDPOINT</span></span><a class="headerlink" href="#envvar-PROJ_NETWORK_ENDPOINT" title="Permalink to this definition">¶</a></dt> +<dd><div class="versionadded"> +<p><span class="versionmodified added">New in version 7.0.0.</span></p> +</div> +<p>Define the endpoint of the CDN storage. Normally defined through the +<code class="file docutils literal notranslate"><span class="pre">proj.ini</span></code> configuration file locale in <span class="target" id="index-2"></span><a class="reference internal" href="#envvar-PROJ_LIB"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PROJ_LIB</span></code></a>. +Alternatively, the <a class="reference internal" href="../development/reference/functions.html#c.proj_context_set_url_endpoint" title="proj_context_set_url_endpoint"><code class="xref c c-func docutils literal notranslate"><span class="pre">proj_context_set_url_endpoint()</span></code></a> function can +be used.</p> +</dd></dl> + +<dl class="std envvar"> +<dt class="sig sig-object std" id="envvar-PROJ_CURL_CA_BUNDLE"> +<span class="sig-name descname"><span class="pre">PROJ_CURL_CA_BUNDLE</span></span><a class="headerlink" href="#envvar-PROJ_CURL_CA_BUNDLE" title="Permalink to this definition">¶</a></dt> +<dd><div class="versionadded"> +<p><span class="versionmodified added">New in version 7.2.0.</span></p> +</div> +<p>Define a custom path to the CA Bundle file. This can be useful if <cite>curl</cite> +and <span class="target" id="index-3"></span><a class="reference internal" href="#envvar-PROJ_NETWORK"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PROJ_NETWORK</span></code></a> are enabled. Alternatively, the +<code class="xref c c-func docutils literal notranslate"><span class="pre">proj_curl_set_ca_bundle_path()</span></code> function can be used.</p> +</dd></dl> + +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="ellipsoids.html" class="btn btn-neutral float-left" title="Ellipsoids" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="differences.html" class="btn btn-neutral float-right" title="Known differences between versions" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + + <hr/> + + <div role="contentinfo"> + <p>© Copyright 1983-2022. + <span class="lastupdated">Last updated on 22 Mar 2022. + </span></p> + </div> + + Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a + <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> + provided by <a href="https://readthedocs.org">Read the Docs</a>. + + +</footer> + </div> + </div> + </section> + </div> + <script> + jQuery(function () { + SphinxRtdTheme.Navigation.enable(true); + }); + </script> + +</body> +</html>
\ No newline at end of file diff --git a/usage/index.html b/usage/index.html new file mode 100644 index 00000000..56120262 --- /dev/null +++ b/usage/index.html @@ -0,0 +1,152 @@ +<!DOCTYPE html> +<html class="writer-html5" lang="en" > +<head> + <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Using PROJ — PROJ 9.0.0 documentation</title> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> + <link rel="shortcut icon" href="../_static/favicon.png"/> + <link rel="canonical" href="https://proj.orgusage/index.html"/> + <!--[if lt IE 9]> + <script src="../_static/js/html5shiv.min.js"></script> + <![endif]--> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + <script src="../_static/js/theme.js"></script> + <link rel="author" title="About these documents" href="../about.html" /> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Quick start" href="quickstart.html" /> + <link rel="prev" title="Installation" href="../install.html" /> +</head> + +<body class="wy-body-for-nav"> + <div class="wy-grid-for-nav"> + <nav data-toggle="wy-nav-shift" class="wy-nav-side"> + <div class="wy-side-scroll"> + <div class="wy-side-nav-search" style="background: #353130" > + <a href="../index.html"> + <img src="../_static/logo.png" class="logo" alt="Logo"/> + </a> + <div class="version"> + 9.0.0 + </div> +<div role="search"> + <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> + <input type="text" name="q" placeholder="Search docs" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> + </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li> +<li class="toctree-l1"><a class="reference internal" href="../news.html">News</a></li> +<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a></li> +<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Using PROJ</a><ul> +<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick start</a></li> +<li class="toctree-l2"><a class="reference internal" href="projections.html">Cartographic projection</a></li> +<li class="toctree-l2"><a class="reference internal" href="transformation.html">Geodetic transformation</a></li> +<li class="toctree-l2"><a class="reference internal" href="ellipsoids.html">Ellipsoids</a></li> +<li class="toctree-l2"><a class="reference internal" href="environmentvars.html">Environment variables</a></li> +<li class="toctree-l2"><a class="reference internal" href="differences.html">Known differences between versions</a></li> +<li class="toctree-l2"><a class="reference internal" href="network.html">Network capabilities</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../apps/index.html">Applications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operations/index.html">Coordinate operations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../resource_files.html">Resource files</a></li> +<li class="toctree-l1"><a class="reference internal" href="../geodesic.html">Geodesic calculations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../specifications/index.html">Specifications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../community/index.html">Community</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li> +<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> +<li class="toctree-l1"><a class="reference internal" href="../zreferences.html">References</a></li> +</ul> + + </div> + </div> + </nav> + + <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #353130" > + <i data-toggle="wy-nav-top" class="fa fa-bars"></i> + <a href="../index.html">PROJ</a> + </nav> + + <div class="wy-nav-content"> + <div class="rst-content"> + <div role="navigation" aria-label="Page navigation"> + <ul class="wy-breadcrumbs"> + <li><a href="../index.html" class="icon icon-home"></a> »</li> + <li>Using PROJ</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/usage/index.rst" class="fa fa-github"> Edit on GitHub</a> + </li> + </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation"> + <a href="../install.html" class="btn btn-neutral float-left" title="Installation" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="quickstart.html" class="btn btn-neutral float-right" title="Quick start" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + <hr/> +</div> + <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> + <div itemprop="articleBody"> + + <section id="using-proj"> +<span id="usage"></span><h1>Using PROJ<a class="headerlink" href="#using-proj" title="Permalink to this headline">¶</a></h1> +<p>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.</p> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick start</a></li> +<li class="toctree-l1"><a class="reference internal" href="projections.html">Cartographic projection</a></li> +<li class="toctree-l1"><a class="reference internal" href="transformation.html">Geodetic transformation</a></li> +<li class="toctree-l1"><a class="reference internal" href="ellipsoids.html">Ellipsoids</a></li> +<li class="toctree-l1"><a class="reference internal" href="environmentvars.html">Environment variables</a></li> +<li class="toctree-l1"><a class="reference internal" href="differences.html">Known differences between versions</a></li> +<li class="toctree-l1"><a class="reference internal" href="network.html">Network capabilities</a></li> +</ul> +</div> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="../install.html" class="btn btn-neutral float-left" title="Installation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="quickstart.html" class="btn btn-neutral float-right" title="Quick start" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + + <hr/> + + <div role="contentinfo"> + <p>© Copyright 1983-2022. + <span class="lastupdated">Last updated on 22 Mar 2022. + </span></p> + </div> + + Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a + <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> + provided by <a href="https://readthedocs.org">Read the Docs</a>. + + +</footer> + </div> + </div> + </section> + </div> + <script> + jQuery(function () { + SphinxRtdTheme.Navigation.enable(true); + }); + </script> + +</body> +</html>
\ No newline at end of file diff --git a/usage/network.html b/usage/network.html new file mode 100644 index 00000000..c3a3dce6 --- /dev/null +++ b/usage/network.html @@ -0,0 +1,237 @@ +<!DOCTYPE html> +<html class="writer-html5" lang="en" > +<head> + <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Network capabilities — PROJ 9.0.0 documentation</title> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> + <link rel="shortcut icon" href="../_static/favicon.png"/> + <link rel="canonical" href="https://proj.orgusage/network.html"/> + <!--[if lt IE 9]> + <script src="../_static/js/html5shiv.min.js"></script> + <![endif]--> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + <script src="../_static/js/theme.js"></script> + <link rel="author" title="About these documents" href="../about.html" /> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Applications" href="../apps/index.html" /> + <link rel="prev" title="Known differences between versions" href="differences.html" /> +</head> + +<body class="wy-body-for-nav"> + <div class="wy-grid-for-nav"> + <nav data-toggle="wy-nav-shift" class="wy-nav-side"> + <div class="wy-side-scroll"> + <div class="wy-side-nav-search" style="background: #353130" > + <a href="../index.html"> + <img src="../_static/logo.png" class="logo" alt="Logo"/> + </a> + <div class="version"> + 9.0.0 + </div> +<div role="search"> + <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> + <input type="text" name="q" placeholder="Search docs" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> + </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li> +<li class="toctree-l1"><a class="reference internal" href="../news.html">News</a></li> +<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a></li> +<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">Using PROJ</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick start</a></li> +<li class="toctree-l2"><a class="reference internal" href="projections.html">Cartographic projection</a></li> +<li class="toctree-l2"><a class="reference internal" href="transformation.html">Geodetic transformation</a></li> +<li class="toctree-l2"><a class="reference internal" href="ellipsoids.html">Ellipsoids</a></li> +<li class="toctree-l2"><a class="reference internal" href="environmentvars.html">Environment variables</a></li> +<li class="toctree-l2"><a class="reference internal" href="differences.html">Known differences between versions</a></li> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Network capabilities</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#cdn-of-geotiff-grids">CDN of GeoTIFF grids</a></li> +<li class="toctree-l3"><a class="reference internal" href="#how-to-enable-network-capabilities">How to enable network capabilities ?</a></li> +<li class="toctree-l3"><a class="reference internal" href="#setting-endpoint">Setting endpoint</a></li> +<li class="toctree-l3"><a class="reference internal" href="#caching">Caching</a></li> +<li class="toctree-l3"><a class="reference internal" href="#download-api">Download API</a></li> +<li class="toctree-l3"><a class="reference internal" href="#download-utility">Download utility</a></li> +<li class="toctree-l3"><a class="reference internal" href="#mirroring">Mirroring</a></li> +<li class="toctree-l3"><a class="reference internal" href="#acknowledgments">Acknowledgments</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../apps/index.html">Applications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operations/index.html">Coordinate operations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../resource_files.html">Resource files</a></li> +<li class="toctree-l1"><a class="reference internal" href="../geodesic.html">Geodesic calculations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../specifications/index.html">Specifications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../community/index.html">Community</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li> +<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> +<li class="toctree-l1"><a class="reference internal" href="../zreferences.html">References</a></li> +</ul> + + </div> + </div> + </nav> + + <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #353130" > + <i data-toggle="wy-nav-top" class="fa fa-bars"></i> + <a href="../index.html">PROJ</a> + </nav> + + <div class="wy-nav-content"> + <div class="rst-content"> + <div role="navigation" aria-label="Page navigation"> + <ul class="wy-breadcrumbs"> + <li><a href="../index.html" class="icon icon-home"></a> »</li> + <li><a href="index.html">Using PROJ</a> »</li> + <li>Network capabilities</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/usage/network.rst" class="fa fa-github"> Edit on GitHub</a> + </li> + </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation"> + <a href="differences.html" class="btn btn-neutral float-left" title="Known differences between versions" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="../apps/index.html" class="btn btn-neutral float-right" title="Applications" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + <hr/> +</div> + <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> + <div itemprop="articleBody"> + + <section id="network-capabilities"> +<span id="network"></span><h1>Network capabilities<a class="headerlink" href="#network-capabilities" title="Permalink to this headline">¶</a></h1> +<div class="versionadded"> +<p><span class="versionmodified added">New in version 7.0.</span></p> +</div> +<p>PROJ 7.0 has introduced, per <a class="reference internal" href="../community/rfc/rfc-4.html#rfc4"><span class="std std-ref">PROJ RFC 4: Remote access to grids and GeoTIFF grids</span></a>, the capability to work with grid files +that are not installed on the local machine where PROJ is executed.</p> +<p>This enables to transparently download the parts of grids that are needed to +perform a coordinate transformation.</p> +<section id="cdn-of-geotiff-grids"> +<span id="cdn-grids"></span><h2>CDN of GeoTIFF grids<a class="headerlink" href="#cdn-of-geotiff-grids" title="Permalink to this headline">¶</a></h2> +<p>Files are accessed by default through a CDN (Content Delivery Network), +accessible through <a class="reference external" href="https://cdn.proj.org">https://cdn.proj.org</a>, that contains <a class="reference internal" href="../specifications/geodetictiffgrids.html#geodetictiffgrids"><span class="std std-ref">Geodetic TIFF grids (GTG)</span></a> +datasets which are mirrored and managed by the +<a class="reference external" href="https://github.com/OSGeo/PROJ-data/">https://github.com/OSGeo/PROJ-data/</a> GitHub project. +Files in the CDN are designed to be used by PROJ 7 or later, but any software +project wishing to use the CDN for shifting support are encouraged to +participate in the project and leverage the CDN.</p> +</section> +<section id="how-to-enable-network-capabilities"> +<h2>How to enable network capabilities ?<a class="headerlink" href="#how-to-enable-network-capabilities" title="Permalink to this headline">¶</a></h2> +<p>This capability assumes that PROJ has been build against <cite>libcurl</cite>, and that +the user authorizes network access.</p> +<p>Authorizing network access can be done in multiple ways:</p> +<blockquote> +<div><ul class="simple"> +<li><p>enabling / uncommenting the <code class="docutils literal notranslate"><span class="pre">network</span> <span class="pre">=</span> <span class="pre">on</span></code> line of <a class="reference internal" href="../resource_files.html#proj-ini"><span class="std std-ref">proj.ini</span></a></p></li> +<li><p>defining the <span class="target" id="index-0"></span><a class="reference internal" href="environmentvars.html#envvar-PROJ_NETWORK"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PROJ_NETWORK</span></code></a> environment variable to ON</p></li> +<li><p>or using the <code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_context_set_enable_network()</span></code> with a +<code class="docutils literal notranslate"><span class="pre">enabled</span> <span class="pre">=</span> <span class="pre">TRUE</span></code> value.</p></li> +</ul> +</div></blockquote> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>Instead of using the <cite>libcurl</cite> implementation, an application using the PROJ +API can supply its own network implementation through C function callbacks +with <code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_context_set_network_callbacks()</span></code>. Enabling network use +must still be done with one of the above mentioned method.</p> +</div> +</section> +<section id="setting-endpoint"> +<h2>Setting endpoint<a class="headerlink" href="#setting-endpoint" title="Permalink to this headline">¶</a></h2> +<p>When this is enabled, and a grid is not found in the various locations where +<a class="reference internal" href="../resource_files.html#resource-file-paths"><span class="std std-ref">resource files are looked for</span></a>, PROJ will then +attempt at loading the file from a remote server, which defaults to +<a class="reference external" href="https://cdn.proj.org">https://cdn.proj.org</a> in <a class="reference internal" href="../resource_files.html#proj-ini"><span class="std std-ref">proj.ini</span></a>. This location can be changed with +the <span class="target" id="index-1"></span><a class="reference internal" href="environmentvars.html#envvar-PROJ_NETWORK_ENDPOINT"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PROJ_NETWORK_ENDPOINT</span></code></a> environment variable or with +<code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_context_set_url_endpoint()</span></code>.</p> +</section> +<section id="caching"> +<h2>Caching<a class="headerlink" href="#caching" title="Permalink to this headline">¶</a></h2> +<p>To avoid repeated access to network, a local cache of downloaded chunks of grids +is implemented as SQLite3 database, <code class="file docutils literal notranslate"><span class="pre">cache.db</span></code>, stored in the +<a class="reference internal" href="../resource_files.html#user-writable-directory"><span class="std std-ref">PROJ user writable directory</span></a>.</p> +<p>This local caching is enabled by default (can be changed in <a class="reference internal" href="../resource_files.html#proj-ini"><span class="std std-ref">proj.ini</span></a> or +with <code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_grid_cache_set_enable()</span></code>). The default maximum size of the +cache is 300 MB, which is more than half of the total size of grids available, +at time of writing. This size can also be customized in <a class="reference internal" href="../resource_files.html#proj-ini"><span class="std std-ref">proj.ini</span></a> or +with <code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_grid_cache_set_max_size()</span></code></p> +</section> +<section id="download-api"> +<h2>Download API<a class="headerlink" href="#download-api" title="Permalink to this headline">¶</a></h2> +<p>When on-demand loading of grid is not desirable, the PROJ API also offers the +capability to download whole grids in the +<a class="reference internal" href="../resource_files.html#user-writable-directory"><span class="std std-ref">PROJ user writable directory</span></a> by using the +<code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_is_download_needed()</span></code> and <code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_download_file()</span></code> functions.</p> +</section> +<section id="download-utility"> +<h2>Download utility<a class="headerlink" href="#download-utility" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="../apps/projsync.html#projsync"><span class="std std-ref">projsync</span></a> is a tool for downloading resource files.</p> +</section> +<section id="mirroring"> +<h2>Mirroring<a class="headerlink" href="#mirroring" title="Permalink to this headline">¶</a></h2> +<p>If you are able, you are encouraged to mirror the grids via AWS S3 command line:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>aws s3 sync s3://cdn.proj.org . +</pre></div> +</div> +<p>If direct S3 access is not possible, you can also use wget to locally mirror the +data:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>wget --mirror https://cdn.proj.org/ +</pre></div> +</div> +</section> +<section id="acknowledgments"> +<h2>Acknowledgments<a class="headerlink" href="#acknowledgments" title="Permalink to this headline">¶</a></h2> +<p>The s3://cdn.proj.org bucket is hosted by the +<a class="reference external" href="https://aws.amazon.com/opendata/public-datasets/">Amazon Public Datasets program</a>. +CDN services are provided by the AWS Public Dataset team via +<a class="reference external" href="https://aws.amazon.com/cloudfront/">CloudFront</a></p> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="differences.html" class="btn btn-neutral float-left" title="Known differences between versions" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="../apps/index.html" class="btn btn-neutral float-right" title="Applications" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + + <hr/> + + <div role="contentinfo"> + <p>© Copyright 1983-2022. + <span class="lastupdated">Last updated on 22 Mar 2022. + </span></p> + </div> + + Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a + <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> + provided by <a href="https://readthedocs.org">Read the Docs</a>. + + +</footer> + </div> + </div> + </section> + </div> + <script> + jQuery(function () { + SphinxRtdTheme.Navigation.enable(true); + }); + </script> + +</body> +</html>
\ No newline at end of file diff --git a/usage/projections.html b/usage/projections.html new file mode 100644 index 00000000..12ab1246 --- /dev/null +++ b/usage/projections.html @@ -0,0 +1,366 @@ +<!DOCTYPE html> +<html class="writer-html5" lang="en" > +<head> + <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Cartographic projection — PROJ 9.0.0 documentation</title> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> + <link rel="shortcut icon" href="../_static/favicon.png"/> + <link rel="canonical" href="https://proj.orgusage/projections.html"/> + <!--[if lt IE 9]> + <script src="../_static/js/html5shiv.min.js"></script> + <![endif]--> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + <script src="../_static/js/theme.js"></script> + <link rel="author" title="About these documents" href="../about.html" /> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Geodetic transformation" href="transformation.html" /> + <link rel="prev" title="Quick start" href="quickstart.html" /> +</head> + +<body class="wy-body-for-nav"> + <div class="wy-grid-for-nav"> + <nav data-toggle="wy-nav-shift" class="wy-nav-side"> + <div class="wy-side-scroll"> + <div class="wy-side-nav-search" style="background: #353130" > + <a href="../index.html"> + <img src="../_static/logo.png" class="logo" alt="Logo"/> + </a> + <div class="version"> + 9.0.0 + </div> +<div role="search"> + <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> + <input type="text" name="q" placeholder="Search docs" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> + </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li> +<li class="toctree-l1"><a class="reference internal" href="../news.html">News</a></li> +<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a></li> +<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">Using PROJ</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick start</a></li> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Cartographic projection</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#units">Units</a></li> +<li class="toctree-l3"><a class="reference internal" href="#false-easting-northing">False Easting/Northing</a></li> +<li class="toctree-l3"><a class="reference internal" href="#longitude-wrapping">Longitude Wrapping</a></li> +<li class="toctree-l3"><a class="reference internal" href="#prime-meridian">Prime Meridian</a></li> +<li class="toctree-l3"><a class="reference internal" href="#axis-orientation">Axis orientation</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="transformation.html">Geodetic transformation</a></li> +<li class="toctree-l2"><a class="reference internal" href="ellipsoids.html">Ellipsoids</a></li> +<li class="toctree-l2"><a class="reference internal" href="environmentvars.html">Environment variables</a></li> +<li class="toctree-l2"><a class="reference internal" href="differences.html">Known differences between versions</a></li> +<li class="toctree-l2"><a class="reference internal" href="network.html">Network capabilities</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../apps/index.html">Applications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operations/index.html">Coordinate operations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../resource_files.html">Resource files</a></li> +<li class="toctree-l1"><a class="reference internal" href="../geodesic.html">Geodesic calculations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../specifications/index.html">Specifications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../community/index.html">Community</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li> +<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> +<li class="toctree-l1"><a class="reference internal" href="../zreferences.html">References</a></li> +</ul> + + </div> + </div> + </nav> + + <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #353130" > + <i data-toggle="wy-nav-top" class="fa fa-bars"></i> + <a href="../index.html">PROJ</a> + </nav> + + <div class="wy-nav-content"> + <div class="rst-content"> + <div role="navigation" aria-label="Page navigation"> + <ul class="wy-breadcrumbs"> + <li><a href="../index.html" class="icon icon-home"></a> »</li> + <li><a href="index.html">Using PROJ</a> »</li> + <li>Cartographic projection</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/usage/projections.rst" class="fa fa-github"> Edit on GitHub</a> + </li> + </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation"> + <a href="quickstart.html" class="btn btn-neutral float-left" title="Quick start" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="transformation.html" class="btn btn-neutral float-right" title="Geodetic transformation" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + <hr/> +</div> + <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> + <div itemprop="articleBody"> + + <section id="cartographic-projection"> +<span id="projections-intro"></span><h1>Cartographic projection<a class="headerlink" href="#cartographic-projection" title="Permalink to this headline">¶</a></h1> +<p>The foundation of PROJ is the large number of +<a class="reference internal" href="../operations/projections/index.html"><span class="doc">projections</span></a> available in the library. This section +is devoted to the generic parameters that can be used on any projection in the +PROJ library.</p> +<p>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 <a class="reference internal" href="../operations/projections/index.html"><span class="doc">projections</span></a>.</p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 14%" /> +<col style="width: 86%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>Parameter</p></th> +<th class="head"><p>Description</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>+a</p></td> +<td><p>Semimajor radius of the ellipsoid axis</p></td> +</tr> +<tr class="row-odd"><td><p>+axis</p></td> +<td><p>Axis orientation</p></td> +</tr> +<tr class="row-even"><td><p>+b</p></td> +<td><p>Semiminor radius of the ellipsoid axis</p></td> +</tr> +<tr class="row-odd"><td><p>+ellps</p></td> +<td><p>Ellipsoid name (see <code class="docutils literal notranslate"><span class="pre">proj</span> <span class="pre">-le</span></code>)</p></td> +</tr> +<tr class="row-even"><td><p>+k</p></td> +<td><p>Scaling factor (deprecated)</p></td> +</tr> +<tr class="row-odd"><td><p>+k_0</p></td> +<td><p>Scaling factor</p></td> +</tr> +<tr class="row-even"><td><p>+lat_0</p></td> +<td><p>Latitude of origin</p></td> +</tr> +<tr class="row-odd"><td><p>+lon_0</p></td> +<td><p>Central meridian</p></td> +</tr> +<tr class="row-even"><td><p>+lon_wrap</p></td> +<td><p>Center longitude to use for wrapping (see below)</p></td> +</tr> +<tr class="row-odd"><td><p>+over</p></td> +<td><p>Allow longitude output outside -180 to 180 range, disables +wrapping (see below)</p></td> +</tr> +<tr class="row-even"><td><p>+pm</p></td> +<td><p>Alternate prime meridian (typically a city name, see below)</p></td> +</tr> +<tr class="row-odd"><td><p>+proj</p></td> +<td><p>Projection name (see <code class="docutils literal notranslate"><span class="pre">proj</span> <span class="pre">-l</span></code>)</p></td> +</tr> +<tr class="row-even"><td><p>+units</p></td> +<td><p>meters, US survey feet, etc.</p></td> +</tr> +<tr class="row-odd"><td><p>+vunits</p></td> +<td><p>vertical units.</p></td> +</tr> +<tr class="row-even"><td><p>+x_0</p></td> +<td><p>False easting</p></td> +</tr> +<tr class="row-odd"><td><p>+y_0</p></td> +<td><p>False northing</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p>In the sections below most of the parameters are explained in details.</p> +<section id="units"> +<h2>Units<a class="headerlink" href="#units" title="Permalink to this headline">¶</a></h2> +<p>Horizontal units can be specified using the <code class="docutils literal notranslate"><span class="pre">+units</span></code> keyword with a symbolic +name for a unit (i.e. <code class="docutils literal notranslate"><span class="pre">us-ft</span></code>). Alternatively the translation to meters can be +specified with the <code class="docutils literal notranslate"><span class="pre">+to_meter</span></code> keyword (i.e. 0.304800609601219 for US feet). The +<code class="docutils literal notranslate"><span class="pre">-lu</span></code> argument to <strong class="program">cs2cs</strong> or <strong class="program">proj</strong> can be used to list +symbolic unit names. The default unit for projected coordinates is the meter. +A few special projections deviate from this behavior, most notably the +latlong pseudo-projection that returns degrees.</p> +<p>Vertical (Z) units can be specified using the <code class="docutils literal notranslate"><span class="pre">+vunits</span></code> keyword with a +symbolic name for a unit (i.e. <code class="docutils literal notranslate"><span class="pre">us-ft</span></code>). Alternatively the translation to +meters can be specified with the <code class="docutils literal notranslate"><span class="pre">+vto_meter</span></code> keyword (i.e. 0.304800609601219 +for US feet). The <code class="docutils literal notranslate"><span class="pre">-lu</span></code> argument to <strong class="program">cs2cs</strong> or <strong class="program">proj</strong> 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.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p><strong class="program">proj</strong> does not handle vertical units at all and hence the +<code class="docutils literal notranslate"><span class="pre">+vto_meter</span></code> argument will be ignored.</p> +</div> +<p>Scaling of output units can be done by applying the <code class="docutils literal notranslate"><span class="pre">+k_0</span></code> argument. The +returned coordinates are scaled by the value assigned with the <code class="docutils literal notranslate"><span class="pre">+k_0</span></code> +parameter.</p> +</section> +<section id="false-easting-northing"> +<h2>False Easting/Northing<a class="headerlink" href="#false-easting-northing" title="Permalink to this headline">¶</a></h2> +<p>Virtually all coordinate systems allow for the presence of a false easting +(<code class="docutils literal notranslate"><span class="pre">+x_0</span></code>) and northing (<code class="docutils literal notranslate"><span class="pre">+y_0</span></code>). 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.</p> +</section> +<section id="longitude-wrapping"> +<h2>Longitude Wrapping<a class="headerlink" href="#longitude-wrapping" title="Permalink to this headline">¶</a></h2> +<p>By default PROJ wraps output longitudes in the range -180 to 180. The <code class="docutils literal notranslate"><span class="pre">+over</span></code> +switch can be used to disable the default wrapping which is done at a low level +in <code class="docutils literal notranslate"><span class="pre">pj_inv()</span></code>. This is particularly useful with projections like the +<a class="reference internal" href="../operations/projections/eqc.html"><span class="doc">equidistant cylindrical</span></a> +where it would be desirable for X values past -20000000 (roughly) to continue +past -180 instead of wrapping to +180.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">+lon_wrap</span></code> option can be used to provide an alternative means of doing +longitude wrapping within <code class="docutils literal notranslate"><span class="pre">pj_transform()</span></code>. The argument to this option is a +center longitude. So <code class="docutils literal notranslate"><span class="pre">+lon_wrap=180</span></code> means wrap longitudes in the range 0 to +360. Note that <code class="docutils literal notranslate"><span class="pre">+over</span></code> does <strong>not</strong> disable <code class="docutils literal notranslate"><span class="pre">+lon_wrap</span></code>.</p> +</section> +<section id="prime-meridian"> +<h2>Prime Meridian<a class="headerlink" href="#prime-meridian" title="Permalink to this headline">¶</a></h2> +<p>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 declared using the “pm” parameter, and may be assigned a symbolic +name, or the longitude of the alternative prime meridian relative to greenwich.</p> +<p>Currently prime meridian declarations are only utilized by the +<code class="docutils literal notranslate"><span class="pre">pj_transform()</span></code> API call, not the <code class="docutils literal notranslate"><span class="pre">pj_inv()</span></code> and <code class="docutils literal notranslate"><span class="pre">pj_fwd()</span></code> calls. +Consequently the user utility <strong class="program">cs2cs</strong> does honour prime meridians but +the <strong class="program">proj</strong> user utility ignores them.</p> +<p>The following predeclared prime meridian names are supported. These can be +listed using with <code class="docutils literal notranslate"><span class="pre">cs2cs</span> <span class="pre">-lm</span></code>.</p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 41%" /> +<col style="width: 59%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>Meridian</p></th> +<th class="head"><p>Longitude</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>greenwich</p></td> +<td><p>0dE</p></td> +</tr> +<tr class="row-odd"><td><p>lisbon</p></td> +<td><p>9d07’54.862”W</p></td> +</tr> +<tr class="row-even"><td><p>paris</p></td> +<td><p>2d20’14.025”E</p></td> +</tr> +<tr class="row-odd"><td><p>bogota</p></td> +<td><p>74d04’51.3”E</p></td> +</tr> +<tr class="row-even"><td><p>madrid</p></td> +<td><p>3d41’16.48”W</p></td> +</tr> +<tr class="row-odd"><td><p>rome</p></td> +<td><p>12d27’8.4”E</p></td> +</tr> +<tr class="row-even"><td><p>bern</p></td> +<td><p>7d26’22.5”E</p></td> +</tr> +<tr class="row-odd"><td><p>jakarta</p></td> +<td><p>106d48’27.79”E</p></td> +</tr> +<tr class="row-even"><td><p>ferro</p></td> +<td><p>17d40’W</p></td> +</tr> +<tr class="row-odd"><td><p>brussels</p></td> +<td><p>4d22’4.71”E</p></td> +</tr> +<tr class="row-even"><td><p>stockholm</p></td> +<td><p>18d3’29.8”E</p></td> +</tr> +<tr class="row-odd"><td><p>athens</p></td> +<td><p>23d42’58.815”E</p></td> +</tr> +<tr class="row-even"><td><p>oslo</p></td> +<td><p>10d43’22.5”E</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p>Example of use. The location <code class="docutils literal notranslate"><span class="pre">long=0</span></code>, <code class="docutils literal notranslate"><span class="pre">lat=0</span></code> in the greenwich based lat/long +coordinates is translated to lat/long coordinates with Madrid as the prime +meridian.</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid +0 0 +3d41'16.48"E 0dN 0.000 +</pre></div> +</div> +</section> +<section id="axis-orientation"> +<h2>Axis orientation<a class="headerlink" href="#axis-orientation" title="Permalink to this headline">¶</a></h2> +<p>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:</p> +<ul class="simple"> +<li><p>“e” - Easting</p></li> +<li><p>“w” - Westing</p></li> +<li><p>“n” - Northing</p></li> +<li><p>“s” - Southing</p></li> +<li><p>“u” - Up</p></li> +<li><p>“d” - Down</p></li> +</ul> +<p>They can be combined in +axis in forms like:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">+axis=enu</span></code> - the default easting, northing, elevation.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">+axis=neu</span></code> - northing, easting, up - useful for “lat/long” geographic +coordinates, or south orientated transverse mercator.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">+axis=wnu</span></code> - westing, northing, up - some planetary coordinate systems +have “west positive” coordinate systems</p></li> +</ul> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>The <code class="docutils literal notranslate"><span class="pre">+axis</span></code> argument does not work with the <strong class="program">proj</strong> command line +utility.</p> +</div> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="quickstart.html" class="btn btn-neutral float-left" title="Quick start" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="transformation.html" class="btn btn-neutral float-right" title="Geodetic transformation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + + <hr/> + + <div role="contentinfo"> + <p>© Copyright 1983-2022. + <span class="lastupdated">Last updated on 22 Mar 2022. + </span></p> + </div> + + Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a + <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> + provided by <a href="https://readthedocs.org">Read the Docs</a>. + + +</footer> + </div> + </div> + </section> + </div> + <script> + jQuery(function () { + SphinxRtdTheme.Navigation.enable(true); + }); + </script> + +</body> +</html>
\ No newline at end of file diff --git a/usage/quickstart.html b/usage/quickstart.html new file mode 100644 index 00000000..6c8b338e --- /dev/null +++ b/usage/quickstart.html @@ -0,0 +1,188 @@ +<!DOCTYPE html> +<html class="writer-html5" lang="en" > +<head> + <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Quick start — PROJ 9.0.0 documentation</title> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> + <link rel="shortcut icon" href="../_static/favicon.png"/> + <link rel="canonical" href="https://proj.orgusage/quickstart.html"/> + <!--[if lt IE 9]> + <script src="../_static/js/html5shiv.min.js"></script> + <![endif]--> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + <script src="../_static/js/theme.js"></script> + <link rel="author" title="About these documents" href="../about.html" /> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Cartographic projection" href="projections.html" /> + <link rel="prev" title="Using PROJ" href="index.html" /> +</head> + +<body class="wy-body-for-nav"> + <div class="wy-grid-for-nav"> + <nav data-toggle="wy-nav-shift" class="wy-nav-side"> + <div class="wy-side-scroll"> + <div class="wy-side-nav-search" style="background: #353130" > + <a href="../index.html"> + <img src="../_static/logo.png" class="logo" alt="Logo"/> + </a> + <div class="version"> + 9.0.0 + </div> +<div role="search"> + <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> + <input type="text" name="q" placeholder="Search docs" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> + </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li> +<li class="toctree-l1"><a class="reference internal" href="../news.html">News</a></li> +<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a></li> +<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">Using PROJ</a><ul class="current"> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Quick start</a></li> +<li class="toctree-l2"><a class="reference internal" href="projections.html">Cartographic projection</a></li> +<li class="toctree-l2"><a class="reference internal" href="transformation.html">Geodetic transformation</a></li> +<li class="toctree-l2"><a class="reference internal" href="ellipsoids.html">Ellipsoids</a></li> +<li class="toctree-l2"><a class="reference internal" href="environmentvars.html">Environment variables</a></li> +<li class="toctree-l2"><a class="reference internal" href="differences.html">Known differences between versions</a></li> +<li class="toctree-l2"><a class="reference internal" href="network.html">Network capabilities</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../apps/index.html">Applications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operations/index.html">Coordinate operations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../resource_files.html">Resource files</a></li> +<li class="toctree-l1"><a class="reference internal" href="../geodesic.html">Geodesic calculations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../specifications/index.html">Specifications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../community/index.html">Community</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li> +<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> +<li class="toctree-l1"><a class="reference internal" href="../zreferences.html">References</a></li> +</ul> + + </div> + </div> + </nav> + + <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #353130" > + <i data-toggle="wy-nav-top" class="fa fa-bars"></i> + <a href="../index.html">PROJ</a> + </nav> + + <div class="wy-nav-content"> + <div class="rst-content"> + <div role="navigation" aria-label="Page navigation"> + <ul class="wy-breadcrumbs"> + <li><a href="../index.html" class="icon icon-home"></a> »</li> + <li><a href="index.html">Using PROJ</a> »</li> + <li>Quick start</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/usage/quickstart.rst" class="fa fa-github"> Edit on GitHub</a> + </li> + </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation"> + <a href="index.html" class="btn btn-neutral float-left" title="Using PROJ" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="projections.html" class="btn btn-neutral float-right" title="Cartographic projection" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + <hr/> +</div> + <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> + <div itemprop="articleBody"> + + <section id="quick-start"> +<span id="quickstart"></span><h1>Quick start<a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h1> +<p>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 +<a class="reference internal" href="transformation.html"><span class="doc">Geodetic transformation</span></a>.</p> +<p>A proj-strings holds the parameters of a given coordinate transformation, e.g.</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>+proj=merc +lat_ts=56.5 +ellps=GRS80 +</pre></div> +</div> +<p>I.e. a proj-string consists of a projection specifier, <code class="docutils literal notranslate"><span class="pre">+proj</span></code>, 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 <a class="reference internal" href="../operations/projections/merc.html"><span class="doc">Mercator projection</span></a> 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 <code class="docutils literal notranslate"><span class="pre">merc</span></code> in the above +example.</p> +<p>By using the above projection definition as parameters for the command line +utility <strong class="program">proj</strong> we can convert the geodetic coordinates to projected space:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ proj +proj=merc +lat_ts=56.5 +ellps=GRS80 +</pre></div> +</div> +<p>If called as above <strong class="program">proj</strong> will be in interactive mode, letting you +type the input data manually and getting a response presented on screen. +<strong class="program">proj</strong> works as any UNIX filter though, which means that you can also +pipe data to the utility, for instance by using the <strong class="program">echo</strong> command:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80 +3399483.80 752085.60 +</pre></div> +</div> +<p>PROJ also comes bundled with the <strong class="program">cs2cs</strong> utility which is used to +transform from one coordinate reference system to another. Say we want to +convert the above Mercator coordinates to UTM, we can do that with +<strong class="program">cs2cs</strong>:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ 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 +</pre></div> +</div> +<p>Notice the <code class="docutils literal notranslate"><span class="pre">+to</span></code> parameter that separates the source and destination +projection definitions.</p> +<p>If you happen to know the EPSG identifiers for the two coordinates reference +systems you are transforming between you can use those with <strong class="program">cs2cs</strong>:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832 +231950.54 1920310.71 0.00 +</pre></div> +</div> +<p>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</p> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="index.html" class="btn btn-neutral float-left" title="Using PROJ" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="projections.html" class="btn btn-neutral float-right" title="Cartographic projection" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + + <hr/> + + <div role="contentinfo"> + <p>© Copyright 1983-2022. + <span class="lastupdated">Last updated on 22 Mar 2022. + </span></p> + </div> + + Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a + <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> + provided by <a href="https://readthedocs.org">Read the Docs</a>. + + +</footer> + </div> + </div> + </section> + </div> + <script> + jQuery(function () { + SphinxRtdTheme.Navigation.enable(true); + }); + </script> + +</body> +</html>
\ No newline at end of file diff --git a/usage/transformation.html b/usage/transformation.html new file mode 100644 index 00000000..8d9e757a --- /dev/null +++ b/usage/transformation.html @@ -0,0 +1,477 @@ +<!DOCTYPE html> +<html class="writer-html5" lang="en" > +<head> + <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Geodetic transformation — PROJ 9.0.0 documentation</title> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> + <link rel="shortcut icon" href="../_static/favicon.png"/> + <link rel="canonical" href="https://proj.orgusage/transformation.html"/> + <!--[if lt IE 9]> + <script src="../_static/js/html5shiv.min.js"></script> + <![endif]--> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + <script src="../_static/js/theme.js"></script> + <link rel="author" title="About these documents" href="../about.html" /> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Ellipsoids" href="ellipsoids.html" /> + <link rel="prev" title="Cartographic projection" href="projections.html" /> +</head> + +<body class="wy-body-for-nav"> + <div class="wy-grid-for-nav"> + <nav data-toggle="wy-nav-shift" class="wy-nav-side"> + <div class="wy-side-scroll"> + <div class="wy-side-nav-search" style="background: #353130" > + <a href="../index.html"> + <img src="../_static/logo.png" class="logo" alt="Logo"/> + </a> + <div class="version"> + 9.0.0 + </div> +<div role="search"> + <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> + <input type="text" name="q" placeholder="Search docs" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> + </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li> +<li class="toctree-l1"><a class="reference internal" href="../news.html">News</a></li> +<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a></li> +<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">Using PROJ</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick start</a></li> +<li class="toctree-l2"><a class="reference internal" href="projections.html">Cartographic projection</a></li> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Geodetic transformation</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#transformation-pipelines">Transformation pipelines</a></li> +<li class="toctree-l3"><a class="reference internal" href="#proj-4-x-5-x-paradigm">PROJ 4.x/5.x paradigm</a></li> +<li class="toctree-l3"><a class="reference internal" href="#grid-based-datum-adjustments">Grid Based Datum Adjustments</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#skipping-missing-grids">Skipping Missing Grids</a></li> +<li class="toctree-l4"><a class="reference internal" href="#the-null-grid">The null Grid</a></li> +<li class="toctree-l4"><a class="reference internal" href="#caveats">Caveats</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="ellipsoids.html">Ellipsoids</a></li> +<li class="toctree-l2"><a class="reference internal" href="environmentvars.html">Environment variables</a></li> +<li class="toctree-l2"><a class="reference internal" href="differences.html">Known differences between versions</a></li> +<li class="toctree-l2"><a class="reference internal" href="network.html">Network capabilities</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../apps/index.html">Applications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operations/index.html">Coordinate operations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../resource_files.html">Resource files</a></li> +<li class="toctree-l1"><a class="reference internal" href="../geodesic.html">Geodesic calculations</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../specifications/index.html">Specifications</a></li> +<li class="toctree-l1"><a class="reference internal" href="../community/index.html">Community</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li> +<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> +<li class="toctree-l1"><a class="reference internal" href="../zreferences.html">References</a></li> +</ul> + + </div> + </div> + </nav> + + <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #353130" > + <i data-toggle="wy-nav-top" class="fa fa-bars"></i> + <a href="../index.html">PROJ</a> + </nav> + + <div class="wy-nav-content"> + <div class="rst-content"> + <div role="navigation" aria-label="Page navigation"> + <ul class="wy-breadcrumbs"> + <li><a href="../index.html" class="icon icon-home"></a> »</li> + <li><a href="index.html">Using PROJ</a> »</li> + <li>Geodetic transformation</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/usage/transformation.rst" class="fa fa-github"> Edit on GitHub</a> + </li> + </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation"> + <a href="projections.html" class="btn btn-neutral float-left" title="Cartographic projection" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="ellipsoids.html" class="btn btn-neutral float-right" title="Ellipsoids" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + <hr/> +</div> + <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> + <div itemprop="articleBody"> + + <section id="geodetic-transformation"> +<span id="transformation"></span><h1>Geodetic transformation<a class="headerlink" href="#geodetic-transformation" title="Permalink to this headline">¶</a></h1> +<p>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 powerful +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 +geodetic transformations of varying complexity can be performed.</p> +<p>In PROJ, two frameworks for geodetic transformations exists, the +<em>PROJ 4.x/5.x</em> / <strong class="program">cs2cs</strong> / <code class="xref c c-func docutils literal notranslate"><span class="pre">pj_transform()</span></code> +framework and the <em>transformation pipelines</em> 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 +<span id="id1">[<a class="reference internal" href="../zreferences.html#id13" title="Evers, K. and Knudsen, T. Transformation pipelines for PROJ.4. In FIG Working Week 2017 Proceedings. Helsinki, Finland, 2017. URL: http://www.fig.net/resources/proceedings/fig_proceedings/fig2017/papers/iss6b/ISS6B_evers_knudsen_9156.pdf.">EversKnudsen2017</a>]</span>.</p> +<p>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:</p> +<ol class="arabic simple"> +<li><p>Back-project the UTM coordinates to geographic coordinates</p></li> +<li><p>Convert the geographic coordinates to 3D cartesian geocentric coordinates</p></li> +<li><p>Apply a Helmert transformation from ED50 to ETRS89</p></li> +<li><p>Convert back from cartesian to geographic coordinates</p></li> +<li><p>Finally project the geographic coordinates to UTM zone 32 planar coordinates.</p></li> +</ol> +<section id="transformation-pipelines"> +<h2>Transformation pipelines<a class="headerlink" href="#transformation-pipelines" title="Permalink to this headline">¶</a></h2> +<p>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.</p> +<p>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 +<code class="docutils literal notranslate"><span class="pre">pipeline</span></code>, 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.</p> +<p>As a first example, let us take a look at the iconic +<em>geodetic → Cartesian → Helmert → geodetic</em> case (steps 2 to 4 in the example in +the introduction). In PROJ it can be implemented as</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>proj=pipeline +step proj=cart ellps=intl +step proj=helmert convention=coordinate_frame + 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 +</pre></div> +</div> +<p>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.</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>proj=pipeline +step init=./s45b.pol:s45b_tc32 +step proj=utm inv ellps=intl zone=32 +step proj=cart ellps=intl +step proj=helmert convention=coordinate_frame + 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 +</pre></div> +</div> +<p>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 <span id="id2">[<a class="reference internal" href="../zreferences.html#id3" title="Altamimi, Z., Sillard, P., and Boucher, C. ITRF2000: a new release of the International Terrestrial Reference Frame for earth science applications. Journal of Geophysical Research: Solid Earth, 2002. doi:10.1029/2001JB000561.">Altamimi2002</a>]</span>, +except the epoch which is the epoch of the transformation. +The last step in the pipeline is converting the +coordinate timestamps back to GPS weeks.</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>proj=pipeline +step proj=unitconvert t_in=gps_week t_out=decimalyear +step proj=helmert convention=coordinate_frame + 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 + t_epoch=1988.0 +step proj=unitconvert t_in=decimalyear t_out=gps_week +</pre></div> +</div> +</section> +<section id="proj-4-x-5-x-paradigm"> +<h2>PROJ 4.x/5.x paradigm<a class="headerlink" href="#proj-4-x-5-x-paradigm" title="Permalink to this headline">¶</a></h2> +<blockquote id="cs2cs-specific-options"> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 16%" /> +<col style="width: 84%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>Parameter</p></th> +<th class="head"><p>Description</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>+datum</p></td> +<td><p>Datum name (see <code class="docutils literal notranslate"><span class="pre">proj</span> <span class="pre">-ld</span></code>)</p></td> +</tr> +<tr class="row-odd"><td><p>+geoidgrids</p></td> +<td><p>Filename of GTX grid file to use for vertical datum transforms</p></td> +</tr> +<tr class="row-even"><td><p>+nadgrids</p></td> +<td><p>Filename of NTv2 grid file to use for datum transforms</p></td> +</tr> +<tr class="row-odd"><td><p>+towgs84</p></td> +<td><p>3 or 7 term datum transform parameters</p></td> +</tr> +<tr class="row-even"><td><p>+to_meter</p></td> +<td><p>Multiplier to convert map units to 1.0m</p></td> +</tr> +<tr class="row-odd"><td><p>+vto_meter</p></td> +<td><p>Vertical conversion to meters</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<div class="admonition warning"> +<p class="admonition-title">Warning</p> +<p>This section documents the behavior of PROJ 4.x and 5.x. In PROJ 6.x, +<strong class="program">cs2cs</strong> has been reworked to use <a class="reference internal" href="../development/reference/functions.html#c.proj_create_crs_to_crs" title="proj_create_crs_to_crs"><code class="xref c c-func docutils literal notranslate"><span class="pre">proj_create_crs_to_crs()</span></code></a> internally, +with <em>late binding</em> capabilities, and thus is no longer constrained to using +WGS84 as a pivot (also called as <em>early binding</em> method). +When <strong class="program">cs2cs</strong> of PROJ 6 is used with PROJ.4 expanded strings to describe the CRS, +including <code class="docutils literal notranslate"><span class="pre">+towgs84</span></code>, <code class="docutils literal notranslate"><span class="pre">+nadgrids</span></code> and <code class="docutils literal notranslate"><span class="pre">+geoidgrids</span></code>, it will generally give +the same results as earlier PROJ versions. When used with AUTHORITY:CODE +CRS descriptions, it may return different results.</p> +</div> +<p>The <em>cs2cs</em> framework in PROJ 4 and 5 delivers a subset of the geodetic transformations available +with the <em>pipeline</em> framework. Coordinate transformations done in this framework +were 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 <code class="docutils literal notranslate"><span class="pre">+towgs84</span></code>, +<code class="docutils literal notranslate"><span class="pre">+nadgrids</span></code> and <code class="docutils literal notranslate"><span class="pre">+geoidgrids</span></code>. +An inverse transform exists for all three and is applied if +specified in the input proj-string. The most common is <code class="docutils literal notranslate"><span class="pre">+towgs84</span></code>, 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-linear planar correction derived from interpolation in a +correction grid can be applied. Originally this was implemented as a means to +transform coordinates between the North 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, <code class="docutils literal notranslate"><span class="pre">+geoidgrids</span></code> +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</p> +<p>In contrast to the <em>transformation pipeline</em> framework, transformations with the +<em>cs2cs</em> framework in PROJ 4 and 5 were expressed as two separate proj-strings. One proj-string <em>to</em> +WGS84 and one <em>from</em> WGS84. Together they form the mapping from the source +coordinate reference system to the destination coordinate reference system. +When used with the <strong class="program">cs2cs</strong> the source and destination CRS’s are separated by the +special <code class="docutils literal notranslate"><span class="pre">+to</span></code> parameter.</p> +<p>The following example demonstrates converting from the Greek GGRS87 datum +to WGS84 with the <code class="docutils literal notranslate"><span class="pre">+towgs84</span></code> parameter.</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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 0.000 +</pre></div> +</div> +<p>With PROJ 6, you can simply use the following:</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>With PROJ 6, the order of coordinates for EPSG geographic coordinate +reference systems is latitude first, longitude second.</p> +</div> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cs2cs "GGRS87" "WGS 84" +35 20 +35d0'9.575"N 20d0'5.467"E 0.000 + +cs2cs EPSG:4121 EPSG:4326 +35 20 +35d0'9.575"N 20d0'5.467"E 0.000 +</pre></div> +</div> +<p>The EPSG database provides this example for transforming from WGS72 to WGS84 +using an approximated 7 parameter transformation.</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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 0.000 +</pre></div> +</div> +<p>With PROJ 6, you can simply use the following (note the reversed order for +latitude and longitude)</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cs2cs "WGS 72" "WGS 84" +55 4 +55d0'0.09"N 4d0'0.554"E 0.000 + +cs2cs EPSG:4322 EPSG:4326 +55 4 +55d0'0.09"N 4d0'0.554"E 0.000 +</pre></div> +</div> +</section> +<section id="grid-based-datum-adjustments"> +<h2>Grid Based Datum Adjustments<a class="headerlink" href="#grid-based-datum-adjustments" title="Permalink to this headline">¶</a></h2> +<p>In many places (notably North America and Australia) 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.</p> +<p>PROJ supports use of grid files for shifting between various reference frames. +The grid shift table formats are CTable, NTv1 (the old Canadian format), and NTv2 +(<code class="file docutils literal notranslate"><span class="pre">.gsb</span></code> - the new Canadian and Australian format).</p> +<p>The text in this section is based on the <em>cs2cs</em> framework. Gridshifting is off +course also possible with the <em>pipeline</em> framework. The major difference between the +two is that the <em>cs2cs</em> framework is limited to grid mappings to WGS84, whereas with +<em>transformation pipelines</em> it is possible to perform grid shifts between any two +reference frames, as long as a grid exists.</p> +<p>Use of grid shifts with <strong class="program">cs2cs</strong> is specified using the <code class="docutils literal notranslate"><span class="pre">+nadgrids</span></code> +keyword in a coordinate system definition. For example:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>% 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 +</pre></div> +</div> +<p>In this case the <code class="file docutils literal notranslate"><span class="pre">/usr/local/share/proj/ntv1_can.dat</span></code> grid shift file was +loaded, and used to get a grid shift value for the selected point.</p> +<p>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.</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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 +</pre></div> +</div> +<section id="skipping-missing-grids"> +<h3>Skipping Missing Grids<a class="headerlink" href="#skipping-missing-grids" title="Permalink to this headline">¶</a></h3> +<p>The special prefix <code class="docutils literal notranslate"><span class="pre">@</span></code> 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 +<code class="file docutils literal notranslate"><span class="pre">ntv2_0.gsb</span></code> file if available, otherwise it would +fallback to using the <code class="file docutils literal notranslate"><span class="pre">ntv1_can.dat</span></code> file.</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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 +</pre></div> +</div> +</section> +<section id="the-null-grid"> +<h3>The null Grid<a class="headerlink" href="#the-null-grid" title="Permalink to this headline">¶</a></h3> +<p>A special <code class="file docutils literal notranslate"><span class="pre">null</span></code> grid shift file is distributed with PROJ. +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.</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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 +</pre></div> +</div> +<p>For more information see the chapter on <a class="reference internal" href="../resource_files.html#id6"><span class="std std-ref">Other transformation grids</span></a>.</p> +</section> +<section id="caveats"> +<h3>Caveats<a class="headerlink" href="#caveats" title="Permalink to this headline">¶</a></h3> +<ul class="simple"> +<li><p>Where grids overlap (such as conus and <code class="file docutils literal notranslate"><span class="pre">ntv1_can.dat</span></code> for instance) the first +found for a point will be used regardless of whether it is appropriate or +not. So, for instance, <code class="docutils literal notranslate"><span class="pre">+nadgrids=ntv1_can.dat</span></code>,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</p></li> +<li><p>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</p></li> +</ul> +</section> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="projections.html" class="btn btn-neutral float-left" title="Cartographic projection" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="ellipsoids.html" class="btn btn-neutral float-right" title="Ellipsoids" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> + </div> + + <hr/> + + <div role="contentinfo"> + <p>© Copyright 1983-2022. + <span class="lastupdated">Last updated on 22 Mar 2022. + </span></p> + </div> + + Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a + <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> + provided by <a href="https://readthedocs.org">Read the Docs</a>. + + +</footer> + </div> + </div> + </section> + </div> + <script> + jQuery(function () { + SphinxRtdTheme.Navigation.enable(true); + }); + </script> + +</body> +</html>
\ No newline at end of file |