# Utilisation des fonctions de transformations de coordonnées

L’extension Geotools pour OpenOffice fournit de nouvelles fonctions réparties dans 2 catégories: Texte et Add-in. Cette page suppose que l’installation de l'extension Geotools s’est déroulée correctement.

Catégorie | Fonction (nom français) | Fonction (nom anglais)
--- | --- | ---
Texte | (...à faire...) | `TEXT.ANGLE TEXT.LATITUDE TEXT.LONGITUDE VALUE.ANGLE`
Referencing | (...à faire...) | `CRS.AXIS CRS.BOUNDING.BOX CRS.DESCRIPTION CRS.REMARKS CRS.SCOPE CRS.VALID.AREA CRS.WKT ORTHODROMIC.DISTANCE ORTHODROMIC.FORWARD TRANSFORM.ACCURACY TRANSFORM.COORD TRANSFORM.WKT`

Notes:

- Au moment d’écrire ces lignes, OpenOffice ne permettait pas encore de créer de nouvelles catégories. La catégorie Referencing apparaît donc pour l’instant dans la catégorie Add-in.
- L’abréviation « CRS » est pour l’expression anglaise Coordinate Reference System.

Le principe de base de fonctions de la catégorie Referencing est le suivant: chaque système de référence des coordonnées est identifié par un code numérique de la base de données EPSG. Cette base de données recense plus de 3000 systèmes en usage sur la planète, ainsi que des paramètres permettant d’effectuer des transformations d’un système vers un autre. Certaines fonctions de la catégories Referencing permettent d’obtenir des informations sur un système de référence en particulier (par exemple `CRS.DESCRIPTION`); ces fonctions n’attendent qu’un seul code EPSG en paramètre. D’autres fonctions agissent non pas à partir d’un système de référence seul, mais plutôt à partir d’une transformation passant d’un système vers un autre (par exemple `TRANSFORM.ACCURACY`). Ces fonctions attendent deux codes EPSG en paramètres, chacun correspondant à un système de référence différent. Le premier code définit le système source, et le second code définit le système destination. La transformation est définit par l’algorithme permettant de passer des coordonnées du système source vers celles du système destination.

Le tableau suivant donne quelques exemples de codes EPSG. Une liste complète peut être obtenue en téléchargeant la base de données directement du site www.epsg.org. L’extension Geotools pour OpenOffice est livrée avec sa propre copie de la base de données EPSG version 6.7 (accédée en utilisant le moteur HSQL livré avec OpenOffice), mais nous n’avons pas encore prévu d’interface graphique permettant d’y naviguer. Ça sera peut-être fait dans une version future.

Code | Type de système | Nom
--- | --- | ---
EPSG:4326 EPSG:4807 EPSG:27572 EPSG:2011 EPSG:3060 EPSG:4181 | Géographique 2D Géographique 2D Projeté Projeté Projeté Géographique 2D | WGS 84 NTF (Paris) NTF (Paris) / Lambert zone II NAD27(CGQ77) / SCoPQ zone 5 IGN72 Grande Terre / UTM zone 58S Luxembourg 1930

La plupart des fonctions opérant sur des coordonnées sont des fonctions matricielles. Leurs sorties nécessitent plusieurs colonnes, autant qu’il y a de dimensions dans le système de référence utilisé. Par exemple si une fonction doit retourner une coordonnée à trois dimensions, alors il faut sélectionner trois colonnes avant d’entrer la fonction, et valider cette dernière en appuyant sur `[Ctrl]` + `[Shift]` + `Entrée`.

Bien qu’il soit possible d’utiliser une fonction par ligne et de la recopier sur de nouvelles lignes autant de fois qu’il y a de coordonnées à transformer, il est beaucoup plus efficace de profiter là aussi du caractère matriciel des fonctions. En plus d’avoir sélectionné le nombre de colonnes nécessaires, sélectionnez autant de lignes qu’il y a de coordonnées à transformer. Cela permet à Geotools de récupérer les informations associées aux codes EPSG une seule fois pour toutes les lignes de la matrice, plutôt que de recommencer cette opération pour chaque fonction recopiée.

## Fonctions de la catégorie Texte

### TEXT.ANGLE

Convertit une valeur numérique en chaîne de caractères représentant un angle. La valeur numérique doit être un angle en degrés décimaux (par exemple 12,5 pour 12°30’). La chaîne retournée peut être un angle sexagésimal, en fonction du modèle donné en argument. Ce modèle comprend six caractères spéciaux : D, M, S, d, m et s. Le caractère D représente la partie entière des degrés, et d la partie fractionnaire. Le symbole M représente la partie entière des minutes, et m la partie fractionnaire. Enfin le symbole S représente la partie entière des secondes, et s la partie fractionnaire.

