Introduction to Apache SISÂ®

(English | FranÃ§ais)

Martin Desruisseaux
- Christina Hough

+ Partially translated by Christina Hough

Modified: sis/site/trunk/book/en/referencing.html URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/referencing.html?rev=1746518&r1=1746517&r2=1746518&view=diff ============================================================================== --- sis/site/trunk/book/en/referencing.html (original) +++ sis/site/trunk/book/en/referencing.html Thu Jun 2 04:57:06 2016 @@ -284,190 +284,126 @@

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 +

+

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: +

+ +

+ Above equations can be represented in matrix form as below: +

+ +

+ 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

+

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. +

Partial derivatives of coordinate operations

Modified: sis/site/trunk/book/fr/referencing.html URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/referencing.html?rev=1746518&r1=1746517&r2=1746518&view=diff ============================================================================== --- sis/site/trunk/book/fr/referencing.html (original) +++ sis/site/trunk/book/fr/referencing.html Thu Jun 2 04:57:06 2016 @@ -283,199 +283,96 @@

Les transformations affines

-
• 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).
• +
• 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.

-

- -

- 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): +

+

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. +

+ +

+ +

- - + + - + - + - + - +

-

TODO

-

ParticularitÃ©s dâune bibliothÃ¨que de calculs matriciels pour un SIG

@@ -591,6 +488,47 @@
+

+

+ 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. +

+