sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1753783 - in /sis/site/trunk: book/en/referencing.html book/fr/referencing.html content/book/en/developer-guide.html content/book/fr/developer-guide.html
Date Fri, 22 Jul 2016 12:47:43 GMT
Author: desruisseaux
Date: Fri Jul 22 12:47:43 2016
New Revision: 1753783

URL: http://svn.apache.org/viewvc?rev=1753783&view=rev
Log:
Begin section about how to transform a point.

Modified:
    sis/site/trunk/book/en/referencing.html
    sis/site/trunk/book/fr/referencing.html
    sis/site/trunk/content/book/en/developer-guide.html
    sis/site/trunk/content/book/fr/developer-guide.html

Modified: sis/site/trunk/book/en/referencing.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/referencing.html?rev=1753783&r1=1753782&r2=1753783&view=diff
==============================================================================
--- sis/site/trunk/book/en/referencing.html (original)
+++ sis/site/trunk/book/en/referencing.html Fri Jul 22 12:47:43 2016
@@ -235,30 +235,43 @@
     <p>
       The axis order is specified by the authority (typically a national agency) defining the <cite>Coordinate Reference System</cite> (<abbr>CRS</abbr>).
       The order depends on the <abbr>CRS</abbr> type and the country defining the <abbr>CRS</abbr>.
-      In the case of geographic <abbr>CRS</abbr>, the (<var>latitude</var>, <var>longitude</var>) axis order is widely used by geographers and pilotes for centuries.
-      However software developers tend to consistently use the (<var>x</var>,<var>y</var>) order for every kind of <abbr>CRS</abbr>.
+      In the case of geographic <abbr>CRS</abbr>, the (<var>latitude</var>, <var>longitude</var>) axis order is widely used by geographers and pilots for centuries.
+      However software developers tend to consistently use the (<var>x</var>, <var>y</var>) order for every kind of <abbr>CRS</abbr>.
       Those different practices resulted in contradictory definitions of axis order for almost every <abbr>CRS</abbr> of kind <code>GeographicCRS</code>,
       for some <code>ProjectedCRS</code> in the South hemisphere (South Africa, Australia, <i>etc.</i>) and for some polar projections among others.
     </p><p>
       Recent <abbr>OGC</abbr> standards mandate the use of axis order as defined by the authority.
-      Oldest <abbr>OGC</abbr> standards used the (<var>x</var>,<var>y</var>) axis order instead, ignoring any authority specification.
-      Many softwares still use the old (<var>x</var>,<var>y</var>) axis order, because it is easier to implement.
+      Oldest <abbr>OGC</abbr> standards used the (<var>x</var>, <var>y</var>) axis order instead, ignoring any authority specification.
+      Many softwares still use the old (<var>x</var>, <var>y</var>) axis order,
+      maybe because such uniformization makes <abbr>CRS</abbr> implementation and usage <em>apparently</em> easier.
       Apache <abbr>SIS</abbr> supports both conventions with the following approach:
       by default, <abbr>SIS</abbr> creates <abbr>CRS</abbr> with axis order <em>as defined by the authority</em>.
       Those <abbr>CRS</abbr> are created by calls to the <code>CRS.forCode(String)</code> method
       and the actual axis order can be verified after the <abbr>CRS</abbr> creation with <code>System.out.println(crs)</code>.
-      But if (<var>x</var>,<var>y</var>) axis order is wanted for compatibility with older <abbr>OGC</abbr> specifications or other softwares,
-      then <abbr>CRS</abbr> forced to <cite>longitude first</cite> axis order can be created by call to the following method:
+      But if (<var>x</var>, <var>y</var>) axis order is wanted for compatibility with older <abbr>OGC</abbr> specifications or other softwares,
+      then <abbr>CRS</abbr> forced to <cite>longitude first</cite> axis order can be created by a call to the following method:
     </p>
-    <blockquote><pre>CoordinateReferenceSystem crs = …;               // CRS obtained by any means.
-crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</pre></blockquote>
+    <pre>CoordinateReferenceSystem crs = …;               // CRS obtained by any means.
+crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</pre>
     <p>
       Among the legacy <abbr>OGC</abbr> standards that used the non-conform axis order,
       an influent one is version 1 of the <cite>Well Known Text</cite> (<abbr>WKT</abbr>) format specification.
-      According that widely-used format, <abbr>WKT</abbr> definitions without explicit <code>AXIS[…]</code> elements
-      shall default to (<var>longitude</var>, <var>latitude</var>) or (<var>x</var>,<var>y</var>) axis order.
+      According that widely-used format, <abbr>WKT</abbr> 1 definitions without explicit <code>AXIS[…]</code> elements
+      shall default to (<var>longitude</var>, <var>latitude</var>) or (<var>x</var>, <var>y</var>) axis order.
       In version 2 of <abbr>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.
+      But if <code>AXIS[…]</code> elements are nevertheless missing in a <abbr>WKT</abbr> 2 definition,
+      Apache <abbr>SIS</abbr> defaults to (<var>latitude</var>, <var>longitude</var>) order.
+      So in summary:
+    </p>
+    <ul>
+      <li>Default <abbr>WKT</abbr> 1 axis order of geographic <abbr>CRS</abbr> is (<var>longitude</var>, <var>latitude</var>) as mandated by <abbr>OGC</abbr> 01-009 specification.</li>
+      <li>Default <abbr>WKT</abbr> 2 axis order of geographic <abbr>CRS</abbr> is (<var>latitude</var>, <var>longitude</var>),
+          but this is <abbr>SIS</abbr>-specific as <abbr>ISO</abbr> 19162 does not mention default axis order.</li>
+    </ul>
+    <p>
+      To avoid ambiguities, users are encouraged to always provide explicit <code>AXIS[…]</code> elements in their <abbr>WKT</abbr>.
+      The <abbr>WKT</abbr> format will be presented in more details in the next sections.
     </p>
 
     <h3 id="GeographicCRS">Geographic reference systems</h3>
@@ -306,10 +319,92 @@ crs = AbstractCRS.castOrCopy(crs).forCon
 
 
     <h2 id="CoordinateOperation">Coordinate operations</h2>
