sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r993297 - in /websites/staging/sis/trunk/content: ./ faq.html
Date Thu, 21 Jul 2016 16:24:47 GMT
Author: buildbot
Date: Thu Jul 21 16:24:47 2016
New Revision: 993297

Log:
Staging update by buildbot for sis

Modified:
    websites/staging/sis/trunk/content/   (props changed)
    websites/staging/sis/trunk/content/faq.html

Propchange: websites/staging/sis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Jul 21 16:24:47 2016
@@ -1 +1 @@
-1753698
+1753710

Modified: websites/staging/sis/trunk/content/faq.html
==============================================================================
--- websites/staging/sis/trunk/content/faq.html (original)
+++ websites/staging/sis/trunk/content/faq.html Thu Jul 21 16:24:47 2016
@@ -97,10 +97,32 @@ h2:hover > .headerlink, h3:hover > .head
 <div class="toc">
 <ul>
 <li><a href="#referencing">Referencing</a><ul>
+<li><a href="#referencing-intro">Getting started</a><ul>
 <li><a href="#transform-point">How do I transform a coordinate?</a></li>
 <li><a href="#operation-methods">Which map projections are supported?</a></li>
 <li><a href="#axisOrder">What is the axis order issue and how is it addressed?</a></li>
+</ul>
+</li>
+<li><a href="#crs">Coordinate Reference Systems</a><ul>
 <li><a href="#UTM">How do I instantiate a Universal Transverse Mercator (UTM)
projection?</a></li>
+<li><a href="#google">How do I instantiate a Google projection?</a></li>
+<li><a href="#projectionKind">How can I identify the projection kind of a CRS?</a></li>
+<li><a href="#lookupEPSG">How do I get the EPSG code of an existing CRS?</a></li>
+<li><a href="#lookupURN">How do I get the "urn:ogc:def:crs:…" URN of an
existing CRS?</a></li>
+<li><a href="#lookupReliability">Can I rely on IdentifiedObjects.lookupEPSG(…)
to work correctly as the inverse of CRS.forCode(…)?</a></li>
+<li><a href="#equalsIgnoreMetadata">How can I determine if two CRS are "functionally"
equal?</a></li>
+<li><a href="#crsHashCode">Are CRS objects safe for use as keys in HashMap?</a></li>
+</ul>
+</li>
+<li><a href="#transforms">Coordinate transformations</a><ul>
+<li><a href="#axisOrderInTransforms">My transformed coordinates are totally wrong!</a></li>
+<li><a href="#projectionName">I have correct axis order but my transformed coordinates
are still wrong.</a></li>
+<li><a href="#parameterUnits">I just used the WKT of a well-known authority and
my transformed coordinates are still wrong!</a></li>
+<li><a href="#BursaWolf">I verified all the above and still have an error of
about one kilometer.</a></li>
+<li><a href="#slightDifferences">I get slightly different results depending on
the environment I’m running in.</a></li>
+<li><a href="#toWGS84">Can I always expect a transform from an arbitrary CRS
to WGS84 to succeed?</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li><a href="#metadata">Metadata</a><ul>
@@ -114,6 +136,7 @@ h2:hover > .headerlink, h3:hover > .head
 </ul>
 </div>
 <h1 id="referencing">Referencing<a class="headerlink" href="#referencing" title="Permanent
link">&para;</a></h1>
+<h2 id="referencing-intro">Getting started<a class="headerlink" href="#referencing-intro"
title="Permanent link">&para;</a></h2>
 <h3 id="transform-point">How do I transform a coordinate?<a class="headerlink" href="#transform-point"
title="Permanent link">&para;</a></h3>
 <p>The following Java code projects a geographic coordinate from the <em>World
Geodetic System 1984</em> (WGS84) to <em>WGS 84 / UTM zone 33N</em>.
 In order to make the example a little bit simpler, this code uses predefined systems given
by the <code>CommonCRS</code> convenience class.
@@ -128,7 +151,7 @@ Note that all geographic coordinates bel
 <span class="kn">import</span> <span class="nn">org.apache.sis.referencing.CommonCRS</span><span
class="o">;</span>
 <span class="kn">import</span> <span class="nn">org.apache.sis.geometry.DirectPosition2D</span><span