> Exemples: |
>     TEXT.ANGLE(167,1590; "DD°")
> | retourne | 167°
>     TEXT.ANGLE(167,1590; "DD°MM'")
> | retourne | 167°10'
>     TEXT.ANGLE(167,1590; "DD°MM'SS""")
> | retourne | 167°09'32"
>     TEXT.ANGLE(167,1590; "DD°MM'SS.s""")
> | retourne | 167°09'32,4"

### TEXT.LATITUDE

Convertit une valeur numérique en chaîne de caractères représentant une latitude. Cette fonction est identique à `TEXT.ANGLE`, excepté qu’elle remplace le signe (positif ou négatif) de l’angle par le symbole de l’hémisphère (N ou S pour Nord et Sud respectivement) placé après l'angle.

### TEXT.LONGITUDE

Convertit une valeur numérique en chaîne de caractères représentant une longitude. Cette fonction est identique à `TEXT.ANGLE`, excepté qu’elle remplace le signe (positif ou négatif) de l’angle par le symbole de l’hémisphère (E ou W pour Est et Ouest respectivement) placé après l'angle.

### VALUE.ANGLE

Convertit en valeur numérique une chaîne de caractères représentant un angle. Cette fonction est l’inverse de `TEXT.ANGLE`. La chaîne de caractères peut représenter un angle sexagésimal, à la condition que les symboles °, ' et " soient correctement utilisés pour identifier les degrés, minutes et secondes respectivement. L’hémisphère (N, S, E ou W) est optionnel. L’angle retourné est toujours exprimé en degrés décimaux.

Les symboles °, ' et " n’ont pas besoin d’être tous présents. Ils peuvent être complètement omis si un modèle approprié est donné en argument. Par exemple si le modèle est DDMM, alors cette fonction traduira le texte 0430 en la valeur 4,5°. Excepté pour de tels cas où les symboles différentiateurs de champs sont complètement absents, le modèle donné à la fonction `VALUE.ANGLE` est plutôt à titre indicatif. Cette fonction est assez tolérante et devrait interpréter correctement des chaînes de caractères qui ne correspondent pas exactement au modèle.

## Fonctions de la catégorie Referencing

### CRS.DESCRIPTION

Renvoie la description (le libellé) correspondant au système de référence spécifié. Le code du système est l’unique argument attendu par cette fonction.

> Exemples: |
>     CRS.DESCRIPTION("EPSG:3060")
> | retourne | IGN72 Grande Terre / UTM zone 58S
>     CRS.DESCRIPTION("EPSG:3061")
> | retourne | Porto Santo 1995 / UTM zone 28N
>     CRS.DESCRIPTION("EPSG:4326")
> | retourne | WGS84
>     CRS.DESCRIPTION("EPSG:4327")
> | retourne | WGS84 (geographic 3D)

### CRS.REMARKS

Retourne des remarques à propos du système de référence spécifié. Ces remarques indiquent parfois qu’un système a été déprécié et est remplacé par un autre. Cette information est habituellement fournit par une phrase ressemblant à « Superseded by X » ou X est le nom et code du nouveau système à utiliser. À ne pas confondre avec « Supersedes Y » qui indiquent justement que ce système en remplace un autre! Enfin, certains systèmes de référence n’ont aucune remarque associée.

### CRS.SCOPE

Retourne l’utilisation principale que l’on fait du système de référence spécifié. Le code du système est l’unique argument attendu par cette fonction.

> Exemples: |
>     CRS.SCOPE("EPSG:3060")
> | retourne | Large and medium scale topographic mapping and engineering survey.
>     CRS.SCOPE("EPSG:4327")
> | retourne | Used by GPS satellite navigation system.

### CRS.VALID.AREA

Retourne une description textuelle de la région dans laquelle un système de référence est valide. Cette description comprend habituellement les noms des pays ou provinces pour lesquels le système a été conçu.

> Exemples: |
>     CRS.VALID.AREA("EPSG:3060")
> | retourne | New Caledonia - Grande Terre.
>     CRS.VALID.AREA("EPSG:4327")
> | retourne | World.

### CRS.BOUNDING.BOX

Retourne dans une plage de cellule de taille 2×2 les coordonnées géographiques de la région dans laquelle un système de référence est valide. L’unique argument de cette méthode est le code EPSG du système dont on veut la région de validité. La sortie contient les coordonnées géographiques (toujours en degrés décimaux de latitude, longitude) du coin supérieur gauche sur la première ligne, et du coin inférieur droit sur la seconde ligne. En d’autres termes, les valeurs retournées par cette fonction se répartissent comme suit:

