From commits-return-7764-apmail-sis-commits-archive=sis.apache.org@sis.apache.org Thu Jun 2 04:57:17 2016 Return-Path: X-Original-To: apmail-sis-commits-archive@www.apache.org Delivered-To: apmail-sis-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id C68191951B for ; Thu, 2 Jun 2016 04:57:17 +0000 (UTC) Received: (qmail 46743 invoked by uid 500); 2 Jun 2016 04:57:17 -0000 Delivered-To: apmail-sis-commits-archive@sis.apache.org Received: (qmail 46710 invoked by uid 500); 2 Jun 2016 04:57:17 -0000 Mailing-List: contact commits-help@sis.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: sis-dev@sis.apache.org Delivered-To: mailing list commits@sis.apache.org Received: (qmail 46661 invoked by uid 99); 2 Jun 2016 04:57:17 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd3-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 02 Jun 2016 04:57:17 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 45662180581 for ; Thu, 2 Jun 2016 04:57:17 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 0.374 X-Spam-Level: X-Spam-Status: No, score=0.374 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, KAM_LAZY_DOMAIN_SECURITY=1, RP_MATCHES_RCVD=-1.426] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024) with ESMTP id 9Pl5tO9Xn8AO for ; Thu, 2 Jun 2016 04:57:11 +0000 (UTC) Received: from mailrelay1-us-west.apache.org (mailrelay1-us-west.apache.org [209.188.14.139]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with ESMTP id A3CC85F24D for ; Thu, 2 Jun 2016 04:57:10 +0000 (UTC) Received: from svn01-us-west.apache.org (svn.apache.org [10.41.0.6]) by mailrelay1-us-west.apache.org (ASF Mail Server at mailrelay1-us-west.apache.org) with ESMTP id 74B08E0E0F for ; Thu, 2 Jun 2016 04:57:08 +0000 (UTC) Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id A3E413A18CE for ; Thu, 2 Jun 2016 04:57:07 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r1746518 [6/6] - in /sis/site/trunk: book/en/ book/fr/ book/math/ content/book/en/ content/book/fr/ Date: Thu, 02 Jun 2016 04:57:06 -0000 To: commits@sis.apache.org From: desruisseaux@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20160602045707.A3E413A18CE@svn01-us-west.apache.org> 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=1746518&r1=1746517&r2=1746518&view=diff ============================================================================== --- sis/site/trunk/content/book/en/developer-guide.html (original) +++ sis/site/trunk/content/book/en/developer-guide.html Thu Jun 2 04:57:06 2016 @@ -19,7 +19,7 @@

Introduction to Apache SIS®

(English | Français)

Martin Desruisseaux
-Christina Hough

+Partially translated by Christina Hough

This work is licensed under the Apache 2 license.

@@ -60,7 +60,8 @@
  • Adding new CRS definitions
  • Coordinate operations
  • Partial derivatives of coordinate operations
  • Coordinate operations
  • Partial derivatives of coordinate operations
    • Transform derivatives applied to envelopes
    • Transform derivatives applied to rasters
      • @@ -1634,36 +1636,98 @@ while countries elongated along the Nort

      3.3.1.1. Affine transform

      Among the many kinds of operations performed by GIS softwares on spatial coordinates, -linear operations are both simple and very common. -Linear operations are combinations of only additions and some multiplications. -Linear operations do not include map projections, which are more complex, but cover many other cases: +affine transforms are both relatively simple and very common. +Affine transforms can represent any combination of scales, shears, flips, rotations and translations, +which are linear operations. +Affine transforms can not handle non-linear operations like map projections, +but the affine transform capabilities nevertheless cover many other cases:

        -
      • Change axis order, for example from (latitude, longitude) to (longitude, latitude).
        • -
      • Change axis direction (for example the y axis in images is often oriented toward down).
        • -
      • Change the prime meridian (for example from Paris to Greenwich).
        • -
      • Change the number of dimensions (for example from 3-dimensional coordinates to 2-dimensional coordinates).
        • -
      • Convert units of measurement (for example convert feet to metres).
        • -
      • Convert pixel coordinates in an image to geodetic coordinates -(for example the conversion represented in the .tfw files associated to some TIFF images).
        • -
      • Handle a small part of map projection task -(for example the False Easting, False Northing and Scale factor parameters).
        • -
      • Apply rotations, translations, scales and shears (part of affines transforms).
        • +
      • Axis order changes, for example from (latitude, longitude) to (longitude, latitude).
        • +
      • Axis direction changes, for example the y axis oriented toward down in images.
        • +
      • Prime meridian rotations, for example from Paris to Greenwich prime meridian.
        • +
      • Dimensionality changes, for example from 3-dimensional coordinates to 2-dimensional coordinates by dropping the height.
        • +
      • Unit conversion, for example from feet to metres.
        • +
      • Pixel to geodetic coordinate, for example the conversion represented in the .tfw files associated to some TIFF images.
        • +
      • Part of map projections, for example the False Easting, False Northing and Scale factor parameters.

      -Linear operations can be concatenated efficiently. -No matter how many linear operations are chained, the result can be represented by a single linear operation. -This property is more easily seen when linear operations are represented by matrices: -in order to concatenate those operations, we only need to multiply the matrices. +Affine transforms can be concatenated efficiently. +No matter how many affine transforms are chained, the result can be represented by a single affine transform. +This property is more easily seen when affine transforms are represented by matrices: +in order to concatenate those operations, we only need to multiply those matrices. +The “pixel to geographic coordinate conversions” case below gives an example.

      -

      Example: -give an image with pixel coordinates represented by (i,j) coordinates, -assuming that all pixels have the same size in longitude and latitude degrees, -and assuming there there is no rotation, then conversion from -(i,j) pixel coordinates to (λ,φ) geographic coordinates -can be represented by the following matrices:

      - -

      -TODO +

      +In this particular case, scale factors S are the pixel size in degrees +and translation terms T are the geographic coordinate of an image corner +(not necessarily the lower-left corner if some axes have been flipped). +This straightforward interpretation holds because of above-cited assumptions, but +matrix coefficients become more complex if the image has shear or rotation +or if pixel coordinates do not start at (0,0). +However it is not necessary to use more complex equations for supporting more generic cases. +The following example starts with an “initial conversion” matrix +where the S and T terms are set to the most straightforward values. +Then the y axis direction is reversed for matching the most common convention in image coordinate systems (change 1), +and axis are swapped resulting in latitude before longitude (change 2). +Note that when affine transform concatenations are written as matrix multiplications, operations are ordered from right to left: +A×B×C is equivalent to first applying operation C, +then operation B and finally operation A.

      +

      -TODO +A key principle is that there is no need to write Java code dedicated to above kinds of axis changes. +Those operations, and many other, can be handled by matrix algebra. +This approach makes easier to write generic code and improves performance. +Apache SIS follows this principle by using affine transforms for every operations +that can be performed by such transform. +For instance there is no code dedicated to changing order of ordinate values in a coordinate.

      -

      TODO

      +

      3.3.1.2. Integration with graphical libraries

      +

      +About all graphical libraries support some kind of coordinate operations, usually as affine transforms +or a slight generalization like perspective transforms. +Each library defines its own API. Some examples are listed below: +

      + + + + + + + + +
      Affine transform implementations in graphical libraries
      Library Transform implementation Dimensions
      Java2D java.awt.geom.AffineTransform 2
      Java3D javax.media.j3d.Transform3D 3
      JavaFX javafx.scene.transform.Affine 2 or 3
      Java Advanced Imaging (JAI) javax.media.jai.PerspectiveTransform 2
      Android android.graphics.Matrix 2
      +

      +However in many cases, affine or perspective transforms are the only kind of coordinate operations supported by the graphical library. +Apache SIS needs to handle a wider range of operations, in which affine transforms are only special cases. +In particular most map projections and datum shifts can not be represented by affine transforms. +SIS also needs to support arbitrary number of dimensions, +while above-cited API restrict the use to a fixed number of dimensions. +For those reasons SIS can not use directly the above-cited API. +Instead, SIS uses the more abstract org.opengis.referencing.transform.MathTransform interface. +But in the special case where the transform is actually affine, SIS may try to use an existing implementation, +in particular Java2D. The following Java code can be used in situations where the Java2D object is desired: +

      +
      MathTransform mt = ...;    // Any math transform created by Apache SIS.
+if (mt instanceof AffineTransform) {
+    AffineTransform at = (AffineTransform) mt;
+    // Use Java2D API from here.
+}
      +

      +However SIS uses Java2D on a best effort basis only. +The above cast is not guaranteed to succeed, +even when the MathTransform meets the requirements allowing Java2D usage. +

      3.3.2. Partial derivatives of coordinate operations

      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=1746518&r1=1746517&r2=1746518&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] Thu Jun 2 04:57:06 2016 @@ -60,7 +60,8 @@

    • Ajout de définitions
  • Opérations sur les coordonnées
  • Dérivées partielles des opérations
  • Opérations sur les coordonnées
  • Dérivées partielles des opérations
    • Utilité des dérivées pour la reprojection d’enveloppes
    • Utilité des dérivées pour la reprojection d’images
      • @@ -1687,36 +1689,102 @@ alors que les pays plutôt allongés dan

      3.3.1.1. Les transformations affines

      -Parmi les sortes d’opérations qu’un SIG doit effectuer sur les coordonnées spatiales, il en est une à la fois simple et très fréquente. -Ce sont les opérations linéaires, constituées uniquement d’une combinaison d’additions et de certaines multiplications. -Ces opérations n’effectuent pas de projections cartographiques, plus complexes, mais couvrent de nombreux autres cas: -

      -
        -
      • Changer l’ordre des axes, par exemple de (latitude, longitude) vers (longitude, latitude).
        • -
      • Changer la direction des axes (par exemple l’axe des y des images pointe souvent vers le bas).
        • -
      • Changer de méridien d’origine (par exemple de Paris vers Greenwich).
        • -
      • Changer le nombre de dimensions (par exemple passer des coordonnées 3D vers 2D).
        • -
      • Convertir des unités de mesures (par exemple convertir des pieds en mètres).
        • -
      • Convertir les coordonnées pixels d’une image en coordonnées géographiques -(par exemple la conversion exprimée dans les fichiers .tfw qui accompagnent certaines images TIFF).
        • -
      • Prendre en charge une petite partie des projections cartographiques -(par exemple les paramètres False Easting, False Northing et Scale factor).
        • -
      • Appliquer des rotations, translations, échelles ou cisaillements (des transformations dites affines).
        • -
      -

      -Les opérations linéaires peuvent se combiner efficacement: -peu importe le nombre d’opérations linéaires que l’on enchaîne, le résultat sera exprimable par une seule opération linéaire. -Cette propriété est plus facilement visible lorsque les opérations linéaires sont exprimées sous forme de matrices: +Parmi les sortes d’opérations qu’un SIG doit effectuer sur les coordonnées spatiales, +les transformations affines sont à la fois relativement simples et très fréquentes. +Les transformations affines peuvent représenter n’importe quelle combinaison d’échelles, de cisaillements, +de retournements, de rotations ou de translations, qui sont toutes des opérations linéaires. +Les transformations affines ne peuvent pas effectuer des opérations non-linéaires +telles que les projections cartographiques, mais couvrent néanmoins de nombreux autres cas: +

      +
        +
      • Changer l’ordre des axes, par exemple de (latitude, longitude) vers (longitude, latitude).
        • +
      • Changer la direction des axes, par exemple l’axe des y qui pointe habituellement vers le bas dans les images.
        • +
      • Changer le méridien d’origine, par exemple du méridien de Paris vers celui de Greenwich.
        • +
      • Changer le nombre de dimensions, par exemple passer des coordonnées 3D vers 2D en supprimant la hauteur.
        • +
      • Convertir des unités de mesures, par exemple convertir des pieds en mètres.
        • +
      • Convertir des coordonnées pixels en coordonnées géographiques, +par exemple la conversion exprimée dans les fichiers .tfw qui accompagnent certaines images TIFF.
        • +
      • Prendre en charge une petite partie des projections cartographiques, +par exemple les paramètres False Easting, False Northing et Scale factor.
        • +
      +

      +Les transformations affines peuvent se combiner efficacement. +Peu importe le nombre de transformations affines que l’on enchaîne, le résultat sera exprimable par une seule transformation affine. +Cette propriété est plus facilement visible lorsque les transformations affines sont exprimées sous forme de matrices: pour combiner les opérations, il suffit de multiplier les matrices. +Le cas des conversions des coordonnées pixels en coordonnées géographiques ci-dessous donne un exemple.

      -

      Example: -supposons que nous disposons d’une image dont les coordonnées des pixels sont représentées par (i,j). -Supposons que la taille de chaque pixel correspond à un nombre fixe de degrées de longitude et de latitude -dans un système géographique donné et qu’il n’y a pas de rotation. -La conversion des coordonnées pixels (i,j) vers les coordonnées géographiques (λ,φ) -est alors linéaire et peut être représentée par la matrice suivante:

      - -

      -Concentrons notre attention sur la matrice du milieu dans l’équation ci-dessus. -Si nous n’interchangeons ni n’inversons la direction d’aucun axe, alors une conversion des coordonnées pixels vers les coordonnées géographiques -pourrait s’exprimer par la matrice « conversion originale » ci-dessous. -Mais si l’on veut en outre inverser la direction de l’axe des j pour se conformer à la convention la plus courante appliquée aux images -(« changement 1 ») et interchanger l’ordre des axes pour exprimer la latitude avant la longitude (« changement 2 »), -alors on peut exprimer ces modifications par des multiplications matricielles comme suit -(l’ordre dans laquelle les opérations sont effectuées sur les coordonnées se lit de droite à gauche): +

      +Dans ce cas particulier, les facteurs d’échelles S correspondent à la taille des pixels en degrés +et les termes de translations T correspondent aux coordonnées géographiques d’un coin de l’image +(pas nécessairement le coin inférieur gauche si certains axes ont été retournés). +Cette interprétation directe n’est possible que lorsque les contraintes énumérées plus haut sont respectées. +Les coefficients des matrices deviennent plus complexes si l’image a un cisaillement ou une rotation, +ou si les coordonnées des pixels ne commencent pas à (0,0). +Toutefois il n’est pas nécessaire d’utiliser des équations plus complexes pour gérer des cas plus génériques. +L’exemple ci-dessous prend comme point de départ la matrice d’une « conversion initiale » +dans laquelle les coefficients S et T sont les valeurs relativement simples données ci-dessus. +Ensuite la direction de l’axe des y est inversée de manière à correspondre +à la convention habituelle des systèmes de coordonnées des images (changement 1), +et les axes sont intervertis de manière à avoir la latitude avant la longitude (changement 2). +Notez que les concaténations de transformations affines écrites sous forme de multiplications matricielles +se lisent de droite à gauche: +A×B×C est équivalent à d’abord appliquer l’opération C, +suivit de l’opération B et finalement l’opération A.

      +

      -L’idée principale est qu’il n’y a pas besoin d’écrire un code dédié à l’inversion des axes. -Cette opération, et bien d’autres, est prise en compte naturellement par l’algèbre matricielle. +Un principe clé est qu’il n’y a pas besoin d’écrire un code dédié à ce type d’opérations sur les axes. +Ces opérations, et bien d’autres, sont prises en compte naturellement par l’algèbre matricielle. On y gagne en généricité du code et en performance. +Apache SIS suit ce principe en utilisant les tranformations affine pour toutes les opérations +où elles peuvent s’appliquer. +Il n’y a par exemple aucun code dédié au changement de l’ordre des ordonnées dans une coordonnée.

      -

      TODO

      -

      Particularités d’une bibliothèque de calculs matriciels pour un SIG

      @@ -2033,6 +2097,47 @@ En résumé, les besoins qui ont amené
    +

    3.3.1.2. Intégration avec les bibliothèques graphiques

    +

    +A peu près toutes les bibliothèques graphiques supportent une forme de transformation de coordonnées, +souvent les transformations affines ou une légère généralisation. +Chaque bibliothèque défini son propre API. +Quelques exemples sont: +

    + + + + + + + + +
    Implémentations des transformations affines dans des bibliothèques graphiques
    Bibliothèque Implementation de la transformation Dimensions
    Java2D java.awt.geom.AffineTransform 2
    Java3D javax.media.j3d.Transform3D 3
    JavaFX javafx.scene.transform.Affine 2 ou 3
    Java Advanced Imaging (JAI) javax.media.jai.PerspectiveTransform 2
    Android android.graphics.Matrix 2
    +

    +Toutefois dans plusieurs cas, les transformations affines sont les seuls types d’opérations supportées par la bibliothèque graphique. +Apache SIS a besoin de gérer un plus grand nombre de type d’opérations, +parmi lesquelles les transformations affines ne sont que des cas particuliers. +Les projections cartographiques et les changements de référentiels notamment, +ne peuvent pas être représentés par des transformations affines. +SIS a aussi besoin de transformer des points ayant un nombre arbitraire de dimensions, +alors que les API cités ci-haut restreignent leur usage à un nombre fixe de dimensions. +Pour ces raisons, SIS ne peut pas utiliser directement ces API. +SIS utilise plutôt une interface plus abstraite, org.opengis.referencing.transform.MathTransform. +Mais dans le cas particulier où la transformation est réellement affine, SIS peut essayer d’utiliser +une implémentation existante, surtout Java2D. +Par exemple le code suivant peut être utilisé dans les situations où un objet Java2D est désiré: +

    +
    MathTransform mt = ...;    // N’importe quelle instance créée par Apache SIS.
+if (mt instanceof AffineTransform) {
+    AffineTransform at = (AffineTransform) mt;
+    // Utiliser l’API de Java2D API à partir d’ici.
+}
    +

    +Toutefois SIS n’utilisera Java2D que sur une base opportuniste. +Le forçage de type ci-haut n’est pas garantit de réussir, même si l’instance de +MathTransform répond aux conditions qui devrait permettre un usage de Java2D. +

    +

    3.3.2. Dérivées partielles des opérations

    La section précédente indiquait comment calculer les coordonnées d’un point géographique dans une projection au choix.