blob: dce4c4b921c5c4ae824828a2c209cea3cf426da3 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="fr">
<head>
<title>Formules ajoutées dans Calc</title>
<meta charset="UTF-8"/>
<link rel="stylesheet" type="text/css" href="../openoffice.css"/>
</head>
<body>
<h1>Formules ajoutées dans Calc</h1>
<p>
L’extension Apache <abbr title="Spatial Information System">SIS</abbr> pour Open/LibreOffice
fournit de nouvelles fonctions réparties dans 2 catégories : <i>Texte</i> et <i>Add-in</i>.
Le principe de base des fonctions de la catégorie <i>Add-in</i> est le suivant :
chaque système de référence des coordonnées est identifié par un code numérique de la
<a href="https://epsg.org/">base de données géodesiques <abbr>EPSG</abbr></a> ou d’une autre autorité.
La base de donnnées <abbr>EPSG</abbr> recense plus de 6000 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 permettent d’obtenir des informations sur un système de référence en particulier,
par exemple son domaine de validité. Ces fonctions n’attendent qu’un seul code <abbr>EPSG</abbr> 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.
Ces fonctions attendent deux codes <abbr>EPSG</abbr> 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.
L’opération est définie par l’algorithme permettant de passer des coordonnées du système source vers celles du système destination.
</p><p>
Les définitions officielles des codes <abbr>EPSG</abbr> peuvent être explorées en-ligne avec le <a href="https://epsg.org/">registre <abbr>EPSG</abbr></a>.
Cette extension pour Open/LibreOffice est toutefois livrée avec sa propre copie (dans un format binaire) de la base de données <abbr>EPSG</abbr>,
dont <a href="https://epsg.org/terms-of-use.html">l’utilisation est soumise à des conditions</a>.
Apache <abbr>SIS</abbr> étend cette liste avec quelques codes définis en dehors d’<abbr>EPSG</abbr>, notamment par l’<abbr title="Open Geospatial Consortium">OGC</abbr>.
Un sommaire des codes embarqués par Apache <abbr>SIS</abbr> est <a href="../../tables/CoordinateReferenceSystems.html">donné ici</a>.
La syntaxe des codes acceptés
<a href="../../apidocs/org/apache/sis/referencing/CRS.html#forCode-java.lang.String-">est décrite dans la Javadoc de Apache <abbr>SIS</abbr></a>.
Par exemple, tous les codes suivants sont considérés équivalents à <code>"EPSG:4326"</code> :
</p>
<ul>
<li><code>"EPSG::4326"</code></li>
<li><code>"urn:ogc:def:crs:EPSG::4326"</code></li>
<li><code>"http://www.opengis.net/def/crs/epsg/0/4326"</code></li>
<li><code>"http://www.opengis.net/gml/srs/epsg.xml#4326"</code></li>
</ul>
<p>
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].
</p><p>
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 points à 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 points à transformer.
Cela permet à Apache <abbr>SIS</abbr> de récupérer les informations associées aux codes <abbr>EPSG</abbr> une seule fois
pour toutes les lignes de la matrice résultante, plutôt que de recommencer cette opération pour chaque fonction recopiée.
</p>
<section>
<span class="eng">(en anglais : <code>TEXT.ANGLE</code>)</span>
<h2 id="TEXT.ANGLE">TEXTE.ANGLE</h2>
<p>
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 quelques caractères spéciaux
<a href="../../apidocs/org/apache/sis/measure/AngleFormat.html">décrits dans la Javadoc de Apache <abbr>SIS</abbr></a>,
dont les principaux sont : <var>D</var>, <var>M</var>, <var>S</var>, <var>d</var>, <var>m</var> et <var>s</var>.
Le caractère <var>D</var> représente la partie entière des degrés, et <var>d</var> la partie fractionnaire.
Le symbole <var>M</var> représente la partie entière des minutes, et <var>m</var> la partie fractionnaire.
Enfin le symbole <var>S</var> représente la partie entière des secondes, et <var>s</var> la partie fractionnaire.
</p>
<table>
<caption>Exemples</caption>
<tr><th>Formule</th> <th>Résultat</th></tr>
<tr><td><code>=TEXTE.ANGLE(167,1590; "DD°")</code></td> <td>167°</td></tr>
<tr><td><code>=TEXTE.ANGLE(167,1590; "DD°MM′")</code></td> <td>167°10′</td></tr>
<tr><td><code>=TEXTE.ANGLE(167,1590; "DD°MM′SS″")</code></td> <td>167°09′32″</td></tr>
<tr><td><code>=TEXTE.ANGLE(167,1590; "DD°MM′SS.s″")</code></td> <td>167°09′32,4″</td></tr>
</table>
</section>
<section>
<span class="eng">(en anglais : <code>VALUE.ANGLE</code>)</span>
<h2 id="VALUE.ANGLE">VALEUR.ANGLE</h2>
<p>
Convertit en valeur numérique une chaîne de caractères représentant un angle.
Cette fonction est l’inverse de <code><a href="#TEXT.ANGLE">TEXTE.ANGLE</a></code>.
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 (<cite>N</cite>, <cite>S</cite>, <cite>E</cite> ou <cite>W</cite>) est optionnel.
L’angle retourné est toujours exprimé en degrés décimaux.
</p><p>
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 <cite>DDMM</cite>, alors cette fonction convertira le texte "0430" en la valeur numérique 4,5.
Excepté pour de tels cas où les symboles différentiateurs de champs sont complètement absents,
le modèle donné à la fonction <code>VALEUR.ANGLE</code> 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.
</p>
</section>
<section>
<span class="eng">(en anglais : <code>CRS.NAME</code>)</span>
<h2 id="CRS.NAME">NOM.SRS</h2>
<p>
Retourne le nom du système de référence identifié par le code donné.
Le code du système est l’unique argument attendu par cette fonction.
Bien que cette fonction soit conçue pour retourner le nom de systèmes de références spatiaux (<abbr>SRS</abbr>),
elle peut aussi retourner le nom de d’autres types d’objets à la condition que leur type soit explicité
(par exemple : <code>"urn:ogc:def:<b>datum</b>:EPSG::6326"</code>).
</p>
<table>
<caption>Exemples</caption>
<tr><th>Formule</th> <th>Résultat</th></tr>
<tr><td><code>=NOM.SRS("EPSG:3060")</code></td> <td>IGN72 Grande Terre / UTM zone 58S</td></tr>
<tr><td><code>=NOM.SRS("EPSG:3061")</code></td> <td>Porto Santo 1995 / UTM zone 28N</td></tr>
<tr><td><code>=NOM.SRS("EPSG:4326")</code></td> <td>WGS 84</td></tr>
<tr><td><code>=NOM.SRS("EPSG:4329")</code></td> <td>WGS 84 (3D)</td></tr>
</table>
</section>
<section>
<span class="eng">(en anglais : <code>CRS.USAGE</code>)</span>
<h2><a id="CRS.USAGE">USAGE.SRS</a></h2>
<p>
Retourne le domaine d’utilisation du système de référence identifié par le code donné.
Le code du système est l’unique argument attendu par cette fonction.
Bien que cette fonction soit conçue pour retourner le domaine d’utilisation de systèmes de références spatiaux (<abbr>SRS</abbr>),
elle peut aussi retourner le domaine de d’autres types d’objets à la condition que leur type soit explicité
(par exemple : <code>"urn:ogc:def:<b>datum</b>:EPSG::6326"</code>).
</p>
<table>
<caption>Exemples</caption>
<tr><th>Formule</th> <th>Résultat</th></tr>
<tr><td><code>=USAGE.SRS("EPSG:3060")</code></td> <td>Large and medium scale topographic mapping and engineering survey.</td></tr>
<tr><td><code>=USAGE.SRS("EPSG:4327")</code></td> <td>Used by GPS satellite navigation system.</td></tr>
</table>
</section>
<section>
<span class="eng">(en anglais : <code>REGION.NAME</code>)</span>
<h2 id="REGION.NAME">NOM.REGION</h2>
<p>
Retourne une description textuelle de la région dans laquelle un objet est valide.
Cette description comprend habituellement les noms des pays ou provinces pour lesquels le système a été conçu.
L’objet donné en argument est souvent, mais pas obligatoirement, un code de Système de Références Spatiales (<abbr>SRS</abbr>).
</p>
<table>
<caption>Exemples</caption>
<tr><th>Formule</th> <th>Résultat</th></tr>
<tr><td><code>=NOM.REGION("EPSG:3060")</code></td> <td>New Caledonia - Grande Terre.</td></tr>
<tr><td><code>=NOM.REGION("EPSG:4326")</code></td> <td>World.</td></tr>
</table>
</section>
<section>
<span class="eng">(en anglais : <code>GEOGRAPHIC.AREA</code>)</span>
<h2 id="GEOGRAPHIC.AREA">REGION.GEOGRAPHIQUE</h2>
<p>
Retourne sous forme de boîte englobante le domaine d’un objet identifié par le code donné.
Si le code donné en argument identifie un système de référence spatial,
alors cette fonction retourne les coordonnées géographiques de la région dans laquelle le système est valide.
La boîte est exprimée par une matrice 2×2 avec les latitudes dans la première colonne
et les longitudes dans la seconde colonne, toujours dans cet ordre et toujours en degrés décimaux.
La première ligne donne les coordonnées du coin supérieur gauche
et la seconde ligne donne celles du coin inférieur droit.
En d’autres termes, les valeurs retournées par cette fonction se répartissent comme suit :
</p>
<table class="grid">
<tr><td>Nord</td> <td>Ouest</td></tr>
<tr><td>Sud</td> <td>Est</td></tr>
</table>
</section>
<section>
<span class="eng">(en anglais : <code>CRS.AXIS</code>)</span>
<h2 id="CRS.AXIS">AXE.SRS</h2>
<p>
Retourne le nom d’un axe d’un système de référence de coordonnées avec ses unités.
Cette fonction attend en arguments le code 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.
</p>
<table>
<caption>Exemples</caption>
<tr><th>Formule</th> <th>Résultat</th></tr>
<tr><td><code>=AXE.SRS("EPSG:4326"; 1)</code></td> <td>Latitude (°)</td></tr>
<tr><td><code>=AXE.SRS("EPSG:4326"; 2)</code></td> <td>Longitude (°)</td></tr>
<tr><td><code>=AXE.SRS("EPSG:32758"; 1)</code></td> <td>Easting (m)</td></tr>
<tr><td><code>=AXE.SRS("EPSG:32758"; 2)</code></td> <td>Northing (m)</td></tr>
</table>
</section>
<section>
<span class="eng">(en anglais : <code>TRANSFORM.POINTS</code>)</span>
<h2 id="TRANSFORM.POINTS">TRANSFORM.POINTS</h2>
<p>
Applique un changement (transformation ou conversion) de coordonnées sur des points.
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 :
</p>
<ul>
<li>Le code du système de référence source.</li>
<li>Le code du système de référence destination.</li>
<li>La plage de coordonnées à transformer.</li>
</ul>
<p>
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 transformées (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 <code><a href="#CRS.AXIS">AXE.SRS</a></code> pour le libellé des colonnes.
</p><p>
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 <code><a href="#TRANSFORM.ACCURACY">PRECISION.TRANSFORM</a></code>
avec les mêmes arguments que ceux qui auront été spécifiés à <code>TRANSFORM.POINTS</code>.
</p>
</section>
<section>
<span class="eng">(en anglais : <code>TRANSFORM.ENVELOPE</code>)</span>
<h2 id="TRANSFORM.ENVELOPE">TRANSFORM.ENVELOPPE</h2>
<p>
Applique un changement (transformation ou conversion) une boîte englobante.
Cette fonction prend les mêmes arguments que <code><a href="#TRANSFORM.POINTS">TRANSFORM.POINTS</a></code>,
mais ne retournera que deux lignes. La première ligne contiendra les coordonnées transformées minimales alors
que la second ligne contiendra les coordonnées transformées maximales.
Ce résultat peut être différent de celui que l’on obtiendrait en transformant d’abord les points
puis en prenant leurs minimums et maximums. La raison de cette différence est que cette fonction
<code>TRANSFORM.ENVELOPPE</code> prend en compte la courbure de la boîte englobante sous l’effet
d’une projection cartographique ou autre transformation.
</p>
</section>
<section>
<span class="eng">(en anglais : <code>TRANSFORM.ACCURACY</code>)</span>
<h2><a id="TRANSFORM.ACCURACY">PRECISION.TRANSFORM</a></h2>
<p>
Retourne une <strong>estimation</strong> 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 sont spécifiés à la fonction
<code><a href="#TRANSFORM.POINTS">TRANSFORM.POINTS</a></code>.
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 limites de l’arithmétique en virgule flottante,
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).
</p><p>
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 <cite>transformation de coordonnées</cite> selon la terminologie de la norme
<abbr title="Organisation internationale de normalisation">ISO</abbr> 19111.
Lorsque le calcul consiste par exemple à appliquer une projection cartographique sans changer de référentiel,
on parle alors de <cite>conversion de coordonnées</cite> (toujours selon la terminologie de la norme <abbr>ISO</abbr>).
Dans ce dernier cas, la fonction <code>TRANSFORM.ACCURACY</code> peut retourner 0,
ce qui signifie l’opération a une précision infinie en théorie.
En pratique, Apache <abbr>SIS</abbr> est limitée par la précision des calculs à virgules flottantes
ainsi que par les approximations utilisées pour certaines formules non-linéaires.
L’erreur ne sera donc <em>pas réellement</em> nulle, mais devrait être faible.
</p>
</section>
</body>
</html>