-    <p style="color: red">TODO</p>
+    <p>
+      Given a <em>source</em> coordinate reference system (<abbr>CRS</abbr>) in which existing coordinate values are expressed,
+      and a <em>target</em> coordinate reference system in which coordinate values are desired,
+      Apache <abbr>SIS</abbr> can provide a <em>coordinate operation</em> performing the conversion or transformation work.
+      The search for coordinate operations may use a third argument, optional but recommended,
+      which is the geographic area of the data to transform.
+      That later argument is recommended because coordinate operations are often valid only in a some geographic area
+      (typically a particular country or state), and many transformations may exist
+      for the same pair of source and target <abbr>CRS</abbr> but different domain of validity.
+      Different coordinate operations may also be different compromises between accuracy and their domain of validity,
+      and specifying a smaller area of interest may allow Apache <abbr>SIS</abbr> to select a more accurate operation.
+    </p>
+    <div class="example"><p><b>Example:</b>
+      the <abbr>EPSG</abbr> geodetic dataset (as of version 7.9) defines 77 coordinate operations from the
+      <cite>North American Datum 1927</cite> (EPSG:4267) coordinate reference system to the
+      <cite>World Geodetic System 1984</cite> (EPSG:4326) <abbr>CRS</abbr>.
+      There is one operation valid only for coordinate transformations in Québec,
+      another operation valid for coordinate transformations in Texas west of 100°W,
+      another operation for the same state but east of 100°W, <i>etc</i>.
+      If the user did not specified any geographic area of interest,
+      then Apache <abbr>SIS</abbr> defaults on the coordinate operation which is valid in the largest area.
+      In this example, the “largest area” criterion results in the selection of a coordinate operation valid for Canada,
+      not <abbr>USA</abbr>.</p>
+    </div>
+    <p>
+      The easiest way to obtain a coordinate operation from above-cited information
+      is to use the <code>org.apache.sis.referencing.CRS</code> convenience class:
+    </p>
+    <pre>CoordinateOperation cop = CRS.findOperation(sourceCRS, targetCRS, areaOfInterest);</pre>
+    <p>
+      Among the information provided by <code>CoordinateOperation</code> object, the following are of special interest:
+    </p>
+    <ul>
+      <li>The <cite>domain of validity</cite>, either as a textual description (e.g. “Canada – onshore and offshore”)
+          or with the coordinates of a geographic bounding box.</li>
+      <li>The <cite>positional accuracy</cite>, which may be anything from 1 centimetre to a few kilometres.</li>
+      <li>The coordinate operation subtype. If the coordinate operation is an instance of <code>Transformation</code>,
+          then it may be one among many possibilities depending on the area of interest, and its accuracy is limited by
+          “real world” constraints (not only rounding errors).
+          If the coordinate operation is rather an instance of <code>Conversion</code>, then it does not have those limitations.</li>
+    </ul>
+    <p>
+      The actual mathematical work is performed by an object obtained by a call to <code>cop.getMathTransform()</code>.
+      The <code>CoordinateOperation</code> and <code>MathTransform</code> types are separated because the later is a kind of “black box”,
+      which may be implemented in a very different way than what the coordinate operation said.
+      In particular many conceptually different coordinate operations (e.g. longitude rotations,
+      change of units of measurement, conversions between two Mercator projections on the same datum, <i>etc.</i>)
+      are implemented by <code>MathTransform</code> as <a href="#AffineTransform">affine transforms</a> and concatenated for efficiency.
+    </p>
 
     <h3 id="MathTransform">Executing an operation on coordinate values</h3>
-    <p style="color: red">TODO</p>
+    <p>
+      The following Java code performs a map projection from geographic coordinates on the <cite>World Geodetic System 1984</cite> (<abbr>WGS84</abbr>) datum
+      coordinates in the <cite>WGS 84 / UTM zone 33N</cite> coordinate reference system.
+      In order to make the example a little bit simpler, this code uses predefined constants given by the <code>CommonCRS</code> convenience class.
+      But more advanced applications will typically use <abbr>EPSG</abbr> codes instead.
+      Note that all geographic coordinates below express latitude before longitude.
+    </p>
+
+<pre>import org.opengis.geometry.DirectPosition;
+import org.opengis.referencing.crs.CoordinateReferenceSystem;
+import org.opengis.referencing.operation.CoordinateOperation;
+import org.opengis.referencing.operation.TransformException;
+import org.opengis.util.FactoryException;
+import org.apache.sis.referencing.CRS;
+import org.apache.sis.referencing.CommonCRS;
+import org.apache.sis.geometry.DirectPosition2D;
+
+public class MyApp {
+    public static void main(String[] args) throws FactoryException, TransformException {
+        CoordinateReferenceSystem sourceCRS = CommonCRS.WGS84.geographic();
+        CoordinateReferenceSystem targetCRS = CommonCRS.WGS84.UTM(40, 14);  // Get whatever zone is valid for 14°E.
+        CoordinateOperation operation = CRS.findOperation(sourceCRS, targetCRS, null);
+
+        // The above lines are costly and should be performed only once before to project many points.
+        // In this example, the operation that we got is valid for coordinates in geographic area from
+        // 12°E to 18°E (UTM zone 33) and 0°N to 84°N.
+
+        DirectPosition ptSrc = new DirectPosition2D(40, 14);           // 40°N 14°E
+        DirectPosition ptDst = operation.getMathTransform().transform(ptSrc, null);
+
+        System.out.println("Source: " + ptSrc);
+        System.out.println("Target: " + ptDst);
+    }
+}</pre>
+
 
     <h4 id="AffineTransform">Affine transform</h4>
     <p>
@@ -430,7 +525,7 @@ if (mt instanceof AffineTransform) {
     // Use Java2D API from here.
 }</pre>
     <p>
-      However <abbr>SIS</abbr> uses Java2D on a <em>best effort</em> basis only.
+      Apache <abbr>SIS</abbr> uses Java2D on a <em>best effort</em> basis only.
       The above cast is not guaranteed to succeed,
       even when the <code>MathTransform</code> meets the requirements allowing Java2D usage.
     </p>

Modified: sis/site/trunk/book/fr/referencing.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/referencing.html?rev=1753783&r1=1753782&r2=1753783&view=diff
==============================================================================
--- sis/site/trunk/book/fr/referencing.html (original)
+++ sis/site/trunk/book/fr/referencing.html Fri Jul 22 12:47:43 2016
@@ -231,6 +231,53 @@
     <h3 id="CoordinateSystem">Systèmes de coordonnées</h3>
     <p style="color: red">TODO</p>
 
