Ref.txt calibration file

The method of calibrating maps by writing a ref.txt calibration file is powerful and versatile. The idea is to specify some calibration points on the map (typically 4, but 2 may be sufficient). A calibration point is a point on a map for which one specifies its geographic coordinates (longitude and latitude, or coordinates in a given map projection). In the ref.txt file, one can also specify the cartographic projection used by the map. This information is generally required to obtain good accuracy in the calibration of large maps (covering areas of more than 100 km).

A ref.txt calibration file is a plain text document that can be written using eg TextEdit (on MacOS) or NotePad (on Windows). Note that Multiplans adopts the convention that the GPS coordinates are given in the order longitude, latitude (and not the reverse order latitude, longitude as in Google Maps).

Two cases may arise:

(A) Case of a map whose cartographic projection is unknown

If the used map projection is unknown, one can calibrate approximately the map by specifying four (or possibly only 2) calibration points on the map. The best results are obtained with four calibration points located near the four corners of the map.

The 1st line of file ref.txt contains the keyword "Bilinear interpolation", which tells Multiplans that it should interpolate or extrapolate the coordinates from the 4 (or 2) calibration points that are given in the next few lines in the file.
The calibration points are entered as lines of the form where x and y are the coordinates (in pixels) of a point on the map, and "longitude, latitude" are the corresponding GPS geographical coordinates of this point (WGS84 datum). The coordinates x = 0, y = 0 corresponds to the upper-left corner of the image, while the point x = 0, y = 8000 pixels is located 8000 pixels below, on the left edge of the image. In this example, the four calibration points are located at the corners of a map of size 8000x8000 pixels, but it is not mandatory to put the calibration points exactly at the corners of the image. The four points must be put at the vertices of a rectangle or of a quadrilateral that is a "not too distorted" rectangle (technically speaking: the quadrilateral must be convex). If three calibration points are aligned along a straight line, the results will not be good!

To find the coordinates (in pixels) of a point on an image, one can use eg GraphicConverter (on MacOS), menu "Windows -> Contact." Alternatively, one can Multiplans to find these coordinates: Import the map without calibration file, and then create a point-of-interest on the map. The information screen on the point of interest displays the pixel coordinates of that point. (In a future version of Multiplan, it will be possible to indicate graphically the calibration points on the map, without having to write a ref.txt calibration file)

The method of bilinear interpolation with 4 points gives in general good results for maps that have a not too large geographical extent (less than 100 km). In the case where the lines of constant longitude (and those of constant latitude) are aligned along the vertical (respectively along the horizontal) direction, it is sufficient to specify only two calibration points. In that case, choose the two calibration points to lie approximately near two diagonally opposite corners of the map.

(B) Case of a map that uses a known projection

This is the ideal case, where we know the cartographic projection used by the map. We can then specify the projection on the first line of the ref.txt file and enter in the following lines of the file only two calibration points. 2 points are indeed sufficient to obtain an exact calibration when the map projection is known. (Warning: specify only 2 calibration points and not more!)

The map projection can be specified either by the keyword "EPSG:" followed by the EPSG projection number or by the keyword "PROJ", followed by a series of keywords describing this projection in the language PROJ library.

Note that if one enter the geographical coordinates of calibration points in the WGS84 system, that is by their GPS coordinates, we have to add the keyword "(WGS84)" after the coordinates (warning: do not write "WGS 84" with a space, but "WGS84"). The syntax for a calibration point is then In the absence of keyword "WGS84", the coordinates are interpreted as being expressed in the system of the map projection defined in the first line of file ref.txt.

To find the EPSG number of a cartographic projection, see table on next page .

Instead of specifying the EPSG projection number, the cartographic projection can be described by using the keywords of the library PROJ4. This is particularly useful when the projection has no assigned EPSG number. Another advantage of using the description by the PROJ library is that the various parameters that enter in the definition of the projection are explicitly mentioned. The first line of the file ref.txt begins then by keyword "PROJ" (instead of "EPSG"), as in the following example:
To find how to describe a map projection using the PROJ library, refer to the next page .

In any case, we can check if a ref.txt calibration file is correct by adding a point of interest on the map, and by checking if its shown longitude and latitude coordinates are correct.