Nord | Ouest
Sud | Est

### CRS.AXIS

Retourne le nom d’un axe d’un système de référence de coordonnées. Cette fonction attend en arguments le code EPSG d’un système de référence, suivit de l’index d’un de ses axes. Les index sont numérotés de 1 jusqu’au nombre de dimensions du système de référence, inclusivement. Cette fonction est particulièrement utile pour obtenir le libellé des colonnes qui contiendront les coordonnées.

> Exemples: |
>     CRS.AXIS("EPSG:4326";  1)
> | retourne | Geodetic latitude
>     CRS.AXIS("EPSG:4326";  2)
> | retourne | Geodetic longitude
>     CRS.AXIS("EPSG:32758"; 1)
> | retourne | Easting
>     CRS.AXIS("EPSG:32758"; 2)
> | retourne | Northing

### TRANSFORM.COORD

Applique un changement (transformation ou conversion) de coordonnées. Les coordonnées à transformer doivent être disposées sous forme de tableau avec une coordonnée par ligne et autant de colonnes qu’il y a de dimensions dans leur système de référence (habituellement deux ou trois). La sortie aura une disposition similaire. Cette fonction attend trois arguments:

- La plage de coordonnées à transformer.
- Le code du système de référence source.
- Le code du système de référence destination.

L’ordre et le nombre de colonnes dans la plage de coordonnées à transformer dépendent du système de référence source. L’ordre et le nombre de colonnes des coordonnées transformer (la sortie de cette méthode) dépendent du système de référence destination. Pour s’y retrouver, il est pratique d’utiliser la fonction `CRS.AXIS` pour le libellé des colonnes.

Toutes les transformations de coordonnées n’ont pas la même précision. Pour obtenir une estimation de l’erreur, on peut utiliser la fonction `TRANSFORM.ACCURACY` avec en arguments les mêmes codes EPSG que ceux qui auront été spécifiés à `TRANSFORM.COORD`.

> Exemples: |

### TRANSFORM.ACCURACY

Retourne une estimation de la précision des transformations de coordonnées entre deux systèmes de référence. Cette fonction attend en argument les codes de deux systèmes de référence, habituellement ceux qui seront spécifiés à la fonction `TRANSFORM.COORD`. Elle retourne une estimation de l’erreur induite par la transformation de coordonnées, toujours en mètres. Il ne s’agit pas de l’erreur due aux éventuelles imprécisions des algorithmes de Geotools, mais plutôt de l’erreur due à la nature stochastique des paramètres dès qu’un changement de référentiel est impliqué (ces paramètres sont déterminés empiriquement à partir d’un ensemble de points exprimés selon les deux systèmes de références).

Des incertitudes sur les coordonnées calculées surviennent dès qu’il y a eu changement de référentiel, auquel cas on parle de transformation de coordonnées selon la terminologie de la norme ISO 19111. Lorsque le calcul consiste par exemple à appliquer une projection cartographique sans changer de référentiel, on parle alors de conversion de coordonnées (toujours selon la terminologie de la norme ISO). Dans ce dernier cas, la fonction `TRANSFORM.ACCURACY` peut retourner 0, ce qui signifie en fait que les changements de coordonnées se feront aux erreurs d’arrondissements près et selon les limites de la précision des algorithmes de Geotools. L’erreur ne sera donc pas réellement nulle, mais devrait être faible.

### TRANSFORM.WKT

Retourne une description au format Well Known Text (WKT) de la transformation entre deux systèmes de référence des coordonnées. Cette information permet de vérifier quel chemin a suivit Geotools pour transformer les coordonnées avec `TRANSFORM.COORD` par exemple. Cette fonction attend en argument les codes des systèmes de référence source et destination. Voyez `CRS.WKT` pour quelques détails sur ce format.

> Exemple: |
>     TRANSFORM.WKT("EPSG:4326", "EPSG:32759", "OGC")
> retourne |
>     CONCAT_MT[PARAM_MT["Affine",
>         PARAMETER["num_row", 3],
>         PARAMETER["num_col", 3],
>         PARAMETER["elt_0_0", 0.0],
>         PARAMETER["elt_0_1", 1.0],
>         PARAMETER["elt_1_0", 1.0],
>         PARAMETER["elt_1_1", 0.0]],
>       PARAM_MT["Transverse_Mercator",
>         PARAMETER["semi_major", 6378137.0],
>         PARAMETER["semi_minor", 6356752.314245179],
>         PARAMETER["central_meridian", 171.0],
>         PARAMETER["latitude_of_origin", 0.0],
>         PARAMETER["scale_factor", 0.9996],
>         PARAMETER["false_easting", 500000.0],
>         PARAMETER["false_northing", 10000000.0]]],
>     AUTHORITY["EPSG","16159"]]