+    <h4 id="AxisOrder">Ordre des axes</h4>
+    <p>
+      L’ordre des axes est spécifié par l’autorité (typiquement une agence nationale) qui définit le
+      <cite>système de référence des coordonnées</cite> (<abbr>CRS</abbr>).
+      L’ordre dépend du type de <abbr>CRS</abbr> ainsi que du pays qui l’a définit.
+      Dans le cas des <abbr>CRS</abbr> de type géographique,
+      l’ordre (<var>latitude</var>, <var>longitude</var>) est utilisé par les géographes et les pilotes depuis des siècles.
+      Toutefois des développeurs de logiciels tendent à préférer l’ordre (<var>x</var>, <var>y</var>) pour tous systèmes de coordonnées.
+      Ces différentes pratiques entraînent des définitions contradictoires de l’ordre des axes pour pratiquement tous les <abbr>CRS</abbr>
+      de type <code>GeographicCRS</code>, pour certains <code>ProjectedCRS</code> dans l’hémisphère sud (Afrique du Sud, Australie, <i>etc.</i>)
+      et pour certaines projections polaires entre autres.
+    </p><p>
+      Les standards <abbr>OGC</abbr> récents demandent d’ordonner les axes tel que spécifié par l’autorité qui a définit le <abbr>CRS</abbr>.
+      Mais des standards <abbr>OGC</abbr> plus anciens utilisaient l’ordre (<var>x</var>, <var>y</var>) inconditionnellement,
+      en ignorant les spécifications des autorités sur ce point.
+      Beaucoup de logiciels continue d’utiliser cet ordre (<var>x</var>, <var>y</var>),
+      peut-être parce qu’une telle uniformisation rend l’implémentation et l’utilisation des <abbr>CRS</abbr> <em>en apparence</em> plus simple.
+      Apache <abbr>SIS</abbr> supporte les deux conventions avec l’approche suivante:
+      par défaut, <abbr>SIS</abbr> construit les <abbr>CRS</abbr> avec les axes <em>dans l’ordre définit par l’autorité</em>.
+      Ces <abbr>CRS</abbr> sont construits par des appels à la méthode <code>CRS.forCode(String)</code>,
+      et l’ordre des axes effectif peut être vérifié après la création du <abbr>CRS</abbr> par un appel à <code>System.out.println(crs)</code>.
+      Mais si l’ordre (<var>x</var>, <var>y</var>) est désiré pour des raisons de compatibilité avec d’anciens standards <abbr>OGC</abbr> ou avec d’autres logiciels,
+      alors les <abbr>CRS</abbr> peuvent être modifiés de manière à avoir la longitude en premier avec un appel à la méthode suivante:
+    </p>
+    <pre>CoordinateReferenceSystem crs = …;    // CRS obtenu de n’importe quel façon.
+crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</pre>
+    <p>
+      Parmi les anciens standards de l’<abbr>OGC</abbr> qui utilisaient un ordre des axes non-conforme,
+      un standard influent était la version 1 du format <cite>Well Known Text</cite> (<abbr>WKT</abbr>).
+      D’après ce format largement utilisé, les définitions <abbr>WKT</abbr> 1 sans éléments <code>AXIS[…]</code> explicites
+      doivent être interprétés comme ayant ses axes dans l’ordre (<var>longitude</var>, <var>latitude</var>) ou (<var>x</var>, <var>y</var>).
+      Dans la version 2 du format <abbr>WKT</abbr>, les éléments <code>AXIS[…]</code> ne sont plus optionnel
+      et devrait contenir explicitement un sous-élément <code>ORDER[…]</code> pour rendre l’ordre voulu encore plus évident.
+      Mais si les éléments <code>AXIS[…]</code> sont malgré tout omis dans une définition <abbr>WKT</abbr> 2,
+      alors Apache <abbr>SIS</abbr> utilise l’ordre (<var>latitude</var>, <var>longitude</var>) par défaut.
+      Pour résumer:
+    </p>
+    <ul>
+      <li>L’ordre par défaut d’un <abbr>CRS</abbr> géographique en <abbr>WKT</abbr> 1 est (<var>longitude</var>, <var>latitude</var>) tel que spécifié par le standard <abbr>OGC</abbr> 01-009.</li>
+      <li>L’ordre par défaut d’un <abbr>CRS</abbr> géographique en <abbr>WKT</abbr> 2 est (<var>latitude</var>, <var>longitude</var>), mais c’est une interprétation spécifique de <abbr>SIS</abbr>
+        vu que la norme <abbr>ISO</abbr> 19162 ne mentionne pas de comportement par défaut.</li>
+    </ul>
+    <p>
+      Pour éviter des ambiguïtés, les utilisateurs sont encouragés à toujours fournir explicitement les éléments <code>AXIS[…]</code> dans leurs <abbr>WKT</abbr>.
+      Le format <abbr>WKT</abbr> sera présenté plus en détails dans les sections suivantes.
+    </p>
+
     <h3 id="GeographicCRS">Systèmes géographiques</h3>
     <p style="color: red">TODO</p>
 
@@ -276,10 +323,92 @@
 
 
     <h2 id="CoordinateOperation">Opérations sur les coordonnées</h2>