Variation: 1-point calibration and resolution
Instead of giving two calibration points, it is possible to give only one point, and to enter in the next line of the file ref.txt, the resolution of the map. For the Swiss map above, we could also write the following calibration files: The resolution of the map must be entered in "unit of cartographic coordinates" / pixel. For example, if the X and Y coordinates are measured in meters, the resolution must be given in meters per pixel.
If the geographic coordinates of the calibration point are given in the WGS84 system, the concomitant use of keyword "resolution" requires version 1.41 (or later) of Multiplans to work properly.

Note: The syntax of the ref.txt has evolved since the first version of Multiplans. The syntax used by the first versions of Multiplans ( see here ) is still accepted, but it is not recommended for use.

Note: In the current version, Multiplans assumes that the map has not been rotated relative to the cartographic projection defined in the first line of file ref.txt. This means that the lines with coordinate X = constant (or Y = constant) (where X and Y are the coordinates defined by the map projection, such as Swiss coordinates) must be horizontal (resp. vertical), as in the example of the Swiss map above. If the map shows a grid of X, Y coordinates which has been rotated, use a drawing program to compensate for the rotation before calibrating the map. The compensation of the rotation must be done for instance in the case of some scans of IGN map sheets: introduce a rotation so that the small black crosses corresponding to the Lambert grid are aligned horizontally and vertically (the problem of rotation applies only to scans of maps IGN paper, not to the maps coming from the IGN geoportal). See this document of Raymondo.

Fichier de calibrage ref.txt

La méthode de calibrage par écriture d'un fichier de calibrage ref.txt est puissante et versatile. L'idée est de préciser quelques points de calibrage sur la carte (typiquement 4, mais 2 peuvent suffire). Un point de calibrage est un point auquel on associe des coordonnées géographiques données (coordonnées de longitude et de latitude, ou coordonnées correspondant à une certaine projection cartographique). Lors du calibrage, on peut également préciser la projection cartographique employée par la carte. Cette information est en général nécessaire pour obtenir une bonne précision dans le calibrage de grandes cartes (couvrant des zones de plus de 100 km).

Noter que le fichier de calibrage ref.txt pour des cartes provenant de certains sites web cartographiques (en particulier les cartes Google maps, les cartes des géoportails français, suisse, anglais, etc.) peuvent être générés automatiquement! Voir explications à la page Visualiseurs de cartes.

