Méthodes mathématiques
Etape 1

La forme de la Terre est très irrégulière et ne peut être représentée exactement au moyen d'un objet géométrique simple. Toutefois, pour la plupart des applications, il est possible de l'approximer soit par un ellipsoïde de révolution, soit par une sphère.

L'approximation par un ellipsoïde est la plus précise, car la Terre est légèrement aplatie aux pôles. Pour cette raison, une telle approximation est utilisée lorsqu'une précision importante est requise. Par exemple, les coordonnées obtenues au moyen d'un appareil GPS (longitude et latitude) font référence à un ellipsoïde.

Pour les applications nécessitant une précision moindre, il est également possible d'approximer la forme de la Terre par une sphère. En effet, son aplatissement aux pôles est faible — environ 0.3% — et elle est donc quasi sphérique.

Pour le dessin de panoramas, l'approximation sphérique suffit largement et a l'avantage de simplifier les calculs par rapport à l'approximation ellipsoïdale. Nous l'utiliserons donc ici, en admettant que la Terre est une sphère parfaite de rayon R = 6371 km.

Un observateur placé à la surface de la Terre et désirant décrire la position des objets qu'il observe autour de lui — montagnes au loin, étoiles dans le ciel, etc. — peut le faire au moyen d'un système de coordonnées horizontales. Dans un tel système, la position d'un objet est décrite par deux angles :

• l'azimut¹, qui est l'angle horizontal entre un plan vertical de référence (p.ex. celui contenant le nord et le sud géographiques) et le plan vertical contenant l'objet,
• l'angle d'élévation, ou simplement l'élévation, aussi appelée hauteur, qui est l'angle vertical entre le plan horizontal et l'objet désigné.

Ces angles sont illustrés dans l'image ci-dessous. L'observateur se trouve au centre de l'hémisphère, indiqué par O, et le plan de son horizon est grisé. La position du point observé (en rouge) est décrite par son azimut a et son élévation h.

L'azimut est compris entre 0° (inclus) et 360° (exclus), et il croît dans le sens horaire, ce qui est contraire à la convention mathématique. L'image ci-dessous illustre cette convention et montre les azimuts correspondants aux quatre points cardinaux (nord, sud, est et ouest) ainsi qu'aux quatre points intercardinaux principaux (nord-est, nord-ouest, sud-est et sud-ouest). La zone blanche est l'octant entourant le nord et tout azimut correspondant à cette zone sera, dans certaines situations, considéré comme équivalent au nord. Des zones de même tailles, non dessinées, entourent chacun des points cardinaux et intercardinaux.