-    <p style="color: red">TODO</p>
+    <p>
+      Étant donné un système de référence des coordonnées (<abbr>CRS</abbr>) <em>source</em> selon lequel sont exprimés des coordonnées existantes
+      et un système de référence des coordonnées <em>destination</em> selon lequel les coordonnées sont désirées,
+      Apache <abbr>SIS</abbr> peut fournir une <em>opération sur les coordonnées</em> qui effectuera le travail de conversion ou de transformation.
+      La recherche d’une opération peut utiliser un troisième argument, optionnel mais recommandé: la région géographique des données à transformer.
+      Ce dernier argument est recommandé parce que les opérations sur les coordonnées sont souvent valides seulement dans une région géographique
+      (typiquement un pays ou une province particulière), et plusieurs transformations peuvent exister pour la même paire de <abbr>CRS</abbr>
+      source et destination mais avec des domaines de validité différents.
+      Il peut aussi y avoir des différentes transformations qui sont différents compromis entre la précision et le domaine de validité,
+      de sorte que spécifier à Apache <abbr>SIS</abbr> qu’on s’intéresse à une région plus petite
+      peut lui permettre de sélectionner une opération plus précise.
+    </p>
+    <div class="example"><p><b>Exemple:</b>
+      la base de données géodésiques <abbr>EPSG</abbr> (dans sa version 7.9) définit 77 opérations sur les coordonnées
+      allant du système géographique <cite>North American Datum 1927</cite> (EPSG:4267)
+      vers le système <cite>World Geodetic System 1984</cite> (EPSG:4326).
+      Il y a une opération valide seulement pour la transformation de coordonnées au Québec,
+      une autre opération valide pour la transformation de coordonnées au Texas mais à l’ouest de 100°W,
+      une autre opération pour le même état mais à l’est de 100°W, <i>etc</i>.
+      Si l’utilisateur ne spécifie pas la région géographique qui l’intéresse,
+      alors le comportement par défaut de Apache <abbr>SIS</abbr> est de sélectionner l’opération valide dans la plus grande région géographique.
+      Dans cet exemple, ce critère entraîne la sélection d’une opération valide pour le Canada, mais qui n’est pas valide pour les États-Unis.</p>
+    </div>
+    <p>
+      La façon la plus facile d’obtenir une opération sur les coordonnées à partir des informations présentées ci-dessus
+      est d’utiliser la classe de commodité <code>org.apache.sis.referencing.CRS</code>:
+    </p>
+    <pre>CoordinateOperation cop = CRS.findOperation(sourceCRS, targetCRS, areaOfInterest);</pre>
+    <p>
+      Parmi les information fournies par l’objet <code>CoordinateOperation</code> obtenu, on note en particulier:
+    </p>
+    <ul>
+      <li>Le <cite>domaine de validité</cite>, soit comme une description textuelle telle que « Canada – onshore and offshore »
+          ou comme les coordonnées géographiques d’une boîte englobante.</li>
+      <li>La <cite>précision</cite>, qui peut être n’importe quoi entre 1 centimètre et quelques kilomètres.</li>
+      <li>Le sous-type de l’opération sur les coordonées. Si l’opération est une instance de <code>Transformation</code>,
+          alors l’opération sélectionnée peut n’être qu’une possibilité parmi plusieurs, selon la région d’intérêt,
+          et sa précision peut être limitée à cause de contrainte du « monde réel » (pas seulement les erreurs d’arrondissements).
+          Si l’opération est plutôt une instance de <code>Conversion</code>, alors elle n’a pas ses limitations.</li>
+    </ul>
+    <p>
+      Le travail mathématique réel est effectué par un objet obtenu par un appel à <code>cop.getMathTransform()</code>.
+      Les types <code>CoordinateOperation</code> et <code>MathTransform</code> sont séparés parce que ce dernier est une sorte de boîte noire,
+      qui peut être implémentée d’une manière très différente à ce que l’objet <code>CoordinateOperation</code> dit.
+      En particulier plusieurs opérations conceptuellement différentes (par exemple rotations de la longitude,
+      changements d’unités de mesure, conversions entre deux projections de Mercator qui utilisent le même référentiel, <i>etc.</i>)
+      sont implémentées par <code>MathTransform</code> comme des <a href="#AffineTransform">transformations affines</a>
+      et concaténées pour des raisons d’efficacité.
+    </p>
 
     <h3 id="MathTransform">Exécution de opérations</h3>
-    <p style="color: red">TODO</p>
+    <p>
+      Le code Java suivant effectue une projection cartographique à partir de coordonnées géographiques selon le référentiel
+      <cite>World Geodetic System 1984</cite> (<abbr>WGS84</abbr>) vers des coordonnées selon le système <cite>WGS 84 / UTM zone 33N</cite>.
+      Afin de rendre l’exemple un peu plus simple, ce code utilise des constantes pré-définies dans la classe de commodité <code>CommonCRS</code>.
+      Mais des applications plus avancées voudront souvent utiliser des codes <abbr>EPSG</abbr> plutôt.
+      Notes que toutes les coordonnées géographiques dans ce code ont la latitude avant la longitude.
+    </p>
+
+<pre>import org.opengis.geometry.DirectPosition;
+import org.opengis.referencing.crs.CoordinateReferenceSystem;
+import org.opengis.referencing.operation.CoordinateOperation;
+import org.opengis.referencing.operation.TransformException;
+import org.opengis.util.FactoryException;
+import org.apache.sis.referencing.CRS;
+import org.apache.sis.referencing.CommonCRS;
+import org.apache.sis.geometry.DirectPosition2D;
+
+public class MyApp {
+    public static void main(String[] args) throws FactoryException, TransformException {
+        CoordinateReferenceSystem sourceCRS = CommonCRS.WGS84.geographic();
+        CoordinateReferenceSystem targetCRS = CommonCRS.WGS84.UTM(40, 14);  // Obtient la zone valide pour 14°E.
+        CoordinateOperation operation = CRS.findOperation(sourceCRS, targetCRS, null);
+
+        // Les lignes précédentes sont coûteuses et ne devraient être exécutées qu’une seule fois avant
+        // de transformer plusieurs points.  Dans cet exemple, l’opération que nous obtenons est valide
+        // pour des coordonnées dans la région géographique allant de 12°E à 18°E (zone 33) et 0°N à 84°N.
+
+        DirectPosition ptSrc = new DirectPosition2D(40, 14);           // 40°N 14°E
+        DirectPosition ptDst = operation.getMathTransform().transform(ptSrc, null);
+
+        System.out.println("Source: " + ptSrc);
+        System.out.println("Target: " + ptDst);
+    }
+}</pre>
+
 
     <h4 id="AffineTransform">Les transformations affines</h4>
     <p>

Modified: sis/site/trunk/content/book/en/developer-guide.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/en/developer-guide.html?rev=1753783&r1=1753782&r2=1753783&view=diff
==============================================================================
--- sis/site/trunk/content/book/en/developer-guide.html (original)
+++ sis/site/trunk/content/book/en/developer-guide.html Fri Jul 22 12:47:43 2016
@@ -46,7 +46,8 @@ Partially translated by <i>Christina Hou
 <li><a href="#CRS_Components">Components of a reference system by coordinates</a><ul>
 <li><a href="#Ellipsoid">Geoid et ellipsoid</a></li>
 <li><a href="#GeodeticDatum">Geodetic datum</a></li>
-<li><a href="#CoordinateSystem">Coordinate systems</a></li>
+<li><a href="#CoordinateSystem">Coordinate systems</a><ul>
+<li><a href="#AxisOrder">Axis order</a></li></ul></li>
 <li><a href="#GeographicCRS">Geographic reference systems</a><ul>
 <li><a href="#GeographicWKT">Well-Known Text format</a></li></ul></li>
 <li><a href="#ProjectedCRS">Map projections</a><ul>
@@ -1366,7 +1367,8 @@ or the use of <code>isWhitespace(…)
 <li><a href="#CRS_Components">Components of a reference system by coordinates</a><ul>
 <li><a href="#Ellipsoid">Geoid et ellipsoid</a></li>
 <li><a href="#GeodeticDatum">Geodetic datum</a></li>
-<li><a href="#CoordinateSystem">Coordinate systems</a></li>
+<li><a href="#CoordinateSystem">Coordinate systems</a><ul>
+<li><a href="#AxisOrder">Axis order</a></li></ul></li>
 <li><a href="#GeographicCRS">Geographic reference systems</a><ul>
 <li><a href="#GeographicWKT">Well-Known Text format</a></li></ul></li>
 <li><a href="#ProjectedCRS">Map projections</a><ul>
@@ -1587,6 +1589,49 @@ The later is used only if <abbr>SIS</abb
 <h3 id="CoordinateSystem"><span class="section-number">3.1.3.</span> Coordinate systems</h3>
 <p style="color: red">TODO</p>
 