Un fichier de calibrage ref.txt est un simple document de texte, que l'on peut écrire par exemple avec TextEdit (sur MacOS) ou NotePad (sur Windows). Noter que Multiplans adopte la convention que les coordonnées GPS sont toujours données dans l'ordre longitude, latitude (et non l'ordre inverse longitude, latitude comme dans Google Maps).

Deux cas peuvent se présenter:

(a) Cas d'une carte de projection cartographique inconnue

Si la projection cartographique utilisée est inconnue, on peut calibrer approximativement la carte en spécifiant 4 (ou éventuellement que 2) points de calibrage sur la carte. Les meilleures résultats seront obtenus avec 4 points de calibrage situés non loins des quatre coins de la carte.

La 1re ligne du fichier ref.txt contient le mot-clé "Bilinear interpolation", qui indique à Multiplans qu'il doit interpoler, voire extrapoler, les coordonnées à partir des 4 (ou 2) points de calibrage indiqués dans les lignes suivantes du fichier.
Les points de calibrage sont donnés à l'aide de lignes de la forme où x et y sont les coordonnées (en pixels) d'un point sur la carte, et "longitude, latitude" sont les coordonnées géographiques correspondantes de ce point (dans le datum WGS84, c'est-à-dire les coordonnées GPS du point). Le point de coordonnées x=0,y=0 correspond au coin en haut à gauche de l'image, tandis que le point x=0,y=8000 est situé 8000 pixels plus bas sur le bord gauche de l'image. Dans cet exemple, les 4 points de calibrage sont situés aux quatre coins d'une carte de dimensions 8000x8000 pixels, mais il n'est pas obligatoire de positionner les points exactement aux coins de l'image. Les 4 points doivent être placés aux sommets d'un rectangle, ou d'un quadrilatère correspondant à un rectangle "pas trop déformé" (techniquement parlant: le quadrilatère doit être convexe). Si 3 points de calibrage sont alignés selon une droite, les résultats ne seront pas bons!

Pour trouver les coordonnées (en pixels) d'un point sur une image, on peut utiliser par exemple GraphicConverter (sur MacOS), menu "Fenêtres-->Coordonnées". Alternativement, on peut utiliser Multiplans pour trouver ces coordonnées: importer la carte sans fichier de calibrage, puis créer un point d'intérêt sur la carte. L'écran d'information sur le point d'intérêt affiche les coordonnées pixels du point. (Dans une version future de Multiplans, il sera possible d'indiquer graphiquement les points de calibrage sur la carte, sans passer par l'écriture d'un fichier de calibrage ref.txt)

La méthode d'interpolation bilinéaire à 4 points donne en général de bons résultats pour des cartes d'une étendue géographique pas trop grande (moins de 100 km). Dans le cas où les lignes de longitude constante (et de latitude constante) sont alignées selon la verticale (respectivement selon l'horizontale), il est suffisant de ne spécifier que 2 points de calibrage. Choisir alors ces deux points de calibrage approximativement vers 2 coins diagonalement opposés de la carte.

(b) Cas d'une carte de projection cartographique connue

Il s'agit du cas idéal, où l'on connaît la projection cartographique employée par la carte. On peut alors indiquer cette projection sur la première ligne du fichier ref.txt et ne spécifier dans les lignes suivantes que 2 points de calibrage. 2 points sont en effet suffisants pour obtenir un calibrage exact lorsque la projection cartographique est connue. (Attention: ne mettre que 2 points de calibrage, et non pas 4!)

La projection cartographique peut être indiquée soit par le mot-clé "EPSG:" suivi du numéro EPSG de la projection, soit par le mot-clé "PROJ:", suivi d'une suite de mot-clés décrivant cette projection dans le langage de la librairie PROJ.

Noter que si l'on indique les coordonnées géographiques des points de calibrage dans le système WGS84, autrement dit par leur coordonnées GPS, il faut ajouter le mot-clé "(WGS84)" après les coordonnées (attention: ne pas écrire "WGS 84" avec un espace, mais bien "WGS84"). La syntaxe pour un point de calibrage est alors En l'absence de ce mot-clé "WGS84", les cordonnées sont interprétées comme étant données dans le système de projection cartographique défini dans la première ligne du fichier ref.txt.

Pour trouver le numéro EPSG d'une projection, se référer au tableau à la page suivante.

Au lieu d'indiquer la projection par son numéro EPSG, on peut la décrire au moyen des mot-clés de la librairie PROJ4. Cela est particulièrement utile dans le cas où la projection n'a pas encore de numéro EPSG attribué. Un autre avantage d'utiliser la description par la librairie PROJ est que les différents paramètres entrant dans la définition de la projection sont explicitement mentionnés. La première ligne du fichier ref.txt commence alors par le mot-clé "PROJ:" (au lieu de "EPSG:"), comme dans l'exemple suivant:
Pour trouver comment décrire une projection cartographique en utilisant la librairie PROJ, se référer à la page suivante.

Dans tous les cas, on peut vérifier si un fichier de calibrage ref.txt est correct en créant un point d'intérêt sur la carte, et en vérifiant si les coordonnées de longitude et latitude de ce point calculées par Multiplans sont correctes.

Variante: calibration à 1 point et résolution
Au lieu de donner deux points de calibrage, il est possible de ne donner qu'un seul point, et d'indiquer, dans le ligne suivante du fichier ref.txt, la résolution de la carte. Pour la carte suisse ci-dessus, on aurait pu par exemple également écrire les fichiers de calibrage suivants: Attention: le mot-clé à utiliser est bien "resolution" (sans accent car en anglais), et non "résolution". La résolution de la carte doit être indiquée en "unité de coordonnées cartographiques"/pixel. Par exemple, si les coordonnées X et Y sont mesurées en mètre, la résolution doit être donnée en mètres par pixel.
Si les coordonnées géographiques du point de calibration sont données dans le système WGS84, l'utilisation concomittante du mot-clé "resolution" ne fonctionne correctement qu'à partir de la version 1.41 de Multiplans.

Remarque: La syntaxe du fichier ref.txt a evolué depuis la première version de Multiplans. La syntaxe utilisée par les premières versions de Multiplans (voir ici) est toujours acceptée, mais il n'est pas recommandé de l'utiliser.

Remarque: Dans la version actuelle, Multiplans suppose que la carte n'a pas subi de rotation par rapport à la projection cartographique définie dans la première ligne du fichier ref.txt. Cela signifie que les lignes de coordonnées X=constante (ou Y=constante) (où X et Y sont les coordonnées cartographiques définies par la projection cartographique, par exemple les coordonnées suisses) doivent être horizontales (resp. verticales), comme dans l'exemple de la carte suisse ci-dessus. Si la carte montre une grille de coordonnées X,Y qui a subi une rotation, il faut utiliser un programme de dessin pour compenser cette rotation avant de calibrer la carte. Cette compensation de la rotation doit être effectuée dans le cas de scans de certaines cartes IGN papier: introduire une rotation de sorte que les petites croix noires de la grille Lambert soient alignées horizontalement et verticalement (ce problème de rotation ne concerne que les scans de cartes IGN papier, et non les cartes IGN du géoportail). Voir ce document de Raymondo.

Exemples de calibrage de cartes

Rappel: la page Visualiseurs de cartes permet de générer automatiquement le fichier de calibrage de cartes de certains sites web.

• Calibrage d'une carte suisse de swisstopo: voir plus haut.


• Calibrage d'une carte du Géoportail français
  
  
  Le géoportail français utilise une projection cartographique qui n'a pas actuellement de numéro EPSG, mais qui peut être définie dans Multiplans en écrivant le texte suivant
  PROJ:+proj=eqc +nadgrids=null +towgs84=0,0,0 +a=6378137 +rf=298.257222101 +lat_0=0 +lon_0=0 +lat_ts=46.5 +x_0=0 +y_0=0 +units=m +no_defs
  dans la première ligne du fichier ref.txt.
  Afficher la carte ci-dessus dans le géoportail en suivant le lien Géoportail: carte d'Abondance. Pour une bonne précision, choisir d'afficher les coordonnées dans le système Lambert II étendu. Sélectionner également l'outil de zoom pour avoir un curseur en forme de croix, plus précis que la main pour relever des positions! On détermine alors les coordonnées géographiques des deux points de calibrage marqués dans l'image ci-dessus:
  • point de calibrage 1 (à l'altitude 1317): X=936113, Y=2152873
  • point de calibrage 2 (à l'altitude 1399): X=939033, Y=2151088.
  On ne peut pas utiliser directement ces coordonnées Lambert dans le fichier de calibrage ref.txt, car les cartes du géoportail n'utilisent en fait pas la projection conique de Lambert, mais la projection cylindrique équidistante définie dans la ligne "PROJ". A l'aide d'un convertisseur de coordonnées, on peut trouver les coordonnées GPS des points de calibrage:
  • point de calibrage 1: longitude=6.7011167, latitude=46.292001 (coordonnées pixels: 98, 34)
  • point de calibrage 2: longitude=6.7376587, latitude=46.274502 (coordonnées pixels: 797, 521)
  On a également déterminé les coordonnées pixels des points de calibrage.
  (Sur MacOS, les coordonnées pixels peuvent être trouvées en utilisant le raccourci clavier commande+majuscule+4 qui sert à faire une copie d'une zone de l'écran; durant la sélection de la zone, les coordonnées pixels sont affichées; appuyer sur la touche 'esc' pour annuler finalement la copie d'écran).

  A l'aide des informations ci-dessus, on peut écrire le fichier de calibrage suivant pour cette carte:

  PROJ:+proj=eqc +nadgrids=null +towgs84=0,0,0 +a=6378137 +rf=298.257222101 +lat_0=0 +lon_0=0 +lat_ts=46.5 +x_0=0 +y_0=0 +units=m +no_defs
  98, 34 = 6.7011167, 46.292001 (WGS84)
  797, 521 = 6.7376587, 46.274502 (WGS84)
  
  Note: Pour une carte de taille modeste comme ci-dessus, la méthode d'interpolation bilinéaire aurait fourni également des résultats de très bonne précision. L'avantage de calibrer la carte via la librairie PROJ est que cette méthode fonctionne pour des cartes aussi grandes que désiré!
  
  
• Calibration d'une carte anglaise de l'Ordnance Survey
  Calibrons la carte ci-dessus, que l'on peut visualiser à l'aide du visualisateur plein écran de Peter Robins. Les cartes de l'Ordnance Survey emploient une projection de Mercator transverse portant le numéro EPSG:27700.
  Les coordonnées en mètres du point sous le curseur peuvent être lues dans le coin supérieur droit de la fenêtre de visualisation (voir les valeurs encadrées en rouge dans l'image ci-dessus). On peut déterminer les coordonnées suivantes:
  
  - coin haut-gauche de la carte: X = 405284, Y = 259604
  - coin bas-droite de la carte: X = 649884, Y = 89404.
  
  La taille de la carte ci-dessus est 1225 x 854 pixels. Le fichier de calibrage de cette carte peut donc s'écrire comme suit:
  EPSG:27700
  0, 0 = 405284, 259604
  1225, 854 = 649884, 89404
  Télécharger cette carte: England_SouthEast.zip


• Calibration of a Google Map
  
  

Google Maps zoom level	Resolution (in m/pixel)
0	156543.03392
1	78271.51696
2	39135.75848
3	19567.87924
4	9783.93962
5	4891.96981
6	2445.98490
7	1222.99245
8	611.49622
9	305.74811
10	152.87405
11	76.43702
12	38.21851
13	19.10925
14	9.55462
15	4.77731
16	2.38865
17	1.19432
18	0.59716
19	0.29858

The resolutions in this table have been calculated with formula

res = π R / (256 * 2^(z-1))

where π = 3.1415926536, R = 6378137 meters is the radius of
the Earth and z is the zoom level.
Let us calibrate the above Google map of the city center of Palma de Majorca, which can be opened by clicking here.
Google Maps (and other similar sites such as Yahoo maps, Bing maps, myTopo.com, ...) use a spherical Mercator projection which bears number EPSG:3857.

To determine the geographical coordinates of a point on the map, right-click on it, and choose item "More info on this location". The longitude and latitude coordinates of the point will then appear in the search bar above the map. One can determine in this way the GPS coordinates of two calibration points, and enter this information (together with the pixel coordinates of the 2 points) in the calibration file ref.txt as in the previous examples.

One can actually avoid having to measure pixel coordinates by using the following method: click on the "link" button which lies next to the "print" and "envelope" icons in the toolbar above the map. This opens a window which contains a link to the map. Find in the link the part that looks like
ll=39.570152,2.647512&spn=0.011926,0.021715&t=h&vpsrc=6&z=16
The two numbers after "ll=" are the latitude and longitude of the map center, while the number after "z=" is the zoom level. Using this information, one can write the following calibration file
EPSG:3857
center = 2.650709, 39.570086 (WGS84)
resolution: 2.38865
where the resolution is found by looking at the table to the right.
This calibration file, which uses simultaneously coordinates in datum WGS84 and the keyword "resolution" keyword requires version 1.41 (or later) of Multiplans to work properly.


• Calibration of a US topographic map (myTopo / USGS map)
  
  
  Site gmap4 can be used to view conveniently maps produced by the USGS. The above map of Yellowstone National Park can be opened in gmap4 by clicking here (with myTopo tiles) or here (with US topo tiles). The source of the "US topo" tiles is the Microsoft Research Maps project, whose maps can be used freely.
  These maps use the same spherical Mercator projection as Google Maps, whose projection number is EPSG:3857.
  One can calibrate this map by giving two calibration points. This is easily done, as right-clicking on a point in the map opens a window that gives the longitude and latitude coordinates of that point.
  
  To avoid having to measure the pixel coordinates of the calibration points, a good choice is to take the first calibration point to lie in the middle of the map (the geographical coordinates of that point are always shown in the lower-right part of the map in gmap4, see picture above), and the second calibration point to be at the top-left corner of the map. For the above map, one finds in this way the following calibration file:
  EPSG:3857
  center = -110.843983, 44.469990 (WGS84)
  0, 0 = -110.881749, 44.488699 (WGS84)