### CRS.WKT

Retourne une description au format Well Known Text (WKT) du système de référence spécifié. Le format WKT est un format standardisé par le consortium Open Geospatial (OGC) pour l’échange d’informations à propos de systèmes de référence des coordonnées. En plus de contenir le code EPSG d’un système de référence, il contient aussi le strict minimum d’informations nécessaires pour pouvoir utiliser ce système de manière autonome, c’est-à-dire sans qu’une connexion à une base de données EPSG ou autre ne soit nécessaire. Il s’agit bien d’un strict minimum; la chaîne retournée ne dit rien sur la région de validité du système de référence, son usage, ses remarques, etc. Le format WKT est utilisé par certains services web, ainsi que par certains logiciels commerciaux, pour spécifier le système de référence des coordonnées (souvent dans un petit fichier texte portant l’extension `.prj`) d’une série de données.

La syntaxe du format WKT est définie en utilisant la notation de Backus Naur étendue. Le dernier argument indique quelle autorité utiliser pour le choix des noms des paramètres apparaissant dans la sortie. Sa valeur est habituellement `"OGC"` (pour Open Geospatial Consortium). Une autre valeur courante est `"GeoTIFF"`.

> Exemple: |
>     CRS.WKT("EPSG:27572", "OGC")
> retourne |
>     PROJCS["NTF (Paris) / Lambert zone II",
>       GEOGCS["NTF (Paris)",
>         DATUM["Nouvelle Triangulation Francaise (Paris)",
>           SPHEROID["Clarke 1880 (IGN)", 6378249.2, 293.4660212936269, AUTHORITY["EPSG","7011"]],
>           AUTHORITY["EPSG","6807"]],
>         PRIMEM["Paris", 2.5969213, AUTHORITY["EPSG","8903"]],
>         UNIT["grade", 0.015707963267948967],
>         AXIS["Geodetic latitude", NORTH, AUTHORITY["EPSG","58"]],
>         AXIS["Geodetic longitude", EAST, AUTHORITY["EPSG","59"]],
>         AUTHORITY["EPSG","4807"]],
>       PROJECTION["Lambert Conic Conformal (1SP)", AUTHORITY["EPSG","9801"]],
>       PARAMETER["central_meridian", 0.0],
>       PARAMETER["latitude_of_origin", 52.0],
>       PARAMETER["scale_factor", 0.99987742],
>       PARAMETER["false_easting", 600000.0],
>       PARAMETER["false_northing", 2200000.0],
>       UNIT["m", 1.0],
>       AXIS["Easting", EAST],
>       AXIS["Northing", NORTH],
>       AUTHORITY["EPSG","27572"]]

### ORTHODROMIC.DISTANCE

Calcule la distance orthodromique entre deux coordonnées exprimées selon le système de référence spécifié. La distance orthodromique est la plus courte distance entre deux points à la surface d’un ellipsoïde. Pour une sphère, son chemin correspond toujours à un arc de grand cercle.

Une autre façon de calculer la distance entre deux points serait de convertir les coordonnées selon une projection plane, et de calculer la distance par une simple relation de Pythagore. Toutefois, toute projection induit des déformations. Ces dernières sont négligeables sur des distances de centaines de kilomètres, mais peuvent devenir perceptibles sur des distances de milliers de kilomètres. Le calcul de la distance orthodromique tient compte de la courbure de la Terre pour donner une réponse plus précise que la relation de Pythagore sur de grandes distances.

Cette fonction attend trois arguments, soit dans l’ordre: les coordonnées du premier point (habituellement sur deux colonnes), les coordonnées du second point (habituellement sur deux colonnes), et le code du système de référence selon lequel ces coordonnées sont exprimées. Si deux colonnes sont sélectionnées pour la sortie, alors la deuxième colonne contiendra l’azimut pour aller du premier point au second. La première colonne contiendra la distance orthodromique dans tous les cas.

> Exemples: |

### ORTHODROMIC.FORWARD

Calcule un point d'arrivé à partir d'un point de départ, une distance orthodromique et d'un azimuth. Cette fonction est l'inverse de `ORTHODROMIC.DISTANCE`.