+<h4 id="AxisOrder"><span class="section-number">3.1.3.1.</span> Axis order</h4>
+<p>
+The axis order is specified by the authority (typically a national agency) defining the <cite>Coordinate Reference System</cite> (<abbr title="Coordinate Reference System">CRS</abbr>).
+The order depends on the <abbr>CRS</abbr> type and the country defining the <abbr>CRS</abbr>.
+In the case of geographic <abbr>CRS</abbr>, the (<var>latitude</var>, <var>longitude</var>) axis order is widely used by geographers and pilots for centuries.
+However software developers tend to consistently use the (<var>x</var>, <var>y</var>) order for every kind of <abbr>CRS</abbr>.
+Those different practices resulted in contradictory definitions of axis order for almost every <abbr>CRS</abbr> of kind <code class="GeoAPI">GeographicCRS</code>,
+for some <code class="GeoAPI">ProjectedCRS</code> in the South hemisphere (South Africa, Australia, <i>etc.</i>) 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>OGC</abbr> standards used the (<var>x</var>, <var>y</var>) axis order instead, ignoring any authority specification.
+Many softwares still use the old (<var>x</var>, <var>y</var>) axis order,
+maybe because such uniformization makes <abbr>CRS</abbr> implementation and usage <em>apparently</em> easier.
+Apache <abbr title="Spatial Information System">SIS</abbr> supports both conventions with the following approach:
+by default, <abbr>SIS</abbr> creates <abbr>CRS</abbr> with axis order <em>as defined by the authority</em>.
+Those <abbr>CRS</abbr> are created by calls to the <code>CRS.forCode(String)</code> method
+and the actual axis order can be verified after the <abbr>CRS</abbr> creation with <code>System.out​.println(crs)</code>.
+But if (<var>x</var>, <var>y</var>) axis order is wanted for compatibility with older <abbr>OGC</abbr> specifications or other softwares,
+then <abbr>CRS</abbr> forced to <cite>longitude first</cite> axis order can be created by a call to the following method:
+</p>
+<pre><code class="GeoAPI">CoordinateReferenceSystem</code> crs = …;               <code class="comment">// CRS obtained by any means.
+</code>crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</pre>
+<p>
+Among the legacy <abbr>OGC</abbr> standards that used the non-conform axis order,
+an influent one is version 1 of the <cite>Well Known Text</cite> (<abbr>WKT</abbr>) format specification.
+According that widely-used format, <abbr>WKT</abbr> 1 definitions without explicit <code>AXIS[…]</code> elements
+shall default to (<var>longitude</var>, <var>latitude</var>) or (<var>x</var>, <var>y</var>) axis order.
+In version 2 of <abbr>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.
+But if <code>AXIS[…]</code> elements are nevertheless missing in a <abbr>WKT</abbr> 2 definition,
+Apache <abbr>SIS</abbr> defaults to (<var>latitude</var>, <var>longitude</var>) order.
+So in summary:
+</p>
+<ul>
+<li>Default <abbr>WKT</abbr> 1 axis order of geographic <abbr>CRS</abbr> is (<var>longitude</var>, <var>latitude</var>) as mandated by <abbr>OGC</abbr> 01-009 specification.</li>
+<li>Default <abbr>WKT</abbr> 2 axis order of geographic <abbr>CRS</abbr> is (<var>latitude</var>, <var>longitude</var>),
+but this is <abbr>SIS</abbr>-specific as <abbr title="International Organization for Standardization">ISO</abbr> 19162 does not mention default axis order.</li>
+</ul>
+<p>
+To avoid ambiguities, users are encouraged to always provide explicit <code>AXIS[…]</code> elements in their <abbr>WKT</abbr>.
+The <abbr>WKT</abbr> format will be presented in more details in the next sections.
+</p>
+
 <h3 id="GeographicCRS"><span class="section-number">3.1.4.</span> Geographic reference systems</h3>
 <p style="color: red">TODO</p>
 
@@ -1632,10 +1677,92 @@ while countries elongated along the Nort
 
 
 <h2 id="CoordinateOperation"><span class="section-number">3.3.</span> Coordinate operations</h2>
-<p style="color: red">TODO</p>
+<p>
+Given a <em>source</em> coordinate reference system (<abbr title="Coordinate Reference System">CRS</abbr>) in which existing coordinate values are expressed,
+and a <em>target</em> coordinate reference system in which coordinate values are desired,
+Apache <abbr title="Spatial Information System">SIS</abbr> can provide a <em>coordinate operation</em> performing the conversion or transformation work.
+The search for coordinate operations may use a third argument, optional but recommended,
+which is the geographic area of the data to transform.
+That later argument is recommended because coordinate operations are often valid only in a some geographic area
+(typically a particular country or state), and many transformations may exist
+for the same pair of source and target <abbr>CRS</abbr> but different domain of validity.
+Different coordinate operations may also be different compromises between accuracy and their domain of validity,
+and specifying a smaller area of interest may allow Apache <abbr>SIS</abbr> to select a more accurate operation.
+</p>
+<div class="example"><p><b>Example:</b>
+the <abbr>EPSG</abbr> geodetic dataset (as of version 7.9) defines 77 coordinate operations from the
+<cite>North American Datum 1927</cite> (EPSG:4267) coordinate reference system to the
+<cite>World Geodetic System 1984</cite> (EPSG:4326) <abbr>CRS</abbr>.
+There is one operation valid only for coordinate transformations in Québec,
+another operation valid for coordinate transformations in Texas west of 100°W,
+another operation for the same state but east of 100°W, <i>etc</i>.
+If the user did not specified any geographic area of interest,
+then Apache <abbr>SIS</abbr> defaults on the coordinate operation which is valid in the largest area.
+In this example, the “largest area” criterion results in the selection of a coordinate operation valid for Canada,
+not <abbr>USA</abbr>.</p>
+</div>
+<p>
+The easiest way to obtain a coordinate operation from above-cited information
+is to use the <code class="SIS">org.apache.sis.referencing.CRS</code> convenience class:
+</p>
+<pre><code class="GeoAPI">CoordinateOperation</code> cop = CRS.findOperation(sourceCRS, targetCRS, areaOfInterest);</pre>
+<p>
+Among the information provided by <code class="GeoAPI">CoordinateOperation</code> object, the following are of special interest:
+</p>
+<ul>
+<li>The <cite>domain of validity</cite>, either as a textual description (e.g. “Canada – onshore and offshore”)
+or with the coordinates of a geographic bounding box.</li>
+<li>The <cite>positional accuracy</cite>, which may be anything from 1 centimetre to a few kilometres.</li>
+<li>The coordinate operation subtype. If the coordinate operation is an instance of <code class="GeoAPI">Transformation</code>,
+then it may be one among many possibilities depending on the area of interest, and its accuracy is limited by
+“real world” constraints (not only rounding errors).
+If the coordinate operation is rather an instance of <code class="GeoAPI">Conversion</code>, then it does not have those limitations.</li>
+</ul>
+<p>
+The actual mathematical work is performed by an object obtained by a call to <code>cop.getMathTransform()</code>.
+The <code class="GeoAPI">CoordinateOperation</code> and <code class="GeoAPI">MathTransform</code> types are separated because the later is a kind of “black box”,
+which may be implemented in a very different way than what the coordinate operation said.
+In particular many conceptually different coordinate operations (e.g. longitude rotations,
+change of units of measurement, conversions between two Mercator projections on the same datum, <i>etc.</i>)
+are implemented by <code class="GeoAPI">MathTransform</code> as <a href="#AffineTransform">affine transforms</a> and concatenated for efficiency.
+</p>
 
 <h3 id="MathTransform"><span class="section-number">3.3.1.</span> Executing an operation on coordinate values</h3>
