diff options
Diffstat (limited to 'community/rfc')
| -rw-r--r-- | community/rfc/index.html | 161 | ||||
| -rw-r--r-- | community/rfc/rfc-1.html | 325 | ||||
| -rw-r--r-- | community/rfc/rfc-2.html | 1032 | ||||
| -rw-r--r-- | community/rfc/rfc-3.html | 291 | ||||
| -rw-r--r-- | community/rfc/rfc-4.html | 881 | ||||
| -rw-r--r-- | community/rfc/rfc-5.html | 280 | ||||
| -rw-r--r-- | community/rfc/rfc-6.html | 474 | ||||
| -rw-r--r-- | community/rfc/rfc-7.html | 294 |
8 files changed, 3738 insertions, 0 deletions
diff --git a/community/rfc/index.html b/community/rfc/index.html new file mode 100644 index 00000000..eb0dd9de --- /dev/null +++ b/community/rfc/index.html @@ -0,0 +1,161 @@ +<!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>Request for Comments — 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.orgcommunity/rfc/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="PROJ RFC 1: Project Committee Guidelines" href="rfc-1.html" /> + <link rel="prev" title="Code of Conduct" href="../code_of_conduct.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"><a class="reference internal" href="../../usage/index.html">Using PROJ</a></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 current"><a class="reference internal" href="../index.html">Community</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="../channels.html">Communication channels</a></li> +<li class="toctree-l2"><a class="reference internal" href="../contributing.html">Contributing</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_contributions.html">Guidelines for PROJ code contributors</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_of_conduct.html">Code of Conduct</a></li> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Request for Comments</a><ul> +<li class="toctree-l3"><a class="reference internal" href="rfc-1.html">PROJ RFC 1: Project Committee Guidelines</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-2.html">PROJ RFC 2: Initial integration of “GDAL SRS barn” work</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-3.html">PROJ RFC 3: Dependency management</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-4.html">PROJ RFC 4: Remote access to grids and GeoTIFF grids</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-5.html">PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-6.html">PROJ RFC 6: Triangulation-based transformations</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-7.html">PROJ RFC 7: Drop Autotools, maintain CMake</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="../index.html#conference">Conference</a></li> +</ul> +</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">Community</a> »</li> + <li>Request for Comments</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/community/rfc/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="../code_of_conduct.html" class="btn btn-neutral float-left" title="Code of Conduct" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-1.html" class="btn btn-neutral float-right" title="PROJ RFC 1: Project Committee Guidelines" 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="request-for-comments"> +<span id="rfcs"></span><h1>Request for Comments<a class="headerlink" href="#request-for-comments" title="Permalink to this headline">¶</a></h1> +<p>A PROJ RFC describes a major change in the technological underpinnings of +PROJ, major additions to functionality, or changes in the direction of +the project.</p> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="rfc-1.html">PROJ RFC 1: Project Committee Guidelines</a></li> +<li class="toctree-l1"><a class="reference internal" href="rfc-2.html">PROJ RFC 2: Initial integration of “GDAL SRS barn” work</a></li> +<li class="toctree-l1"><a class="reference internal" href="rfc-3.html">PROJ RFC 3: Dependency management</a></li> +<li class="toctree-l1"><a class="reference internal" href="rfc-4.html">PROJ RFC 4: Remote access to grids and GeoTIFF grids</a></li> +<li class="toctree-l1"><a class="reference internal" href="rfc-5.html">PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</a></li> +<li class="toctree-l1"><a class="reference internal" href="rfc-6.html">PROJ RFC 6: Triangulation-based transformations</a></li> +<li class="toctree-l1"><a class="reference internal" href="rfc-7.html">PROJ RFC 7: Drop Autotools, maintain CMake</a></li> +</ul> +</div> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="../code_of_conduct.html" class="btn btn-neutral float-left" title="Code of Conduct" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-1.html" class="btn btn-neutral float-right" title="PROJ RFC 1: Project Committee Guidelines" 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/community/rfc/rfc-1.html b/community/rfc/rfc-1.html new file mode 100644 index 00000000..0bc47530 --- /dev/null +++ b/community/rfc/rfc-1.html @@ -0,0 +1,325 @@ +<!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>PROJ RFC 1: Project Committee Guidelines — 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.orgcommunity/rfc/rfc-1.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="PROJ RFC 2: Initial integration of “GDAL SRS barn” work" href="rfc-2.html" /> + <link rel="prev" title="Request for Comments" 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"><a class="reference internal" href="../../usage/index.html">Using PROJ</a></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 current"><a class="reference internal" href="../index.html">Community</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="../channels.html">Communication channels</a></li> +<li class="toctree-l2"><a class="reference internal" href="../contributing.html">Contributing</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_contributions.html">Guidelines for PROJ code contributors</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_of_conduct.html">Code of Conduct</a></li> +<li class="toctree-l2 current"><a class="reference internal" href="index.html">Request for Comments</a><ul class="current"> +<li class="toctree-l3 current"><a class="current reference internal" href="#">PROJ RFC 1: Project Committee Guidelines</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#summary">Summary</a></li> +<li class="toctree-l4"><a class="reference internal" href="#list-of-psc-members">List of PSC Members</a></li> +<li class="toctree-l4"><a class="reference internal" href="#detailed-process">Detailed Process</a></li> +<li class="toctree-l4"><a class="reference internal" href="#when-is-vote-required">When is Vote Required?</a></li> +<li class="toctree-l4"><a class="reference internal" href="#observations">Observations</a></li> +<li class="toctree-l4"><a class="reference internal" href="#committee-membership">Committee Membership</a></li> +<li class="toctree-l4"><a class="reference internal" href="#membership-responsibilities">Membership Responsibilities</a></li> +<li class="toctree-l4"><a class="reference internal" href="#updates">Updates</a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="rfc-2.html">PROJ RFC 2: Initial integration of “GDAL SRS barn” work</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-3.html">PROJ RFC 3: Dependency management</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-4.html">PROJ RFC 4: Remote access to grids and GeoTIFF grids</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-5.html">PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-6.html">PROJ RFC 6: Triangulation-based transformations</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-7.html">PROJ RFC 7: Drop Autotools, maintain CMake</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="../index.html#conference">Conference</a></li> +</ul> +</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">Community</a> »</li> + <li><a href="index.html">Request for Comments</a> »</li> + <li>PROJ RFC 1: Project Committee Guidelines</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/community/rfc/rfc-1.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="Request for Comments" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-2.html" class="btn btn-neutral float-right" title="PROJ RFC 2: Initial integration of “GDAL SRS barn” work" 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="proj-rfc-1-project-committee-guidelines"> +<span id="rfc1"></span><h1>PROJ RFC 1: Project Committee Guidelines<a class="headerlink" href="#proj-rfc-1-project-committee-guidelines" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Author</dt> +<dd class="field-odd"><p>Frank Warmerdam, Howard Butler</p> +</dd> +<dt class="field-even">Contact</dt> +<dd class="field-even"><p><a class="reference external" href="mailto:howard%40hobu.co">howard<span>@</span>hobu<span>.</span>co</a></p> +</dd> +<dt class="field-odd">Status</dt> +<dd class="field-odd"><p>Passed</p> +</dd> +<dt class="field-even">Last Updated</dt> +<dd class="field-even"><p>2018-06-08</p> +</dd> +</dl> +<section id="summary"> +<h2>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2> +<p>This document describes how the PROJ Project Steering Committee (PSC) +determines membership, and makes decisions on all aspects of the +PROJ project - both technical and non-technical.</p> +<p>Examples of PSC management responsibilities:</p> +<ul class="simple"> +<li><p>setting the overall development road map</p></li> +<li><p>developing technical standards and policies (e.g. coding standards, +file naming conventions, etc…)</p></li> +<li><p>ensuring regular releases (major and maintenance) of PROJ software</p></li> +<li><p>reviewing RFC for technical enhancements to the software</p></li> +<li><p>project infrastructure (e.g. GitHub, continuous integration hosting options, etc…)</p></li> +<li><p>formalization of affiliation with external entities such as OSGeo</p></li> +<li><p>setting project priorities, especially with respect to project sponsorship</p></li> +<li><p>creation and oversight of specialized sub-committees (e.g. project +infrastructure, training)</p></li> +</ul> +<p>In brief the project team votes on proposals on the <a class="reference external" href="http://lists.maptools.org/mailman/listinfo/proj">proj mailing list</a>. Proposals are available for review for at least two days, and a single +veto is sufficient delay progress though ultimately a majority of members can +pass a proposal.</p> +</section> +<section id="list-of-psc-members"> +<h2>List of PSC Members<a class="headerlink" href="#list-of-psc-members" title="Permalink to this headline">¶</a></h2> +<p>(up-to-date as of 2018-06)</p> +<ul class="simple"> +<li><p>Kristian Evers <a class="reference external" href="https://github.com/kbevers">@kbevers</a> (DK) <strong>Chair</strong></p></li> +<li><p>Howard Butler <a class="reference external" href="https://github.com/hobu">@hobu</a> (USA)</p></li> +<li><p>Charles Karney <a class="reference external" href="https://github.com/cffk">@cffk</a> (USA)</p></li> +<li><p>Thomas Knudsen <a class="reference external" href="https://github.com/busstoptaktik">@busstoptaktik</a> (DK)</p></li> +<li><p>Even Rouault <a class="reference external" href="https://github.com/rouault">@rouault</a> (FR)</p></li> +<li><p>Kurt Schwehr <a class="reference external" href="https://github.com/schwehr">@schwehr</a> (USA)</p></li> +<li><p>Frank Warmerdam <a class="reference external" href="https://github.com/warmerdam">@warmerdam</a> (USA) <strong>Emeritus</strong></p></li> +</ul> +</section> +<section id="detailed-process"> +<h2>Detailed Process<a class="headerlink" href="#detailed-process" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>Proposals are written up and submitted on the <a class="reference external" href="http://lists.maptools.org/mailman/listinfo/proj">proj mailing list</a> +for discussion and voting, by any interested party, not just +committee members.</p></li> +<li><p>Proposals need to be available for review for at least two business +days before a final decision can be made.</p></li> +<li><p>Respondents may vote “+1” to indicate support for the proposal and a +willingness to support implementation.</p></li> +<li><p>Respondents may vote “-1” to veto a proposal, but must provide clear +reasoning and alternate approaches to resolving the problem within +the two days.</p></li> +<li><p>A vote of -0 indicates mild disagreement, but has no effect. A 0 +indicates no opinion. A +0 indicate mild support, but has no +effect.</p></li> +<li><p>Anyone may comment on proposals on the list, but only members of the +Project Steering Committee’s votes will be counted.</p></li> +<li><p>A proposal will be accepted if it receives +2 (including the +author) and no vetoes (-1).</p></li> +<li><p>If a proposal is vetoed, and it cannot be revised to satisfy all +parties, then it can be resubmitted for an override vote in which a +majority of all eligible voters indicating +1 is sufficient to pass it. +Note that this is a majority of all committee members, not just those who +actively vote.</p></li> +<li><p>Upon completion of discussion and voting the author should announce +whether they are proceeding (proposal accepted) or are withdrawing +their proposal (vetoed).</p></li> +<li><p>The Chair gets a vote.</p></li> +<li><p>The Chair is responsible for keeping track of who is a member of the +Project Steering Committee (perhaps as part of a PSC file in CVS).</p></li> +<li><p>Addition and removal of members from the committee, as well as selection +of a Chair should be handled as a proposal to the committee.</p></li> +<li><p>The Chair adjudicates in cases of disputes about voting.</p></li> +</ul> +<section id="rfc-origin"> +<h3>RFC Origin<a class="headerlink" href="#rfc-origin" title="Permalink to this headline">¶</a></h3> +<p>PROJ RFC and Project Steering Committee is derived from similar governance +bodies in both the <a class="reference external" href="https://trac.osgeo.org/gdal/wiki/rfc1_pmc">GDAL</a> and +<a class="reference external" href="http://mapserver.org/development/rfc/ms-rfc-23.html">MapServer</a> software +projects.</p> +</section> +</section> +<section id="when-is-vote-required"> +<h2>When is Vote Required?<a class="headerlink" href="#when-is-vote-required" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>Any change to committee membership (new members, removing inactive members)</p></li> +<li><p>Changes to project infrastructure (e.g. tool, location or substantive +configuration)</p></li> +<li><p>Anything that could cause backward compatibility issues.</p></li> +<li><p>Adding substantial amounts of new code.</p></li> +<li><p>Changing inter-subsystem APIs, or objects.</p></li> +<li><p>Issues of procedure.</p></li> +<li><p>When releases should take place.</p></li> +<li><p>Anything dealing with relationships with external entities such as OSGeo</p></li> +<li><p>Anything that might be controversial.</p></li> +</ul> +</section> +<section id="observations"> +<h2>Observations<a class="headerlink" href="#observations" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>The Chair is the ultimate adjudicator if things break down.</p></li> +<li><p>The absolute majority rule can be used to override an obstructionist +veto, but it is intended that in normal circumstances vetoers need to be +convinced to withdraw their veto. We are trying to reach consensus.</p></li> +</ul> +</section> +<section id="committee-membership"> +<h2>Committee Membership<a class="headerlink" href="#committee-membership" title="Permalink to this headline">¶</a></h2> +<p>The PSC is made up of individuals consisting of technical contributors +(e.g. developers) and prominent members of the PROJ user community. +There is no set number of members for the PSC although the initial desire +is to set the membership at 6.</p> +<section id="adding-members"> +<h3>Adding Members<a class="headerlink" href="#adding-members" title="Permalink to this headline">¶</a></h3> +<p>Any member of the <a class="reference external" href="http://lists.maptools.org/mailman/listinfo/proj">proj mailing list</a> may nominate someone for +committee membership at any time. Only existing PSC committee members may +vote on new members. Nominees must receive a majority vote from existing +members to be added to the PSC.</p> +</section> +<section id="stepping-down"> +<h3>Stepping Down<a class="headerlink" href="#stepping-down" title="Permalink to this headline">¶</a></h3> +<p>If for any reason a PSC member is not able to fully participate then they +certainly are free to step down. If a member is not active (e.g. no +voting, no IRC or email participation) for a period of two months then +the committee reserves the right to seek nominations to fill that position. +Should that person become active again (hey, it happens) then they would +certainly be welcome, but would require a nomination.</p> +</section> +</section> +<section id="membership-responsibilities"> +<h2>Membership Responsibilities<a class="headerlink" href="#membership-responsibilities" title="Permalink to this headline">¶</a></h2> +<section id="guiding-development"> +<h3>Guiding Development<a class="headerlink" href="#guiding-development" title="Permalink to this headline">¶</a></h3> +<p>Members should take an active role guiding the development of new features +they feel passionate about. Once a change request has been accepted +and given a green light to proceed does not mean the members are free of +their obligation. PSC members voting “+1” for a change request are +expected to stay engaged and ensure the change is implemented and +documented in a way that is most beneficial to users. Note that this +applies not only to change requests that affect code, but also those +that affect the web site, technical infrastructure, policies and standards.</p> +</section> +<section id="mailing-list-participation"> +<h3>Mailing List Participation<a class="headerlink" href="#mailing-list-participation" title="Permalink to this headline">¶</a></h3> +<p>PSC members are expected to be active on the +<a class="reference external" href="http://lists.maptools.org/mailman/listinfo/proj">proj mailing list</a>, subject to Open Source mailing list +etiquette. Non-developer members of the PSC are not expected to respond +to coding level questions on the developer mailing list, however they +are expected to provide their thoughts and opinions on user level +requirements and compatibility issues when RFC discussions take place.</p> +</section> +</section> +<section id="updates"> +<h2>Updates<a class="headerlink" href="#updates" title="Permalink to this headline">¶</a></h2> +<p><strong>June 2018</strong></p> +<p>RFC 1 was ratified by the following members</p> +</section> +</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="Request for Comments" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-2.html" class="btn btn-neutral float-right" title="PROJ RFC 2: Initial integration of “GDAL SRS barn” work" 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/community/rfc/rfc-2.html b/community/rfc/rfc-2.html new file mode 100644 index 00000000..e9dcd2d6 --- /dev/null +++ b/community/rfc/rfc-2.html @@ -0,0 +1,1032 @@ +<!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>PROJ RFC 2: Initial integration of “GDAL SRS barn” work — 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.orgcommunity/rfc/rfc-2.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="PROJ RFC 3: Dependency management" href="rfc-3.html" /> + <link rel="prev" title="PROJ RFC 1: Project Committee Guidelines" href="rfc-1.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"><a class="reference internal" href="../../usage/index.html">Using PROJ</a></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 current"><a class="reference internal" href="../index.html">Community</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="../channels.html">Communication channels</a></li> +<li class="toctree-l2"><a class="reference internal" href="../contributing.html">Contributing</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_contributions.html">Guidelines for PROJ code contributors</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_of_conduct.html">Code of Conduct</a></li> +<li class="toctree-l2 current"><a class="reference internal" href="index.html">Request for Comments</a><ul class="current"> +<li class="toctree-l3"><a class="reference internal" href="rfc-1.html">PROJ RFC 1: Project Committee Guidelines</a></li> +<li class="toctree-l3 current"><a class="current reference internal" href="#">PROJ RFC 2: Initial integration of “GDAL SRS barn” work</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#summary">Summary</a></li> +<li class="toctree-l4"><a class="reference internal" href="#related-standards">Related standards</a></li> +<li class="toctree-l4"><a class="reference internal" href="#details">Details</a></li> +<li class="toctree-l4"><a class="reference internal" href="#code-repository">Code repository</a></li> +<li class="toctree-l4"><a class="reference internal" href="#database">Database</a></li> +<li class="toctree-l4"><a class="reference internal" href="#utilities">Utilities</a></li> +<li class="toctree-l4"><a class="reference internal" href="#impacted-files">Impacted files</a></li> +<li class="toctree-l4"><a class="reference internal" href="#c-api">C API</a></li> +<li class="toctree-l4"><a class="reference internal" href="#documentation">Documentation</a></li> +<li class="toctree-l4"><a class="reference internal" href="#testing">Testing</a></li> +<li class="toctree-l4"><a class="reference internal" href="#build-requirements">Build requirements</a></li> +<li class="toctree-l4"><a class="reference internal" href="#runtime-requirements">Runtime requirements</a></li> +<li class="toctree-l4"><a class="reference internal" href="#backward-compatibility">Backward compatibility</a></li> +<li class="toctree-l4"><a class="reference internal" href="#future-work">Future work</a></li> +<li class="toctree-l4"><a class="reference internal" href="#adoption-status">Adoption status</a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="rfc-3.html">PROJ RFC 3: Dependency management</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-4.html">PROJ RFC 4: Remote access to grids and GeoTIFF grids</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-5.html">PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-6.html">PROJ RFC 6: Triangulation-based transformations</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-7.html">PROJ RFC 7: Drop Autotools, maintain CMake</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="../index.html#conference">Conference</a></li> +</ul> +</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">Community</a> »</li> + <li><a href="index.html">Request for Comments</a> »</li> + <li>PROJ RFC 2: Initial integration of “GDAL SRS barn” work</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/community/rfc/rfc-2.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="rfc-1.html" class="btn btn-neutral float-left" title="PROJ RFC 1: Project Committee Guidelines" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-3.html" class="btn btn-neutral float-right" title="PROJ RFC 3: Dependency management" 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="proj-rfc-2-initial-integration-of-gdal-srs-barn-work"> +<span id="rfc2"></span><h1>PROJ RFC 2: Initial integration of “GDAL SRS barn” work<a class="headerlink" href="#proj-rfc-2-initial-integration-of-gdal-srs-barn-work" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Author</dt> +<dd class="field-odd"><p>Even Rouault</p> +</dd> +<dt class="field-even">Contact</dt> +<dd class="field-even"><p>even.rouault at spatialys.com</p> +</dd> +<dt class="field-odd">Status</dt> +<dd class="field-odd"><p>Adopted, implemented in PROJ 6.0</p> +</dd> +<dt class="field-even">Initial version</dt> +<dd class="field-even"><p>2018-10-09</p> +</dd> +<dt class="field-odd">Last Updated</dt> +<dd class="field-odd"><p>2018-10-31</p> +</dd> +</dl> +<section id="summary"> +<h2>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2> +<p>This RFC is the result of a first phase of the <a class="reference external" href="https://gdalbarn.com/">GDAL Coordinate System Barn Raising</a> +efforts. In its current state, this work mostly consists of:</p> +<blockquote> +<div><ul class="simple"> +<li><p>a C++ implementation of the ISO-19111:2018 / OGC Topic 2 “Referencing by +coordinates” classes to represent Datums, Coordinate systems, CRSs +(Coordinate Reference Systems) and Coordinate Operations.</p></li> +<li><p>methods to convert between this C++ modeling and WKT1, WKT2 and PROJ string representations of those objects</p></li> +<li><p>management and query of a SQLite3 database of CRS and Coordinate Operation definition</p></li> +<li><p>a C API binding part of those capabilities</p></li> +</ul> +</div></blockquote> +</section> +<section id="related-standards"> +<h2>Related standards<a class="headerlink" href="#related-standards" title="Permalink to this headline">¶</a></h2> +<p>Consult <a class="reference external" href="http://even.rouault.free.fr/proj_cpp_api/html/general_doc.html#standards">Applicable standards</a></p> +<p>(They will be linked from the PROJ documentation)</p> +</section> +<section id="details"> +<h2>Details<a class="headerlink" href="#details" title="Permalink to this headline">¶</a></h2> +<section id="structure-in-packages-namespaces"> +<h3>Structure in packages / namespaces<a class="headerlink" href="#structure-in-packages-namespaces" title="Permalink to this headline">¶</a></h3> +<p>The C++ implementation of the (upcoming) ISO-19111:2018 / OGC Topic 2 “Referencing by +coordinates” classes follows this abstract modeling as much as possible, using +package names as C++ namespaces, abstract classes and method names. A new +BoundCRS class has been added to cover the modeling of the WKT2 BoundCRS +construct, that is a generalization of the WKT1 TOWGS84 concept. It is +strongly recommended to have the ISO-19111 standard open to have an introduction +for the concepts when looking at the code. A few classes have also been +inspired by the GeoAPI</p> +<p>The classes are organized into several namespaces:</p> +<blockquote> +<div><ul> +<li><dl> +<dt>osgeo::proj::util</dt><dd><p>A set of base types from ISO 19103, GeoAPI and other PROJ “technical” +specific classes</p> +<p>Template optional<T>, classes BaseObject, IComparable, BoxedValue, +ArrayOfBaseObject, PropertyMap, LocalName, NameSpace, GenericName, +NameFactory, CodeList, Exception, InvalidValueTypeException, +UnsupportedOperationException</p> +</dd> +</dl> +</li> +<li><dl> +<dt>osgeo::proj::metadata:</dt><dd><p>Common classes from ISO 19115 (Metadata) standard</p> +<p>Classes Citation, GeographicExtent, GeographicBoundingBox, +TemporalExtent, VerticalExtent, Extent, Identifier, PositionalAccuracy,</p> +</dd> +</dl> +</li> +<li><dl class="simple"> +<dt>osgeo::proj::common:</dt><dd><p>Common classes: UnitOfMeasure, Measure, Scale, Angle, Length, DateTime, +DateEpoch, IdentifiedObject, ObjectDomain, ObjectUsage</p> +</dd> +</dl> +</li> +<li><dl> +<dt>osgeo::proj::cs:</dt><dd><p>Coordinate systems and their axis</p> +<p>Classes AxisDirection, Meridian, CoordinateSystemAxis, CoordinateSystem, +SphericalCS, EllipsoidalCS, VerticalCS, CartesianCS, OrdinalCS, +ParametricCS, TemporalCS, DateTimeTemporalCS, TemporalCountCS, +TemporalMeasureCS</p> +</dd> +</dl> +</li> +<li><dl> +<dt>osgeo::proj::datum:</dt><dd><p>Datum (the relationship of a coordinate system to the body)</p> +<p>Classes Ellipsoid, PrimeMeridian, Datum, DatumEnsemble, +GeodeticReferenceFrame, DynamicGeodeticReferenceFrame, +VerticalReferenceFrame, DynamicVerticalReferenceFrame, TemporalDatum, +EngineeringDatum, ParametricDatum</p> +</dd> +</dl> +</li> +<li><dl> +<dt>osgeo::proj::crs:</dt><dd><p>CRS = coordinate reference system = coordinate system with a datum</p> +<p>Classes CRS, GeodeticCRS, GeographicCRS, DerivedCRS, ProjectedCRS, +VerticalCRS, CompoundCRS, BoundCRS, TemporalCRS, EngineeringCRS, +ParametricCRS, DerivedGeodeticCRS, DerivedGeographicCRS, +DerivedProjectedCRS, DerivedVerticalCRS</p> +</dd> +</dl> +</li> +<li><dl> +<dt>osgeo::proj::operation:</dt><dd><p>Coordinate operations (relationship between any two coordinate +reference systems)</p> +<p>Classes CoordinateOperation, GeneralOperationParameter, +OperationParameter, GeneralParameterValue, ParameterValue, +OperationParameterValue, OperationMethod, InvalidOperation, +SingleOperation, Conversion, Transformation, PointMotionOperation, +ConcatenatedOperation</p> +</dd> +</dl> +</li> +<li><dl class="simple"> +<dt>osgeo::proj::io:</dt><dd><p>I/O classes: WKTFormatter, PROJStringFormatter, FormattingException, +ParsingException, IWKTExportable, IPROJStringExportable, WKTNode, +WKTParser, PROJStringParser, DatabaseContext, AuthorityFactory, +FactoryException, NoSuchAuthorityCodeException</p> +</dd> +</dl> +</li> +</ul> +</div></blockquote> +</section> +<section id="what-does-what"> +<h3>What does what?<a class="headerlink" href="#what-does-what" title="Permalink to this headline">¶</a></h3> +<p>The code to parse WKT and PROJ strings and build ISO-19111 objects is +contained in <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/io.cpp">io.cpp</a></p> +<p>The code to format WKT and PROJ strings from ISO-19111 objects is mostly +contained in the related exportToWKT() and exportToPROJString() methods +overridden in the applicable classes. <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/io.cpp">io.cpp</a> contains the general mechanics +to build such strings.</p> +<p>Regarding WKT strings, three variants are handled in import and export:</p> +<blockquote> +<div><ul class="simple"> +<li><p>WKT2_2018: variant corresponding to the upcoming ISO-19162:2018 standard</p></li> +<li><p>WKT2_2015: variant corresponding to the current ISO-19162:2015 standard</p></li> +<li><p>WKT1_GDAL: variant corresponding to the way GDAL understands the OGC +01-099 and OGC 99-049 standards</p></li> +</ul> +</div></blockquote> +<p>Regarding PROJ strings, two variants are handled in import and export:</p> +<blockquote> +<div><ul class="simple"> +<li><p>PROJ5: variant used by PROJ >= 5, possibly using pipeline constructs, +and avoiding +towgs84 / +nadgrids legacy constructs. This variant honours +axis order and input/output units. That is the pipeline for the conversion +of EPSG:4326 to EPSG:32631 will assume that the input coordinates are in +latitude, longitude order, with degrees.</p></li> +<li><p>PROJ4: variant used by PROJ 4.x</p></li> +</ul> +</div></blockquote> +<p>The raw query of the proj.db database and the upper level construction of +ISO-19111 objects from the database contents is done in <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/factory.cpp">factory.cpp</a></p> +</section> +<section id="a-few-design-principles"> +<h3>A few design principles<a class="headerlink" href="#a-few-design-principles" title="Permalink to this headline">¶</a></h3> +<p>Methods generally take and return xxxNNPtr objects, that is non-null shared +pointers (pointers with internal reference counting). The advantage of this +approach is that the user has not to care about the life-cycle of the +instances (and this makes the code leak-free by design). The only point of +attention is to make sure no reference cycles are made. This is the case for +all classes, except the CoordinateOperation class that point to CRS for +sourceCRS and targetCRS members, whereas DerivedCRS point to a Conversion +instance (which derives from CoordinateOperation). This issue was detected in +the ISO-19111 standard. The solution adopted here is to use std::weak_ptr +in the CoordinateOperation class to avoid the cycle. This design artefact is +transparent to users.</p> +<p>Another important design point is that all ISO19111 objects are immutable after +creation, that is they only have getters that do not modify their states. +Consequently they could possibly use in a thread-safe way. There are however +classes like PROJStringFormatter, WKTFormatter, DatabaseContext, AuthorityFactory +and CoordinateOperationContext whose instances are mutable and thus can not be +used by multiple threads at once.</p> +<p>Example how to build the EPSG:4326 / WGS84 Geographic2D definition from scratch:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>auto greenwich = PrimeMeridian::create( + util::PropertyMap() + .set(metadata::Identifier::CODESPACE_KEY, + metadata::Identifier::EPSG) + .set(metadata::Identifier::CODE_KEY, 8901) + .set(common::IdentifiedObject::NAME_KEY, "Greenwich"), + common::Angle(0)); +// actually predefined as PrimeMeridian::GREENWICH constant + +auto ellipsoid = Ellipsoid::createFlattenedSphere( + util::PropertyMap() + .set(metadata::Identifier::CODESPACE_KEY, metadata::Identifier::EPSG) + .set(metadata::Identifier::CODE_KEY, 7030) + .set(common::IdentifiedObject::NAME_KEY, "WGS 84"), + common::Length(6378137), + common::Scale(298.257223563)); +// actually predefined as Ellipsoid::WGS84 constant + +auto datum = GeodeticReferenceFrame::create( + util::PropertyMap() + .set(metadata::Identifier::CODESPACE_KEY, metadata::Identifier::EPSG) + .set(metadata::Identifier::CODE_KEY, 6326) + .set(common::IdentifiedObject::NAME_KEY, "World Geodetic System 1984"); + ellipsoid + util::optional<std::string>(), // anchor + greenwich); +// actually predefined as GeodeticReferenceFrame::EPSG_6326 constant + +auto geogCRS = GeographicCRS::create( + util::PropertyMap() + .set(metadata::Identifier::CODESPACE_KEY, metadata::Identifier::EPSG) + .set(metadata::Identifier::CODE_KEY, 4326) + .set(common::IdentifiedObject::NAME_KEY, "WGS 84"), + datum, + cs::EllipsoidalCS::createLatitudeLongitude(scommon::UnitOfMeasure::DEGREE)); +// actually predefined as GeographicCRS::EPSG_4326 constant +</pre></div> +</div> +</section> +<section id="algorithmic-focus"> +<h3>Algorithmic focus<a class="headerlink" href="#algorithmic-focus" title="Permalink to this headline">¶</a></h3> +<p>On the algorithmic side, a somewhat involved logic is the +CoordinateOperationFactory::createOperations() in <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/coordinateoperation.cpp">coordinateoperation.cpp</a> +that takes a pair of source and target CRS and returns a set of possible +<a class="reference external" href="https://proj.org/operations/index.html">coordinate operations</a> (either single operations like a Conversion or a +Transformation, or concatenated operations). It uses the intrinsic structure +of those objects to create the coordinate operation pipeline. That is, if +going from a ProjectedCRS to another one, by doing first the inverse conversion +from the source ProjectedCRS to its base GeographicCRS, then finding the +appropriate transformation(s) from this base GeographicCRS to the base +GeographicCRS of the target CRS, and then applying the conversion from this +base GeographicCRS to the target ProjectedCRS. At each step, it queries the +database to find if one or several transformations are available. The +resulting coordinate operations are filtered, and sorted, with user provided hints:</p> +<blockquote> +<div><ul class="simple"> +<li><p>desired accuracy</p></li> +<li><p>area of use, defined as a bounding box in longitude, latitude space (its +actual CRS does not matter for the intended use)</p></li> +<li><p>if no area of use is defined, if and how the area of use of the source +and target CRS should be used. By default, the smallest area of use is +used. The rationale is for example when transforming between a national +ProjectedCRS and a world-scope GeographicCRS to use the are of use of +this ProjectedCRS to select the appropriate datum shifts.</p></li> +<li><p>how the area of use of the candidate transformations and the desired area of +use (either explicitly or implicitly defined, as explained above) are +compared. By default, only transformations whose area of use is fully +contained in the desired area of use are selected. It is also possible +to relax this test by specifying that only an intersection test must be used.</p></li> +<li><p>whether <a class="reference external" href="https://proj.org/resource_files.html#transformation-grids">PROJ transformation grid</a> names should be substituted to the +official names, when a match is found in the <cite>grid_alternatives</cite> table +of the database. Defaults to true</p></li> +<li><p>whether the availability of those grids should be used to filter and sort +the results. By default, the transformations using grids available in the +system will be presented first.</p></li> +</ul> +</div></blockquote> +<p>The results are sorted, with the most relevant ones appearing first in the +result vector. The criteria used are in that order</p> +<blockquote> +<div><ul class="simple"> +<li><p>grid actual availability: operations referencing grids not available will be +listed after ones with available grids</p></li> +<li><p>grid potential availability: operation referencing grids not known at +all in the proj.db will be listed after operations with grids known, but +not available.</p></li> +<li><p>known accuracy: operations with unknown accuracies will be listed +after operations with known accuracy</p></li> +<li><p>area of use: operations with smaller area of use (the intersection of the +operation area of used with the desired area of use) will be listed after +the ones with larger area of use</p></li> +<li><p>accuracy: operations with lower accuracy will be listed after operations +with higher accuracy (caution: lower accuracy actually means a higher numeric +value of the accuracy property, since it is a precision in metre)</p></li> +</ul> +</div></blockquote> +<p>All those settings can be specified in the CoordinateOperationContext instance +passed to createOperations().</p> +<p>An interesting example to understand how those parameters play together is +to use <cite>projinfo -s EPSG:4267 -t EPSG:4326</cite> (NAD27 to WGS84 conversions), +and see how specifying desired area of use, spatial criterion, grid availability, +etc. affects the results.</p> +<p>The following command currently returns 78 results:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>projinfo -s EPSG:4267 -t EPSG:4326 --summary --spatial-test intersects +</pre></div> +</div> +<p>The createOperations() algorithm also does a kind of “CRS routing”. +A typical example is if wanting to transform between CRS A and +CRS B, but no direct transformation is referenced in proj.db between those. +But if there are transformations between A <–> C and B <–> C, then it +is possible to build a concatenated operation A –> C –> B. The typical +example is when C is WGS84, but the implementation is generic and just finds +a common pivot from the database. An example of finding a non-WGS84 pivot is +when searching a transformation between EPSG:4326 and EPSG:6668 (JGD2011 - +Japanese Geodetic Datum 2011), which has no direct transformation registered +in the EPSG database . However there are transformations between those two +CRS and JGD2000 (and also Tokyo datum, but that one involves less accurate +transformations)</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>projinfo -s EPSG:4326 -t EPSG:6668 --grid-check none --bbox 135.42,34.84,142.14,41.58 --summary + +Candidate operations found: 7 +unknown id, Inverse of JGD2000 to WGS 84 (1) + JGD2000 to JGD2011 (1), 1.2 m, Japan - northern Honshu +unknown id, Inverse of JGD2000 to WGS 84 (1) + JGD2000 to JGD2011 (2), 2 m, Japan excluding northern main province +unknown id, Inverse of Tokyo to WGS 84 (108) + Tokyo to JGD2011 (2), 9.2 m, Japan onshore excluding northern main province +unknown id, Inverse of Tokyo to WGS 84 (108) + Tokyo to JGD2000 (2) + JGD2000 to JGD2011 (1), 9.4 m, Japan - northern Honshu +unknown id, Inverse of Tokyo to WGS 84 (2) + Tokyo to JGD2011 (2), 13.2 m, Japan - onshore mainland and adjacent islands +unknown id, Inverse of Tokyo to WGS 84 (2) + Tokyo to JGD2000 (2) + JGD2000 to JGD2011 (1), 13.4 m, Japan - northern Honshu +unknown id, Inverse of Tokyo to WGS 84 (1) + Tokyo to JGD2011 (2), 29.2 m, Asia - Japan and South Korea +</pre></div> +</div> +</section> +</section> +<section id="code-repository"> +<h2>Code repository<a class="headerlink" href="#code-repository" title="Permalink to this headline">¶</a></h2> +<p>The current state of the work can be found in the +<a class="reference external" href="https://github.com/rouault/proj.4/tree/iso19111">iso19111 branch of rouault/proj.4 repository</a> , and is also available as +a GitHub pull request at <a class="reference external" href="https://github.com/OSGeo/proj.4/pull/1040">https://github.com/OSGeo/proj.4/pull/1040</a></p> +<p>Here is a not-so-usable <a class="reference external" href="https://github.com/OSGeo/proj.4/compare/iso19111_dev...rouault:iso19111">comparison with a fixed snapshot of master branch</a></p> +</section> +<section id="database"> +<h2>Database<a class="headerlink" href="#database" title="Permalink to this headline">¶</a></h2> +<section id="content"> +<h3>Content<a class="headerlink" href="#content" title="Permalink to this headline">¶</a></h3> +<p>The database contains CRS and coordinate operation definitions from the <a class="reference external" href="http://www.epsg.org/">EPSG</a> +database (IOGP’s EPSG Geodetic Parameter Dataset) v9.5.3, +<a class="reference external" href="https://geodesie.ign.fr/index.php?page=documentation#titre3">IGNF registry</a> (French National Geographic Institute), ESRI database, as well +as a few customizations.</p> +</section> +<section id="building-for-proj-developers-creating-the-database"> +<h3>Building (for PROJ developers creating the database)<a class="headerlink" href="#building-for-proj-developers-creating-the-database" title="Permalink to this headline">¶</a></h3> +<p>The building of the database is a several stage process:</p> +<section id="construct-sql-scripts-for-epsg"> +<h4>Construct SQL scripts for EPSG<a class="headerlink" href="#construct-sql-scripts-for-epsg" title="Permalink to this headline">¶</a></h4> +<p>The first stage consists in constructing .sql scripts mostly with +CREATE TABLE and INSERT statements to create the database structure and +populate it. There is one .sql file for each database table, populated +with the content of the EPSG database, automatically +generated with the <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a> script, which processes the PostgreSQL +dumps issued by IOGP. A number of other scripts are dedicated to manual +editing, for example <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_alternatives.sql">grid_alternatives.sql</a> file that binds official +grid names to PROJ grid names</p> +</section> +<section id="concert-utf8-sql-to-sqlite3-db"> +<h4>Concert UTF8 SQL to sqlite3 db<a class="headerlink" href="#concert-utf8-sql-to-sqlite3-db" title="Permalink to this headline">¶</a></h4> +<p>The second stage is done automatically by the make process. It pipes the +.sql script, in the right order, to the sqlite3 binary to generate a +first version of the proj.db SQLite3 database.</p> +</section> +<section id="add-extra-registries"> +<h4>Add extra registries<a class="headerlink" href="#add-extra-registries" title="Permalink to this headline">¶</a></h4> +<p>The third stage consists in creating additional .sql files from the +content of other registries. For that process, we need to bind some +definitions of those registries to those of the EPSG database, to be +able to link to existing objects and detect some boring duplicates. +The <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/ignf.sql">ignf.sql</a> file has been generated using +the <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_create_ignf.py">build_db_create_ignf.py</a> script from the current data/IGNF file +that contains CRS definitions (and implicit transformations to WGS84) +as PROJ.4 strings. +The <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/esri.sql">esri.sql</a> file has been generated using the <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_from_esri.py">build_db_from_esri.py</a> +script, from the .csv files in +<a class="reference external" href="https://github.com/Esri/projection-engine-db-doc/tree/master/csv">https://github.com/Esri/projection-engine-db-doc/tree/master/csv</a></p> +</section> +<section id="finalize-proj-db"> +<h4>Finalize proj.db<a class="headerlink" href="#finalize-proj-db" title="Permalink to this headline">¶</a></h4> +<p>The last stage runs make again to incorporate the new .sql files generated +in the previous stage (so the process of building the database involves +a kind of bootstrapping…)</p> +</section> +</section> +<section id="building-for-proj-users"> +<h3>Building (for PROJ users)<a class="headerlink" href="#building-for-proj-users" title="Permalink to this headline">¶</a></h3> +<p>The make process just runs the second stage mentioned above from the .sql +files. The resulting proj.db is currently 5.3 MB large.</p> +</section> +<section id="structure"> +<h3>Structure<a class="headerlink" href="#structure" title="Permalink to this headline">¶</a></h3> +<p>The database is structured into the following tables and views. They generally +match a ISO-19111 concept, and is generally close to the general structure of +the EPSG database. Regarding identification of objects, where the EPSG database +only contains a ‘code’ numeric column, the PROJ database identifies objects +with a (auth_name, code) tuple of string values, allowing several registries to +be combined together.</p> +<ul class="simple"> +<li><dl class="simple"> +<dt>Technical:</dt><dd><ul> +<li><p><cite>authority_list</cite>: view enumerating the authorities present in the database. Currently: EPSG, IGNF, PROJ</p></li> +<li><p><cite>metadata</cite>: a few key/value pairs, for example to indicate the version of the registries imported in the database</p></li> +<li><p><cite>object_view</cite>: synthetic view listing objects (ellipsoids, datums, CRS, coordinate operations…) code and name, and the table name where they are further described</p></li> +<li><p><cite>alias_names</cite>: list possible alias for the <cite>name</cite> field of object table</p></li> +<li><p><cite>link_from_deprecated_to_non_deprecated</cite>: to handle the link between old ESRI to new ESRI/EPSG codes</p></li> +</ul> +</dd> +</dl> +</li> +<li><dl class="simple"> +<dt>Common:</dt><dd><ul> +<li><p><cite>unit_of_measure</cite>: table with UnitOfMeasure definitions.</p></li> +<li><p><cite>area</cite>: table with area-of-use (bounding boxes) applicable to CRS and coordinate operations.</p></li> +</ul> +</dd> +</dl> +</li> +<li><dl class="simple"> +<dt>Coordinate systems:</dt><dd><ul> +<li><p><cite>axis</cite>: table with CoordinateSystemAxis definitions.</p></li> +<li><p><cite>coordinate_system</cite>: table with CoordinateSystem definitions.</p></li> +</ul> +</dd> +</dl> +</li> +<li><dl class="simple"> +<dt>Ellipsoid and datums:</dt><dd><ul> +<li><p><cite>ellipsoid</cite>: table with ellipsoid definitions.</p></li> +<li><p><cite>prime_meridian</cite>: table with PrimeMeridian definitions.</p></li> +<li><p><cite>geodetic_datum</cite>: table with GeodeticReferenceFrame definitions.</p></li> +<li><p><cite>vertical_datum</cite>: table with VerticalReferenceFrame definitions.</p></li> +</ul> +</dd> +</dl> +</li> +<li><dl class="simple"> +<dt>CRS:</dt><dd><ul> +<li><p><cite>geodetic_crs</cite>: table with GeodeticCRS and GeographicCRS definitions.</p></li> +<li><p><cite>projected_crs</cite>: table with ProjectedCRS definitions.</p></li> +<li><p><cite>vertical_crs</cite>: table with VerticalCRS definitions.</p></li> +<li><p><cite>compound_crs</cite>: table with CompoundCRS definitions.</p></li> +</ul> +</dd> +</dl> +</li> +<li><dl class="simple"> +<dt>Coordinate operations:</dt><dd><ul> +<li><p><cite>coordinate_operation_view</cite>: view giving a number of common attributes shared by the concrete tables implementing CoordinateOperation</p></li> +<li><p><cite>conversion</cite>: table with definitions of Conversion (mostly parameter and values of Projection)</p></li> +<li><p><cite>concatenated_operation</cite>: table with definitions of ConcatenatedOperation.</p></li> +<li><p><cite>grid_transformation</cite>: table with all grid-based transformations.</p></li> +<li><p><cite>grid_packages</cite>: table listing packages in which grids can be found. ie “proj-datumgrid”, “proj-datumgrid-europe”, …</p></li> +<li><p><cite>grid_alternatives</cite>: table binding official grid names to PROJ grid names. e.g “Und_min2.5x2.5_egm2008_isw=82_WGS84_TideFree.gz” –> “egm08_25.gtx”</p></li> +<li><p><cite>helmert_transformation</cite>: table with all Helmert-based transformations.</p></li> +<li><p><cite>other_transformation</cite>: table with other type of transformations.</p></li> +</ul> +</dd> +</dl> +</li> +</ul> +<p>The main departure with the structure of the EPSG database is the split of +the various coordinate operations over several tables. This was done mostly +for human-readability as the EPSG organization of coordoperation, +coordoperationmethod, coordoperationparam, coordoperationparamusage, +coordoperationparamvalue tables makes it hard to grasp at once all the +parameters and values for a given operation.</p> +</section> +</section> +<section id="utilities"> +<h2>Utilities<a class="headerlink" href="#utilities" title="Permalink to this headline">¶</a></h2> +<p>A new <cite>projinfo</cite> utility has been added. It enables the user to enter a CRS or +coordinate operation by a AUTHORITY:CODE, PROJ string or WKT string, and see +it translated in the different flavors of PROJ and WKT strings. +It also enables to build coordinate operations between two CRSs.</p> +<section id="usage"> +<h3>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h3> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>usage: projinfo [-o formats] [-k crs|operation] [--summary] [-q] + [--bbox min_long,min_lat,max_long,max_lat] + [--spatial-test contains|intersects] + [--crs-extent-use none|both|intersection|smallest] + [--grid-check none|discard_missing|sort] + [--boundcrs-to-wgs84] + {object_definition} | (-s {srs_def} -t {srs_def}) + +-o: formats is a comma separated combination of: all,default,PROJ4,PROJ,WKT_ALL,WKT2_2015,WKT2_2018,WKT1_GDAL + Except 'all' and 'default', other format can be preceded by '-' to disable them +</pre></div> +</div> +</section> +<section id="examples"> +<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3> +<section id="specify-crs-by-authority-code"> +<h4>Specify CRS by AUTHORITY:CODE<a class="headerlink" href="#specify-crs-by-authority-code" title="Permalink to this headline">¶</a></h4> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ projinfo EPSG:4326 + +PROJ string: ++proj=pipeline +step +proj=longlat +ellps=WGS84 +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1 + +WKT2_2015 string: +GEODCRS["WGS 84", + DATUM["World Geodetic System 1984", + ELLIPSOID["WGS 84",6378137,298.257223563, + LENGTHUNIT["metre",1]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + CS[ellipsoidal,2], + AXIS["geodetic latitude (Lat)",north, + ORDER[1], + ANGLEUNIT["degree",0.0174532925199433]], + AXIS["geodetic longitude (Lon)",east, + ORDER[2], + ANGLEUNIT["degree",0.0174532925199433]], + AREA["World"], + BBOX[-90,-180,90,180], + ID["EPSG",4326]] +</pre></div> +</div> +</section> +<section id="specify-crs-by-proj-string-and-specify-output-formats"> +<h4>Specify CRS by PROJ string and specify output formats<a class="headerlink" href="#specify-crs-by-proj-string-and-specify-output-formats" title="Permalink to this headline">¶</a></h4> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ projinfo -o PROJ4,PROJ,WKT1_GDAL,WKT2_2018 "+title=IGN 1972 Nuku Hiva - UTM fuseau 7 Sud +proj=tmerc +towgs84=165.7320,216.7200,180.5050,-0.6434,-0.4512,-0.0791,7.420400 +a=6378388.0000 +rf=297.0000000000000 +lat_0=0.000000000 +lon_0=-141.000000000 +k_0=0.99960000 +x_0=500000.000 +y_0=10000000.000 +units=m +no_defs" + +PROJ string: +Error when exporting to PROJ string: BoundCRS cannot be exported as a PROJ.5 string, but its baseCRS might + +PROJ.4 string: ++proj=utm +zone=7 +south +ellps=intl +towgs84=165.732,216.72,180.505,-0.6434,-0.4512,-0.0791,7.4204 + +WKT2_2018 string: +BOUNDCRS[ + SOURCECRS[ + PROJCRS["IGN 1972 Nuku Hiva - UTM fuseau 7 Sud", + BASEGEOGCRS["unknown", + DATUM["unknown", + ELLIPSOID["International 1909 (Hayford)",6378388,297, + LENGTHUNIT["metre",1, + ID["EPSG",9001]]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8901]]], + CONVERSION["unknown", + METHOD["Transverse Mercator", + ID["EPSG",9807]], + PARAMETER["Latitude of natural origin",0, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8801]], + PARAMETER["Longitude of natural origin",-141, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8802]], + PARAMETER["Scale factor at natural origin",0.9996, + SCALEUNIT["unity",1], + ID["EPSG",8805]], + PARAMETER["False easting",500000, + LENGTHUNIT["metre",1], + ID["EPSG",8806]], + PARAMETER["False northing",10000000, + LENGTHUNIT["metre",1], + ID["EPSG",8807]]], + CS[Cartesian,2], + AXIS["(E)",east, + ORDER[1], + LENGTHUNIT["metre",1, + ID["EPSG",9001]]], + AXIS["(N)",north, + ORDER[2], + LENGTHUNIT["metre",1, + ID["EPSG",9001]]]]], + TARGETCRS[ + GEOGCRS["WGS 84", + DATUM["World Geodetic System 1984", + ELLIPSOID["WGS 84",6378137,298.257223563, + LENGTHUNIT["metre",1]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + CS[ellipsoidal,2], + AXIS["latitude",north, + ORDER[1], + ANGLEUNIT["degree",0.0174532925199433]], + AXIS["longitude",east, + ORDER[2], + ANGLEUNIT["degree",0.0174532925199433]], + ID["EPSG",4326]]], + ABRIDGEDTRANSFORMATION["Transformation from unknown to WGS84", + METHOD["Position Vector transformation (geog2D domain)", + ID["EPSG",9606]], + PARAMETER["X-axis translation",165.732, + ID["EPSG",8605]], + PARAMETER["Y-axis translation",216.72, + ID["EPSG",8606]], + PARAMETER["Z-axis translation",180.505, + ID["EPSG",8607]], + PARAMETER["X-axis rotation",-0.6434, + ID["EPSG",8608]], + PARAMETER["Y-axis rotation",-0.4512, + ID["EPSG",8609]], + PARAMETER["Z-axis rotation",-0.0791, + ID["EPSG",8610]], + PARAMETER["Scale difference",1.0000074204, + ID["EPSG",8611]]]] + +WKT1_GDAL: +PROJCS["IGN 1972 Nuku Hiva - UTM fuseau 7 Sud", + GEOGCS["unknown", + DATUM["unknown", + SPHEROID["International 1909 (Hayford)",6378388,297], + TOWGS84[165.732,216.72,180.505,-0.6434,-0.4512,-0.0791,7.4204]], + PRIMEM["Greenwich",0, + AUTHORITY["EPSG","8901"]], + UNIT["degree",0.0174532925199433, + AUTHORITY["EPSG","9122"]], + AXIS["Longitude",EAST], + AXIS["Latitude",NORTH]], + PROJECTION["Transverse_Mercator"], + PARAMETER["latitude_of_origin",0], + PARAMETER["central_meridian",-141], + PARAMETER["scale_factor",0.9996], + PARAMETER["false_easting",500000], + PARAMETER["false_northing",10000000], + UNIT["metre",1, + AUTHORITY["EPSG","9001"]], + AXIS["Easting",EAST], + AXIS["Northing",NORTH]] +</pre></div> +</div> +</section> +<section id="find-transformations-between-2-crs"> +<h4>Find transformations between 2 CRS<a class="headerlink" href="#find-transformations-between-2-crs" title="Permalink to this headline">¶</a></h4> +<p>Between “Poland zone I” (based on Pulkovo 42 datum) and “UTM WGS84 zone 34N”</p> +<p>Summary view:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ projinfo -s EPSG:2171 -t EPSG:32634 --summary + +Candidate operations found: 1 +unknown id, Inverse of Poland zone I + Pulkovo 1942(58) to WGS 84 (1) + UTM zone 34N, 1 m, Poland - onshore +</pre></div> +</div> +<p>Display of pipelines:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ PROJ_LIB=data src/projinfo -s EPSG:2171 -t EPSG:32634 -o PROJ + +PROJ string: ++proj=pipeline +step +proj=axisswap +order=2,1 +step +inv +proj=sterea +lat_0=50.625 +lon_0=21.0833333333333 +k=0.9998 +x_0=4637000 +y_0=5647000 +ellps=krass +step +proj=cart +ellps=krass +step +proj=helmert +x=33.4 +y=-146.6 +z=-76.3 +rx=-0.359 +ry=-0.053 +rz=0.844 +s=-0.84 +convention=position_vector +step +inv +proj=cart +ellps=WGS84 +step +proj=utm +zone=34 +ellps=WGS84 +</pre></div> +</div> +</section> +</section> +</section> +<section id="impacted-files"> +<h2>Impacted files<a class="headerlink" href="#impacted-files" title="Permalink to this headline">¶</a></h2> +<p>New files (excluding makefile.am, CMakeLists.txt and other build infrastructure +artefacts):</p> +<blockquote> +<div><ul class="simple"> +<li><dl class="simple"> +<dt>include/proj/: Public installed C++ headers</dt><dd><ul> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/common.hpp">common.hpp</a>: declarations of osgeo::proj::common namespace.</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/coordinateoperation.hpp">coordinateoperation.hpp</a>: declarations of osgeo::proj::operation namespace.</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/coordinatesystem.hpp">coordinatesystem.hpp</a>: declarations of osgeo::proj::cs namespace.</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/crs.hpp">crs.hpp</a>: declarations of osgeo::proj::crs namespace.</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/datum.hpp">datum.hpp</a>: declarations of osgeo::proj::datum namespace.</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/io.hpp">io.hpp</a>: declarations of osgeo::proj::io namespace.</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/metadata.hpp">metadata.hpp</a>: declarations of osgeo::proj::metadata namespace.</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/util.hpp">util.hpp</a>: declarations of osgeo::proj::util namespace.</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/nn.hpp">nn.hpp</a>: Code from <a class="reference external" href="https://github.com/dropbox/nn">https://github.com/dropbox/nn</a> to manage Non-nullable pointers for C++</p></li> +</ul> +</dd> +</dl> +</li> +</ul> +<ul class="simple"> +<li><dl class="simple"> +<dt>include/proj/internal: Private non-installed C++ headers</dt><dd><ul> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/coordinateoperation_internal.hpp">coordinateoperation_internal.hpp</a>: classes InverseCoordinateOperation, InverseConversion, InverseTransformation, PROJBasedOperation, and functions to get conversion mappings between WKT and PROJ syntax</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/coordinateoperation_constants.hpp">coordinateoperation_constants.hpp</a>: Select subset of conversion/transformation EPSG names and codes for the purpose of translating them to PROJ strings</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/coordinatesystem_internal.hpp">coordinatesystem_internal.hpp</a>: classes AxisDirectionWKT1, AxisName and AxisAbbreviation</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/internal.hpp">internal.hpp</a>: a few helper functions, mostly to do string-based operations</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/io_internal.hpp">io_internal.hpp</a>: class WKTConstants</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/helmert_constants.hpp">helmert_constants.hpp</a>: Helmert-based transformation & parameters names and codes.</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/lru_cache.hpp">lru_cache.hpp</a>: code from <a class="reference external" href="https://github.com/mohaps/lrucache11">https://github.com/mohaps/lrucache11</a> to have a generic Least-Recently-Used cache of objects</p></li> +</ul> +</dd> +</dl> +</li> +</ul> +<ul class="simple"> +<li><dl class="simple"> +<dt>src/:</dt><dd><ul> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/c_api.cpp">c_api.cpp</a>: C++ API mapped to C functions</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/common.cpp">common.cpp</a>: implementation of <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/common.hpp">common.hpp</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/coordinateoperation.cpp">coordinateoperation.cpp</a>: implementation of <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/coordinateoperation.hpp">coordinateoperation.hpp</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/coordinatesystem.cpp">coordinatesystem.cpp</a>: implementation of <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/coordinatesystem.hpp">coordinatesystem.hpp</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/crs.cpp">crs.cpp</a>: implementation of <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/crs.hpp">crs.hpp</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/datum.cpp">datum.cpp</a>: implementation of <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/datum.hpp">datum.hpp</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/factory.cpp">factory.cpp</a>: implementation of AuthorityFactory class (from <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/io.hpp">io.hpp</a>)</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/internal.cpp">internal.cpp</a>: implementation of <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/internal/internal.hpp">internal.hpp</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/io.cpp">io.cpp</a>: implementation of <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/io.hpp">io.hpp</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/metadata.cpp">metadata.cpp</a>: implementation of <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/metadata.hpp">metadata.hpp</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/static.cpp">static.cpp</a>: a number of static constants (like pre-defined well-known ellipsoid, datum and CRS), put in the right order for correct static initializations</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/util.cpp">util.cpp</a>: implementation of <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/include/proj/util.hpp">util.hpp</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/projinfo.cpp">projinfo.cpp</a>: new ‘projinfo’ binary</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/src/general.dox">general.dox</a>: generic introduction documentation.</p></li> +</ul> +</dd> +</dl> +</li> +</ul> +<ul class="simple"> +<li><dl class="simple"> +<dt>data/sql/:</dt><dd><ul> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/area.sql">area.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/axis.sql">axis.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/begin.sql">begin.sql</a>: hand generated (trivial)</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/commit.sql">commit.sql</a>: hand generated (trivial)</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/compound_crs.sql">compound_crs.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/concatenated_operation.sql">concatenated_operation.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/conversion.sql">conversion.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/coordinate_operation.sql">coordinate_operation.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/coordinate_system.sql">coordinate_system.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/crs.sql">crs.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/customizations.sql">customizations.sql</a>: hand generated (empty)</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/ellipsoid.sql">ellipsoid.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/geodetic_crs.sql">geodetic_crs.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/geodetic_datum.sql">geodetic_datum.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_alternatives.sql">grid_alternatives.sql</a>: hand-generated. Contains links between official registry grid names and PROJ ones</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_transformation.sql">grid_transformation.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/grid_transformation_custom.sql">grid_transformation_custom.sql</a>: hand-generated</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/helmert_transformation.sql">helmert_transformation.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/ignf.sql">ignf.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_create_ignf.py">build_db_create_ignf.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/esri.sql">esri.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_from_esri.py">build_db_from_esri.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/metadata.sql">metadata.sql</a>: hand-generated</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/other_transformation.sql">other_transformation.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/prime_meridian.sql">prime_meridian.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/proj_db_table_defs.sql">proj_db_table_defs.sql</a>: hand-generated. Database structure: CREATE TABLE / CREATE VIEW / CREATE TRIGGER</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/projected_crs.sql">projected_crs.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/unit_of_measure.sql">unit_of_measure.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/vertical_crs.sql">vertical_crs.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/vertical_datum.sql">vertical_datum.sql</a>: generated by <a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a></p></li> +</ul> +</dd> +</dl> +</li> +</ul> +<ul class="simple"> +<li><dl class="simple"> +<dt>scripts/:</dt><dd><ul> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db.py">build_db.py</a> : generate .sql files from EPSG database dumps</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_create_ignf.py">build_db_create_ignf.py</a>: generates data/sql/<a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/ignf.sql">ignf.sql</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/build_db_from_esri.py">build_db_from_esri.py</a>: generates data/sql/<a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/esri.sql">esri.sql</a></p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/doxygen.sh">doxygen.sh</a>: generates Doxygen documentation</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/gen_html_coverage.sh">gen_html_coverage.sh</a>: generates HTML report of the coverage for –coverage build</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/filter_lcov_info.py">filter_lcov_info.py</a>: utility used by gen_html_coverage.sh</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/reformat.sh">reformat.sh</a>: used by reformat_cpp.sh</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/scripts/reformat_cpp.sh">reformat_cpp.sh</a>: reformat all .cpp/.hpp files according to LLVM-style formatting rules</p></li> +</ul> +</dd> +</dl> +</li> +</ul> +<ul class="simple"> +<li><dl class="simple"> +<dt>tests/unit/</dt><dd><ul> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_c_api.cpp">test_c_api.cpp</a>: test of src/c_api.cpp</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_common.cpp">test_common.cpp</a>: test of src/common.cpp</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_util.cpp">test_util.cpp</a>: test of src/util.cpp</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_crs.cpp">test_crs.cpp</a>: test of src/crs.cpp</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_datum.cpp">test_datum.cpp</a>: test of src/datum.cpp</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_factory.cpp">test_factory.cpp</a>: test of src/factory.cpp</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_io.cpp">test_io.cpp</a>: test of src/io.cpp</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_metadata.cpp">test_metadata.cpp</a>: test of src/metadata.cpp</p></li> +<li><p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_operation.cpp">test_operation.cpp</a>: test of src/operation.cpp</p></li> +</ul> +</dd> +</dl> +</li> +</ul> +</div></blockquote> +</section> +<section id="c-api"> +<h2>C API<a class="headerlink" href="#c-api" title="Permalink to this headline">¶</a></h2> +<p><a class="reference external" href="http://even.rouault.free.fr/proj_cpp_api/html/proj_8h.html">proj.h</a> has been extended to bind a number of C++ classes/methods to a C API.</p> +<p>The main structure is an opaque PJ_OBJ* roughly encapsulating a osgeo::proj::BaseObject, +that can represent a CRS or a CoordinateOperation object. A number of the +C functions will work only if the right type of underlying C++ object is used +with them. Misuse will be properly handled at runtime. If a user passes +a PJ_OBJ* representing a coordinate operation to a pj_obj_crs_xxxx() function, +it will properly error out. This design has been chosen over creating a +dedicate PJ_xxx object for each C++ class, because such an approach would +require adding many conversion and free functions for little benefit.</p> +<p>This C API is incomplete. In particular, it does not allow to +build ISO19111 objects at hand. However it currently permits a number of +actions:</p> +<blockquote> +<div><ul class="simple"> +<li><p>building CRS and coordinate operations from WKT and PROJ strings, or +from the proj.db database</p></li> +<li><p>exporting CRS and coordinate operations as WKT and PROJ strings</p></li> +<li><p>querying main attributes of those objects</p></li> +<li><p>finding coordinate operations between two CRS.</p></li> +</ul> +</div></blockquote> +<p><a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/test/unit/test_c_api.cpp">test_c_api.cpp</a> should demonstrates simple usage of the API (note: +for the conveniency of writing the tests in C++, test_c_api.cpp wraps the C PJ_OBJ* +instances in C++ ‘keeper’ objects that automatically call the pj_obj_unref() +function at function end. In a pure C use, the caller must use pj_obj_unref() +to prevent leaks.)</p> +</section> +<section id="documentation"> +<h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h2> +<p>All public C++ classes and methods and C functions are documented with +Doxygen.</p> +<p><a class="reference external" href="http://even.rouault.free.fr/proj_cpp_api/html/annotated.html">Current snapshot of Class list</a></p> +<p><a class="reference external" href="http://even.rouault.free.fr/proj_cpp_api/html/inherits.html">Spaghetti inheritance diagram</a></p> +<p>A basic integration of the Doxygen XML output into the general PROJ +documentation (using reStructuredText format) has been done with the +Sphinx extension <a class="reference external" href="https://breathe.readthedocs.io/en/latest/">Breathe</a>, producing:</p> +<blockquote> +<div><ul class="simple"> +<li><p><a class="reference external" href="http://even.rouault.free.fr/proj_cpp_api/rst_generated/html/development/reference/cpp/index.html">One section with the C++ API</a></p></li> +<li><p><a class="reference external" href="http://even.rouault.free.fr/proj_cpp_api/rst_generated/html/development/reference/functions.html#c-api-for-iso-19111-functionality">One section with the C API</a></p></li> +</ul> +</div></blockquote> +</section> +<section id="testing"> +<h2>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2> +<p>Nearly all exported methods are tested by a unit test. Global line coverage +of the new files is 92%. Those tests represent 16k lines of codes.</p> +</section> +<section id="build-requirements"> +<h2>Build requirements<a class="headerlink" href="#build-requirements" title="Permalink to this headline">¶</a></h2> +<p>The new code leverages on a number of C++11 features (auto keyword, constexpr, +initializer list, std::shared_ptr, lambda functions, etc.), which means that +a C++11-compliant compiler must be used to generate PROJ:</p> +<blockquote> +<div><ul class="simple"> +<li><p>gcc >= 4.8</p></li> +<li><p>clang >= 3.3</p></li> +<li><p>Visual Studio >= 2015.</p></li> +</ul> +</div></blockquote> +<p>Compilers tested by the Travis-CI and AppVeyor continuous integration +environments:</p> +<blockquote> +<div><ul class="simple"> +<li><p>GCC 4.8</p></li> +<li><p>mingw-w64-x86-64 4.8</p></li> +<li><p>clang 5.0</p></li> +<li><p>Apple LLVM version 9.1.0 (clang-902.0.39.2)</p></li> +<li><p>MSVC 2015 32 and 64 bit</p></li> +<li><p>MSVC 2017 32 and 64 bit</p></li> +</ul> +</div></blockquote> +<p>The libsqlite3 >= 3.7 development package must also be available. And the sqlite3 +binary must be available to build the proj.db files from the .sql files.</p> +</section> +<section id="runtime-requirements"> +<h2>Runtime requirements<a class="headerlink" href="#runtime-requirements" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>libc++/libstdc++/MSVC runtime consistent with the compiler used</p></li> +<li><p>libsqlite3 >= 3.7</p></li> +</ul> +</section> +<section id="backward-compatibility"> +<h2>Backward compatibility<a class="headerlink" href="#backward-compatibility" title="Permalink to this headline">¶</a></h2> +<p>At this stage, no backward compatibility issue is foreseen, as no +existing functional C code has been modified to use the new capabilities</p> +</section> +<section id="future-work"> +<h2>Future work<a class="headerlink" href="#future-work" title="Permalink to this headline">¶</a></h2> +<p>The work described in this RFC will be pursued in a number of directions. +Non-exhaustively:</p> +<blockquote> +<div><ul class="simple"> +<li><p>Support for ESRI WKT1 dialect (PROJ currently ingest the ProjectedCRS in +<a class="reference external" href="https://github.com/rouault/proj.4/blob/iso19111/data/sql/esri.sql">esri.sql</a> in that dialect, but there is no mapping between it and EPSG +operation and parameter names, so conversion to PROJ strings does not +always work.</p></li> +<li><p>closer integration with the existing code base. In particular, the +init=dict:code +syntax should now go first to the database (then the <cite>epsg</cite> and <cite>IGNF</cite> +files can be removed). Similarly proj_create_crs_to_crs() could use the +new capabilities to find an appropriate coordinate transformation.</p></li> +<li><p>and whatever else changes are needed to address GDAL and libgeotiff needs</p></li> +</ul> +</div></blockquote> +</section> +<section id="adoption-status"> +<h2>Adoption status<a class="headerlink" href="#adoption-status" title="Permalink to this headline">¶</a></h2> +<p>The RFC has been adopted with support from PSC members Kurt Schwehr, Kristian +Evers, Howard Butler and Even Rouault.</p> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="rfc-1.html" class="btn btn-neutral float-left" title="PROJ RFC 1: Project Committee Guidelines" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-3.html" class="btn btn-neutral float-right" title="PROJ RFC 3: Dependency management" 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/community/rfc/rfc-3.html b/community/rfc/rfc-3.html new file mode 100644 index 00000000..3719c8f2 --- /dev/null +++ b/community/rfc/rfc-3.html @@ -0,0 +1,291 @@ +<!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>PROJ RFC 3: Dependency management — 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.orgcommunity/rfc/rfc-3.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="PROJ RFC 4: Remote access to grids and GeoTIFF grids" href="rfc-4.html" /> + <link rel="prev" title="PROJ RFC 2: Initial integration of “GDAL SRS barn” work" href="rfc-2.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"><a class="reference internal" href="../../usage/index.html">Using PROJ</a></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 current"><a class="reference internal" href="../index.html">Community</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="../channels.html">Communication channels</a></li> +<li class="toctree-l2"><a class="reference internal" href="../contributing.html">Contributing</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_contributions.html">Guidelines for PROJ code contributors</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_of_conduct.html">Code of Conduct</a></li> +<li class="toctree-l2 current"><a class="reference internal" href="index.html">Request for Comments</a><ul class="current"> +<li class="toctree-l3"><a class="reference internal" href="rfc-1.html">PROJ RFC 1: Project Committee Guidelines</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-2.html">PROJ RFC 2: Initial integration of “GDAL SRS barn” work</a></li> +<li class="toctree-l3 current"><a class="current reference internal" href="#">PROJ RFC 3: Dependency management</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#summary">Summary</a></li> +<li class="toctree-l4"><a class="reference internal" href="#background">Background</a></li> +<li class="toctree-l4"><a class="reference internal" href="#c-and-c">C and C++</a></li> +<li class="toctree-l4"><a class="reference internal" href="#software-dependencies">Software dependencies</a></li> +<li class="toctree-l4"><a class="reference internal" href="#bootstrapping">Bootstrapping</a></li> +<li class="toctree-l4"><a class="reference internal" href="#adoption-status">Adoption status</a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="rfc-4.html">PROJ RFC 4: Remote access to grids and GeoTIFF grids</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-5.html">PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-6.html">PROJ RFC 6: Triangulation-based transformations</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-7.html">PROJ RFC 7: Drop Autotools, maintain CMake</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="../index.html#conference">Conference</a></li> +</ul> +</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">Community</a> »</li> + <li><a href="index.html">Request for Comments</a> »</li> + <li>PROJ RFC 3: Dependency management</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/community/rfc/rfc-3.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="rfc-2.html" class="btn btn-neutral float-left" title="PROJ RFC 2: Initial integration of “GDAL SRS barn” work" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-4.html" class="btn btn-neutral float-right" title="PROJ RFC 4: Remote access to grids and GeoTIFF grids" 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="proj-rfc-3-dependency-management"> +<span id="rfc3"></span><h1>PROJ RFC 3: Dependency management<a class="headerlink" href="#proj-rfc-3-dependency-management" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Author</dt> +<dd class="field-odd"><p>Kristian Evers</p> +</dd> +<dt class="field-even">Contact</dt> +<dd class="field-even"><p><a class="reference external" href="mailto:kreve%40sdfe.dk">kreve<span>@</span>sdfe<span>.</span>dk</a></p> +</dd> +<dt class="field-odd">Status</dt> +<dd class="field-odd"><p>Adopted</p> +</dd> +<dt class="field-even">Last Updated</dt> +<dd class="field-even"><p>2019-01-16</p> +</dd> +</dl> +<section id="summary"> +<h2>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2> +<p>This document defines a set of guidelines for dependency management in PROJ. +With PROJ being a core component in many downstream software packages clearly +stating which dependencies the library has is of great value. This document +concern both programming language standards as well as minimum required +versions of library dependencies and build tools.</p> +<p>It is proposed to adopt a rolling update scheme that ensures that PROJ is +sufficiently accessible, even on older systems, as well as keeping up with the +technological evolution. The scheme is divided in two parts, one concerning +versions of used programming languages within PROJ and the other concerning +software packages that PROJ depend on.</p> +<p>With adoption of this RFC, versions used for</p> +<ol class="arabic simple"> +<li><p>programming languages will always be at least two revisions behind the most +recent standard</p></li> +<li><p>software packages will always be at least two years old +(patch releases are exempt)</p></li> +</ol> +<p>A change in programming language standard can only be introduced with a new +major version release of PROJ. Changes for software package dependencies can be +introduced with minor version releases of PROJ. Changing the version +requirements for a dependency needs to be approved by the PSC.</p> +<p>Following the above rule set will ensure that all but the most conservative +users of PROJ will be able to build and use the most recent version of the +library.</p> +<p>In the sections below details concerning programming languages and software +dependencies are outlined. The RFC is concluded with a bootstrapping section +that details the state of dependencies after the accept of the RFC.</p> +</section> +<section id="background"> +<h2>Background<a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h2> +<p>PROJ has traditionally been written in C89. Until recently, no formal +requirements of e.g. build systems has been defined and formally accepted by +the project. <a class="reference internal" href="rfc-2.html#rfc2"><span class="std std-ref">RFC2</span></a> formally introduces dependencies on C++11 and +SQLite 3.7.</p> +<p>In this RFC a rolling update of version or standard requirements is described. +The reasoning behind a rolling update scheme is that it has become increasingly +evident that C89 is becoming outdated and creating a less than optimal +development environment for contributors. It has been noted that the most +commonly used compilers all now support more recent versions of C, so the +strict usage of C89 is no longer as critical as it used to be.</p> +<p>Similarly, rolling updates to other tools and libraries that PROJ depend on +will ensure that the code base can be kept modern and in line with the rest of +the open source software ecosphere.</p> +</section> +<section id="c-and-c"> +<h2>C and C++<a class="headerlink" href="#c-and-c" title="Permalink to this headline">¶</a></h2> +<p>Following <a class="reference internal" href="rfc-2.html#rfc2"><span class="std std-ref">RFC2</span></a> PROJ is written in both C and C++. At the time of +writing the core library is C based and the code described in RFC2 is written +in C++. While the core library is mostly written in C it is compiled as C++. +Minor sections of PROJ, like the geodesic algorithms are still compiled as C +since there is no apparent benefit of compiling with a C++ compiler. This may +change in the future.</p> +<p>Both the C and C++ standards are updated with regular intervals. After an +update of a standard it takes time for compiler manufacturers to implement the +standards fully, which makes adaption of new standards potentially troublesome +if done too soon. On the other hand, waiting too long to adopt new standards +will eventually make the code base feel old and new contributors are more +likely to stay away because they don’t want to work using tools of the past. +With a rolling update scheme both concerns can be managed by always staying +behind the most recent standard, but not so far away that potential +contributors are scared away. Keeping a policy of always lagging behind be two +iterations of the standard is thought to be the best comprise between the two +concerns.</p> +<p>C comes in four ISO standardised varieties: C89, C99, C11, C18. In this +document we refer to their informal names for ease of reading. C++ exists in +five varieties: C++98, C++03, C++11, C++14, C++17. Before adoption of this RFC +PROJ uses C89 and C++11. For C, that means that the used standard is three +iterations behind the most recent standard. C++ is two iterations behind. +Following the rules in this RFC the required C standard used in PROJ is at +allowed to be two iterations behind the most recent standard. That means that a +change to C99 is possible, as long as the PROJ PSC acknowledges such a change.</p> +<p>When a new standard for either C or C++ is released PROJ should consider +changing its requirement to the next standard in the line. For C++ that means a +change in standard roughly every three years, for C the periods between +standard updates is expected to be longer. Adaptation of new programming +language standards should be coordinated with a major version release of PROJ.</p> +</section> +<section id="software-dependencies"> +<h2>Software dependencies<a class="headerlink" href="#software-dependencies" title="Permalink to this headline">¶</a></h2> +<p>At the time of writing PROJ is dependent on very few external packages. In +fact only one runtime dependency is present: SQLite. Building PROJ also +requires one of two external dependencies for configuration: Autotools or +CMake.</p> +<p>As with programming language standards it is preferable that software +dependencies are a bit behind the most recent development. For this reason it +is required that the minimum version supported in PROJ dependencies is at least +two years old, preferably more. It is not a requirement that the minimum +version of dependencies is always kept strictly two years behind current +development, but it is allowed in case future development of PROJ warrants an +update. Changes in minimum version requirements are allowed to happen with +minor version releases of PROJ.</p> +<p>At the time of writing the minimum version required for SQLite it 3.7 which was +released in 2010. CMake currently is required to be at least at version 2.8.3 +which was also released in 2010.</p> +</section> +<section id="bootstrapping"> +<h2>Bootstrapping<a class="headerlink" href="#bootstrapping" title="Permalink to this headline">¶</a></h2> +<p>This RFC comes with a set of guidelines for handling dependencies for PROJ in +the future. Up until now dependencies hasn’t been handled consistently, with +some dependencies not being approved formally by the projects governing body. +Therefore minimum versions of PROJ dependencies is proposed so that at the +acception of this RFC PROJ will have the following external requirements:</p> +<ul class="simple"> +<li><p>C99 (was C89)</p></li> +<li><p>C++11 (already approved in <a class="reference internal" href="rfc-2.html#rfc2"><span class="std std-ref">RFC2</span></a>)</p></li> +<li><p>SQLite 3.7 (already approved in <a class="reference internal" href="rfc-2.html#rfc2"><span class="std std-ref">RFC2</span></a>)</p></li> +<li><p>CMake 3.5 (was 2.8.3)</p></li> +</ul> +</section> +<section id="adoption-status"> +<h2>Adoption status<a class="headerlink" href="#adoption-status" title="Permalink to this headline">¶</a></h2> +<p>The RFC was adopted on 2018-01-19 with +1’s from the following PSC members</p> +<ul class="simple"> +<li><p>Kristian Evers</p></li> +<li><p>Even Rouault</p></li> +<li><p>Thomas Knudsen</p></li> +<li><p>Howard Butler</p></li> +</ul> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="rfc-2.html" class="btn btn-neutral float-left" title="PROJ RFC 2: Initial integration of “GDAL SRS barn” work" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-4.html" class="btn btn-neutral float-right" title="PROJ RFC 4: Remote access to grids and GeoTIFF grids" 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/community/rfc/rfc-4.html b/community/rfc/rfc-4.html new file mode 100644 index 00000000..03b40b69 --- /dev/null +++ b/community/rfc/rfc-4.html @@ -0,0 +1,881 @@ +<!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>PROJ RFC 4: Remote access to grids and GeoTIFF grids — 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.orgcommunity/rfc/rfc-4.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="PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ" href="rfc-5.html" /> + <link rel="prev" title="PROJ RFC 3: Dependency management" href="rfc-3.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"><a class="reference internal" href="../../usage/index.html">Using PROJ</a></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 current"><a class="reference internal" href="../index.html">Community</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="../channels.html">Communication channels</a></li> +<li class="toctree-l2"><a class="reference internal" href="../contributing.html">Contributing</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_contributions.html">Guidelines for PROJ code contributors</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_of_conduct.html">Code of Conduct</a></li> +<li class="toctree-l2 current"><a class="reference internal" href="index.html">Request for Comments</a><ul class="current"> +<li class="toctree-l3"><a class="reference internal" href="rfc-1.html">PROJ RFC 1: Project Committee Guidelines</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-2.html">PROJ RFC 2: Initial integration of “GDAL SRS barn” work</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-3.html">PROJ RFC 3: Dependency management</a></li> +<li class="toctree-l3 current"><a class="current reference internal" href="#">PROJ RFC 4: Remote access to grids and GeoTIFF grids</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#motivation">Motivation</a></li> +<li class="toctree-l4"><a class="reference internal" href="#summary-of-work-planned-by-this-rfc">Summary of work planned by this RFC</a></li> +<li class="toctree-l4"><a class="reference internal" href="#network-access-to-grids">Network access to grids</a></li> +<li class="toctree-l4"><a class="reference internal" href="#grids-in-geotiff-format">Grids in GeoTIFF format</a></li> +<li class="toctree-l4"><a class="reference internal" href="#dropping-grid-catalog-functionality">Dropping grid catalog functionality</a></li> +<li class="toctree-l4"><a class="reference internal" href="#backward-compatibility-issues">Backward compatibility issues</a></li> +<li class="toctree-l4"><a class="reference internal" href="#potential-future-related-work">Potential future related work</a></li> +<li class="toctree-l4"><a class="reference internal" href="#documentation">Documentation</a></li> +<li class="toctree-l4"><a class="reference internal" href="#testing">Testing</a></li> +<li class="toctree-l4"><a class="reference internal" href="#proposed-implementation">Proposed implementation</a></li> +<li class="toctree-l4"><a class="reference internal" href="#adoption-status">Adoption status</a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="rfc-5.html">PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-6.html">PROJ RFC 6: Triangulation-based transformations</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-7.html">PROJ RFC 7: Drop Autotools, maintain CMake</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="../index.html#conference">Conference</a></li> +</ul> +</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">Community</a> »</li> + <li><a href="index.html">Request for Comments</a> »</li> + <li>PROJ RFC 4: Remote access to grids and GeoTIFF grids</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/community/rfc/rfc-4.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="rfc-3.html" class="btn btn-neutral float-left" title="PROJ RFC 3: Dependency management" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-5.html" class="btn btn-neutral float-right" title="PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ" 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="proj-rfc-4-remote-access-to-grids-and-geotiff-grids"> +<span id="rfc4"></span><h1>PROJ RFC 4: Remote access to grids and GeoTIFF grids<a class="headerlink" href="#proj-rfc-4-remote-access-to-grids-and-geotiff-grids" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Author</dt> +<dd class="field-odd"><p>Even Rouault, Howard Butler</p> +</dd> +<dt class="field-even">Contact</dt> +<dd class="field-even"><p><a class="reference external" href="mailto:even.rouault%40spatialys.com">even<span>.</span>rouault<span>@</span>spatialys<span>.</span>com</a>, <a class="reference external" href="mailto:howard%40hobu.co">howard<span>@</span>hobu<span>.</span>co</a></p> +</dd> +<dt class="field-odd">Status</dt> +<dd class="field-odd"><p>Adopted</p> +</dd> +<dt class="field-even">Implementation target</dt> +<dd class="field-even"><p>PROJ 7</p> +</dd> +<dt class="field-odd">Last Updated</dt> +<dd class="field-odd"><p>2020-01-10</p> +</dd> +</dl> +<section id="motivation"> +<h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2> +<p>PROJ 6 brings undeniable advances in the management of coordinate +transformations between datums by relying and applying information available in +the PROJ database. PROJ’s rapid evolution from a cartographic projections +library with a little bit of geodetic capability to a full geodetic +transformation and description environment has highlighted the importance of +the support data. Users desire the convenience of software doing the right +thing with the least amount of fuss, and survey organizations wish to deliver +their models across as wide a software footprint as possible. To get results +with the highest precision, a grid file that defines a model that provides +dimension shifts is often needed. The proj-datumgrid project centralizes grids +available under an open data license and bundles them in different archives +split along major geographical regions of the world .</p> +<p>It is assumed that a PROJ user has downloaded and installed grid files that are +referred to in the PROJ database. These files can be quite large in aggregate, +and packaging support by major distribution channels is somewhat uneven due to +their size, sometimes ambiguous licensing story, and difficult-to-track +versioning and lineage. It is not always clear to the user, especially to +those who may not be so familiar with geodetic operations, that the highest +precision transformation may not always being applied if grid data is not +available. Users want both convenience and correctness, and management of the +shift files can be challenging to those who may not be aware of their +importance to the process.</p> +<p>The computing environment in which PROJ operates is also changing. Because the +shift data can be so large (currently more than 700 MB of uncompressed data, +and growing), deployment of high accuracy operations can be limited due to +deployment size constraints (serverless operations, for example). Changing to a +delivery format that supports incremental access over a network along with +convenient access and compression will ease the resource burden the shift files +present while allowing the project to deliver transformation capability with +the highest known precision provided by the survey organizations.</p> +<p>Adjustment grids also tend to be provided in many different formats depending +on the organization and country that produced them. In PROJ, we have over time +“standardized” on using horizontal shift grids as NTv2 and vertical shift grids +using GTX. Both have poor general support as dedicated formats, limited +metadata capabilities, and neither are not necessarily “cloud optimized” for +incremental access across a network.</p> +</section> +<section id="summary-of-work-planned-by-this-rfc"> +<h2>Summary of work planned by this RFC<a class="headerlink" href="#summary-of-work-planned-by-this-rfc" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>Grids will be hosted by one or several Content Delivery Networks (CDN)</p></li> +<li><p>Grid loading mechanism will be reworked to be able to download grids or parts +of grids from a online repository. When opted in, users will no longer have to +manually fetch grid files and place them in PROJ_LIB. +Full and accurate capability of the software will no longer require hundreds +of megabytes of grid shift files in advance, even if only just a few of them +are needed for the transformations done by the user.</p></li> +<li><p>Local caching of grid files, or even part of files, so that users end up +mirroring what they actually use.</p></li> +<li><p>A grid shift format, for both horizontal and vertical shift grids (and in +potential future steps, for other needs, such as deformation models) will be +implemented.</p></li> +</ul> +<p>The use of grids locally available will of course still be available, and will +be the default behavior.</p> +</section> +<section id="network-access-to-grids"> +<h2>Network access to grids<a class="headerlink" href="#network-access-to-grids" title="Permalink to this headline">¶</a></h2> +<p>curl will be an optional build dependency of PROJ, added in autoconf and cmake +build systems. It can be disabled at build time, but this must be +an explicit setting of configure/cmake as the resulting builds have less functionality. +When curl is enabled at build time, download of grids themselves will not be +enabled by default at runtime. It will require explicit consent of the user, either +through the API +(<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>) through the PROJ_NETWORK=ON +environment variable, or the <code class="docutils literal notranslate"><span class="pre">network</span> <span class="pre">=</span> <span class="pre">on</span></code> setting of proj.ini.</p> +<p>Regarding the minimum version of libcurl required, given GDAL experience that +can build with rather ancient libcurl for similar functionality, we can aim for +libcurl >= 7.29.0 (as being available in RHEL 7).</p> +<p>An alternate pluggable network interface can also be set by the user in case +support for libcurl was not built in, or if for the desired context of use, the +user wishes to provide the network implementation (a typical use case could be +QGIS that would use its QT-based networking facilities to solve issues with +SSL, proxy, authentication, etc.)</p> +<p>A text configuration file, installed in ${installation_prefix}/share/proj/proj.ini +(or ${PROJ_LIB}/proj.ini) +will contain the URL of the CDN that will be used. +The user may also override this setting with 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> or through the PROJ_NETWORK_ENDPOINT +environment variable.</p> +<p>The rationale for putting proj.ini in that location is +that it is a well-known place by PROJ users, with the existing PROJ_LIB mechanics +for systems like Windows where hardcoded paths at runtime aren’t generally usable.</p> +<section id="c-api"> +<h3>C API<a class="headerlink" href="#c-api" title="Permalink to this headline">¶</a></h3> +<p>The preliminary C API for the above is:</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/** Enable or disable network access.</span> +<span class="cm">*</span> +<span class="cm">* @param ctx PROJ context, or NULL</span> +<span class="cm">* @return TRUE if network access is possible. That is either libcurl is</span> +<span class="cm">* available, or an alternate interface has been set.</span> +<span class="cm">*/</span><span class="w"></span> +<span class="kt">int</span><span class="w"> </span><span class="nf">proj_context_set_enable_network</span><span class="p">(</span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">enable</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Define URL endpoint to query for remote grids.</span> +<span class="cm">*</span> +<span class="cm">* This overrides the default endpoint in the PROJ configuration file or with</span> +<span class="cm">* the PROJ_NETWORK_ENDPOINT environment variable.</span> +<span class="cm">*</span> +<span class="cm">* @param ctx PROJ context, or NULL</span> +<span class="cm">* @param url Endpoint URL. Must NOT be NULL.</span> +<span class="cm">*/</span><span class="w"></span> +<span class="kt">void</span><span class="w"> </span><span class="nf">proj_context_set_url_endpoint</span><span class="p">(</span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">url</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Opaque structure for PROJ. Implementations might cast it to their</span> +<span class="cm"> * structure/class of choice. */</span><span class="w"></span> +<span class="k">typedef</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">PROJ_NETWORK_HANDLE</span><span class="w"> </span><span class="n">PROJ_NETWORK_HANDLE</span><span class="p">;</span><span class="w"></span> + +<span class="cm">/** Network access: open callback</span> +<span class="cm">*</span> +<span class="cm">* Should try to read the size_to_read first bytes at the specified offset of</span> +<span class="cm">* the file given by URL url,</span> +<span class="cm">* and write them to buffer. *out_size_read should be updated with the actual</span> +<span class="cm">* amount of bytes read (== size_to_read if the file is larger than size_to_read).</span> +<span class="cm">* During this read, the implementation should make sure to store the HTTP</span> +<span class="cm">* headers from the server response to be able to respond to</span> +<span class="cm">* proj_network_get_header_value_cbk_type callback.</span> +<span class="cm">*</span> +<span class="cm">* error_string_max_size should be the maximum size that can be written into</span> +<span class="cm">* the out_error_string buffer (including terminating nul character).</span> +<span class="cm">*</span> +<span class="cm">* @return a non-NULL opaque handle in case of success.</span> +<span class="cm">*/</span><span class="w"></span> +<span class="k">typedef</span><span class="w"> </span><span class="n">PROJ_NETWORK_HANDLE</span><span class="o">*</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">proj_network_open_cbk_type</span><span class="p">)(</span><span class="w"></span> +<span class="w"> </span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">url</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="n">offset</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">size_to_read</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">buffer</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">size_t</span><span class="o">*</span><span class="w"> </span><span class="n">out_size_read</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">error_string_max_size</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">out_error_string</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">user_data</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Network access: close callback */</span><span class="w"></span> +<span class="k">typedef</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">proj_network_close_cbk_type</span><span class="p">)(</span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">PROJ_NETWORK_HANDLE</span><span class="o">*</span><span class="w"> </span><span class="n">handle</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">user_data</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Network access: get HTTP headers */</span><span class="w"></span> +<span class="k">typedef</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">proj_network_get_header_value_cbk_type</span><span class="p">)(</span><span class="w"></span> +<span class="w"> </span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">PROJ_NETWORK_HANDLE</span><span class="o">*</span><span class="w"> </span><span class="n">handle</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">header_name</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">user_data</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Network access: read range</span> +<span class="cm">*</span> +<span class="cm">* Read size_to_read bytes from handle, starting at offset, into</span> +<span class="cm">* buffer.</span> +<span class="cm">* During this read, the implementation should make sure to store the HTTP</span> +<span class="cm">* headers from the server response to be able to respond to</span> +<span class="cm">* proj_network_get_header_value_cbk_type callback.</span> +<span class="cm">*</span> +<span class="cm">* error_string_max_size should be the maximum size that can be written into</span> +<span class="cm">* the out_error_string buffer (including terminating nul character).</span> +<span class="cm">*</span> +<span class="cm">* @return the number of bytes actually read (0 in case of error)</span> +<span class="cm">*/</span><span class="w"></span> +<span class="k">typedef</span><span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">proj_network_read_range_type</span><span class="p">)(</span><span class="w"></span> +<span class="w"> </span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">PROJ_NETWORK_HANDLE</span><span class="o">*</span><span class="w"> </span><span class="n">handle</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="n">offset</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">size_to_read</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">buffer</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">error_string_max_size</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">out_error_string</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">user_data</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Define a custom set of callbacks for network access.</span> +<span class="cm">*</span> +<span class="cm">* All callbacks should be provided (non NULL pointers).</span> +<span class="cm">*</span> +<span class="cm">* @param ctx PROJ context, or NULL</span> +<span class="cm">* @param open_cbk Callback to open a remote file given its URL</span> +<span class="cm">* @param close_cbk Callback to close a remote file.</span> +<span class="cm">* @param get_header_value_cbk Callback to get HTTP headers</span> +<span class="cm">* @param read_range_cbk Callback to read a range of bytes inside a remote file.</span> +<span class="cm">* @param user_data Arbitrary pointer provided by the user, and passed to the</span> +<span class="cm">* above callbacks. May be NULL.</span> +<span class="cm">* @return TRUE in case of success.</span> +<span class="cm">*/</span><span class="w"></span> +<span class="kt">int</span><span class="w"> </span><span class="nf">proj_context_set_network_callbacks</span><span class="p">(</span><span class="w"></span> +<span class="w"> </span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">proj_network_open_cbk_type</span><span class="w"> </span><span class="n">open_cbk</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">proj_network_close_cbk_type</span><span class="w"> </span><span class="n">close_cbk</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">proj_network_get_header_value_cbk_type</span><span class="w"> </span><span class="n">get_header_value_cbk</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">proj_network_read_range_type</span><span class="w"> </span><span class="n">read_range_cbk</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">user_data</span><span class="p">);</span><span class="w"></span> +</pre></div> +</div> +<p>To make network access efficient, PROJ will internally have a in-memory cache +of file ranges to only issue network requests by chunks of 16 KB or multiple of them, +to limit the number of HTTP GET requests and minimize latency caused by network +access. This is very similar to the behavior of the GDAL +<a class="reference external" href="https://gdal.org/user/virtual_file_systems.html#vsicurl-http-https-ftp-files-random-access">/vsicurl/</a> +I/O layer. The plan is to mostly copy GDAL’s vsicurl implementation inside PROJ, with +needed adjustments and proper namespacing of it.</p> +<p>A retry strategy (typically a delay with an exponential back-off and some random +jitter) will be added to account for intermittent network or server-side failure.</p> +</section> +<section id="url-building"> +<h3>URL building<a class="headerlink" href="#url-building" title="Permalink to this headline">¶</a></h3> +<p>The PROJ database has a <code class="docutils literal notranslate"><span class="pre">grid_transformation</span></code> grid whose column <code class="docutils literal notranslate"><span class="pre">grid_name</span></code> +(and possibly <code class="docutils literal notranslate"><span class="pre">grid2_name</span></code>) contain the name of the grid as indicated by the +authority having registered the transformation (typically EPSG). As those +grid names are not generally directly usable by PROJ, the PROJ database has +also a <code class="docutils literal notranslate"><span class="pre">grid_alternatives</span></code> table that link original grid names to the ones used +by PROJ. When network access will be available and needed due to lack of a +local grid, the full URL will be the +endpoint from the configuration or set by the user, the basename of the PROJ +usable filename, and the “tif” suffix. So if the CDN is at <a class="reference external" href="http://example.com">http://example.com</a> +and the name from <code class="docutils literal notranslate"><span class="pre">grid_alternatives</span></code> is egm96_15.gtx, then the URL will +be <a class="reference external" href="http://example.com/egm96_15.tif">http://example.com/egm96_15.tif</a></p> +</section> +<section id="grid-loading"> +<h3>Grid loading<a class="headerlink" href="#grid-loading" title="Permalink to this headline">¶</a></h3> +<p>The following files will be affected, in one way or another, by the above describes +changes: +nad_cvt.cpp, nad_intr.cpp, nad_init.cpp, grid_info.cpp, grid_list.cpp, apply_gridshift.cpp, +apply_vgridshift.cpp.</p> +<p>In particular the current logic that consists to ingest all the values of a +grid/subgrid in the ct->cvs array will be completely modified, to enable +access to grid values at a specified (x,y) location.</p> +</section> +<section id="proj-create-crs-to-crs-proj-create-operations-impacts"> +<h3>proj_create_crs_to_crs() / proj_create_operations() impacts<a class="headerlink" href="#proj-create-crs-to-crs-proj-create-operations-impacts" title="Permalink to this headline">¶</a></h3> +<p>Once network access is available, all grids known to the PROJ database +(grid_transformation + grid_alternatives table) will be assumed to be available, +when computing the potential pipelines between two CRS.</p> +<p>Concretely, this will be equivalent to calling +<code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_operation_factory_context_set_grid_availability_use()</span></code> +with the <code class="docutils literal notranslate"><span class="pre">use</span></code> argument set to a new enumeration value</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/** Results will be presented as if grids known to PROJ (that is</span> +<span class="cm">* registered in the grid_alternatives table of its database) were</span> +<span class="cm">* available. Used typically when networking is enabled.</span> +<span class="cm">*/</span><span class="w"></span> +<span class="n">PROJ_GRID_AVAILABILITY_KNOWN_AVAILABLE</span><span class="w"></span> +</pre></div> +</div> +</section> +<section id="local-on-disk-caching-of-remote-grids"> +<h3>Local on-disk caching of remote grids<a class="headerlink" href="#local-on-disk-caching-of-remote-grids" title="Permalink to this headline">¶</a></h3> +<p>As many workflows will tend to use the same grids over and over, a local +on-disk caching of remote grids will be added. The cache will be a single +SQLite3 database, in a user-writable directory shared by all applications using +PROJ.</p> +<p>Its total size will be configurable, with a default maximum size of 100 MB +in proj.ini. The cache will also keep the timestamp of the last time it checked +various global properties of the file (its size, Last-Modified and ETag headers). +A time-to-live parameter, with a default of 1 day in proj.ini, will be used to +determine whether the CDN should be hit to verify if the information in the +cache is still up-to-date.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/** Enable or disable the local cache of grid chunks</span> +<span class="cm">*</span> +<span class="cm">* This overrides the setting in the PROJ configuration file.</span> +<span class="cm">*</span> +<span class="cm">* @param ctx PROJ context, or NULL</span> +<span class="cm">* @param enabled TRUE if the cache is enabled.</span> +<span class="cm">*/</span><span class="w"></span> +<span class="kt">void</span><span class="w"> </span><span class="nf">proj_grid_cache_set_enable</span><span class="p">(</span><span class="n">PJ_CONTEXT</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">enabled</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Override, for the considered context, the path and file of the local</span> +<span class="cm">* cache of grid chunks.</span> +<span class="cm">*</span> +<span class="cm">* @param ctx PROJ context, or NULL</span> +<span class="cm">* @param fullname Full name to the cache (encoded in UTF-8). If set to NULL,</span> +<span class="cm">* caching will be disabled.</span> +<span class="cm">*/</span><span class="w"></span> +<span class="kt">void</span><span class="w"> </span><span class="nf">proj_grid_cache_set_filename</span><span class="p">(</span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">fullname</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Override, for the considered context, the maximum size of the local</span> +<span class="cm">* cache of grid chunks.</span> +<span class="cm">*</span> +<span class="cm">* @param ctx PROJ context, or NULL</span> +<span class="cm">* @param max_size_MB Maximum size, in mega-bytes (1024*1024 bytes), or</span> +<span class="cm">* negative value to set unlimited size.</span> +<span class="cm">*/</span><span class="w"></span> +<span class="kt">void</span><span class="w"> </span><span class="nf">proj_grid_cache_set_max_size</span><span class="p">(</span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">max_size_MB</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Override, for the considered context, the time-to-live delay for</span> +<span class="cm">* re-checking if the cached properties of files are still up-to-date.</span> +<span class="cm">*</span> +<span class="cm">* @param ctx PROJ context, or NULL</span> +<span class="cm">* @param ttl_seconds Delay in seconds. Use negative value for no expiration.</span> +<span class="cm">*/</span><span class="w"></span> +<span class="kt">void</span><span class="w"> </span><span class="nf">proj_grid_cache_set_ttl</span><span class="p">(</span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">ttl_seconds</span><span class="p">);</span><span class="w"></span> + +<span class="cm">/** Clear the local cache of grid chunks.</span> +<span class="cm"> *</span> +<span class="cm"> * @param ctx PROJ context, or NULL.</span> +<span class="cm"> */</span><span class="w"></span> +<span class="kt">void</span><span class="w"> </span><span class="nf">proj_grid_cache_clear</span><span class="p">(</span><span class="n">PJ_CONTEXT</span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">);</span><span class="w"></span> +</pre></div> +</div> +<p>The planned database structure is:</p> +<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="c1">-- General properties on a file</span> +<span class="k">CREATE</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="n">properties</span><span class="p">(</span><span class="w"></span> +<span class="w"> </span><span class="n">url</span><span class="w"> </span><span class="nb">TEXT</span><span class="w"> </span><span class="k">PRIMARY</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">lastChecked</span><span class="w"> </span><span class="k">TIMESTAMP</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">fileSize</span><span class="w"> </span><span class="nb">INTEGER</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">lastModified</span><span class="w"> </span><span class="nb">TEXT</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">etag</span><span class="w"> </span><span class="nb">TEXT</span><span class="w"></span> +<span class="p">);</span><span class="w"></span> + +<span class="c1">-- Store chunks of data. To avoid any potential fragmentation of the</span> +<span class="c1">-- cache, the data BLOB is always set to the maximum chunk size of 16 KB</span> +<span class="c1">-- (right padded with 0-byte)</span> +<span class="c1">-- The actual size is stored in chunks.data_size</span> +<span class="k">CREATE</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="n">chunk_data</span><span class="p">(</span><span class="w"></span> +<span class="w"> </span><span class="n">id</span><span class="w"> </span><span class="nb">INTEGER</span><span class="w"> </span><span class="k">PRIMARY</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="n">AUTOINCREMENT</span><span class="w"> </span><span class="k">CHECK</span><span class="w"> </span><span class="p">(</span><span class="n">id</span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="mi">0</span><span class="p">),</span><span class="w"></span> +<span class="w"> </span><span class="k">data</span><span class="w"> </span><span class="nb">BLOB</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="w"></span> +<span class="p">);</span><span class="w"></span> + +<span class="c1">-- Record chunks of data by (url, offset)</span> +<span class="k">CREATE</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="n">chunks</span><span class="p">(</span><span class="w"></span> +<span class="w"> </span><span class="n">id</span><span class="w"> </span><span class="nb">INTEGER</span><span class="w"> </span><span class="k">PRIMARY</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="n">AUTOINCREMENT</span><span class="w"> </span><span class="k">CHECK</span><span class="w"> </span><span class="p">(</span><span class="n">id</span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="mi">0</span><span class="p">),</span><span class="w"></span> +<span class="w"> </span><span class="n">url</span><span class="w"> </span><span class="nb">TEXT</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="k">offset</span><span class="w"> </span><span class="nb">INTEGER</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">data_id</span><span class="w"> </span><span class="nb">INTEGER</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">data_size</span><span class="w"> </span><span class="nb">INTEGER</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">fk_chunks_url</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="p">(</span><span class="n">url</span><span class="p">)</span><span class="w"> </span><span class="k">REFERENCES</span><span class="w"> </span><span class="n">properties</span><span class="p">(</span><span class="n">url</span><span class="p">),</span><span class="w"></span> +<span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">fk_chunks_data</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="p">(</span><span class="n">data_id</span><span class="p">)</span><span class="w"> </span><span class="k">REFERENCES</span><span class="w"> </span><span class="n">chunk_data</span><span class="p">(</span><span class="n">id</span><span class="p">)</span><span class="w"></span> +<span class="p">);</span><span class="w"></span> +<span class="k">CREATE</span><span class="w"> </span><span class="k">INDEX</span><span class="w"> </span><span class="n">idx_chunks</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="n">chunks</span><span class="p">(</span><span class="n">url</span><span class="p">,</span><span class="w"> </span><span class="k">offset</span><span class="p">);</span><span class="w"></span> + +<span class="c1">-- Doubly linked list of chunks. The next link is to go to the least-recently</span> +<span class="c1">-- used entries.</span> +<span class="k">CREATE</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="n">linked_chunks</span><span class="p">(</span><span class="w"></span> +<span class="w"> </span><span class="n">id</span><span class="w"> </span><span class="nb">INTEGER</span><span class="w"> </span><span class="k">PRIMARY</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="n">AUTOINCREMENT</span><span class="w"> </span><span class="k">CHECK</span><span class="w"> </span><span class="p">(</span><span class="n">id</span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="mi">0</span><span class="p">),</span><span class="w"></span> +<span class="w"> </span><span class="n">chunk_id</span><span class="w"> </span><span class="nb">INTEGER</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">prev</span><span class="w"> </span><span class="nb">INTEGER</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="k">next</span><span class="w"> </span><span class="nb">INTEGER</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">fk_links_chunkid</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="p">(</span><span class="n">chunk_id</span><span class="p">)</span><span class="w"> </span><span class="k">REFERENCES</span><span class="w"> </span><span class="n">chunks</span><span class="p">(</span><span class="n">id</span><span class="p">),</span><span class="w"></span> +<span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">fk_links_prev</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="p">(</span><span class="n">prev</span><span class="p">)</span><span class="w"> </span><span class="k">REFERENCES</span><span class="w"> </span><span class="n">linked_chunks</span><span class="p">(</span><span class="n">id</span><span class="p">),</span><span class="w"></span> +<span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">fk_links_next</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="p">(</span><span class="k">next</span><span class="p">)</span><span class="w"> </span><span class="k">REFERENCES</span><span class="w"> </span><span class="n">linked_chunks</span><span class="p">(</span><span class="n">id</span><span class="p">)</span><span class="w"></span> +<span class="p">);</span><span class="w"></span> +<span class="k">CREATE</span><span class="w"> </span><span class="k">INDEX</span><span class="w"> </span><span class="n">idx_linked_chunks_chunk_id</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="n">linked_chunks</span><span class="p">(</span><span class="n">chunk_id</span><span class="p">);</span><span class="w"></span> + +<span class="c1">-- Head and tail pointers of the linked_chunks. The head pointer is for</span> +<span class="c1">-- the most-recently used chunk.</span> +<span class="c1">-- There should be just one row in this table.</span> +<span class="k">CREATE</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="n">linked_chunks_head_tail</span><span class="p">(</span><span class="w"></span> +<span class="w"> </span><span class="n">head</span><span class="w"> </span><span class="nb">INTEGER</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="n">tail</span><span class="w"> </span><span class="nb">INTEGER</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">lht_head</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="p">(</span><span class="n">head</span><span class="p">)</span><span class="w"> </span><span class="k">REFERENCES</span><span class="w"> </span><span class="n">linked_chunks</span><span class="p">(</span><span class="n">id</span><span class="p">),</span><span class="w"></span> +<span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">lht_tail</span><span class="w"> </span><span class="k">FOREIGN</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="p">(</span><span class="n">tail</span><span class="p">)</span><span class="w"> </span><span class="k">REFERENCES</span><span class="w"> </span><span class="n">linked_chunks</span><span class="p">(</span><span class="n">id</span><span class="p">)</span><span class="w"></span> +<span class="p">);</span><span class="w"></span> +<span class="k">INSERT</span><span class="w"> </span><span class="k">INTO</span><span class="w"> </span><span class="n">linked_chunks_head_tail</span><span class="w"> </span><span class="k">VALUES</span><span class="w"> </span><span class="p">(</span><span class="k">NULL</span><span class="p">,</span><span class="w"> </span><span class="k">NULL</span><span class="p">);</span><span class="w"></span> +</pre></div> +</div> +<p>The chunks table will store 16 KB chunks (or less for terminating chunks). +The linked_chunks and linked_chunks_head_tail table swill act as a doubly linked +list of chunks, with the least recently used ones at the end of the list, which +will be evicted when the cache saturates.</p> +<p>The directory used to locate this database will be ${XDG_DATA_HOME}/proj +(per <a class="reference external" href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html</a>) +where ${XDG_DATA_HOME} defaults to ${HOME}/.local/share on Unix builds +and ${LOCALAPPDATA} on Windows builds. Exact details to be sorted out, but +<a class="reference external" href="https://github.com/ActiveState/appdirs/blob/a54ea98feed0a7593475b94de3a359e9e1fe8fdb/appdirs.py#L45-L97">https://github.com/ActiveState/appdirs/blob/a54ea98feed0a7593475b94de3a359e9e1fe8fdb/appdirs.py#L45-L97</a> +can be a good reference.</p> +<p>As this database might be accessed by several threads or processes at the same +time, the code accessing to it will carefully honour SQLite3 errors regarding +to locks, to do appropriate retries if another thread/process is currently +locking the database. Accesses requiring a modification of the database will +start with a BEGIN IMMEDIATE transaction so as to acquire a write lock.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>This database should be hosted on a local disk, not a network one. +Otherwise SQLite3 locking issues are to be expected.</p> +</div> +</section> +<section id="cdn-provider"> +<h3>CDN provider<a class="headerlink" href="#cdn-provider" title="Permalink to this headline">¶</a></h3> +<p><a class="reference external" href="https://aws.amazon.com/opendata/public-datasets/">Amazon Public Datasets</a> +has offered to be a storage and CDN provider.</p> +<p>The program covers storage and egress (bandwidth) of the data. +They generally don’t allow usage of CloudFront +(their CDN) as part of the program (we would usually look to have it covered +by credits), but in this instance, they would be fine to provide it. +They’d only ask that we keep the CloudFront URL “visible” (as appropriate for +the use case) so people can see where the data is hosted in case they go looking. +Their terms can be seen at <a class="reference external" href="https://aws.amazon.com/service-terms/">https://aws.amazon.com/service-terms/</a> and CloudFront +has its own, small section. Those terms may change a bit from time to time for +minor changes. Major changing service terms is assumed to be unfrequent. +There are also the Public Dataset Program terms at <a class="reference external" href="http://aws.amazon.com/public-datasets/terms/">http://aws.amazon.com/public-datasets/terms/</a>. +Those also do not effectively change over time and are renewed on a 2 year basis.</p> +</section> +<section id="criteria-for-grid-hosting"> +<h3>Criteria for grid hosting<a class="headerlink" href="#criteria-for-grid-hosting" title="Permalink to this headline">¶</a></h3> +<p>The grids hosted on the CDN will be exactly the ones collected, +currently and in the future, by the <a class="reference external" href="https://github.com/OSGeo/proj-datumgrid/">proj-datumgrid</a> +initiative. In particular, new grids are accepted as long as +they are released under a license that is compatible with the +<a class="reference external" href="https://opensource.org/osd-annotated">Open Source Definition</a> and the source +of the grid is clearly stated and verifiable. Suitable licenses include:</p> +<ul class="simple"> +<li><p>Public domain</p></li> +<li><p>X/MIT</p></li> +<li><p>BSD 2/3/4 clause</p></li> +<li><p>CC0</p></li> +<li><p>CC-BY (v3.0 or later)</p></li> +<li><p>CC-BY-SA (v3.0 or later)</p></li> +</ul> +<p>For new grids to be transparently used by the proj_create_crs_to_crs() mechanics, +they must be registered in the PROJ database (proj.db) in the <code class="docutils literal notranslate"><span class="pre">grid_transformation</span></code> and +<code class="docutils literal notranslate"><span class="pre">grid_alternatives</span></code> table. The nominal path to have a new record in the grid_transformation +is to have a transformation being registered in the EPSG dataset (if there is no +existing one), which will be subsequently imported into the PROJ database.</p> +</section> +<section id="versioning-historical-preservation-of-grids"> +<h3>Versioning, historical preservation of grids<a class="headerlink" href="#versioning-historical-preservation-of-grids" title="Permalink to this headline">¶</a></h3> +<p>The policy regarding this should be similar to the one applied to +<a class="reference external" href="https://github.com/OSGeo/proj-datumgrid/">proj-datumgrid</a>, which even if +not formalized, is around the following lines:</p> +<ul class="simple"> +<li><p>Geodetic agencies release regularly new version of grids. Typically for the +USA, NOAA has released GEOID99, GEOID03, GEOID06, GEOID09, GEOID12A, GEOID12B, +GEOID18 for the NAVD88 to NAD83/NAD83(2011) vertical adjustments. Each of these +grids is considered by EPSG and PROJ has a separate object, with distinct filenames. +The release of a new version does not cause the old grid to be automatically removed. +That said, due to advertized accuracies and supersession rules of the EPSG dataset, the +most recent grid will generally be used for a CRS -> CRS transformation if the +user uses proj_create_crs_to_crs() (with the exception that if a VERT_CRS WKT +includes a GEOID_MODEL known to PROJ, an old version of the grid will be used). +If the user specifies a whole pipeline with an explicit grid name, it will be +of course strictly honoured. +As time goes, the size of the datasets managed by proj-datumgrid will be increasing, +we will have to explore on we managed that for the distributed .zip / .tar.gz +archives. This should not be a concern for CDN hosted content.</p></li> +<li><p>In case software-related conversion errors from the original grid format to the +one used by PROJ (be it GTX, NTv2 or GeoTIFF) would happen, the previous erroneous +version of the dataset would be replaced by the corrected one. In that situation, +this might have an effect with the local on-disk caching of remote grids. We will +have to see with the CDN providers used if we can use for example the ETag HTTP header +on the client to detect a change, so that old cached content is not erroneously +reused (if not possible, we’ll have to use some text file listing the grid names and their +current md5sum)</p></li> +</ul> +</section> +</section> +<section id="grids-in-geotiff-format"> +<h2>Grids in GeoTIFF format<a class="headerlink" href="#grids-in-geotiff-format" title="Permalink to this headline">¶</a></h2> +<section id="limitations-of-current-formats"> +<h3>Limitations of current formats<a class="headerlink" href="#limitations-of-current-formats" title="Permalink to this headline">¶</a></h3> +<p>Several formats exist depending on the ad-hoc needs and ideas of the original +data producer. It would be appropriate to converge on a common format able to +address the different use cases.</p> +<ul class="simple"> +<li><p>Not tiled. Tiling is a nice to have property for cloud-friendly access to +large files.</p></li> +<li><p>No support for compression</p></li> +<li><p>The NTv2 structures is roughly: header of main grid, data of main grid, +header of subgrid 1, data of subgrid 1, header of subgrid 2, data of subgrid 2, +etc.Due to the headers being scattered through the file, it is not possibly +to retrieve with a single HTTP GET request all header information.</p></li> +<li><p>GTX format has no provision to store metadata besides the minimum georeferencing +of the grid. NTv2 is a bit richer, but no extensible metadata possible.</p></li> +</ul> +</section> +<section id="discussion-on-choice-of-format"> +<h3>Discussion on choice of format<a class="headerlink" href="#discussion-on-choice-of-format" title="Permalink to this headline">¶</a></h3> +<p>We have been made recently aware of other initiatives from the industry to come +with a common format to store geodetic adjustment data. Some discussions have +happen recently within the OGC CRS Working group. Past efforts include the +Esri’s proposed Geodetic data Grid eXchange Format, GGXF, briefly mentioned at +page 86 of +<a class="reference external" href="https://iag.dgfi.tum.de/fileadmin/IAG-docs/Travaux2015/01_Travaux_Template_Comm_1_tvd.pdf">https://iag.dgfi.tum.de/fileadmin/IAG-docs/Travaux2015/01_Travaux_Template_Comm_1_tvd.pdf</a> +and page 66 of <a class="reference external" href="ftp://ftp.iaspei.org/pub/meetings/2010-2019/2015-Prague/IAG-Geodesy.pdf">ftp://ftp.iaspei.org/pub/meetings/2010-2019/2015-Prague/IAG-Geodesy.pdf</a> +The current trend of those works would be to use a netCDF / HDF5 container.</p> +<p>So, for the sake of completeness, we list hereafter a few potential candidate +formats and their pros and cons.</p> +<section id="tiff-geotiff"> +<h4>TIFF/GeoTIFF<a class="headerlink" href="#tiff-geotiff" title="Permalink to this headline">¶</a></h4> +<p>Strong points:</p> +<ul class="simple"> +<li><p>TIFF is a well-known and widespread format.</p></li> +<li><p>The GeoTIFF encoding is a widely industry supported scheme to encode georeferencing. +It is now a <a class="reference external" href="https://www.opengeospatial.org/standards/geotiff">OGC standard</a></p></li> +<li><p>There are independent initiatives to share grids as GeoTIFF, like +<a class="reference external" href="https://www.agisoft.com/downloads/geoids/">that one</a></p></li> +<li><p>TIFF can contain multiple images (IFD: Image File Directory) chained together. +This is the mechanism used for multiple-page scanned TIFF files, or in the +geospatial field to store multi-resolution/pyramid rasters. So it can be +used with sub-grids as in the NTv2 format.</p></li> +<li><p>Extensive experience with the TIFF format, and its appropriateness for network +access, in particular through the <a class="reference external" href="https://www.cogeo.org/">Cloud Optimized GeoTIFF initiative</a> +whose layout can make use of sub-grids efficient from a network access +perspective, because grid headers can be put at the beginning of the file, and +so being retrieved in a single HTTP GET request.</p></li> +<li><p>TIFF can be tiled.</p></li> +<li><p>TIFF can be compressed. Commonly found compression formats are DEFLATE, LZW, +combined with differential integer or floating point predictors</p></li> +<li><p>A TIFF image can contain a configurable number of channels/bands/samples. +In the rest of the document, we will use the sample terminology for this concept.</p></li> +<li><p>TIFF sample organization can be configured: either the values of different +samples are packed together (<a class="reference external" href="https://www.awaresystems.be/imaging/tiff/tifftags/planarconfiguration.html">PlanarConfiguration</a> = Contig), or put in separate tiles/strips +(PlanarConfiguration = Separate)</p></li> +<li><p>libtiff is a dependency commonly found in binary distributions of the +“ecosystem” to which PROJ belongs too</p></li> +<li><p>libtiff benefits from many years of efforts to increase its security, for +example being integrated to the oss-fuzz initiative. Given the potential +fetching of grids, using security tested components is an important concern.</p></li> +<li><p>Browser-side: there are “ports” of libtiff/libgeotiff in the browser such +as <a class="reference external" href="https://geotiffjs.github.io/">https://geotiffjs.github.io/</a> which could potentially make a port of PROJ +easier.</p></li> +</ul> +<p>Weak points:</p> +<ul class="simple"> +<li><p>we cannot use libgeotiff, since it depends itself on PROJ (to resolve CRS +or components of CRS from their EPSG codes). That said, for PROJ intended +use, we only need to decode the ModelTiepointTag and ModelPixelScaleTag TIFF +tags, so this can be done “at hand”</p></li> +<li><p>the metadata capabilities of TIFF baseline are limited. The TIFF format comes +with a predefined set of metadata items whose keys have numeric values. That +said, GDAL has used for the last 20 years or so a dedicated tag, +<a class="reference external" href="https://www.awaresystems.be/imaging/tiff/tifftags/gdal_metadata.html">GDAL_METADATA</a> +of code 42112 that holds a XML-formatted string being able to store arbitrary +key-pair values.</p></li> +</ul> +</section> +<section id="netcdf-v3"> +<h4>netCDF v3<a class="headerlink" href="#netcdf-v3" title="Permalink to this headline">¶</a></h4> +<p>Strong points:</p> +<ul class="simple"> +<li><p>The binary format description as given in +<a class="reference external" href="http://portal.opengeospatial.org/files/?artifact_id=43734">OGC 10-092r3</a> is relatively simple, +but it would still probably be necessary to use libnetcdf-c to access it</p></li> +<li><p>Metadata can be stored easily in netCDF attributes</p></li> +</ul> +<p>Weak points:</p> +<ul class="simple"> +<li><p>No compression in netCDF v3</p></li> +<li><p>No tiling in netCDF v3</p></li> +<li><p>Multi-samples variables are located in different sections of the files +(correspond to TIFF PlanarConfiguration = Separate)</p></li> +<li><p>No natural way of having hierarchical / multigrids. They must be encoded as +separate variables</p></li> +<li><p>georeferencing in netCDF is somewhat less standardized than TIFF/GeoTIFF. +The generally used model is <a class="reference external" href="http://cfconventions.org/">the conventions for CF (Climate and Forecast) +metadata</a> +but there is nothing really handy in them for simple georeferencing with +the coordinate of the upper-left pixel and the resolution. The practice is +to write explicit lon and lat variables with all values taken by the grid. +GDAL has for many years supported a simpler syntax, using a GeoTransform +attribute.</p></li> +<li><p>From the format description, its layout could be relatively cloud friendly, +except that libnetcdf has no API to plug an alternate I/O layer.</p></li> +<li><p>Most binary distributions of netCDF nowadays are based on libnetcdf v4, which +implies the HDF5 dependency.</p></li> +<li><p>From a few issues we identified a few years ago regarding crashes on corrupted +datasets, we contacted libnetcdf upstream, but they did not seem to be +interested in addressing those security issues.</p></li> +</ul> +</section> +<section id="netcdf-v4-hdf5"> +<h4>netCDF v4 / HDF5<a class="headerlink" href="#netcdf-v4-hdf5" title="Permalink to this headline">¶</a></h4> +<p>Note: The netCDF v4 format is a profile of the HDF5 file format.</p> +<p>Strong points:</p> +<ul class="simple"> +<li><p>Compression supported (ZLIB and SZIP predefined)</p></li> +<li><p>Tiling (chunking) supported</p></li> +<li><p>Values of Multi-sample variables can be interleaved together (similarly +to TIFF PlanarConfiguration = Contig) by using compound data types.</p></li> +<li><p>Hierarchical organization with groups</p></li> +<li><p>While the netCDF API does not provide an alternate I/O layer, this is +possible with the HDF5 API.</p></li> +<li><p>Grids can be indexed by more than 2 dimensions (for current needs, we +don’t need more than 2D support)</p></li> +</ul> +<p>Weak points:</p> +<ul class="simple"> +<li><p>The <a class="reference external" href="https://support.hdfgroup.org/HDF5/doc/H5.format.html">HDF 5 File format</a> +is more complex than netCDF v3, and likely more than TIFF. We do not have +in-depth expertise of it to assess its cloud-friendliness.</p></li> +<li><p>The ones mentioned for netCDF v3 regarding georeferencing and security apply.</p></li> +</ul> +</section> +<section id="geopackage"> +<h4>GeoPackage<a class="headerlink" href="#geopackage" title="Permalink to this headline">¶</a></h4> +<p>As PROJ has already a SQLite3 dependency, GeoPackage could be examined as a +potential solution.</p> +<p>Strong points:</p> +<ul class="simple"> +<li><p>SQLite3 dependency</p></li> +<li><p>OGC standard</p></li> +<li><p>Multi-grid capabilities</p></li> +<li><p>Tiling</p></li> +<li><p>Compression</p></li> +<li><p>Metadata capabilities</p></li> +</ul> +<p>Weak points:</p> +<ul class="simple"> +<li><p>GeoPackage mostly address the RGB(A) Byte use case, or via the tile gridded +data extension, single-sample non-Byte data. No native support for multi-sample +non-Byte data: each sample should be put in a separate raster table.</p></li> +<li><p>Experience shows that SQLite3 layout (at least the layout adopted when using +the standard libsqlite3) is not cloud friendly. Indices may be scattered in +different places of the file.</p></li> +</ul> +</section> +<section id="conclusions"> +<h4>Conclusions<a class="headerlink" href="#conclusions" title="Permalink to this headline">¶</a></h4> +<p>The 2 major contenders regarding our goals and constraints are GeoTIFF and HDF5. +Given past positive experience and its long history, GeoTIFF remains our preferred +choice.</p> +</section> +</section> +<section id="format-description"> +<span id="description-geotiff-format"></span><h3>Format description<a class="headerlink" href="#format-description" title="Permalink to this headline">¶</a></h3> +<p>The format description is available in a dedicated <a class="reference internal" href="../../specifications/geodetictiffgrids.html#geodetictiffgrids"><span class="std std-ref">Geodetic TIFF grids (GTG)</span></a> +document.</p> +</section> +<section id="tooling"> +<h3>Tooling<a class="headerlink" href="#tooling" title="Permalink to this headline">¶</a></h3> +<p>A script will be developed to accept a list of individual grids to combine +together into a single file.</p> +<p>A ntv2_to_gtiff.py convenience script will be created to convert NTv2 grids, +including their subgrids, to the above +described GeoTIFF layout.</p> +<p>A validation Python script will be created to check that a file meets the above +described requirements and recommendations.</p> +</section> +<section id="build-requirements"> +<h3>Build requirements<a class="headerlink" href="#build-requirements" title="Permalink to this headline">¶</a></h3> +<p>The minimum libtiff version will be 4.0 (RHEL 7 ships with libtiff 4.0.3). +To be able to read grids stored on the CDN, libtiff will need to build against +zlib to have DEFLATE and LZW support, which is met by all known binary distributions +of libtiff.</p> +<p>The libtiff dependency can be disabled at build time, but this must be +an explicit setting of configure/cmake as the resulting builds have less functionality.</p> +</section> +</section> +<section id="dropping-grid-catalog-functionality"> +<h2>Dropping grid catalog functionality<a class="headerlink" href="#dropping-grid-catalog-functionality" title="Permalink to this headline">¶</a></h2> +<p>While digging through existing code, I more or less discovered that the PROJ +code base has the concept of a grid catalog. This is a feature apparently triggered by +using the +catalog=somefilename.csv in a PROJ string, where the CSV file list +grid names, their extent, priority and date. It seems to be an alternative to using ++nadgrids with multiple grids, with the extra ability to interpolate shift values between +several grids if a +date parameter is provided and the grid catalog mentions a +date for each grids. +It was added in June 2012 per <a class="reference external" href="https://github.com/OSGeo/PROJ/commit/fcb186942ec8532655ff6cf4cc990e5da669a3bc">commit fcb186942ec8532655ff6cf4cc990e5da669a3bc</a></p> +<p>This feature is likely unknown to most users as there is no known documentation for +it (neither in current documentation, nor in <a class="reference external" href="https://web.archive.org/web/20160601000000*/http://trac.osgeo.org/proj/wiki/GenParms">historic one</a>). +It is not either tested by PROJ tests, so its working status is unknown. It would +likely make implementation of this RFC easier if this was removed. This would result in +completely dropping the gridcatalog.cpp and gc_reader.cpp files, their call sites +and the catalog_name and datum_date parameter from the PJ structure.</p> +<p>In case similar functionality would be be needed, it might be later reintroduced +as an extra mode of <a class="reference internal" href="../../operations/transformations/hgridshift.html#hgridshift"><span class="std std-ref">Horizontal grid shift</span></a>, or using a dedicated transformation method, +similarly to the <a class="reference internal" href="../../operations/transformations/deformation.html#deformation"><span class="std std-ref">Kinematic datum shifting utilizing a deformation model</span></a> one, +and possibly combining the several grids to interpolate among in the same file, +with a date metadata item.</p> +</section> +<section id="backward-compatibility-issues"> +<h2>Backward compatibility issues<a class="headerlink" href="#backward-compatibility-issues" title="Permalink to this headline">¶</a></h2> +<p>None anticipated, except the removal of the (presumably little used) grid catalog +functionality.</p> +</section> +<section id="potential-future-related-work"> +<h2>Potential future related work<a class="headerlink" href="#potential-future-related-work" title="Permalink to this headline">¶</a></h2> +<p>The foundations set in the definition of the GeoTIFF grid format should hopefully +be reused to extend them to support deformation models (was initially discussed +per <a class="reference external" href="https://github.com/OSGeo/PROJ/issues/1001">https://github.com/OSGeo/PROJ/issues/1001</a>).</p> +<p>Definition of such an extension is out of scope of this RFC.</p> +</section> +<section id="documentation"> +<h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>New API function will be documented.</p></li> +<li><p>A dedicated documentation page will be created to explain the working of +network-based access.</p></li> +<li><p>A dedicated documentation page will be created to describe the GeoTIFF based +grid format. Mostly reusing above material.</p></li> +</ul> +</section> +<section id="testing"> +<h2>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2> +<p>Number of GeoTIFF formulations (tiled vs untiled, PlanarConfiguration Separate vs +Contig, data types, scale+offset vs not, etc.) will be tested.</p> +<p>For testing of network capabilities, a mix of real hits to the CDN and use of +the alternate pluggable network interface to test edge cases will be used.</p> +</section> +<section id="proposed-implementation"> +<h2>Proposed implementation<a class="headerlink" href="#proposed-implementation" title="Permalink to this headline">¶</a></h2> +<p>A proposed implementation is available at <a class="reference external" href="https://github.com/OSGeo/PROJ/pull/1817">https://github.com/OSGeo/PROJ/pull/1817</a></p> +<p>Tooling scripts are currently available at <a class="reference external" href="https://github.com/rouault/sample_proj_gtiff_grids/">https://github.com/rouault/sample_proj_gtiff_grids/</a> +(will be ultimately stored in PROJ repository)</p> +</section> +<section id="adoption-status"> +<h2>Adoption status<a class="headerlink" href="#adoption-status" title="Permalink to this headline">¶</a></h2> +<p>The RFC was adopted on 2020-01-10 with +1’s from the following PSC members</p> +<ul class="simple"> +<li><p>Kristian Evers</p></li> +<li><p>Even Rouault</p></li> +<li><p>Thomas Knudsen</p></li> +<li><p>Howard Butler</p></li> +<li><p>Kurt Schwehr</p></li> +</ul> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="rfc-3.html" class="btn btn-neutral float-left" title="PROJ RFC 3: Dependency management" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-5.html" class="btn btn-neutral float-right" title="PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ" 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/community/rfc/rfc-5.html b/community/rfc/rfc-5.html new file mode 100644 index 00000000..c709c5ed --- /dev/null +++ b/community/rfc/rfc-5.html @@ -0,0 +1,280 @@ +<!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>PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with 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.orgcommunity/rfc/rfc-5.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="PROJ RFC 6: Triangulation-based transformations" href="rfc-6.html" /> + <link rel="prev" title="PROJ RFC 4: Remote access to grids and GeoTIFF grids" href="rfc-4.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"><a class="reference internal" href="../../usage/index.html">Using PROJ</a></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 current"><a class="reference internal" href="../index.html">Community</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="../channels.html">Communication channels</a></li> +<li class="toctree-l2"><a class="reference internal" href="../contributing.html">Contributing</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_contributions.html">Guidelines for PROJ code contributors</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_of_conduct.html">Code of Conduct</a></li> +<li class="toctree-l2 current"><a class="reference internal" href="index.html">Request for Comments</a><ul class="current"> +<li class="toctree-l3"><a class="reference internal" href="rfc-1.html">PROJ RFC 1: Project Committee Guidelines</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-2.html">PROJ RFC 2: Initial integration of “GDAL SRS barn” work</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-3.html">PROJ RFC 3: Dependency management</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-4.html">PROJ RFC 4: Remote access to grids and GeoTIFF grids</a></li> +<li class="toctree-l3 current"><a class="current reference internal" href="#">PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#motivation">Motivation</a></li> +<li class="toctree-l4"><a class="reference internal" href="#summary-of-work-planned-by-this-rfc-and-related-decisions">Summary of work planned by this RFC and related decisions</a></li> +<li class="toctree-l4"><a class="reference internal" href="#backward-compatibility">Backward compatibility</a></li> +<li class="toctree-l4"><a class="reference internal" href="#testing">Testing</a></li> +<li class="toctree-l4"><a class="reference internal" href="#proposed-implementation">Proposed implementation</a></li> +<li class="toctree-l4"><a class="reference internal" href="#adoption-status">Adoption status</a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="rfc-6.html">PROJ RFC 6: Triangulation-based transformations</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-7.html">PROJ RFC 7: Drop Autotools, maintain CMake</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="../index.html#conference">Conference</a></li> +</ul> +</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">Community</a> »</li> + <li><a href="index.html">Request for Comments</a> »</li> + <li>PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/community/rfc/rfc-5.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="rfc-4.html" class="btn btn-neutral float-left" title="PROJ RFC 4: Remote access to grids and GeoTIFF grids" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-6.html" class="btn btn-neutral float-right" title="PROJ RFC 6: Triangulation-based transformations" 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="proj-rfc-5-adopt-geotiff-based-grids-for-grids-delivered-with-proj"> +<span id="rfc5"></span><h1>PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ<a class="headerlink" href="#proj-rfc-5-adopt-geotiff-based-grids-for-grids-delivered-with-proj" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Author</dt> +<dd class="field-odd"><p>Even Rouault</p> +</dd> +<dt class="field-even">Contact</dt> +<dd class="field-even"><p><a class="reference external" href="mailto:even.rouault%40spatialys.com">even<span>.</span>rouault<span>@</span>spatialys<span>.</span>com</a></p> +</dd> +<dt class="field-odd">Status</dt> +<dd class="field-odd"><p>Adopted</p> +</dd> +<dt class="field-even">Implementation target</dt> +<dd class="field-even"><p>PROJ 7</p> +</dd> +<dt class="field-odd">Last Updated</dt> +<dd class="field-odd"><p>2020-01-28</p> +</dd> +</dl> +<section id="motivation"> +<h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2> +<p>This RFC is a continuation of <a class="reference internal" href="rfc-4.html#rfc4"><span class="std std-ref">PROJ RFC 4: Remote access to grids and GeoTIFF grids</span></a>. With RFC4, PROJ can, upon request +of the user, download grids from a CDN in a progressive way. There is also API, +such as <code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_download_file()</span></code> to be able to download a GeoTIFF grid in +the user writable directory. The content of the CDN at <a class="reference external" href="https://cdn.proj.org">https://cdn.proj.org</a> +is <a class="reference external" href="https://github.com/OSGeo/PROJ-data">https://github.com/OSGeo/PROJ-data</a> , which has the same content +as <a class="reference external" href="https://github.com/OSGeo/proj-datumgrid">https://github.com/OSGeo/proj-datumgrid</a> converted in GeoTIFF files. In the +current state, we could have a somewhat inconsistency between users relying on +the proj-datumgrid, proj-datumgrid-[world,northamerica,oceania,europe] packages +of mostly NTv2 and GTX files, and what is shipped through the CDN. Maintaining +two repositories is also a maintenance burden in the long term.</p> +<p>It is thus desirable to have a single source of truth, and we propose it to be +based on the GeoTIFF grids.</p> +</section> +<section id="summary-of-work-planned-by-this-rfc-and-related-decisions"> +<h2>Summary of work planned by this RFC and related decisions<a class="headerlink" href="#summary-of-work-planned-by-this-rfc-and-related-decisions" title="Permalink to this headline">¶</a></h2> +<ul> +<li><p><a class="reference external" href="https://github.com/OSGeo/PROJ-data/">https://github.com/OSGeo/PROJ-data/</a> will be used, starting with +PROJ 7.0, to create “static” grid packages.</p></li> +<li><p>For now, a single package of, mostly GeoTIFF grids (a few text files for +PROJ init style files, as well as a few edge cases for deformation models where +grids have not been converted), will be delivered. +Its size at the time of writing is 486 MB (compared to 1.5 GB of uncompressed +NTv2 + GTX content, compressed to ~ 700 MB currently)</p></li> +<li><p>The content of this archive will be flat, i.e. no subdirectories</p></li> +<li><p>Each file will be named according to the following pattern +<code class="docutils literal notranslate"><span class="pre">${agency_name}_${filename}[.ext]</span></code>. For example fr_ign_ntf_r93.tif +This convention should allow packagers, if the need arise, to be able to +split the monolithic package in smaller ones, based on criterion related to +the country.</p> +<p>The agency name is the one you can see from the directory names at +<a class="reference external" href="https://github.com/OSGeo/PROJ-data/">https://github.com/OSGeo/PROJ-data/</a>. +<code class="docutils literal notranslate"><span class="pre">${agency_name}</span></code> itself is structure like <code class="docutils literal notranslate"><span class="pre">${two_letter_country_code_of_agency_nationality}_${some_abbreviation}</span></code> +(with the exception of eur_nkg, for the Nordic Geodetic Commission which +isn’t affiliated to a single country but to some European countries, and +follows the general scheme)</p> +</li> +<li><p><a class="reference external" href="https://github.com/OSGeo/proj-datumgrid">https://github.com/OSGeo/proj-datumgrid</a> and related packages will only be +maintained during the remaining lifetime of PROJ 6.x. After that, the +repository will no longer receive any update and will be put in archiving +state (see <a class="reference external" href="https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-archiving-repositories">https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-archiving-repositories</a>)</p></li> +<li><p>PROJ database <code class="docutils literal notranslate"><span class="pre">grid_alternatives</span></code> table will be updated to point to the new +TIFF filenames. It will also maintain the old names as used by current +proj-datumgrid packages to be able to provide backward compatibility when +a PROJ string refers to a grid by its previous name.</p></li> +<li><p>Upon adoption of this RFC, new grids referenced by PROJ database will only +point to GeoTIFF grid names.</p></li> +<li><p>Related to the above point, if a PROJ string refers to a grid name, let’s +say foo.gsb. This grid will first be looked for in all the relevant locations +under this name. If no match is found, then a lookup in the +<code class="docutils literal notranslate"><span class="pre">grid_alternatives</span></code> table will be done to retrieve the potential new name +(GeoTIFF file), and if there’s such match, a new look-up in the file system +will be done with the name of this GeoTIFF file.</p></li> +<li><p>The <code class="docutils literal notranslate"><span class="pre">package_name</span></code> column of grid_alternatives will no longer be filled. +And <code class="docutils literal notranslate"><span class="pre">url</span></code> will be filled with the direct URL to the grid in the CDN, for +example: <a class="reference external" href="https://cdn.proj.org/fr_ign_ntf_r93.tif">https://cdn.proj.org/fr_ign_ntf_r93.tif</a></p></li> +<li><p>The Python scripts to convert grids (NTv2, GTX) to GeoTIFF currently available at +<a class="reference external" href="https://github.com/rouault/sample_proj_gtiff_grids/">https://github.com/rouault/sample_proj_gtiff_grids/</a> will be moved to a +grid_tools/ subdirectories of <a class="reference external" href="https://github.com/OSGeo/PROJ-data/">https://github.com/OSGeo/PROJ-data/</a> +Documentation for those utilities will be added to PROJ documentation.</p></li> +<li><p>Obviously, all the above assumes PROJ builds to have libtiff enabled. +Non-libtiff builds are not considered as nominal PROJ builds (if a PROJ master +build is attempted and libtiff is not detected, it fails. The user has to +explicitly ask to disable TIFF support), and users deciding to go through that +route will have to deal with the consequences (that is that +grid-based transformations generated by PROJ will likely be non working)</p></li> +</ul> +</section> +<section id="backward-compatibility"> +<h2>Backward compatibility<a class="headerlink" href="#backward-compatibility" title="Permalink to this headline">¶</a></h2> +<p>This change is considered to be <em>mostly</em> backward compatible. There might be +impacts for software using <code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_coordoperation_get_grid_used()</span></code> and +assuming that the url returned is one of the proj-datumgrid-xxx files at +<a class="reference external" href="https://download.osgeo.org">https://download.osgeo.org</a>. As mentioned in +<a class="reference external" href="https://lists.osgeo.org/pipermail/proj/2020-January/009274.html">https://lists.osgeo.org/pipermail/proj/2020-January/009274.html</a> , this +assumption was not completely bullet-proof either. +There will be impacts on software checking the value of PROJ pipeline strings +resulting <code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">proj_create_crs_to_crs()</span></code>. The new grid names will now +be returned (the most impacted software will likely be PROJ’s own test suite)</p> +<p>Although discouraged, people not using the new proj-datumgrid-geotiff-XXX.zip +archives, should still be able to use the old archives made of NTv2/GTX files, +at least as long as the PROJ database does not only point to a GeoTIFF grid. +So this might be a short-term partly working solution, but at time goes, it +will become increasingly non-working. The nominal combination will be +PROJ 7.0 + proj-datumgrid-geotiff-1.0.zip</p> +</section> +<section id="testing"> +<h2>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2> +<p>PROJ test suite will have to be adapted for the new TIFF based filenames.</p> +<p>Mechanism to auto-promote existing NTv2/GTX names to TIFF ones will be exercised.</p> +</section> +<section id="proposed-implementation"> +<h2>Proposed implementation<a class="headerlink" href="#proposed-implementation" title="Permalink to this headline">¶</a></h2> +<p><a class="reference external" href="https://github.com/OSGeo/PROJ/pull/1891">https://github.com/OSGeo/PROJ/pull/1891</a> and <a class="reference external" href="https://github.com/OSGeo/PROJ-data/pull/5">https://github.com/OSGeo/PROJ-data/pull/5</a></p> +</section> +<section id="adoption-status"> +<h2>Adoption status<a class="headerlink" href="#adoption-status" title="Permalink to this headline">¶</a></h2> +<p>The RFC was adopted on 2020-01-28 with +1’s from the following PSC members</p> +<ul class="simple"> +<li><p>Kristian Evers</p></li> +<li><p>Even Rouault</p></li> +<li><p>Thomas Knudsen</p></li> +<li><p>Howard Butler</p></li> +<li><p>Kurt Schwehr</p></li> +</ul> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="rfc-4.html" class="btn btn-neutral float-left" title="PROJ RFC 4: Remote access to grids and GeoTIFF grids" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-6.html" class="btn btn-neutral float-right" title="PROJ RFC 6: Triangulation-based transformations" 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/community/rfc/rfc-6.html b/community/rfc/rfc-6.html new file mode 100644 index 00000000..ed464a2e --- /dev/null +++ b/community/rfc/rfc-6.html @@ -0,0 +1,474 @@ +<!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>PROJ RFC 6: Triangulation-based transformations — 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.orgcommunity/rfc/rfc-6.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="PROJ RFC 7: Drop Autotools, maintain CMake" href="rfc-7.html" /> + <link rel="prev" title="PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ" href="rfc-5.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"><a class="reference internal" href="../../usage/index.html">Using PROJ</a></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 current"><a class="reference internal" href="../index.html">Community</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="../channels.html">Communication channels</a></li> +<li class="toctree-l2"><a class="reference internal" href="../contributing.html">Contributing</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_contributions.html">Guidelines for PROJ code contributors</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_of_conduct.html">Code of Conduct</a></li> +<li class="toctree-l2 current"><a class="reference internal" href="index.html">Request for Comments</a><ul class="current"> +<li class="toctree-l3"><a class="reference internal" href="rfc-1.html">PROJ RFC 1: Project Committee Guidelines</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-2.html">PROJ RFC 2: Initial integration of “GDAL SRS barn” work</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-3.html">PROJ RFC 3: Dependency management</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-4.html">PROJ RFC 4: Remote access to grids and GeoTIFF grids</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-5.html">PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</a></li> +<li class="toctree-l3 current"><a class="current reference internal" href="#">PROJ RFC 6: Triangulation-based transformations</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#summary">Summary</a></li> +<li class="toctree-l4"><a class="reference internal" href="#details">Details</a></li> +<li class="toctree-l4"><a class="reference internal" href="#backward-compatibility">Backward compatibility</a></li> +<li class="toctree-l4"><a class="reference internal" href="#testing">Testing</a></li> +<li class="toctree-l4"><a class="reference internal" href="#documentation">Documentation</a></li> +<li class="toctree-l4"><a class="reference internal" href="#proposed-implementation">Proposed implementation</a></li> +<li class="toctree-l4"><a class="reference internal" href="#references">References</a></li> +<li class="toctree-l4"><a class="reference internal" href="#adoption-status">Adoption status</a></li> +<li class="toctree-l4"><a class="reference internal" href="#funding">Funding</a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="rfc-7.html">PROJ RFC 7: Drop Autotools, maintain CMake</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="../index.html#conference">Conference</a></li> +</ul> +</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">Community</a> »</li> + <li><a href="index.html">Request for Comments</a> »</li> + <li>PROJ RFC 6: Triangulation-based transformations</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/community/rfc/rfc-6.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="rfc-5.html" class="btn btn-neutral float-left" title="PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-7.html" class="btn btn-neutral float-right" title="PROJ RFC 7: Drop Autotools, maintain CMake" 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="proj-rfc-6-triangulation-based-transformations"> +<span id="rfc6"></span><h1>PROJ RFC 6: Triangulation-based transformations<a class="headerlink" href="#proj-rfc-6-triangulation-based-transformations" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Author</dt> +<dd class="field-odd"><p>Even Rouault</p> +</dd> +<dt class="field-even">Contact</dt> +<dd class="field-even"><p><a class="reference external" href="mailto:even.rouault%40spatialys.com">even<span>.</span>rouault<span>@</span>spatialys<span>.</span>com</a></p> +</dd> +<dt class="field-odd">Status</dt> +<dd class="field-odd"><p>Adopted</p> +</dd> +<dt class="field-even">Implementation target</dt> +<dd class="field-even"><p>PROJ 7.2</p> +</dd> +<dt class="field-odd">Last Updated</dt> +<dd class="field-odd"><p>2020-09-02</p> +</dd> +</dl> +<section id="summary"> +<h2>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2> +<p>This RFC adds a new transformation method, <code class="docutils literal notranslate"><span class="pre">tinshift</span></code> (TIN stands for +Triangulated Irregular Network)</p> +<p>The motivation for this work is to be able to handle the official transformations +created by National Land Survey of Finland, for:</p> +<ul class="simple"> +<li><p>horizontal transformation between the KKJ and ETRS89 horizontal datums</p></li> +<li><p>vertical transformations between N43 and N60 heights, and N60 and N2000 heights.</p></li> +</ul> +<p>Such transformations are somehow related to traditional grid-based transformations, +except that the correction values are hold by the vertices of the triangulation, +instead of being at nodes of a grid.</p> +<p>Triangulation are in a number of cases the initial product of a geodesic adjustment, +with grids being a derived product. The Swiss grids have for example +derived products of an original triangulation.</p> +<p>Grid-based transformations remain very convenient to use because accessing +correction values is really easy and efficient, so triangulation-based transformations +are not meant as replacing them, but more about it being a complement, that is +sometimes necessary to be able to replicate the results of a officially vetted +transformation to a millimetric or better precision (speaking here about reproducibility +of numeric results, rather than the physical accuracy of the transformation that +might rather be centimetric). It is always possible to approach the result of +the triangulation with a grid, but that may require to adopt a small grid step, +and thus generate a grid that can be much larger than the original triangulation.</p> +</section> +<section id="details"> +<h2>Details<a class="headerlink" href="#details" title="Permalink to this headline">¶</a></h2> +<section id="transformation"> +<h3>Transformation<a class="headerlink" href="#transformation" title="Permalink to this headline">¶</a></h3> +<p>A new transformation method, <code class="docutils literal notranslate"><span class="pre">tinshift</span></code>, is added. It takes one mandatory +argument, <code class="docutils literal notranslate"><span class="pre">file</span></code>, that points to a JSON file, which contains the triangulation +and associated metadata. Input and output coordinates must be geographic or projected. +Depending on the content +of the JSON file, horizontal, vertical or both components of the coordinates may +be transformed.</p> +<p>The transformation is used like:</p> +<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 3210000.0000 6700000.0000 0 2020 | cct +proj=tinshift +file=./triangulation_kkj.json + +209948.3217 6697187.0009 0.0000 2020 +</pre></div> +</div> +<p>The transformation is invertible, with the same computational complexity than +the forward transformation.</p> +</section> +<section id="algorithm"> +<h3>Algorithm<a class="headerlink" href="#algorithm" title="Permalink to this headline">¶</a></h3> +<p>Internally, <code class="docutils literal notranslate"><span class="pre">tinshift</span></code> ingest the whole file into memory. It is considered that +triangulation should be small enough for that. The above mentioned KKJ to ETRS89 +triangulation fits into 65 KB of JSON, for 1449 triangles and 767 vertices.</p> +<p>When a point is transformed, one must find the triangle into which it falls into. +Instead of iterating over all triangles, we build a in-memory quadtree to speed-up +the identification of candidates triangles. On the above mentioned KKJ -> ETRS89 +triangulation, this speeds up the whole transformation by a factor of 10. The +quadtree structure is a very good compromise between the performance gain it brings +and the simplicity of its implementation (we have ported the implementation coming +from GDAL, inherit from the one used for shapefile .spx spatial indices).</p> +<p>To determine if a point falls into a triangle, one computes its 3 +<a class="reference external" href="https://en.wikipedia.org/wiki/Barycentric_coordinate_system#Conversion_between_barycentric_and_Cartesian_coordinates">barycentric coordinates</a> +from its projected coordinates, <span class="math notranslate nohighlight">\(\lambda_i\)</span> for <span class="math notranslate nohighlight">\(i=1,2,3\)</span>. +They are real values (in the [0,1] range for a point inside the triangle), +giving the weight of each of the 3 vertices of the triangles.</p> +<p>Once those weights are known, interpolating the target horizontal +coordinate is a matter of doing the linear combination of those weights with +the target horizontal coordinates at the 3 vertices of the triangle (<span class="math notranslate nohighlight">\(Xt_i\)</span> and <span class="math notranslate nohighlight">\(Yt_i\)</span>):</p> +<div class="math notranslate nohighlight"> +\[ \begin{align}\begin{aligned}X_{target} = Xt_1 * \lambda_1 + Xt_2 * \lambda_2 + Xt_3 * \lambda_3\\Y_{target} = Yt_1 * \lambda_1 + Yt_2 * \lambda_2 + Yt_3 * \lambda_3\end{aligned}\end{align} \]</div> +<p>This interpolation is exact at the vertices of the triangulation, and has linear properties +inside each triangle. It is completely equivalent to other formulations of +triangular interpolation, such as</p> +<div class="math notranslate nohighlight"> +\[ \begin{align}\begin{aligned}X_{target} = A + X_{source} * B + Y_{source} * C\\Y_{target} = D + X_{source} * E + Y_{source} * F\end{aligned}\end{align} \]</div> +<p>where the A, B, C, D, E, F constants (for a given triangle) are found by solving +the 2 systems of 3 linear equations, constraint by the source and target coordinate pairs +of the 3 vertices of the triangle:</p> +<div class="math notranslate nohighlight"> +\[ \begin{align}\begin{aligned}Xt_i = A + Xs_i * B + Ys_i * C\\Yt_i = D + Xs_i * E + Ys_i * F\end{aligned}\end{align} \]</div> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>From experiments, the interpolation using barycentric coordinates is slightly +more numerically robust when interpolating projected coordinates of amplitude of the +order of 1e5 / 1e6, due to computations involving differences of coordinates. +Whereas the formulation with the A, B, C, D, E, F tends to have big values for +the A and D constants, and values clause to 0 for C and E, and close to 1 for +B and F. However, the difference between the two approaches is negligible for +practical purposes (below micrometre precision)</p> +</div> +<p>Similarly for a vertical coordinate transformation, where <span class="math notranslate nohighlight">\(Zoff_i\)</span> is the vertical +offset at each vertex of the triangle:</p> +<div class="math notranslate nohighlight"> +\[Z_{target} = Z_{source} + Zoff_1 * \lambda_1 + Zoff_2 * \lambda_2 + Zoff_3 * \lambda_3\]</div> +</section> +<section id="constraints-on-the-triangulation"> +<h3>Constraints on the triangulation<a class="headerlink" href="#constraints-on-the-triangulation" title="Permalink to this headline">¶</a></h3> +<p>No check is done on the consistence of the triangulation. It is highly +recommended that triangles do not overlap each other (when considering the +source coordinates or the forward transformation, or the target coordinates for +the inverse transformation), otherwise which triangle will be selected is +unspecified. Besides that, the triangulation does not need to have particular +properties (like being a Delaunay triangulation)</p> +</section> +<section id="file-format"> +<h3>File format<a class="headerlink" href="#file-format" title="Permalink to this headline">¶</a></h3> +<p>To the best of our knowledge, there are no established file formats to convey +geodetic transformations as triangulations. Potential similar formats to store TINs +are <a class="reference external" href="http://vterrain.org/Implementation/Formats/ITF.html">ITF</a> or +<a class="reference external" href="https://www.xmswiki.com/wiki/TIN_Files">XMS</a>. +Both of them would need to be extended in order to handle datum shift information, +since they are both intended for mostly DEM use.</p> +<p>We thus propose a text-based format, using JSON as a serialization. Using a text-based +format could potentially be thought as a limitation performance-wise compared to +binary formats, but for the size of triangulations considered (a few thousands triangles / vertices), +there is no issue. Loading such file is a matter of 20 milliseconds or so. For reference, +loading a triangulation of about 115 000 triangles and 71 000 vertices takes 450 ms.</p> +<p>Using JSON provides generic formatting and parsing rules, and convenience to +create it from Python script for examples. This could also be easily generated “at hand” +by non-JSON aware writers.</p> +<p>For generic metadata, we reuse closely what has been used for the +<a class="reference external" href="https://github.com/linz/deformation-model-format">Deformation model master file</a></p> +<p>Below a minimal example, from the KKJ to ETRS89 transformation, with just a +single triangle:</p> +<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="w"></span> +<span class="w"> </span><span class="nt">"file_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"triangulation_file"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"format_version"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.0"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Name"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"version"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Version"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"publication_date"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2018-07-01T00:00:00Z"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"license"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Creative Commons Attribution 4.0 International"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Test triangulation"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"authority"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"></span> +<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Authority name"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"http://example.com"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Address"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"test@example.com"</span><span class="w"></span> +<span class="w"> </span><span class="p">},</span><span class="w"></span> +<span class="w"> </span><span class="nt">"links"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"></span> +<span class="w"> </span><span class="p">{</span><span class="w"></span> +<span class="w"> </span><span class="nt">"href"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://example.com/about.html"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"rel"</span><span class="p">:</span><span class="w"> </span><span class="s2">"about"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"text/html"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"About"</span><span class="w"></span> +<span class="w"> </span><span class="p">},</span><span class="w"></span> +<span class="w"> </span><span class="p">{</span><span class="w"></span> +<span class="w"> </span><span class="nt">"href"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://example.com/download"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"rel"</span><span class="p">:</span><span class="w"> </span><span class="s2">"source"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"application/zip"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Authoritative source"</span><span class="w"></span> +<span class="w"> </span><span class="p">},</span><span class="w"></span> +<span class="w"> </span><span class="p">{</span><span class="w"></span> +<span class="w"> </span><span class="nt">"href"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://creativecommons.org/licenses/by/4.0/"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"rel"</span><span class="p">:</span><span class="w"> </span><span class="s2">"license"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"text/html"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Creative Commons Attribution 4.0 International license"</span><span class="w"></span> +<span class="w"> </span><span class="p">},</span><span class="w"></span> +<span class="w"> </span><span class="p">{</span><span class="w"></span> +<span class="w"> </span><span class="nt">"href"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://example.com/metadata.xml"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"rel"</span><span class="p">:</span><span class="w"> </span><span class="s2">"metadata"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"application/xml"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">" ISO 19115 XML encoded metadata regarding the triangulation"</span><span class="w"></span> +<span class="w"> </span><span class="p">}</span><span class="w"></span> +<span class="w"> </span><span class="p">],</span><span class="w"></span> +<span class="w"> </span><span class="nt">"input_crs"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EPSG:2393"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"target_crs"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EPSG:3067"</span><span class="p">,</span><span class="w"></span> +<span class="w"> </span><span class="nt">"transformed_components"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"horizontal"</span><span class="w"> </span><span class="p">],</span><span class="w"></span> +<span class="w"> </span><span class="nt">"vertices_columns"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"source_x"</span><span class="p">,</span><span class="w"> </span><span class="s2">"source_y"</span><span class="p">,</span><span class="w"> </span><span class="s2">"target_x"</span><span class="p">,</span><span class="w"> </span><span class="s2">"target_y"</span><span class="w"> </span><span class="p">],</span><span class="w"></span> +<span class="w"> </span><span class="nt">"triangles_columns"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"idx_vertex1"</span><span class="p">,</span><span class="w"> </span><span class="s2">"idx_vertex2"</span><span class="p">,</span><span class="w"> </span><span class="s2">"idx_vertex3"</span><span class="w"> </span><span class="p">],</span><span class="w"></span> +<span class="w"> </span><span class="nt">"vertices"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="p">[</span><span class="mf">3244102.707</span><span class="p">,</span><span class="w"> </span><span class="mf">6693710.937</span><span class="p">,</span><span class="w"> </span><span class="mf">244037.137</span><span class="p">,</span><span class="w"> </span><span class="mf">6690900.686</span><span class="p">],</span><span class="w"></span> +<span class="w"> </span><span class="p">[</span><span class="mf">3205290.722</span><span class="p">,</span><span class="w"> </span><span class="mf">6715311.822</span><span class="p">,</span><span class="w"> </span><span class="mf">205240.895</span><span class="p">,</span><span class="w"> </span><span class="mf">6712492.577</span><span class="p">],</span><span class="w"></span> +<span class="w"> </span><span class="p">[</span><span class="mf">3218328.492</span><span class="p">,</span><span class="w"> </span><span class="mf">6649538.429</span><span class="p">,</span><span class="w"> </span><span class="mf">218273.648</span><span class="p">,</span><span class="w"> </span><span class="mf">6646745.973</span><span class="p">]</span><span class="w"> </span><span class="p">],</span><span class="w"></span> +<span class="w"> </span><span class="nt">"triangles"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="p">]</span><span class="w"></span> +<span class="p">}</span><span class="w"></span> +</pre></div> +</div> +<p>So after the generic metadata, we define the input and output CRS (informative +only), and that the transformation affects horizontal components of +coordinates. We name the columns of the <code class="docutils literal notranslate"><span class="pre">vertices</span></code> and <code class="docutils literal notranslate"><span class="pre">triangles</span></code> arrays. +We defined the source and target coordinates of each vertex, and define a +triangle by referring to the index of its vertices in the <code class="docutils literal notranslate"><span class="pre">vertices</span></code> array.</p> +<p>More formally, the specific items for the triangulation file are:</p> +<dl class="simple"> +<dt>input_crs</dt><dd><p>String identifying the CRS of source coordinates +in the vertices. Typically <code class="docutils literal notranslate"><span class="pre">EPSG:XXXX</span></code>. If the transformation is for vertical +component, this should be the code for a compound CRS (can be EPSG:XXXX+YYYY +where XXXX is the code of the horizontal CRS and YYYY the code of the vertical CRS). +For example, for the KKJ->ETRS89 transformation, this is EPSG:2393 +(<code class="docutils literal notranslate"><span class="pre">KKJ</span> <span class="pre">/</span> <span class="pre">Finland</span> <span class="pre">Uniform</span> <span class="pre">Coordinate</span> <span class="pre">System</span></code>). The input coordinates are assumed +to be passed in the “normalized for visualisation” / “GIS friendly” order, +that is longitude, latitude for geographic coordinates and +easting, northing for projected coordinates.</p> +</dd> +<dt>output_crs</dt><dd><p>String identifying the CRS of target coordinates in the vertices. +Typically <code class="docutils literal notranslate"><span class="pre">EPSG:XXXX</span></code>. If the transformation is for vertical component, +this should be the code for a compound CRS (can be EPSG:XXXX+YYYY where +XXXX is the code of the horizontal CRS and YYYY the code of the vertical CRS). +For example, for the KKJ->ETRS89 transformation, this is EPSG:3067 +("ETRS89 / TM35FIN(E,N)"). The output coordinates will be returned in +the “normalized for visualisation” / “GIS friendly” order, +that is longitude, latitude for geographic coordinates and +easting, northing for projected coordinates.</p> +</dd> +<dt>transformed_components</dt><dd><p>Array which may contain one or two strings: “horizontal” when horizontal +components of the coordinates are transformed and/or “vertical” when the +vertical component is transformed.</p> +</dd> +<dt>vertices_columns</dt><dd><p>Specify the name of the columns of the rows in the <code class="docutils literal notranslate"><span class="pre">vertices</span></code> +array. There must be exactly as many elements in <code class="docutils literal notranslate"><span class="pre">vertices_columns</span></code> as in a +row of <code class="docutils literal notranslate"><span class="pre">vertices</span></code>. The following names have a special meaning: <code class="docutils literal notranslate"><span class="pre">source_x</span></code>, +<code class="docutils literal notranslate"><span class="pre">source_y</span></code>, <code class="docutils literal notranslate"><span class="pre">target_x</span></code>, <code class="docutils literal notranslate"><span class="pre">target_y</span></code>, <code class="docutils literal notranslate"><span class="pre">source_z</span></code>, <code class="docutils literal notranslate"><span class="pre">target_z</span></code> and +<code class="docutils literal notranslate"><span class="pre">offset_z</span></code>. <code class="docutils literal notranslate"><span class="pre">source_x</span></code> and <code class="docutils literal notranslate"><span class="pre">source_y</span></code> are compulsory. +<code class="docutils literal notranslate"><span class="pre">source_x</span></code> is for the source longitude (in degree) or easting. +<code class="docutils literal notranslate"><span class="pre">source_y</span></code> is for the source latitude (in degree) or northing. +<code class="docutils literal notranslate"><span class="pre">target_x</span></code> and <code class="docutils literal notranslate"><span class="pre">target_y</span></code> are compulsory when <code class="docutils literal notranslate"><span class="pre">horizontal</span></code> is specified +in <code class="docutils literal notranslate"><span class="pre">transformed_components</span></code>. (<code class="docutils literal notranslate"><span class="pre">source_z</span></code> and <code class="docutils literal notranslate"><span class="pre">target_z</span></code>) or +<code class="docutils literal notranslate"><span class="pre">offset_z</span></code> are compulsory when <code class="docutils literal notranslate"><span class="pre">vertical</span></code> is specified in <code class="docutils literal notranslate"><span class="pre">transformed_components</span></code></p> +</dd> +<dt>triangles_columns</dt><dd><p>Specify the name of the columns of the rows in the +<code class="docutils literal notranslate"><span class="pre">triangles</span></code> array. There must be exactly as many elements in <code class="docutils literal notranslate"><span class="pre">triangles_columns</span></code> +as in a row of <code class="docutils literal notranslate"><span class="pre">triangles</span></code>. The following names have a special meaning: +<code class="docutils literal notranslate"><span class="pre">idx_vertex1</span></code>, <code class="docutils literal notranslate"><span class="pre">idx_vertex2</span></code>, <code class="docutils literal notranslate"><span class="pre">idx_vertex3</span></code>. They are compulsory.</p> +</dd> +<dt>vertices</dt><dd><p>An array whose items are themselves arrays with as many columns as +described in <code class="docutils literal notranslate"><span class="pre">vertices_columns</span></code>.</p> +</dd> +<dt>triangles</dt><dd><p>An array whose items are themselves arrays with as many columns as +described in <code class="docutils literal notranslate"><span class="pre">triangles_columns</span></code>. +The value of the <code class="docutils literal notranslate"><span class="pre">idx_vertexN</span></code> columns must be indices +(between 0 and len(<code class="docutils literal notranslate"><span class="pre">vertices</span></code>-1) of items of the <code class="docutils literal notranslate"><span class="pre">vertices</span></code> array.</p> +</dd> +</dl> +</section> +<section id="code-impacts"> +<h3>Code impacts<a class="headerlink" href="#code-impacts" title="Permalink to this headline">¶</a></h3> +<p>The following new files are added in src/transformations:</p> +<ul class="simple"> +<li><p>tinshift.cpp: PROJ specific code for defining the new operation. Takes care +of the input and output coordinate conversions (between input_crs and triangulation_source_crs, +and triangulation_target_crs and output_crs), when needed.</p></li> +<li><p>tinshift.hpp: Header-based implementation. This file contains the API.</p></li> +<li><p>tinshift_exceptions.hpp: Exceptions that can be raised during file parsing</p></li> +<li><p>tinshift_impl.hpp: Implementation of file loading, triangle search and interpolation.</p></li> +</ul> +<p>This is the approach that has been followed for the deformation model implementation, +and which makes it easier to do unit test.</p> +<p>src/quadtree.hpp contains a quadtree implementation.</p> +</section> +<section id="performance-indications"> +<h3>Performance indications<a class="headerlink" href="#performance-indications" title="Permalink to this headline">¶</a></h3> +<p>Tested on Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz, transforming 4 million points</p> +<p>For the KKJ to ETRS89 transformation (1449 triangles and 767 vertices), +4.4 million points / sec can be transformed.</p> +<p>For comparison, the Helmert-based KKJ to ETRS89 transformation operates at +1.6 million points / sec.</p> +<p>A triangulation with about 115 000 triangles and 71 000 vertices +operates at 2.2 million points / sec +(throughput on more points would be better since the initial loading of the +triangulation is non-negligible here)</p> +</section> +</section> +<section id="backward-compatibility"> +<h2>Backward compatibility<a class="headerlink" href="#backward-compatibility" title="Permalink to this headline">¶</a></h2> +<p>New functionality fully backward compatible.</p> +</section> +<section id="testing"> +<h2>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2> +<p>The PROJ test suite will be enhanced to test the new transformation, with a +new .gie file, and a C++ unit test to test at a lower level.</p> +</section> +<section id="documentation"> +<h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>The tinshift method will be documented.</p></li> +<li><p>The JSON format will be documented under <a class="reference external" href="https://proj.org/specifications/">https://proj.org/specifications/</a></p></li> +<li><p>A JSON schema will also be provided.</p></li> +</ul> +</section> +<section id="proposed-implementation"> +<h2>Proposed implementation<a class="headerlink" href="#proposed-implementation" title="Permalink to this headline">¶</a></h2> +<p>An initial implementation is available at <a class="reference external" href="https://github.com/rouault/PROJ/tree/tinshift">https://github.com/rouault/PROJ/tree/tinshift</a></p> +</section> +<section id="references"> +<h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2> +<p><a class="reference external" href="https://translate.google.fr/translate?sl=auto&tl=en&u=https%3A%2F%2Fwww.maanmittauslaitos.fi%2Fkartat-ja-paikkatieto%2Fasiantuntevalle-kayttajalle%2Fkoordinaattimuunnokset">Finnish coordinate transformation (automated translation to English)</a></p> +</section> +<section id="adoption-status"> +<h2>Adoption status<a class="headerlink" href="#adoption-status" title="Permalink to this headline">¶</a></h2> +<p>The RFC was adopted on 2020-09-02 with +1’s from the following PSC members</p> +<ul class="simple"> +<li><p>Kristian Evers</p></li> +<li><p>Charles Karney</p></li> +<li><p>Thomas Knudsen</p></li> +<li><p>Even Rouault</p></li> +</ul> +</section> +<section id="funding"> +<h2>Funding<a class="headerlink" href="#funding" title="Permalink to this headline">¶</a></h2> +<p>This work is funded by <a class="reference external" href="https://www.maanmittauslaitos.fi/en">National Land Survey of Finland</a></p> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="rfc-5.html" class="btn btn-neutral float-left" title="PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="rfc-7.html" class="btn btn-neutral float-right" title="PROJ RFC 7: Drop Autotools, maintain CMake" 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/community/rfc/rfc-7.html b/community/rfc/rfc-7.html new file mode 100644 index 00000000..b3dab5f5 --- /dev/null +++ b/community/rfc/rfc-7.html @@ -0,0 +1,294 @@ +<!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>PROJ RFC 7: Drop Autotools, maintain CMake — 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.orgcommunity/rfc/rfc-7.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="FAQ" href="../../faq.html" /> + <link rel="prev" title="PROJ RFC 6: Triangulation-based transformations" href="rfc-6.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"><a class="reference internal" href="../../usage/index.html">Using PROJ</a></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 current"><a class="reference internal" href="../index.html">Community</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="../channels.html">Communication channels</a></li> +<li class="toctree-l2"><a class="reference internal" href="../contributing.html">Contributing</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_contributions.html">Guidelines for PROJ code contributors</a></li> +<li class="toctree-l2"><a class="reference internal" href="../code_of_conduct.html">Code of Conduct</a></li> +<li class="toctree-l2 current"><a class="reference internal" href="index.html">Request for Comments</a><ul class="current"> +<li class="toctree-l3"><a class="reference internal" href="rfc-1.html">PROJ RFC 1: Project Committee Guidelines</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-2.html">PROJ RFC 2: Initial integration of “GDAL SRS barn” work</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-3.html">PROJ RFC 3: Dependency management</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-4.html">PROJ RFC 4: Remote access to grids and GeoTIFF grids</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-5.html">PROJ RFC 5: Adopt GeoTIFF-based grids for grids delivered with PROJ</a></li> +<li class="toctree-l3"><a class="reference internal" href="rfc-6.html">PROJ RFC 6: Triangulation-based transformations</a></li> +<li class="toctree-l3 current"><a class="current reference internal" href="#">PROJ RFC 7: Drop Autotools, maintain CMake</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#summary">Summary</a></li> +<li class="toctree-l4"><a class="reference internal" href="#background">Background</a></li> +<li class="toctree-l4"><a class="reference internal" href="#motivation">Motivation</a></li> +<li class="toctree-l4"><a class="reference internal" href="#why-drop-autotools">Why drop Autotools?</a></li> +<li class="toctree-l4"><a class="reference internal" href="#why-use-cmake">Why use CMake?</a></li> +<li class="toctree-l4"><a class="reference internal" href="#why-not-cmake">Why not CMake?</a></li> +<li class="toctree-l4"><a class="reference internal" href="#potential-impacts">Potential impacts</a></li> +<li class="toctree-l4"><a class="reference internal" href="#transition-plan">Transition plan</a></li> +<li class="toctree-l4"><a class="reference internal" href="#adoption-status">Adoption status</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="../index.html#conference">Conference</a></li> +</ul> +</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">Community</a> »</li> + <li><a href="index.html">Request for Comments</a> »</li> + <li>PROJ RFC 7: Drop Autotools, maintain CMake</li> + <li class="wy-breadcrumbs-aside"> + <a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/community/rfc/rfc-7.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="rfc-6.html" class="btn btn-neutral float-left" title="PROJ RFC 6: Triangulation-based transformations" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="../../faq.html" class="btn btn-neutral float-right" title="FAQ" 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="proj-rfc-7-drop-autotools-maintain-cmake"> +<span id="rfc7"></span><h1>PROJ RFC 7: Drop Autotools, maintain CMake<a class="headerlink" href="#proj-rfc-7-drop-autotools-maintain-cmake" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Author</dt> +<dd class="field-odd"><p>Mike Taves</p> +</dd> +<dt class="field-even">Contact</dt> +<dd class="field-even"><p><a class="reference external" href="mailto:mwtoews%40gmail.com">mwtoews<span>@</span>gmail<span>.</span>com</a></p> +</dd> +<dt class="field-odd">Status</dt> +<dd class="field-odd"><p>Adopted</p> +</dd> +<dt class="field-even">Implementation target</dt> +<dd class="field-even"><p>PROJ 9.0</p> +</dd> +<dt class="field-odd">Last Updated</dt> +<dd class="field-odd"><p>2021-10-27</p> +</dd> +</dl> +<section id="summary"> +<h2>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2> +<p>This RFC proposes to drop Autotools for PROJ 9.0, and to maintain CMake +for build automation, testing and packaging. This will reduce the overall +maintenance for PROJ and will enable the library to be integrated into other +projects that use CMake.</p> +</section> +<section id="background"> +<h2>Background<a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h2> +<p>Here is a short timeline of the build tools used for PROJ:</p> +<ul class="simple"> +<li><p>Throughout the mid-1990s, Gerald Evenden maintained a Unix build system with +a few scripts (some derived from Autoconf), and Makefile templates.</p></li> +<li><p>In 2000, Frank Warmerdam wrote Autoconf and Automake configurations for +PROJ 4.4.0.</p></li> +<li><p>This was followed by a NMake configuration to build PROJ 4.4.2 for Windows.</p></li> +<li><p>In 2014, a CMake build setup was introduced by Howard Butler for +PROJ 4.9.0RC1. The CMake configuration was improved for the 4.9.1 release, +but not considered at feature parity with the Autotools builds at the time.</p></li> +<li><p>The NMake build setup was removed for PROJ 6.0.0, as its functionality had +been replaced by CMake.</p></li> +</ul> +</section> +<section id="motivation"> +<h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2> +<p>The primary motivation in removing Autotools is to reduce the burden of +maintaining multiple build configurations, which requires developers to be +familiar with different tools and configuration files. There are several other +benefits in maintaining a single build system:</p> +<ul class="simple"> +<li><p>Remove extra configuration and m4 macro files from source repository,</p></li> +<li><p>Simplify scripts used for running tests for CI services (GitHub Actions, +TravisCI),</p></li> +<li><p>Reduce compilation time (and carbon footprint) used for testing on CI +services,</p></li> +<li><p>Ease development effort, particularly with new contributors.</p></li> +</ul> +</section> +<section id="why-drop-autotools"> +<h2>Why drop Autotools?<a class="headerlink" href="#why-drop-autotools" title="Permalink to this headline">¶</a></h2> +<p>The GNU Build System or Autotools consist of a suite of tools including +Autoconf and Automake, which can be used to build software on Unix-like +systems. These tools are not cross-platform, and do not naively integrate +with development environments on Microsoft Windows. Furthermore, the existing +PROJ Autotools builds do not install the CMake configuration files required to +find PROJ from other projects that use CMake +(<a class="reference external" href="https://github.com/OSGeo/PROJ/issues/2546">#2546</a>).</p> +</section> +<section id="why-use-cmake"> +<h2>Why use CMake?<a class="headerlink" href="#why-use-cmake" title="Permalink to this headline">¶</a></h2> +<p>CMake is an open source cross-platform tool for build automation, testing and +packaging of software. It does not directly compile the software, but manages +the build process using generators, including Unix Makefiles and Ninja among +other command-based and IDE tools. The CMake software has been under active +development since its origins in 2000. The CMake language is carefully +developed with backwards-compatible policies that aim to provide consistent +behaviour across different versions. CMake is currently the preferred build +tool for PROJ for the following reasons:</p> +<ul class="simple"> +<li><p>It has existed in the PROJ code base since 2014, and is familiar to active +PROJ contributors,</p></li> +<li><p>It can install configuration files that can be used by other software that +use CMake to find PROJ for linking via <code class="docutils literal notranslate"><span class="pre">find_package()</span></code>,</p></li> +<li><p>CMake configurations are used in 3rd-party binary packages of PROJ, +including conda-forge and vcpkg,</p></li> +<li><p>It can be used to build PROJ on all major operating systems and compiler +combinations (where compatible),</p></li> +<li><p>It has integration with modern IDEs and tools, including +Microsoft Visual Studio and Qt Creator.</p></li> +</ul> +</section> +<section id="why-not-cmake"> +<h2>Why not CMake?<a class="headerlink" href="#why-not-cmake" title="Permalink to this headline">¶</a></h2> +<p>Other modern cross-platform build systems exist, including Meson and Bazel, +which have many advantages over CMake. However, they are currently not widely +used by active PROJ contributors. This RFC should not restrict future build +system configurations being introduced to PROJ, if they are proven to have +advantages to CMake over time.</p> +</section> +<section id="potential-impacts"> +<h2>Potential impacts<a class="headerlink" href="#potential-impacts" title="Permalink to this headline">¶</a></h2> +<p>Binary packagers that currently rely on Autotools would obviously need to +transition building and testing PROJ with CMake. Issues related to +multiarch builds of PROJ may become apparent, which can be patched and/or +reported to PROJ developers. One feature of Autotools is that both static and +dynamic (shared) libraries are built, which packagers may distribute. This +feature is currently not set-up for PROJ, as it would need to be configured +and built twice.</p> +<p>End-users that use binary packages of PROJ should not be impacted. PROJ should +be discoverable via both pkg-config and CMake’s <code class="docutils literal notranslate"><span class="pre">find_package()</span></code>. +Other projects that use Autotools will continue to work as expected, +linking statically or dynamically to PROJ built by CMake.</p> +</section> +<section id="transition-plan"> +<h2>Transition plan<a class="headerlink" href="#transition-plan" title="Permalink to this headline">¶</a></h2> +<p>If this proposal is approved, the following tasks should be completed:</p> +<ul class="simple"> +<li><p>Rewrite CI tests to only use CMake for packaging, building, testing, +installation and post-install tests,</p></li> +<li><p>Remove files only used by Autotools, also update <code class="docutils literal notranslate"><span class="pre">.gitignore</span></code>,</p></li> +<li><p>Update documentation and <code class="docutils literal notranslate"><span class="pre">HOWTORELEASE</span></code> notes.</p></li> +</ul> +<p>Related issues will be tracked on GitHub with a tag +<a class="reference external" href="https://github.com/OSGeo/PROJ/labels/RFC7%3A%20Autotools%E2%86%92CMake">RFC7: Autotools→CMake</a>.</p> +</section> +<section id="adoption-status"> +<h2>Adoption status<a class="headerlink" href="#adoption-status" title="Permalink to this headline">¶</a></h2> +<p>The RFC was adopted on 2021-10-26 with +1’s from the following PSC members</p> +<ul class="simple"> +<li><p>Kristian Evers</p></li> +<li><p>Even Rouault</p></li> +<li><p>Howard Butler</p></li> +<li><p>Thomas Knudsen</p></li> +<li><p>Kurt Schwehr</p></li> +<li><p>Charles Karney</p></li> +<li><p>Thomas Knudsen</p></li> +</ul> +</section> +</section> + + + </div> + </div> + <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> + <a href="rfc-6.html" class="btn btn-neutral float-left" title="PROJ RFC 6: Triangulation-based transformations" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> + <a href="../../faq.html" class="btn btn-neutral float-right" title="FAQ" 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 |