class="o">;</span>
 
-<span class="kd">public</span> <span class="kd">final</span> <span
class="kd">class</span> <span class="nc">Test</span> <span class="o">{</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">MyApp</span> <span class="o">{</span>
     <span class="kd">public</span> <span class="kd">static</span>
<span class="kt">void</span> <span class="nf">main</span><span
class="o">(</span><span class="n">String</span><span class="o">[]</span>
<span class="n">args</span><span class="o">)</span> <span class="kd">throws</span>
<span class="n">FactoryException</span><span class="o">,</span> <span
class="n">TransformException</span> <span class="o">{</span>
         <span class="n">CoordinateReferenceSystem</span> <span class="n">sourceCRS</span>
<span class="o">=</span> <span class="n">CommonCRS</span><span
class="o">.</span><span class="na">WGS84</span><span class="o">.</span><span
class="na">geographic</span><span class="o">();</span>
         <span class="n">CoordinateReferenceSystem</span> <span class="n">targetCRS</span>
<span class="o">=</span> <span class="n">CommonCRS</span><span
class="o">.</span><span class="na">WGS84</span><span class="o">.</span><span
class="na">UTM</span><span class="o">(</span><span class="mi">40</span><span
class="o">,</span> <span class="mi">14</span><span class="o">);</span>
 <span class="c1">// Get whatever zone is valid for 14°E.</span>
@@ -162,7 +185,7 @@ The predefined <abbr title="Coordinate R
 <h3 id="axisOrder">What is the axis order issue and how is it addressed?<a class="headerlink"
href="#axisOrder" title="Permanent link">&para;</a></h3>
 <p>The axis order is specified by the authority (typically a national agency) defining
the <em>Coordinate Reference System</em> (<abbr title="Coordinate Reference
System">CRS</abbr>).
 The order depends on the <abbr title="Coordinate Reference System">CRS</abbr>
type and the country defining the <abbr title="Coordinate Reference System">CRS</abbr>.
-In the case of geographic <abbr title="Coordinate Reference System">CRS</abbr>,
the (<em>latitude</em>, <em>longitude</em>) axis order is widely used
by geographers and pilotes for centuries.
+In the case of geographic <abbr title="Coordinate Reference System">CRS</abbr>,
the (<em>latitude</em>, <em>longitude</em>) axis order is widely used
by geographers and pilots for centuries.
 However software developers tend to consistently use the (<em>x</em>,<em>y</em>)
order for every kind of <abbr title="Coordinate Reference System">CRS</abbr>.
 Those different practices resulted in contradictory definitions of axis order for almost
every <abbr title="Coordinate Reference System">CRS</abbr> of kind <code>GeographicCRS</code>,
 for some <code>ProjectedCRS</code> in the South hemisphere (South Africa, Australia,
<em>etc.</em>) and for some polar projections among others.</p>
@@ -176,9 +199,9 @@ In version 2 of WKT format, <code>AXIS[�
 and should contain an explicit <code>ORDER[…]</code> sub-element for making
the intended order yet more obvious.</p>
 <p>Many softwares still use the old (<em>x</em>,<em>y</em>)
axis order, because it is easier to implement.
 Apache SIS defaults to axis order <em>as defined by the authority</em> (except
when parsing a WKT 1 definition),
-but allows to change axis order to (<var>x</var>,<var>y</var>) order
after <abbr title="Coordinate Reference System">CRS</abbr> creation.
+but allows to change axis order to (<em>x</em>,<em>y</em>) order
after <abbr title="Coordinate Reference System">CRS</abbr> creation.
 This change can be done with the following code:</p>
-<div class="codehilite"><pre><span class="n">CoordinateReferenceSystem</span>
<span class="n">crs</span> <span class="o">=</span> <span class="err">…</span><span
class="o">;</span>   <span class="c1">// CRS obtained by any mean.</span>
+<div class="codehilite"><pre><span class="n">CoordinateReferenceSystem</span>
<span class="n">crs</span> <span class="o">=</span> <span class="err">…</span><span
class="o">;</span>             <span class="c1">// CRS obtained by any means.</span>
 <span class="n">crs</span> <span class="o">=</span> <span class="n">AbstractCRS</span><span
class="o">.</span><span class="na">castOrCopy</span><span class="o">(</span><span
class="n">crs</span><span class="o">).</span><span class="na">forConvention</span><span
class="o">(</span><span class="n">AxesConvention</span><span class="o">.</span><span
class="na">RIGHT_HANDED</span><span class="o">)</span>
 </pre></div>
 
@@ -187,24 +210,24 @@ This change can be done with the followi
 official EPSG registry at <a href="http://www.epsg-registry.org">http://www.epsg-registry.org</a>
 (not to be confused with other sites having "epsg" in their name,
 but actually unrelated to the organization in charge of EPSG definition and maintenance):
-Click on the <em>"Retrieve by code"</em> link and enter the numerical code.
+click on the <em>"Retrieve by code"</em> link and enter the numerical code.
 Then click on the <em>"View"</em> link on the right side,
 and click on the <em>"+"</em> symbol of the left side of <em>"Axes"</em>.</p>
+<h2 id="crs">Coordinate Reference Systems<a class="headerlink" href="#crs" title="Permanent
link">&para;</a></h2>
 <h3 id="UTM">How do I instantiate a Universal Transverse Mercator (UTM) projection?<a
class="headerlink" href="#UTM" title="Permanent link">&para;</a></h3>
 <p>If the UTM zone is unknown, an easy way is to use the <code>UTM</code>
method in one of the <code>CommonCRS</code> pre-defined constants.
 That method receives in argument a geographic coordinate in (<em>latitude</em>,
<em>longitude</em>) order and computes the UTM zone from it.
 See the <a href="#transform-point">above Java code example</a>.</p>
 <p>If the UTM zone is know, one way is to use the "EPSG" or "AUTO" authority factory.
 The EPSG code of some UTM projections can be determined as below, where <em>zone</em>
is a number from 1 to 60 inclusive (unless otherwise specified):</p>
-<div class="codehilite"><pre><span class="o">*</span> <span class="n">WGS</span>
84 <span class="p">(</span><span class="n">northern</span> <span
class="n">hemisphere</span><span class="p">):</span> 32600 <span class="o">+</span>
<span class="n">_zone_</span>
-<span class="o">*</span> <span class="n">WGS</span> 84 <span class="p">(</span><span
class="n">southern</span> <span class="n">hemisphere</span><span class="p">):</span>
32700 <span class="o">+</span> <span class="n">_zone_</span>
-<span class="o">*</span> <span class="n">WGS</span> 72 <span class="p">(</span><span
class="n">northern</span> <span class="n">hemisphere</span><span class="p">):</span>
32200 <span class="o">+</span> <span class="n">_zone_</span>
-<span class="o">*</span> <span class="n">WGS</span> 72 <span class="p">(</span><span
class="n">southern</span> <span class="n">hemisphere</span><span class="p">):</span>
32300 <span class="o">+</span> <span class="n">_zone_</span>
-<span class="o">*</span> <span class="n">NAD</span> 83 <span class="p">(</span><span
class="n">northern</span> <span class="n">hemisphere</span><span class="p">):</span>
26900 <span class="o">+</span> <span class="n">_zone_</span> <span
class="p">(</span><span class="n">zone</span> 1 <span class="n">to</span>
23 <span class="n">only</span><span class="p">)</span>
-<span class="o">*</span> <span class="n">NAD</span> 27 <span class="p">(</span><span
class="n">northern</span> <span class="n">hemisphere</span><span class="p">):</span>
26700 <span class="o">+</span> <span class="n">_zone_</span> <span
class="p">(</span><span class="n">zone</span> 1 <span class="n">to</span>
22 <span class="n">only</span><span class="p">)</span>
-</pre></div>
-
-
+<ul>
+<li>WGS 84 (northern hemisphere): 32600 + <em>zone</em></li>
+<li>WGS 84 (southern hemisphere): 32700 + <em>zone</em></li>
+<li>WGS 72 (northern hemisphere): 32200 + <em>zone</em></li>
+<li>WGS 72 (southern hemisphere): 32300 + <em>zone</em></li>
+<li>NAD 83 (northern hemisphere): 26900 + <em>zone</em> (zone 1 to 23 only)</li>
+<li>NAD 27 (northern hemisphere): 26700 + <em>zone</em> (zone 1 to 22 only)</li>
+</ul>
 <p>Note that the above list is incomplete. See the EPSG database for additional UTM
definitions
 (WGS 72BE, SIRGAS 2000, SIRGAS 1995, SAD 69, ETRS 89, <em>etc.</em>, most of
them defined only for a few zones).
 Once the EPSG code of the UTM projection has been determined, the <abbr title="Coordinate
Reference System">CRS</abbr> can be obtained as in the example below:</p>
@@ -217,6 +240,174 @@ Once the EPSG code of the UTM projection
 way is to instantiate directly a <code>MathTransform</code> using the parameters
documented in the
 <a href="tables/CoordinateOperationMethods.html#9807">Coordinate Operation Methods</a>
page,
 then build a <code>DefaultProjectedCRS</code> instance using it.</p>
+<h3 id="google">How do I instantiate a Google projection?<a class="headerlink" href="#google"
title="Permanent link">&para;</a></h3>
+<p>The Google projection is a Mercator projection that pretends to be defined on the
WGS84 datum,
+but actually ignores the ellipsoidal nature of that datum and uses the simpler spherical
formulas instead.
+Since version 6.15 of the EPSG geodetic dataset, the preferred way to get that projection
is to invoke <code>CRS.forCode("EPSG:3857")</code>.
+Note that the use of that projection is <strong>not</strong> recommended, unless
needed for compatibility with other data.</p>
+<p>The EPSG:3857 definition uses a map projection method named "Popular Visualisation
Pseudo Mercator".
+The EPSG geodetic dataset provides also some other map projections that use spherical formulas
despite the ellipsoidal nature of the ellipsoid.
+Those methods have "(Spherical)" in their name, for example "Mercator (Spherical)"
+(which differs from "Popular Visualisation Pseudo Mercator" by the use of a more appropriate
sphere radius).
+Those projection methods can be used in Well Known Text (WKT) definitions.</p>
+<p>If there is a need to use spherical formulas with a projection that does not have
a "(Spherical)" counterpart,
+this can be done with explicit declarations of "semi_major" and "semi_minor" parameter values
in the WKT definition.
+Those parameters are usually inferred from the datum, but Apache SIS allows explicit declarations
to override the inferred values.</p>
+<h3 id="projectionKind">How can I identify the projection kind of a <abbr title="Coordinate
Reference System">CRS</abbr>?<a class="headerlink" href="#projectionKind" title="Permanent
link">&para;</a></h3>
+<p>The "kind of projection" (Mercator, Lambert Conformal, <em>etc.</em>)
is called <em>Operation Method</em> in <abbr title="International Organization
for Standardization">ISO</abbr> 19111 terminology.
+One approach is to check the value of <code>OperationMethod.getName()</code>
and compare them against the <abbr title="Open Geospatial Consortium">OGC</abbr>
or EPSG names
+listed in the <a href="tables/CoordinateOperationMethods.html">Coordinate Operation
Methods</a> page.</p>
+<h3 id="lookupEPSG">How do I get the EPSG code of an existing <abbr title="Coordinate
Reference System">CRS</abbr>?<a class="headerlink" href="#lookupEPSG" title="Permanent
link">&para;</a></h3>
+<p>The <em>identifier</em> of a Coordinate Reference System (<abbr title="Coordinate
Reference System">CRS</abbr>) object can be obtained by the <code>getIdentifiers()</code>
method,
+which usually return a collection of zero or one element.
+If the <abbr title="Coordinate Reference System">CRS</abbr> has been created
from a Well Known Text (WKT) parsing
+and the WKT ends with an <code>AUTHORITY["EPSG", "xxxx"]</code> (WKT 1) or <code>ID["EPSG",
xxxx]</code> (WKT 2) element,
+then the identifier (an EPSG numerical code in this example) is the <em>xxxx</em>
value in that element.
+If the <abbr title="Coordinate Reference System">CRS</abbr> has been created
from the EPSG geodetic dataset (for example by a call to <code>CRS.forCode("EPSG:xxxx")</code>),
+then the identifier is that <em>xxxx</em> code.
+If the <abbr title="Coordinate Reference System">CRS</abbr> has been created
in another way, then the collection returned by the <code>getIdentifiers()</code>
method
+may or may not be empty depending if the program that created the <abbr title="Coordinate
Reference System">CRS</abbr> took the responsibility of providing identifiers.</p>
+<p>If the collection of identifiers is empty, the most effective fix is to make sure
that the WKT
+contains an <code>AUTHORITY</code> or <code>ID</code> element (assuming
that the <abbr title="Coordinate Reference System">CRS</abbr> was parsed from
a WKT).
+If this is not possible, then the <code>org.apache.sis.referencing.IdentifiedObjects</code>
class contains
+some convenience methods which may help. Example:</p>
+<div class="codehilite"><pre><span class="n">CoordinateReferenceSystem</span>
<span class="n">myCRS</span> <span class="o">=</span> <span class="err">…</span><span
class="o">;</span>
+<span class="n">Integer</span> <span class="n">identifier</span>
<span class="o">=</span> <span class="n">IdentifiedObjects</span><span
class="o">.</span><span class="na">lookupEPSG</span><span class="o">(</span><span
class="n">myCRS</span><span class="o">);</span>
+<span class="k">if</span> <span class="o">(</span><span class="n">identifier</span>
<span class="o">!=</span> <span class="kc">null</span><span class="o">)</span>
<span class="o">{</span>
+    <span class="n">System</span><span class="o">.</span><span
class="na">out</span><span class="o">.</span><span class="na">println</span><span
class="o">(</span><span class="s">&quot;The EPSG code has been found: &quot;</span>
<span class="o">+</span> <span class="n">identifier</span><span
class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The above call will scan the EPSG database for a <abbr title="Coordinate Reference
System">CRS</abbr> equals (ignoring metadata) to the given one.
+<em>Note that this scan is sensitive to axis order.</em>
+Most geographic <abbr title="Coordinate Reference System">CRS</abbr> in the EPSG
database are declared with (<em>latitude</em>, <em>longitude</em>)
axis order.
+Consequently if the given <abbr title="Coordinate Reference System">CRS</abbr>
has (<em>longitude</em>, <em>latitude</em>) axis order, then the scan
is likely to find no match.</p>
+<h3 id="lookupURN">How do I get the "urn:ogc:def:crs:…" URN of an existing <abbr
title="Coordinate Reference System">CRS</abbr>?<a class="headerlink" href="#lookupURN"
title="Permanent link">&para;</a></h3>
+<p><abbr title="Open Geospatial Consortium">OGC</abbr> defines URN for
<abbr title="Coordinate Reference System">CRS</abbr> identifiers, for example
"urn:ogc:def:crs:epsg:7.1:4326" where "7.1" is the version of the EPSG database used.
+URN may or may not be present in the set of identifiers returned by <code>crs.getIdentifiers()</code>.
+In many cases (especially if the <abbr title="Coordinate Reference System">CRS</abbr>
was parsed from a Well Known Text), only simple identifiers like "EPSG:4326" are provided.
+An easy way to build the full URN is to use the code below:</p>
+<div class="codehilite"><pre><span class="n">CoordinateReferenceSystem</span>
<span class="n">myCRS</span> <span class="o">=</span> <span class="err">…</span><span
class="o">;</span>
+<span class="n">String</span> <span class="n">urn</span> <span
class="o">=</span> <span class="n">IdentifiedObjects</span><span class="o">.</span><span
class="na">lookupURN</span><span class="o">(</span><span class="n">myCRS</span><span
class="o">);</span>
+</pre></div>
+
+
+<p>The above call may scan the EPSG database for finding the information if it was
not explicitely provided in the given <abbr title="Coordinate Reference System">CRS</abbr>.</p>
+<h3 id="lookupReliability">Can I rely on IdentifiedObjects.lookupEPSG(…) to work
correctly as the inverse of <abbr title="Coordinate Reference System">CRS</abbr>.forCode(…)?<a
class="headerlink" href="#lookupReliability" title="Permanent link">&para;</a></h3>
+<p>For <abbr title="Coordinate Reference System">CRS</abbr> created from
the EPSG geodetic dataset, usually yes.
+Note however that <code>IdentifiedObjects.getIdentifier(…)</code> is cheaper
and insensitive to the details of <abbr title="Coordinate Reference System">CRS</abbr>
definition,
+since it never query the database. But it works only if the <abbr title="Coordinate Reference
System">CRS</abbr> declares explicitly its code,
+which is the case for <abbr title="Coordinate Reference System">CRS</abbr> created
from the EPSG database or parsed from a Well Known Text (WKT) having an <code>AUTHORITY</code>
or <code>ID</code> element.
+The <code>lookupEPSG(…)</code> method on the other hand is robust to erroneous
code declaration,
+since it always compares the <abbr title="Coordinate Reference System">CRS</abbr>
with the database content.
+But it fails if there is slight mismatch (for example rounding errors in projection parameters)
+between the supplied <abbr title="Coordinate Reference System">CRS</abbr> and
the <abbr title="Coordinate Reference System">CRS</abbr> found in the database.</p>
+<h3 id="equalsIgnoreMetadata">How can I determine if two <abbr title="Coordinate
Reference System">CRS</abbr> are "functionally" equal?<a class="headerlink" href="#equalsIgnoreMetadata"
title="Permanent link">&para;</a></h3>
+<p>Two Coordinate Reference Systems may not be considered equal if they are associated
to different metadata
+(name, identifiers, scope, domain of validity, remarks), even though they represent the same
logical <abbr title="Coordinate Reference System">CRS</abbr>.
+In order to test if two <abbr title="Coordinate Reference System">CRS</abbr>
are functionally equivalent, use <code>Utilities.equalsIgnoreMetadata(Object, Object)</code>.</p>
+<h3 id="crsHashCode">Are <abbr title="Coordinate Reference System">CRS</abbr>
objects safe for use as keys in HashMap?<a class="headerlink" href="#crsHashCode" title="Permanent
link">&para;</a></h3>
+<p>Yes, every classes defined in the <code>org.apache.sis.referencing.crs</code>,
<code>cs</code> and <code>datum</code> packages
+define properly their <code>equals(Object)</code> and <code>hashCode()</code>
methods.
+The Apache SIS library itself uses <abbr title="Coordinate Reference System">CRS</abbr>
objects in <code>HashMap</code>-like containers for caching purpose.</p>
+<h2 id="transforms">Coordinate transformations<a class="headerlink" href="#transforms"
title="Permanent link">&para;</a></h2>
+<h3 id="axisOrderInTransforms">My transformed coordinates are totally wrong!<a class="headerlink"
href="#axisOrderInTransforms" title="Permanent link">&para;</a></h3>
+<p>This is most frequently caused by ordinate values given in the wrong order.
+Developers tend to assume a (<em>x</em>, <em>y</em>) or (<em>longitude</em>,
<em>latitude</em>) axis order.
+But geographers and pilots are using (<em>latitude</em>, <em>longitude</em>)
axis order for centuries,
+and the EPSG geodetic dataset defines geographic coordinate reference systems that way.
+If a coordinate transformation seems to produce totally wrong values,
+the first thing to do should be to print the source and target coordinate reference systems:</p>
+<div class="codehilite"><pre><span class="n">System</span><span
class="o">.</span><span class="na">out</span><span class="o">.</span><span
class="na">println</span><span class="o">(</span><span class="n">sourceCRS</span><span
class="o">);</span>
+<span class="n">System</span><span class="o">.</span><span class="na">out</span><span
class="o">.</span><span class="na">println</span><span class="o">(</span><span
class="n">targetCRS</span><span class="o">);</span>
+</pre></div>
+
+
+<p>Attention should be paid to the order of <code>AXIS</code> elements.
+In the example below, the coordinate reference system clearly uses (<em>latitude</em>,
<em>longitude</em>) axis order:</p>
+<div class="codehilite"><pre>GeodeticCRS[&quot;WGS 84&quot;,
+  Datum[&quot;World Geodetic System 1984&quot;,
+    Ellipsoid[&quot;WGS 84&quot;, 6378137.0, 298.257223563]],
+  CS[ellipsoidal, 2],
+    Axis[&quot;Geodetic latitude (Lat)&quot;, north],
+    Axis[&quot;Geodetic longitude (Lon)&quot;, east],
+    Unit[&quot;degree&quot;, 0.017453292519943295]]
+</pre></div>
+
+
+<p>If (<em>longitude</em>, <em>latitude</em>) axis order is
really wanted, Apache SIS can be forced to that order <a href="#axisOrder">as described
above</a>.</p>
+<h3 id="projectionName">I have correct axis order but my transformed coordinates are
still wrong.<a class="headerlink" href="#projectionName" title="Permanent link">&para;</a></h3>
+<p>Make sure that the right projection is used. Some projection names are confusing.
+For example <em>"Oblique Mercator"</em> and <em>"Hotine Oblique Mercator"</em>
(in EPSG naming) are two different projections.
+But <em>"Oblique Mercator"</em> (not Hotine) in EPSG naming is also called <em>"Hotine
Oblique Mercator Azimuth Center"</em> by ESRI,
+while <em>"Hotine Oblique Mercator"</em> (EPSG naming) is called <em>"Hotine
Oblique Mercator Azimuth Natural Origin"</em> by ESRI.</p>
+<p>The <em>"Oblique Stereographic"</em> projection (EPSG name) is called
<em>"Double Stereographic"</em> by ESRI.
+ESRI also defines a <em>"Stereographic"</em> projection, which is actually an
oblique projection like the former but using different formulas.</p>
+<h3 id="parameterUnits">I just used the WKT of a well-known authority and my transformed
coordinates are still wrong!<a class="headerlink" href="#parameterUnits" title="Permanent
link">&para;</a></h3>
+<p>The Well Known Text (WKT) specification has been interpreted in different ways by
different implementors.
+One subtle issue is the angular units of prime meridian and projection parameter values.
+The WKT 1 specification clary states: <em>"If the <code>PRIMEM</code> clause
occurs inside a <code>GEOGCS</code>,
+then the longitude units will match those of the geographic coordinate system"</em>
(source: <abbr title="Open Geospatial Consortium">OGC</abbr> 01-009).
+However ESRI and GDAL among others unconditionally use decimal degrees, ignoring this part
of the WKT specification.
+This problem can be identified by WKT inspection as in the following example:</p>
+<div class="codehilite"><pre>PROJCS[&quot;Lambert II étendu&quot;,
+  GEOGCS[&quot;Nouvelle Triangulation Française&quot;,
+    …,
+    PRIMEM[&quot;Paris&quot;, 2.337229167],
+    UNIT[&quot;grad&quot;, 0.01570796326794897]]
+  PROJECTION[&quot;Lambert_Conformal_Conic_1SP&quot;],
+  PARAMETER[&quot;latitude_of_origin&quot;, 46.8],
+  …]
+</pre></div>
+
+
+<p>The Paris prime meridian is located at approximatively 2.597 gradians from Greenwich,
which is 2.337 degrees.
+From this fact, we can see that the above WKT uses decimal degrees despite its <code>UNIT["grad"]</code>
declaration.
+This mismatch applies also to the parameter value, which declare 46.8° in the above example
while the official value is 52 gradians.
+By default, Apache SIS interprets those angular values as gradians when parsing such WKT,
resulting in a large error.
+In order to get the intended result, there is a choice:</p>
+<ul>
+<li>
+<p>Replace <code>UNIT["grad", 0.01570796326794897]</code> by <code>UNIT["degree",
0.017453292519943295]</code>,
+    which ensure that Apache SIS, GDAL and ESRI understand that WKT in the same way.</p>
+</li>
+<li>
+<p>Or ask explicitely Apache SIS to parse the WKT using the ESRI or GDAL conventions,
by specifying the
+    <code>Convention.WKT1_COMMON_UNITS</code> enumeration value to <code>WKTFormat</code>
in the <code>org.apache.sis.io.wkt</code> package.</p>
+</li>
+</ul>
+<p>Note that the GeoPackage standard explicitely requires <abbr title="Open Geospatial
Consortium">OGC</abbr> 01-009 compliant WKT
+and the new WKT 2 standard also follows the <abbr title="Open Geospatial Consortium">OGC</abbr>
01-009 interpretation.
+The default Apache SIS behavior is consistent with those two standards.</p>
+<h3 id="BursaWolf">I verified all the above and still have an error of about one kilometer.<a
class="headerlink" href="#BursaWolf" title="Permanent link">&para;</a></h3>
+<p>Coordinate Reference Systems (<abbr title="Coordinate Reference System">CRS</abbr>)
approximate the Earth’s shape by an ellipsoid.
+Different ellipsoids (actually different <em>datum</em>) are used in different
countries of the world and at different time in history.
+When transforming coordinates between two <abbr title="Coordinate Reference System">CRS</abbr>
using the same datum, no Bursa-Wolf parameters are needed.
+But when the transformation involves a change of datum, the referencing module needs some
information about how to perform that datum shift.</p>
+<p>There is many way to specify how to perform a datum shift, and most of them are
only approximation.
+The Bursa-Wolf method is one of them, not the only one. However it is one of the most frequently
used method.
+The Bursa-Wolf parameters can specified inside a <code>TOWGS84</code> element
in version 1 of Well Known Text (WKT) format,
+or in a <code>BOUNDCRS</code> element in version 2 of WKT format.
+If the <abbr title="Coordinate Reference System">CRS</abbr> are parsed from a
WKT string, make sure that the string contains the appropriate element.</p>
+<h3 id="slightDifferences">I get slightly different results depending on the environment
I’m running in.<a class="headerlink" href="#slightDifferences" title="Permanent link">&para;</a></h3>
+<p>The results of coordinates converted when running in a web application container
(JBoss, <em>etc.</em>)
+may be a few meters off compared to coordinates converted in an IDE (NetBeans, Eclipse, <em>etc.</em>).
+The results depend on whatever an EPSG factory is available on the classpath, <strong>regardless
how the <abbr title="Coordinate Reference System">CRS</abbr> were created</strong>,
+because the EPSG factory specifies explicitly the coordinate operation to apply for some
pairs of <abbr title="Coordinate Reference System">CRS</abbr>.
+In such case, the coordinate operation specified by EPSG has precedence over the Burwa-Wolf
parameters
+(the <code>TOWGS84</code> element in version 1 of Well Known Text format).</p>
+<p>A connection to the EPSG database may have been established for one environment
+(typically the JEE one) and not the other (typically the IDE one) because only the former
has <abbr title="Java DataBase Connectivity">JDBC</abbr> driver.
+The recommended way to uniformize the results is to add in the second environment (IDE)
+the same <abbr title="Java DataBase Connectivity">JDBC</abbr> driver than the
first environment (JEE).
+It should be one of the following: JavaDB (a.k.a. Derby), HSQL or PostgreSQL.
+Make sure that the <a href="epsg.html">connection parameters to the EPSG database</a>
are also the same.</p>
+<h3 id="toWGS84">Can I always expect a transform from an arbitrary <abbr title="Coordinate
Reference System">CRS</abbr> to WGS84 to succeed?<a class="headerlink" href="#toWGS84"
title="Permanent link">&para;</a></h3>
+<p>For 2D horizontal <abbr title="Coordinate Reference System">CRS</abbr>
created from the EPSG database, calls to <code>CRS.findOperation(…)</code>
should generally succeed.
+For 3D <abbr title="Coordinate Reference System">CRS</abbr> having any kind of
height different than ellipsoid height, or for a 2D <abbr title="Coordinate Reference System">CRS</abbr>
of type <code>EngineeringCRS</code>, it may fail.
+Note however that even if the call to <code>CRS.findOperation(…)</code>
succeed, the call to <code>MathTransform.transform(…)</code> may fail
+or produce <code>NaN</code> or infinity values if the coordinate to transform
is far from the projection area of validity.</p>
 <h1 id="metadata">Metadata<a class="headerlink" href="#metadata" title="Permanent
link">&para;</a></h1>
 <h2 id="metadata-implementation">Custom implementations<a class="headerlink" href="#metadata-implementation"
title="Permanent link">&para;</a></h2>
 <h3 id="metadata-proxy">My metadata are stored in a database-like framework. Implementing
every GeoAPI interfaces for them is impractical.<a class="headerlink" href="#metadata-proxy"
title="Permanent link">&para;</a></h3>



Mime
View raw message