-<p style="color: red">TODO</p>
+<p>
+The following Java code performs a map projection from geographic coordinates on the <cite>World Geodetic System 1984</cite> (<abbr title="World Geodetic System 1984">WGS84</abbr>) datum
+coordinates in the <cite>WGS 84 / UTM zone 33N</cite> coordinate reference system.
+In order to make the example a little bit simpler, this code uses predefined constants given by the <code>CommonCRS</code> convenience class.
+But more advanced applications will typically use <abbr>EPSG</abbr> codes instead.
+Note that all geographic coordinates below express latitude before longitude.
+</p>
+
+<pre><b>import</b> org.opengis.geometry.<code class="GeoAPI">DirectPosition</code>;
+<b>import</b> org.opengis.referencing.crs.<code class="GeoAPI">CoordinateReferenceSystem</code>;
+<b>import</b> org.opengis.referencing.operation.<code class="GeoAPI">CoordinateOperation</code>;
+<b>import</b> org.opengis.referencing.operation.<code class="GeoAPI">TransformException</code>;
+<b>import</b> org.opengis.util.<code class="GeoAPI">FactoryException</code>;
+<b>import</b> org.apache.sis.referencing.CRS;
+<b>import</b> org.apache.sis.referencing.CommonCRS;
+<b>import</b> org.apache.sis.geometry.DirectPosition2D;
+
+<b>public</b> <b>class</b> MyApp {
+    <b>public</b> <b>static</b> <b>void</b> main(String[] args) <b>throws</b> <code class="GeoAPI">FactoryException</code>, <code class="GeoAPI">TransformException</code> {
+        <code class="GeoAPI">CoordinateReferenceSystem</code> sourceCRS = CommonCRS.WGS84.geographic();
+        <code class="GeoAPI">CoordinateReferenceSystem</code> targetCRS = CommonCRS.WGS84.UTM(40, 14);  <code class="comment">// Get whatever zone is valid for 14°E.
+</code>        <code class="GeoAPI">CoordinateOperation</code> operation = CRS.findOperation(sourceCRS, targetCRS, <b>null</b>);
+
+        <code class="comment">// The above lines are costly and should be performed only once before to project many points.
+</code>        <code class="comment">// In this example, the operation that we got is valid for coordinates in geographic area from
+</code>        <code class="comment">// 12°E to 18°E (UTM zone 33) and 0°N to 84°N.
+</code>
+        <code class="GeoAPI">DirectPosition</code> ptSrc = <b>new</b> DirectPosition2D(40, 14);           <code class="comment">// 40°N 14°E
+</code>        <code class="GeoAPI">DirectPosition</code> ptDst = operation.getMathTransform().transform(ptSrc, <b>null</b>);
+
+        System.out.println(<i>"Source: "</i> + ptSrc);
+        System.out.println(<i>"Target: "</i> + ptDst);
+    }
+}</pre>
+
 
 <h4 id="AffineTransform"><span class="section-number">3.3.1.1.</span> Affine transform</h4>
 <p>
@@ -1959,7 +2086,7 @@ in particular Java2D. The following Java
     <code class="comment">// Use Java2D API from here.
 </code>}</pre>
 <p>
-However <abbr>SIS</abbr> uses Java2D on a <em>best effort</em> basis only.
+Apache <abbr>SIS</abbr> uses Java2D on a <em>best effort</em> basis only.
 The above cast is not guaranteed to succeed,
 even when the <code class="GeoAPI">MathTransform</code> meets the requirements allowing Java2D usage.
 </p>

Modified: sis/site/trunk/content/book/fr/developer-guide.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/fr/developer-guide.html?rev=1753783&r1=1753782&r2=1753783&view=diff
==============================================================================
--- sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] (original)
+++ sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] Fri Jul 22 12:47:43 2016
@@ -46,7 +46,8 @@
 <li><a href="#CRS_Components">Composantes d’un système de références par coordonnées</a><ul>
 <li><a href="#Ellipsoid">Géoïde et ellipsoïde</a></li>
 <li><a href="#GeodeticDatum">Référentiel géodésique</a></li>
-<li><a href="#CoordinateSystem">Systèmes de coordonnées</a></li>
+<li><a href="#CoordinateSystem">Systèmes de coordonnées</a><ul>
+<li><a href="#AxisOrder">Ordre des axes</a></li></ul></li>
 <li><a href="#GeographicCRS">Systèmes géographiques</a><ul>
 <li><a href="#GeographicWKT">Format Well-Known Text</a></li></ul></li>
 <li><a href="#ProjectedCRS">Projections cartographiques</a><ul>
@@ -1420,7 +1421,8 @@ de la bibliothèque <abbr>SIS</abbr>.
 <li><a href="#CRS_Components">Composantes d’un système de références par coordonnées</a><ul>
 <li><a href="#Ellipsoid">Géoïde et ellipsoïde</a></li>
 <li><a href="#GeodeticDatum">Référentiel géodésique</a></li>
-<li><a href="#CoordinateSystem">Systèmes de coordonnées</a></li>
+<li><a href="#CoordinateSystem">Systèmes de coordonnées</a><ul>
+<li><a href="#AxisOrder">Ordre des axes</a></li></ul></li>
 <li><a href="#GeographicCRS">Systèmes géographiques</a><ul>
 <li><a href="#GeographicWKT">Format Well-Known Text</a></li></ul></li>
 <li><a href="#ProjectedCRS">Projections cartographiques</a><ul>
