sis-commits mailing list archives

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

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 14:11:47 2016
@@ -1 +1 @@
-1753248
+1753698

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 14:11:47 2016
@@ -96,24 +96,129 @@ h2:hover > .headerlink, h3:hover > .head
 <p>This page lists some Frequently Asked Questions (FAQ) when using Apache SIS.</p>
 <div class="toc">
 <ul>
+<li><a href="#referencing">Referencing</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>
+<li><a href="#UTM">How do I instantiate a Universal Transverse Mercator (UTM)
projection?</a></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 can't marshall my custom implementation.</a></li>
+<li><a href="#metadata-unknownClass">I can not marshall my custom implementation.</a></li>
 </ul>
 </li>
 </ul>
 </li>
-<li><a href="#referencing">Referencing</a><ul>
-<li><a href="#axisOrder">Axis order</a></li>
-</ul>
-</li>
 </ul>
 </div>
+<h1 id="referencing">Referencing<a class="headerlink" href="#referencing" title="Permanent
link">&para;</a></h1>
+<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.
+But more advanced applications will typically use EPSG codes instead.
+Note that all geographic coordinates below express latitude <em>before</em> longitude.</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">org.opengis.geometry.DirectPosition</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.opengis.referencing.crs.CoordinateReferenceSystem</span><span
class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.opengis.referencing.operation.CoordinateOperation</span><span
class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.opengis.referencing.operation.TransformException</span><span
class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.opengis.util.FactoryException</span><span
class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.apache.sis.referencing.CRS</span><span
class="o">;</span>
+<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">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>
+        <span class="n">CoordinateOperation</span> <span class="n">operation</span>
<span class="o">=</span> <span class="n">CRS</span><span class="o">.</span><span
class="na">findOperation</span><span class="o">(</span><span class="n">sourceCRS</span><span
class="o">,</span> <span class="n">targetCRS</span><span class="o">,</span>
<span class="kc">null</span><span class="o">);</span>
+
+        <span class="c1">// The above lines are costly and should be performed only
once before to project many points.</span>
+        <span class="c1">// In this example, the operation that we got is valid for
coordinates in geographic area from</span>
+        <span class="c1">// 12°E to 18°E (UTM zone 33) and 0°N to 84°N.</span>
+
+        <span class="n">DirectPosition</span> <span class="n">ptSrc</span>
<span class="o">=</span> <span class="k">new</span> <span class="n">DirectPosition2D</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">// 40°N 14°E</span>
+        <span class="n">DirectPosition</span> <span class="n">ptDst</span>
<span class="o">=</span> <span class="n">operation</span><span
class="o">.</span><span class="na">getMathTransform</span><span class="o">().</span><span
class="na">transform</span><span class="o">(</span><span class="n">ptSrc</span><span
class="o">,</span> <span class="kc">null</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;Source: &quot;</span>
<span class="o">+</span> <span class="n">ptSrc</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;Target: &quot;</span>
<span class="o">+</span> <span class="n">ptDst</span><span class="o">);</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="operation-methods">Which map projections are supported?<a class="headerlink"
href="#operation-methods" title="Permanent link">&para;</a></h3>
+<p>The operation <em>methods</em> (including, but not limited to, map projections)
supported by Apache SIS
+are listed in the <a href="tables/CoordinateOperationMethods.html">Coordinate Operation
Methods</a> page.
+The amount of map projection <em>methods</em> is relatively small,
+but the amount of <em>projected <abbr title="Coordinate Reference System">CRS</abbr></em>
that we can build from them can be very large.
+For example with only three methods (namely <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>For convenience, some pre-defined combinations of operation methods with parameter
values are assigned a code.
+A well-known source of codes is the EPSG geodetic dataset, but other authorities also exist.
+The predefined <abbr title="Coordinate Reference System">CRS</abbr> known to
Apache SIS is listed in the
+<a href="tables/CoordinateReferenceSystems.html">Coordinate Reference Systems</a>
page.</p>
+<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.
+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>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, WKT 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 WKT 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 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.
+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>
+<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>
+
+
+<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="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.
+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>
+<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>
+
+
+<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>
+<div class="codehilite"><pre><span class="kt">int</span> <span
class="n">code</span> <span class="o">=</span> <span class="mi">32600</span>
<span class="o">+</span> <span class="n">zone</span><span class="o">;</span>
+<span class="n">CoordinateReferenceSystem</span> <span class="n">crs</span>
<span class="o">=</span> <span class="n">CRS</span><span class="o">.</span><span
class="na">forCode</span><span class="o">(</span><span class="s">&quot;EPSG:&quot;</span>
<span class="o">+</span> <span class="n">code</span><span class="o">);</span>
+</pre></div>
+
+
+<p>If no EPSG code is available for the desired projection, a more powerful (but also
more difficult)
+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>
 <h1 id="metadata">Metadata<a class="headerlink" href="#metadata" title="Permanent
link">&para;</a></h1>
-<p>Frequently asked questions about the <code>sis-metadata</code> module.</p>
 <h2 id="metadata-implementation">Custom implementations<a class="headerlink" href="#metadata-implementation"
title="Permanent link">&para;</a></h2>
-<p>Frequently asked questions custom implementations of <code>org.opengis.metadata</code>
interfaces.</p>
 <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>
 <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
@@ -131,7 +236,7 @@ See the <code>Proxy</code> Javadoc for d
 
 <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 can't marshall my custom implementation.<a class="headerlink"
href="#metadata-unknownClass" title="Permanent link">&para;</a></h3>
+<h3 id="metadata-unknownClass">I can not marshall my custom implementation.<a class="headerlink"
href="#metadata-unknownClass" title="Permanent link">&para;</a></h3>
 <p>The classes given to the JAXB marshaller shall contain JAXB annotations,
 otherwise the following exception is thrown:</p>
 <div class="codehilite"><pre>javax.xml.bind.JAXBException: class MyCustomClass
nor any of its super class is known to this context.
@@ -143,10 +248,6 @@ provided in the <code>org.apache.metadat
 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>
-<h1 id="referencing">Referencing<a class="headerlink" href="#referencing" title="Permanent
link">&para;</a></h1>
-<p>Frequently asked questions about the <code>sis-referencing</code> module.</p>
-<h3 id="axisOrder">Axis order<a class="headerlink" href="#axisOrder" title="Permanent
link">&para;</a></h3>
-<p>(... to be provided later ...)</p>
             </article>
           </section>
         </div><!--/span-->



Mime
View raw message