| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| |
| |
| <title>Apache SIS - Frequently asked questions</title> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/css/bootstrap.min.css" |
| rel="stylesheet" integrity="sha384-F3w7mX95PdgyTmZZMECAngseQB83DfGTowi0iMjiWaeVhAn4FJkqJByhZMI3AhiU" crossorigin="anonymous"> |
| <link rel="stylesheet" type="text/css" media="screen" href="./syntax.css"> |
| <link rel="stylesheet" type="text/css" media="screen" href="./sis.css"> |
| </head> |
| |
| <body> |
| |
| <nav class="navbar navbar-expand-md navbar-dark fixed-top bg-dark"> |
| <div class="container-fluid"> |
| <a class="navbar-brand" href="./index.html"> Apache SIS™</a> |
| <ul class="navbar-nav me-auto mb-2 mb-md-0"> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuAbout" data-bs-toggle="dropdown" aria-expanded="false">About</a> |
| <ul class="dropdown-menu" aria-labelledby="menuAbout"> |
| <li><a class="dropdown-item" href="http://www.apache.org/licenses/">License</a></li> |
| <li><a class="dropdown-item" href="./mail-lists.html">Mailing Lists</a></li> |
| <li><a class="dropdown-item" href="./team-list.html">Project Team</a></li> |
| <li><a class="dropdown-item" href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuDownload" data-bs-toggle="dropdown" aria-expanded="false">Download</a> |
| <ul class="dropdown-menu" aria-labelledby="menuDownload"> |
| <li><a class="dropdown-item" href="./downloads.html">Downloads</a></li> |
| <li><a class="dropdown-item" href="./source.html">Checkout Sources</a></li> |
| <li><a class="dropdown-item" href="./epsg.html">EPSG Database</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuDocumentation" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a> |
| <ul class="dropdown-menu" aria-labelledby="menuDocumentation"> |
| <li><a class="dropdown-item" href="./apidocs/index.html">Online Javadoc</a></li> |
| <li><a class="dropdown-item" href="./book/en/developer-guide.html">Developer Guide</a></li> |
| <li><a class="dropdown-item" href="./howto.html">How to…</a></li> |
| <li><a class="dropdown-item" href="./formats.html">Supported formats</a></li> |
| <li><a class="dropdown-item" href="./tables/CoordinateReferenceSystems.html">Supported CRS</a></li> |
| <li><a class="dropdown-item" href="./tables/CoordinateOperationMethods.html">Map Projections</a></li> |
| <li><a class="dropdown-item" href="./code-patterns.html">Code Patterns</a></li> |
| <li><a class="dropdown-item" href="./faq.html">FAQ</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuContribute" data-bs-toggle="dropdown" aria-expanded="false">Contribute</a> |
| <ul class="dropdown-menu" aria-labelledby="menuContribute"> |
| <li><a class="dropdown-item" href="./contributor.html">New Contributor</a></li> |
| <li><a class="dropdown-item" href="./coding-conventions.html">Coding Conventions</a></li> |
| <li><a class="dropdown-item" href="./mail-lists.html">Mailing Lists</a></li> |
| <li><a class="dropdown-item" href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li> |
| <li><a class="dropdown-item" href="https://github.com/apache/sis">GitHub mirror</a></li> |
| <li><a class="dropdown-item" href="https://cwiki.apache.org/confluence/display/SIS">Wiki</a></li> |
| <li><hr class="dropdown-divider"></li> |
| <li><a class="dropdown-item" href="./release-management.html">Release management</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" id="menuASF" data-bs-toggle="dropdown" aria-expanded="false">The Foundation</a> |
| <ul class="dropdown-menu" aria-labelledby="menuASF"> |
| <li><a class="dropdown-item" href="http://www.apache.org">The Foundation</a></li> |
| <li><a class="dropdown-item" href="http://www.apache.org/foundation/sponsorship.html">Donate</a></li> |
| <li><a class="dropdown-item" href="http://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| <li><a class="dropdown-item" href="http://www.apache.org/security/">Security</a></li> |
| </ul> |
| </li> |
| </ul> |
| <ul class="navbar-nav ml-auto mb-2 mb-md-0"> |
| <li class="nav-item"> |
| <a href="https://www.apache.org/events/current-event.html"> |
| <img class="apache-con" src="https://www.apache.org/events/current-event-234x60.png" alt="ApacheCon"/> |
| </a> |
| </li> |
| </ul> |
| </div> |
| </nav> |
| |
| |
| <div class="row flex-nowrap"> |
| <div class="d-flex flex-column flex-shrink-0 p-3 text-white bg-dark" style="width:13rem; min-height:40rem"> |
| <ul class="nav nav-pills flex-column mb-auto position-fixed"> |
| <li><a class="nav-link text-white " href="./index.html">Home</a></li> |
| <li><a class="nav-link text-white" href="http://www.apache.org/licenses/">License</a></li> |
| <li><a class="nav-link text-white " href="./downloads.html">Downloads</a></li> |
| <li><a class="nav-link text-white " href="./howto.html">How to…</a></li> |
| <li><a class="nav-link text-white " href="./standards.html">Standards</a></li> |
| <li><a class="nav-link text-white " href="./formats.html">Data formats</a></li> |
| <li><a class="nav-link text-white " href="./epsg.html">EPSG Database</a></li> |
| <li><a class="nav-link text-white " href="./javafx.html">Application (demo)</a></li> |
| <li><a class="nav-link text-white" href="./apidocs/index.html">Online Javadoc</a></li> |
| <li><a class="nav-link text-white" href="./book/en/developer-guide.html">Developer Guide</a></li> |
| <li><a class="nav-link text-white " href="./code-patterns.html">Code patterns</a></li> |
| <li><a class="nav-link active " href="./faq.html">FAQ</a></li> |
| </ul> |
| </div> |
| <div class="col"> |
| <main class="container"> |
| <article> |
| <img src="./images/logo.png" class="sis-logo" align="left"/> |
| <p class="page-title">Frequently asked questions</p> |
| |
| <p>This page lists some Frequently Asked Questions (FAQ) when using Apache <abbr title="Spatial Information System">SIS</abbr>.</p> |
| <nav id="TableOfContents"> |
| <ul> |
| <li><a href="#referencing">Referencing </a> |
| <ul> |
| <li><a href="#referencing-intro">Getting started </a> |
| <ul> |
| <li><a href="#getCRS">How do I get a Coordinate Reference System? </a></li> |
| <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> |
| </ul> |
| </li> |
| <li><a href="#crs">Coordinate Reference Systems </a> |
| <ul> |
| <li><a href="#google">What is the Google projection? </a></li> |
| <li><a href="#axisOrder">What is the axis order issue and how is it addressed? </a></li> |
| <li><a href="#lookupReliability">Is IdentifiedObjects.lookupEPSG(…) a reliable inverse of CRS.forCode(…)? </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> |
| <li><a href="#metadata-implementation">Custom implementations </a> |
| <ul> |
| <li><a href="#metadata-proxy">My metadata are stored in a database-like framework. Implementing every GeoAPI interfaces for them is impractical. </a></li> |
| <li><a href="#metadata-unknownClass">I cannot marshall my custom implementation. </a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| <h1 id="referencing">Referencing </h1> |
| <h2 id="referencing-intro">Getting started </h2> |
| <h3 id="getCRS">How do I get a Coordinate Reference System? </h3> |
| <p>The <code>CRS</code> class in the <code>org.apache.sis.referencing.crs</code> package provides static convenience methods. |
| The most notable methods are:</p> |
| <ul> |
| <li><code>CRS.forCode(String)</code> for fetching a <abbr title="Coordinate Reference System">CRS</abbr> from an authority code in a database. |
| Some supported authorities are <a href="epsg.html">EPSG</a>, AUTO, AUTO2 and CRS.</li> |
| <li><code>CRS.fromWKT(String)</code> for parsing a <abbr title="Coordinate Reference System">CRS</abbr> definition from a character string in Well-Known Text (WKT) format.</li> |
| <li><code>CRS.fromXML(String)</code> for parsing a <abbr title="Coordinate Reference System">CRS</abbr> definition from a character string in Geographic Markup Language (GML) format.</li> |
| </ul> |
| <h3 id="transform-point">How do I transform a coordinate? </h3> |
| <p>See the <a href="howto.html#referencing">“How to…”</a> page for Java code examples. |
| Those examples get Coordinate Reference Systems (CRS) instances in various ways |
| and apply coordinate operations between two reference systems.</p> |
| <h3 id="operation-methods">Which map projections are supported? </h3> |
| <p>The operation <em>methods</em> (including, but not limited to, map projections) supported by |
| Apache <abbr title="Spatial Information System">SIS</abbr> are listed in the <a href="tables/CoordinateOperationMethods.html">Coordinate Operation Methods</a> page. |
| The amount of map projection methods is relatively small, |
| but the amount of <em>projected Coordinate Reference Systems</em> that we can build from them can be very large. |
| For example with only three family of methods (<em>Cylindrical Mercator</em>, <em>Transverse Mercator</em> and <em>Lambert Conic Conformal</em>) |
| used with different parameter values, we can cover thousands of projected <abbr title="Coordinate Reference System">CRS</abbr> listed in the EPSG geodetic dataset.</p> |
| <p>In order to use a map projection method, we need to know the value to assign to the projection parameters. |
| For convenience, thousands of projected <abbr title="Coordinate Reference System">CRS</abbr> with predefined parameter values are are assigned a unique identifier. |
| A well-known source of such definitions is the EPSG geodetic dataset, but other authorities also exist. |
| The predefined <abbr title="Coordinate Reference System">CRS</abbr> known to Apache <abbr title="Spatial Information System">SIS</abbr> are listed in the |
| <a href="tables/CoordinateReferenceSystems.html">Coordinate Reference Systems</a> page.</p> |
| <h2 id="crs">Coordinate Reference Systems </h2> |
| <h3 id="google">What is the Google projection? </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 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 <em>“Popular Visualisation Pseudo Mercator”</em>. |
| The EPSG geodetic dataset provides also some other map projections that use spherical formulas. |
| Those methods have “(Spherical)” in their name, for example <em>“Mercator (Spherical)”</em>, |
| and differs from <em>“Popular Visualisation Pseudo Mercator”</em> 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 <code>"semi_major"</code> and <code>"semi_minor"</code> parameter values in the <abbr title="Well Known Text">WKT</abbr> definition. |
| Those parameter values are usually inferred from the datum, but Apache <abbr title="Spatial Information System">SIS</abbr> allows explicit declarations to override the inferred values. |
| This hack is provided for making possible to use data that ignore the ellipsoid flattening factor |
| (which are unfortunately not uncommon), but it should be used in last resort only.</p> |
| <h3 id="axisOrder">What is the axis order issue and how is it addressed? </h3> |
| <p>The axis order is specified by the authority (typically a national agency) defining the Coordinate Reference System (CRS). |
| 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 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> |
| <p>For any <abbr title="Coordinate Reference System">CRS</abbr> identified by an EPSG code, the official axis order can be checked on the |
| official EPSG registry at <a href="https://epsg.org/">https://epsg.org/</a> |
| (not to be confused with other sites having “epsg” in their name, |
| but actually unrelated to the organization in charge of EPSG definitions): |
| 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> |
| <p>Recent <abbr title="Open Geospatial Consortium">OGC</abbr> standards mandate the use of axis order as defined by the authority. |
| Oldest <abbr title="Open Geospatial Consortium">OGC</abbr> standards used the (<em>x</em>, <em>y</em>) axis order instead, ignoring any authority specification. |
| Among the legacy <abbr title="Open Geospatial Consortium">OGC</abbr> standards that used the non-conform axis order, |
| an influent one is version 1 of the <em>Well Known Text</em> (WKT) format specification. |
| According that widely-used format, <abbr title="Well Known Text">WKT</abbr> definitions without explicit <code>AXIS[…]</code> elements |
| shall default to (<em>longitude</em>, <em>latitude</em>) or (<em>x</em>, <em>y</em>) axis order. |
| In version 2 of the <abbr title="Well Known Text">WKT</abbr> format, <code>AXIS[…]</code> elements are no longer optional |
| and should contain an explicit <code>ORDER[…]</code> sub-element for making the intended order yet more obvious.</p> |
| <p>Many software products still use the old (<em>x</em>, <em>y</em>) axis order, sometimes because it is easier to implement. |
| But Apache <abbr title="Spatial Information System">SIS</abbr> rather defaults to axis order <em>as defined by the authority</em> (except when parsing a <abbr title="Well Known Text">WKT</abbr> 1 definition), |
| but allows changing axis order to the (<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="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">CoordinateReferenceSystem</span> <span class="n">crs</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// CRS obtained by any means. |
| </span></span></span><span class="line"><span class="cl"><span class="c1"></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></span></span></code></pre></div> |
| <h3 id="lookupReliability">Is IdentifiedObjects.lookupEPSG(…) a reliable inverse of CRS.forCode(…)? </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 may fail 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="crsHashCode">Are CRS objects safe for use as keys in HashMap? </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 <abbr title="Spatial Information System">SIS</abbr> 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 </h2> |
| <h3 id="axisOrderInTransforms">My transformed coordinates are totally wrong! </h3> |
| <p>This is most frequently caused by coordinate 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="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><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></span><span class="line"><span class="cl"><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></span></span></code></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="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">GeodeticCRS["WGS 84", |
| </span></span><span class="line"><span class="cl"> Datum["World Geodetic System 1984", |
| </span></span><span class="line"><span class="cl"> Ellipsoid["WGS 84", 6378137.0, 298.257223563]], |
| </span></span><span class="line"><span class="cl"> CS[ellipsoidal, 2], |
| </span></span><span class="line"><span class="cl"> Axis["Geodetic latitude (Lat)", north], |
| </span></span><span class="line"><span class="cl"> Axis["Geodetic longitude (Lon)", east], |
| </span></span><span class="line"><span class="cl"> Unit["degree", 0.017453292519943295]]</span></span></code></pre></div> |
| <p>If (<em>longitude</em>, <em>latitude</em>) axis order is really wanted, Apache <abbr title="Spatial Information System">SIS</abbr> 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. </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! </h3> |
| <p>The version 1 of 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 <abbr title="Well Known Text">WKT</abbr> 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 <abbr title="Well Known Text">WKT</abbr> 1 specification |
| (note: this remark does not apply to <abbr title="Well Known Text">WKT</abbr> 2). |
| This problem can be identified by <abbr title="Well Known Text">WKT</abbr> inspection as in the following extract:</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">PROJCS["Lambert II étendu", |
| </span></span><span class="line"><span class="cl"> GEOGCS["Nouvelle Triangulation Française", ..., |
| </span></span><span class="line"><span class="cl"> PRIMEM["Paris", 2.337229167], |
| </span></span><span class="line"><span class="cl"> UNIT["grad", 0.01570796326794897]] |
| </span></span><span class="line"><span class="cl"> PROJECTION["Lambert_Conformal_Conic_1SP"], |
| </span></span><span class="line"><span class="cl"> PARAMETER["latitude_of_origin", 46.8], ...]</span></span></code></pre></div> |
| <p>The Paris prime meridian is located at approximately 2.597 gradians from Greenwich, which is 2.337 degrees. |
| From this fact, we can see that the above <abbr title="Well Known Text">WKT</abbr> 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 <abbr title="Spatial Information System">SIS</abbr> interprets those angular values as gradians when parsing such <abbr title="Well Known Text">WKT</abbr>, 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 <abbr title="Spatial Information System">SIS</abbr>, GDAL and ESRI understand that <abbr title="Well Known Text">WKT</abbr> 1 in the same way.</p> |
| </li> |
| <li> |
| <p>Or ask explicitly Apache <abbr title="Spatial Information System">SIS</abbr> to parse the <abbr title="Well Known Text">WKT</abbr> 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 explicitly requires <abbr title="Open Geospatial Consortium">OGC</abbr> 01-009 compliant <abbr title="Well Known Text">WKT</abbr> |
| and the new <abbr title="Well Known Text">WKT</abbr> 2 standard also follows the <abbr title="Open Geospatial Consortium">OGC</abbr> 01-009 interpretation. |
| The default Apache <abbr title="Spatial Information System">SIS</abbr> 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. </h3> |
| <p>Coordinate Reference Systems (CRS) 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 methods. |
| The Bursa-Wolf parameters can be specified inside a <code>TOWGS84</code> element with version 1 of Well Known Text (WKT) format, |
| or in a <code>BOUNDCRS</code> element with version 2 of <abbr title="Well Known Text">WKT</abbr> format. |
| If the CRS are parsed from a <abbr title="Well Known Text">WKT</abbr> 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. </h3> |
| <p>The results of coordinate transformations when running in a web application container (JBoss, <em>etc.</em>) |
| may be a few meters off compared to coordinates transformations in an IDE (NetBeans, Eclipse, <em>etc.</em>). |
| The results depend on whether 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 one available in 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 CRS to WGS84 to succeed? </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 ellipsoidal 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 domain of validity.</p> |
| <h1 id="metadata">Metadata </h1> |
| <h2 id="metadata-implementation">Custom implementations </h2> |
| <h3 id="metadata-proxy">My metadata are stored in a database-like framework. Implementing every GeoAPI interfaces for them is impractical. </h3> |
| <p>Developers do not need to implement directly the metadata interfaces. |
| If the underlying storage framework can access metadata from their class and attribute names (either Java names |
| or <abbr title="International Organization for Standardization">ISO</abbr>/<abbr title="Open Geospatial Consortium">OGC</abbr> names), then it is possible to implement a single engine accessing any kind of metadata and let the |
| Java Virtual Machine implements the GeoAPI interfaces on-the-fly, using the <code>java.lang.reflect.Proxy</code> class. |
| See the <code>Proxy</code> Javadoc for details, keeping in mind that the <abbr title="International Organization for Standardization">ISO</abbr>/<abbr title="Open Geospatial Consortium">OGC</abbr> name of a <code>java.lang.Class</code> or |
| <code>java.lang.reflect.Method</code> object can be obtained as below:</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">UML</span> <span class="n">uml</span> <span class="o">=</span> <span class="n">method</span><span class="o">.</span><span class="na">getAnnotation</span><span class="o">(</span><span class="n">UML</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> |
| </span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="o">(</span><span class="n">uml</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span> |
| </span></span><span class="line"><span class="cl"> <span class="n">String</span> <span class="n">name</span> <span class="o">=</span> <span class="n">uml</span><span class="o">.</span><span class="na">identifier</span><span class="o">();</span> |
| </span></span><span class="line"><span class="cl"> <span class="c1">// Fetch the metadata here. |
| </span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="o">}</span></span></span></code></pre></div> |
| <p>This is indeed the approach taken by the <code>org.apache.sis.metadata.sql</code> package for providing an implementation |
| of all GeoAPI metadata interfaces reading their values directly from a SQL database.</p> |
| <h3 id="metadata-unknownClass">I cannot marshall my custom implementation. </h3> |
| <p>The classes given to the JAXB marshaller shall contain JAXB annotations, |
| otherwise the following exception is thrown:</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">javax.xml.bind.JAXBException: class MyCustomClass nor any of its super class is known to this context.</span></span></code></pre></div> |
| <p>The easiest workaround is to wrap the custom implementation into one of the implementations |
| provided in the <code>org.apache.metadata.iso</code> package. |
| All those SIS implementation classes provide shallow copy constructor for making that easy. |
| Note that you need to wrap only the root class, not the attributes. |
| The attribute values will be wrapped automatically as needed by JAXB adapters.</p> |
| |
| |
| </article> |
| </main> |
| <footer class="footer"> |
| <div class="container"> |
| <p> |
| Copyright © 2013-2023 The Apache Software Foundation, Licensed under the |
| <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/> |
| Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| </footer> |
| </div> |
| </div> |
| |
| <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/js/bootstrap.bundle.min.js" |
| integrity="sha384-/bQdsTh/da6pkI1MST/rWKFNjaCP5gBSY4sEBT38Q/9RBh9AH40zEOg7Hlq2THRZ" crossorigin="anonymous"></script> |
| |
| </body> |
| </html> |