@@ -1641,6 +1643,53 @@ s’il ne peut pas appliquer l’approch
 <h3 id="CoordinateSystem"><span class="section-number">3.1.3.</span> Systèmes de coordonnées</h3>
 <p style="color: red">TODO</p>
 
+<h4 id="AxisOrder"><span class="section-number">3.1.3.1.</span> Ordre des axes</h4>
+<p>
+L’ordre des axes est spécifié par l’autorité (typiquement une agence nationale) qui définit le
+<cite>système de référence des coordonnées</cite> (<abbr title="Coordinate Reference System">CRS</abbr>).
+L’ordre dépend du type de <abbr>CRS</abbr> ainsi que du pays qui l’a définit.
+Dans le cas des <abbr>CRS</abbr> de type géographique,
+l’ordre (<var>latitude</var>, <var>longitude</var>) est utilisé par les géographes et les pilotes depuis des siècles.
+Toutefois des développeurs de logiciels tendent à préférer l’ordre (<var>x</var>, <var>y</var>) pour tous systèmes de coordonnées.
+Ces différentes pratiques entraînent des définitions contradictoires de l’ordre des axes pour pratiquement tous les <abbr>CRS</abbr>
+de type <code class="GeoAPI">GeographicCRS</code>, pour certains <code class="GeoAPI">ProjectedCRS</code> dans l’hémisphère sud (Afrique du Sud, Australie, <i>etc.</i>)
+et pour certaines projections polaires entre autres.
+</p><p>
+Les standards <abbr title="Open Geospatial Consortium">OGC</abbr> récents demandent d’ordonner les axes tel que spécifié par l’autorité qui a définit le <abbr>CRS</abbr>.
+Mais des standards <abbr>OGC</abbr> plus anciens utilisaient l’ordre (<var>x</var>, <var>y</var>) inconditionnellement,
+en ignorant les spécifications des autorités sur ce point.
+Beaucoup de logiciels continue d’utiliser cet ordre (<var>x</var>, <var>y</var>),
+peut-être parce qu’une telle uniformisation rend l’implémentation et l’utilisation des <abbr>CRS</abbr> <em>en apparence</em> plus simple.
+Apache <abbr title="Spatial Information System">SIS</abbr> supporte les deux conventions avec l’approche suivante:
+par défaut, <abbr>SIS</abbr> construit les <abbr>CRS</abbr> avec les axes <em>dans l’ordre définit par l’autorité</em>.
+Ces <abbr>CRS</abbr> sont construits par des appels à la méthode <code>CRS.forCode(String)</code>,
+et l’ordre des axes effectif peut être vérifié après la création du <abbr>CRS</abbr> par un appel à <code>System.out​.println(crs)</code>.
+Mais si l’ordre (<var>x</var>, <var>y</var>) est désiré pour des raisons de compatibilité avec d’anciens standards <abbr>OGC</abbr> ou avec d’autres logiciels,
+alors les <abbr>CRS</abbr> peuvent être modifiés de manière à avoir la longitude en premier avec un appel à la méthode suivante:
+</p>
+<pre><code class="GeoAPI">CoordinateReferenceSystem</code> crs = …;    <code class="comment">// CRS obtenu de n’importe quel façon.
+</code>crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</pre>
+<p>
+Parmi les anciens standards de l’<abbr>OGC</abbr> qui utilisaient un ordre des axes non-conforme,
+un standard influent était la version 1 du format <cite>Well Known Text</cite> (<abbr>WKT</abbr>).
+D’après ce format largement utilisé, les définitions <abbr>WKT</abbr> 1 sans éléments <code>AXIS[…]</code> explicites
+doivent être interprétés comme ayant ses axes dans l’ordre (<var>longitude</var>, <var>latitude</var>) ou (<var>x</var>, <var>y</var>).
+Dans la version 2 du format <abbr>WKT</abbr>, les éléments <code>AXIS[…]</code> ne sont plus optionnel
+et devrait contenir explicitement un sous-élément <code>ORDER[…]</code> pour rendre l’ordre voulu encore plus évident.
+Mais si les éléments <code>AXIS[…]</code> sont malgré tout omis dans une définition <abbr>WKT</abbr> 2,
+alors Apache <abbr>SIS</abbr> utilise l’ordre (<var>latitude</var>, <var>longitude</var>) par défaut.
+Pour résumer:
+</p>
+<ul>
+<li>L’ordre par défaut d’un <abbr>CRS</abbr> géographique en <abbr>WKT</abbr> 1 est (<var>longitude</var>, <var>latitude</var>) tel que spécifié par le standard <abbr>OGC</abbr> 01-009.</li>
+<li>L’ordre par défaut d’un <abbr>CRS</abbr> géographique en <abbr>WKT</abbr> 2 est (<var>latitude</var>, <var>longitude</var>), mais c’est une interprétation spécifique de <abbr>SIS</abbr>
+vu que la norme <abbr title="International Organization for Standardization">ISO</abbr> 19162 ne mentionne pas de comportement par défaut.</li>
+</ul>
+<p>
+Pour éviter des ambiguïtés, les utilisateurs sont encouragés à toujours fournir explicitement les éléments <code>AXIS[…]</code> dans leurs <abbr>WKT</abbr>.
+Le format <abbr>WKT</abbr> sera présenté plus en détails dans les sections suivantes.
+</p>
+
 <h3 id="GeographicCRS"><span class="section-number">3.1.4.</span> Systèmes géographiques</h3>
 <p style="color: red">TODO</p>
 
@@ -1686,10 +1735,92 @@ alors que les pays plutôt allongés dan
 
 
 <h2 id="CoordinateOperation"><span class="section-number">3.3.</span> Opérations sur les coordonnées</h2>
