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

• ``` Coordinate operations Executing an operation on coordinate values -Affine transform +Affine transform +Integration with graphical libraries 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: - + +Example: +given an image with pixel coordinates represented by (x,y) tuples +and given the following assumptions: + + +There is no shear, no rotation and no flip. +All pixels have the same width in degrees of longitude. +All pixels have the same height in degrees of latitude. +Pixel indices are positive integers starting at (0,0) inclusive. + +Then conversions from pixel coordinates (x,y) +to geographic coordinates (Î»,Ï) can be represented by the following equations, +where Nx is the image width and +Ny the image height in number of pixels: + + + +$MathML capable browser required$ + +Above equations can be represented in matrix form as below: + $MathML capable browser required$ - -where - - -S is a scale factor which, in this example, is equals to the pixel size in degrees. -H is a shear factor, usually equals to zero except if the image is rotated. -T is a translation term which, in this example, is equals to the geographic coordinate of an image corner. - - - -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. + Change 2 Change 1 -Original conversion -Modified conversionInitial conversion +Concatenated operation $MathML capable browser required$ -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 librariesLibrary Transform implementation DimensionsJava2D java.awt.geom.AffineTransform 2Java3D javax.media.j3d.Transform3D 3JavaFX javafx.scene.transform.Affine 2 or 3Java Advanced Imaging (JAI) javax.media.jai.PerspectiveTransform 2Android 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 Exécution de opérations -Les transformations affines +Les transformations affines +Intégration avec les bibliothèques graphiques 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 @@ -1429,7 +1430,8 @@ de la bibliothèque SIS. Ajout de définitions Opérations sur les coordonnées Exécution de opérations -Les transformations affines +Les transformations affines +Intégration avec les bibliothèques graphiques 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: - + +Exemple: +supposons que nous disposons d’une image dont les coordonnées des pixels sont représentées par (x,y). +Supposons aussi que les contraintes suivantes sont respectées: + + +Il n’y a ni cisaillement, ni rotation, ni retournement de l’image. +Tous les pixels ont la même largeur en degrés de longitude. +Tous les pixels ont la même hauteur en degrés de latitude. +Les coordonnées des pixels commencent à (0,0) inclusivement. + +Alors la conversion des coordonnées pixels (x,y) +vers les coordonnées géographiques (λ,φ) +peut être représentée par les équations suivantes, +où Nx est la largeur +et Ny la hauteur de l’image en nombre de pixels. + + + +$MathML capable browser required$ + +Les équations ci-dessus peuvent être représentées sous forme de matrices comme ci-dessous: + $MathML capable browser required$ - -où - - -S est un facteur d’échelle (Scale) correspondant dans cet exemple à la taille des pixels en degrés. -H est un terme de cisaillement (Shear), habituellement zéro sauf si l’image a une rotation. -T est une translation (Translation) correspondant dans cet exemple à la coordonnée géographique d’un coin de l’image. - - - -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. + Changement 2 Changement 1 -Conversion originale -Conversion modifiéeConversion initiale +Opérations combinées $MathML capable browser required$ -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 graphiquesBibliothèque Implementation de la transformation DimensionsJava2D java.awt.geom.AffineTransform 2Java3D javax.media.j3d.Transform3D 3JavaFX javafx.scene.transform.Affine 2 ou 3Java Advanced Imaging (JAI) javax.media.jai.PerspectiveTransform 2Android 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. ```