Notez qu'il serait tout à fait possible de considérer que les valeurs hors de l'intervalle [0°; 360°[ constituent également des azimuts valides, interprétés modulo 360. Par exemple, -45° serait équivalent à 315°, et 370° serait équivalent à 10°. Néanmoins, il est généralement plus simple de manipuler ce que nous nommerons des azimuts canoniques, c-à-d compris dans l'intervalle [0°; 360°[.

L'angle d'élévation est compris entre -90° et 90° (inclus), et 0° correspond à l'horizon, 90° aux points situés verticalement au-dessus de l'observateur (zénith) et -90° aux points situés verticalement au-dessous de lui (nadir).

Différentes fonctions mathématiques seront nécessaires à ce projet et méritent une brève introduction.

La plupart des méthodes de cette étape travaillent sur de simples nombres en virgule flottante de type double. Idéalement, de telles méthodes devraient pouvoir être définies hors de toute classe ou interface, mais Java ne permet pas cela. Dès lors, il faut décider dans quelle classe ou interface les placer.

Une solution souvent utilisée, p.ex. pour la classe Math du paquetage java.lang, consiste à définir de telles méthodes comme des méthodes statiques d'une classe définie uniquement dans ce but. Généralement, le constructeur d'une telle classe est rendu privé, ce qui interdit la création d'instances.

Depuis Java 8, une solution alternative consiste à déclarer ces méthodes comme méthodes statiques d'une interface, et c'est ce que nous avons choisi de faire. Un petit avantage de cette solution est qu'il n'est pas nécessaire de définir un constructeur privé, car une interface n'en a pas. Par contre, elle interdit la définition de méthodes auxiliaires privées, ce qui peut parfois être utile.

Dans tous les cas, il est important de comprendre que ce genre de classes ou interfaces n'ont pas pour but de jouer leur rôle « normal » dans un programme Java : une classe comme java.lang.Math n'a pas pour but d'être instanciée ou de servir de classe mère, et les interfaces définies ci-dessous n'ont pas pour but d'être implémentée par une classe quelconque. Elles ne servent que de conteneur à des méthodes statiques qui devraient être déclarées de manière indépendante si Java le permettait.

A l'utilisation, il est fortement conseillé d'importer statiquement les attributs et méthodes de ces classes ou interfaces, comme dans l'exemple ci-dessous :

import static java.lang.Math.PI;
import static java.lang.Math.sin;

public final class Main {
  public static void main(String[] args) {
    System.out.println("sin(π) = " + sin(PI));
  }
}

Fréquemment, les méthodes d'un programme s'attendent à ce que leurs arguments satisfassent certaines conditions. Par exemple, une méthode prenant un angle en argument peut s'attendre à ce que celui-ci se trouve dans l'intervalle \([0; 2\pi[\). De telles conditions sont parfois appelées préconditions car elles doivent être satisfaites avant l'appel d'une méthode, par l'appelant.

En Java, la convention veut que chaque méthode vérifie ses préconditions et lève une exception — souvent IllegalArgumentException — si l'une d'entre elles n'est pas satisfaite. Par exemple, une méthode m prenant en argument un angle et demandant à ce que celui-ci soit dans l'intervalle \([0; 2\pi[\) pourrait commencer ainsi :

double m(double angle) {
  if (! (0 <= angle && angle < 2 * PI))
    throw new IllegalArgumentException("invalid angle");
  // …
}

L'interface Preconditions du paquetage ch.epfl.alpano a pour but de faciliter l'écriture de telles préconditions. En l'utilisant, la méthode ci-dessus pourrait être récrite ainsi :

import static ch.epfl.alpano.Preconditions.checkArgument;

double m(double angle) {
  checkArgument(0 <= angle && angle < 2 * PI,
                "invalid angle");
  // …
}

Pour ce faire, l'interface Preconditions offre les deux méthodes publiques et statiques suivantes :

• void checkArgument(boolean b), qui lève l'exception IllegalArgumentException, sans message attaché, si son argument est faux, et ne fait rien sinon,
• void checkArgument(boolean b, String message), qui lève l'exception IllegalArgumentException avec le message donné attaché si son argument est faux, et ne fait rien sinon.

L'interface Distance contient des méthodes permettant de convertir des distances à la surface de la Terre de radians en mètres, et inversément. Elle possède un champ public et statique :

• double EARTH_RADIUS, qui donne le rayon de la Terre, en mètres, soit 6371000,

ainsi que les méthodes publiques et statiques suivantes :

• double toRadians(double distanceInMeters), qui convertit une distance à la surface de la Terre exprimée en mètres en l'angle correspondant, en radians,
• double toMeters(double distanceInRadians), qui convertit un angle en radians en la distance correspondant à la surface de la Terre, en mètres.

L'interface Math2 du paquetage ch.epfl.alpano contient différentes méthodes mathématiques utiles au projet. Elle joue un rôle similaire à la classe java.lang.Math de la bibliothèque Java, et lui sert de complément.

Notez qu'il aurait techniquement été possible de nommer cette interface Math au lieu de Math2, car elle est dans un paquetage différent de la classe Math de la bibliothèque Java. En pratique, il est malheureusement pénible d'utiliser deux classes ou interfaces ayant le même nom (non qualifié) dans un seul projet Java, raison pour laquelle nous utilisons Math2.

L'interface Math2 offre un unique champ statique :

• double PI2, qui vaut 2*Math.PI, soit approximativement \(2\pi\),

et les méthodes statiques suivantes :

• double sq(double x), qui retourne x élevé au carré,
• double floorMod(double x, double y), qui retourne le reste de la division entière par défaut de x par y,
• double haversin(double x), qui retourne le demi sinus verse de x,
• double angularDistance(double a1, double a2), qui retourne la différence angulaire de a1 et a2,
• double lerp(double y0, double y1, double x), qui retourne la valeur de f(x) obtenue par interpolation linéaire, sachant que f(0) vaut y0 et f(1) vaut y1 ; notez que x peut être quelconque,
• double bilerp(double z00, double z10, double z01, double z11, double x, double y), qui retourne la valeur de f(x,y) obtenue par interpolation bilinéaire, sachant que f(0,0) vaut z00, f(1,0) vaut z10, f(0,1) vaut z01 et f(1,1) vaut z11 ; notez que x et y peuvent être quelconques,
• double firstIntervalContainingRoot(DoubleUnaryOperator f, double minX, double maxX, double dX), qui cherche et retourne la borne inférieure du premier intervalle de taille dX contenant un zéro de la fonction f et compris entre minX et maxX ; si aucun zéro n'est trouvé, retourne Double.POSITIVE_INFINITY; l'interface DoubleUnaryOperator est décrite plus bas,
• double improveRoot(DoubleUnaryOperator f, double x1, double x2, double epsilon), qui utilise la méthode de la dichotomie pour déterminer un intervalle compris entre x1 et x2, de taille inférieure ou égale à epsilon et contenant un zéro de f, et retourne sa borne inférieure ; lève l'exception IllegalArgumentException si f(x1) et f(x2) sont de même signe.

L'interface Azimuth du paquetage ch.epfl.alpano regroupe les méthodes permettant de manipuler des nombres représentant des azimuts exprimés en radians. Elle possède les méthodes publiques et statiques suivantes :

• boolean isCanonical(double azimuth), qui retourne vrai ssi son argument est un azimut « canonique », c-à-d compris dans l'intervalle \([0; 2\pi[\),
• double canonicalize(double azimuth), qui retourne l'azimut canonique équivalent à celui passé en argument, c-à-d compris dans l'intervalle \([0; 2\pi[\),
• double toMath(double azimuth), qui transforme un azimut en angle mathématique, c-à-d exprimé dans le sens antihoraire, ou lève l'exception IllegalArgumentException si son argument n'est pas un azimut canonique,
• double fromMath(double angle), qui transforme un angle mathématique en azimut, c-à-d exprimé dans le sens horaire, ou lève l'exception IllegalArgumentException si l'argument n'est pas compris dans l'intervalle \([0; 2\pi[\),
• String toOctantString(double azimuth, String n, String e, String s, String w), qui retourne une chaîne correspondant à l'octant dans lequel se trouve l'azimut donné, formée en combinant les chaînes n, e, s et w correspondant aux quatre points cardinaux (resp. nord, est, sud et ouest), comme décrit ci-dessous ; lève l'exception IllegalArgumentException si l'azimut donnée n'est pas canonique.

La méthode toOctantString a pour but de transformer un azimut en le nom de l'octant qui le contient. Chaque octant couvre une zone de 45° centrée sur chaque point cardinal ou intercardinal, comme illustré à la figure 2. Par exemple, appliquée à l'azimut \(\tfrac{\pi}{6}\) (30°) et aux chaînes "N", "E", "S" et "W" (dans cet ordre), elle retourne la chaîne "NE".

Pour vous aider à démarrer ce projet, nous vous fournissons exceptionnellement une archive Zip contenant des tests unitaires JUnit pour cette étape.

Pour pouvoir utiliser ces tests, il vous faut tout d'abord les importer dans votre projet en suivant les indications d'importation d'archive Zip dans Eclipse, puis ajouter la bibliothèque JUnit à votre projet, en suivant les explications à ce sujet.

Une fois les tests exécutés avec succès, il vous reste à documenter la totalité des entités publiques (classes, attributs et méthodes) définies dans cette étape, au moyen de commentaires Javadoc, comme décrit dans le guide consacré à ce sujet. Vous pouvez écrire ces commentaires en français ou en anglais, en fonction de votre préférence, mais vous ne devez utiliser qu'une seule langue pour tout le projet.