-<p style="color: red">TODO</p>
+<p>
+Étant donné un système de référence des coordonnées (<abbr title="Coordinate Reference System">CRS</abbr>) <em>source</em> selon lequel sont exprimés des coordonnées existantes
+et un système de référence des coordonnées <em>destination</em> selon lequel les coordonnées sont désirées,
+Apache <abbr title="Spatial Information System">SIS</abbr> peut fournir une <em>opération sur les coordonnées</em> qui effectuera le travail de conversion ou de transformation.
+La recherche d’une opération peut utiliser un troisième argument, optionnel mais recommandé: la région géographique des données à transformer.
+Ce dernier argument est recommandé parce que les opérations sur les coordonnées sont souvent valides seulement dans une région géographique
+(typiquement un pays ou une province particulière), et plusieurs transformations peuvent exister pour la même paire de <abbr>CRS</abbr>
+source et destination mais avec des domaines de validité différents.
+Il peut aussi y avoir des différentes transformations qui sont différents compromis entre la précision et le domaine de validité,
+de sorte que spécifier à Apache <abbr>SIS</abbr> qu’on s’intéresse à une région plus petite
+peut lui permettre de sélectionner une opération plus précise.
+</p>
+<div class="example"><p><b>Exemple:</b>
+la base de données géodésiques <abbr>EPSG</abbr> (dans sa version 7.9) définit 77 opérations sur les coordonnées
+allant du système géographique <cite>North American Datum 1927</cite> (EPSG:4267)
+vers le système <cite>World Geodetic System 1984</cite> (EPSG:4326).
+Il y a une opération valide seulement pour la transformation de coordonnées au Québec,
+une autre opération valide pour la transformation de coordonnées au Texas mais à l’ouest de 100°W,
+une autre opération pour le même état mais à l’est de 100°W, <i>etc</i>.
+Si l’utilisateur ne spécifie pas la région géographique qui l’intéresse,
+alors le comportement par défaut de Apache <abbr>SIS</abbr> est de sélectionner l’opération valide dans la plus grande région géographique.
+Dans cet exemple, ce critère entraîne la sélection d’une opération valide pour le Canada, mais qui n’est pas valide pour les États-Unis.</p>
+</div>
+<p>
+La façon la plus facile d’obtenir une opération sur les coordonnées à partir des informations présentées ci-dessus
+est d’utiliser la classe de commodité <code class="SIS">org.apache.sis.referencing.CRS</code>:
+</p>
+<pre><code class="GeoAPI">CoordinateOperation</code> cop = CRS.findOperation(sourceCRS, targetCRS, areaOfInterest);</pre>
+<p>
+Parmi les information fournies par l’objet <code class="GeoAPI">CoordinateOperation</code> obtenu, on note en particulier:
+</p>
+<ul>
+<li>Le <cite>domaine de validité</cite>, soit comme une description textuelle telle que « Canada – onshore and offshore »
+ou comme les coordonnées géographiques d’une boîte englobante.</li>
+<li>La <cite>précision</cite>, qui peut être n’importe quoi entre 1 centimètre et quelques kilomètres.</li>
+<li>Le sous-type de l’opération sur les coordonées. Si l’opération est une instance de <code class="GeoAPI">Transformation</code>,
+alors l’opération sélectionnée peut n’être qu’une possibilité parmi plusieurs, selon la région d’intérêt,
+et sa précision peut être limitée à cause de contrainte du « monde réel » (pas seulement les erreurs d’arrondissements).
+Si l’opération est plutôt une instance de <code class="GeoAPI">Conversion</code>, alors elle n’a pas ses limitations.</li>
+</ul>
+<p>
+Le travail mathématique réel est effectué par un objet obtenu par un appel à <code>cop.getMathTransform()</code>.
+Les types <code class="GeoAPI">CoordinateOperation</code> et <code class="GeoAPI">MathTransform</code> sont séparés parce que ce dernier est une sorte de boîte noire,
+qui peut être implémentée d’une manière très différente à ce que l’objet <code class="GeoAPI">CoordinateOperation</code> dit.
+En particulier plusieurs opérations conceptuellement différentes (par exemple rotations de la longitude,
+changements d’unités de mesure, conversions entre deux projections de Mercator qui utilisent le même référentiel, <i>etc.</i>)
+sont implémentées par <code class="GeoAPI">MathTransform</code> comme des <a href="#AffineTransform">transformations affines</a>
+et concaténées pour des raisons d’efficacité.
+</p>
 
 <h3 id="MathTransform"><span class="section-number">3.3.1.</span> Exécution de opérations</h3>
-<p style="color: red">TODO</p>
+<p>
+Le code Java suivant effectue une projection cartographique à partir de coordonnées géographiques selon le référentiel
+<cite>World Geodetic System 1984</cite> (<abbr title="World Geodetic System 1984">WGS84</abbr>) vers des coordonnées selon le système <cite>WGS 84 / UTM zone 33N</cite>.
+Afin de rendre l’exemple un peu plus simple, ce code utilise des constantes pré-définies dans la classe de commodité <code>CommonCRS</code>.
+Mais des applications plus avancées voudront souvent utiliser des codes <abbr>EPSG</abbr> plutôt.
+Notes que toutes les coordonnées géographiques dans ce code ont la latitude avant la longitude.
+</p>
+
+<pre><b>import</b> org.opengis.geometry.<code class="GeoAPI">DirectPosition</code>;
+<b>import</b> org.opengis.referencing.crs.<code class="GeoAPI">CoordinateReferenceSystem</code>;
+<b>import</b> org.opengis.referencing.operation.<code class="GeoAPI">CoordinateOperation</code>;
+<b>import</b> org.opengis.referencing.operation.<code class="GeoAPI">TransformException</code>;
+<b>import</b> org.opengis.util.<code class="GeoAPI">FactoryException</code>;
+<b>import</b> org.apache.sis.referencing.CRS;
+<b>import</b> org.apache.sis.referencing.CommonCRS;
+<b>import</b> org.apache.sis.geometry.DirectPosition2D;
+
+<b>public</b> <b>class</b> MyApp {
+    <b>public</b> <b>static</b> <b>void</b> main(String[] args) <b>throws</b> <code class="GeoAPI">FactoryException</code>, <code class="GeoAPI">TransformException</code> {
+        <code class="GeoAPI">CoordinateReferenceSystem</code> sourceCRS = CommonCRS.WGS84.geographic();
+        <code class="GeoAPI">CoordinateReferenceSystem</code> targetCRS = CommonCRS.WGS84.UTM(40, 14);  <code class="comment">// Obtient la zone valide pour 14°E.
+</code>        <code class="GeoAPI">CoordinateOperation</code> operation = CRS.findOperation(sourceCRS, targetCRS, <b>null</b>);
+
+        <code class="comment">// Les lignes précédentes sont coûteuses et ne devraient être exécutées qu’une seule fois avant
+</code>        <code class="comment">// de transformer plusieurs points.  Dans cet exemple, l’opération que nous obtenons est valide
+</code>        <code class="comment">// pour des coordonnées dans la région géographique allant de 12°E à 18°E (zone 33) et 0°N à 84°N.
+</code>
+        <code class="GeoAPI">DirectPosition</code> ptSrc = <b>new</b> DirectPosition2D(40, 14);           <code class="comment">// 40°N 14°E
+</code>        <code class="GeoAPI">DirectPosition</code> ptDst = operation.getMathTransform().transform(ptSrc, <b>null</b>);
+
+        System.out.println(<i>"Source: "</i> + ptSrc);
+        System.out.println(<i>"Target: "</i> + ptDst);
+    }
+}</pre>
+
 
 <h4 id="AffineTransform"><span class="section-number">3.3.1.1.</span> Les transformations affines</h4>
 <p>



Mime
View raw message