Warning: Most maps are protected by laws on copyright. Before using a map with Multiplans, make sure you have the right to do so!

Importing a map

There are several ways to import a map into Multiplans:

• If the map comes from a website and can be downloaded by Atlas Mobile Creator (example: OpenStreetMap maps, topographic maps of New Zealand ...), importing the map in Multiplans is particularly simple. Use Mobile Atlas Creator to download the map and save it as OSZ, which is a format of maps directly recognized by Multiplans.
  
  Step-by-step instructions


• (General case) If you own a map, it is always possible to import it into Multiplans. All you need to do is to create a zip archive that contains:
  • the map image in a standard graphics file format (such as jpeg, tiff or png)
  • a calibration file (.map or ref.txt) that contains geographical informations on the map. Those informations are necessary to enable GPS localization on the map. If no calibration file is provided, the map can still be imported into Multiplans (no need then to compress it into a zip archive), but all functions related to GPS localization will be disabled.
    
    
  
  Supported graphics file formats
  Multiplane recognizes the following graphic file formats: jpeg, tiff, png, bmp, gif, xbm and OSZ.

  The ECW format is currently not recognized by Multiplans. To import an ECW map, you need to convert it first into one of the supported formats. On MacOS, this can be done for example by using program GraphicConverter.

  The map may have an arbitrary size. Some users have imported in Multiplans maps that are over 1 GB and cover a whole country. In the current version of Multiplan, the zip file containing the map must not exceed 2 GB If needed, it is possible to bypass this size limit without much difficulty.

Program MAPC2MAPC (£10, windows) can take a wide range of calibration files (including ECW, GeoTIFF, .MAP, .KAP, .JPR, .CAL, .TAB, .TFW, .JPW, .PGW and KMZ and KAP combined files) and image formats and write different outputs, including an osz map archive that can be imported directly into Multiplans. If needed, MAPC2MAPC reprojects the map to Mercator and cuts the image into tiles. Though writing a ref.txt calibration file is not difficult, MAPC2MAPC allows to import calibrated maps into Multiplans by just pointing and clicking.

Optimization: cutting the map into tiles
When importing a map, Multiplans slices the map image into tiles of size 256x256 pixels (this is needed to display the map on the iPhone). Although the code that slices the map has been carefully optimized, it can take some time on very large maps. To speed up importing very large maps, it is recommended to cut the map image into tiles on a computer before importation into Multiplans. There is no need to do this slicing in the case of maps saved as OSZ because these maps are already cut into tiles.
Instructions for cutting a map into tiles

The next two sections contain more information on the transfer of a map in Multiplans, and on creating a calibration file.

Adding a map into Multiplans

There are two ways to add a map in Multiplans (the map must be an OSZ file, a zip archive, or a simple image file):

• transfer the map by wifi using the web gateway.
• transfer the map by USB cable using iTunes

To transfer a map, open the "Add maps" screen by tapping on the on the main screen Multiplans.
When the "Add maps" screen is opened, a web gateway is created at the address indicated (http://192.168.1.83:8080 in this example). Connect to this gateway to transfer the map from the computer into Multiplans.
Step-by-step instructions

To transfer a map by USB cable using iTunes:

1. Open iTunes, and select your iPhone.
2. Go under "Apps" and select Multiplans.
3. Click on button "Add..." to add a new map.
4. After iTunes transfered your map to the iPhone, open the "Add maps" screen in Multiplans. Importation of the map transferred in step 3 should then start right away.

Note: Do not use iTunes to delete maps in Multiplans. For that, use the "Delete map" button in Multiplans.

Calibration of a map

GPS positioning is available only on maps that are calibrated. Calibrating a map amounts to give some information on the map (calibration points and cartographic projection), information that is necessary to locate a point on the map from its geographic coordinates. As already mentioned, maps in OSZ format are calibrated automatically.

The calibration information is often provided with the map. Maps in ECW, GeoTIFF and GeoPDF formats contain the calibration information inside the file. Other maps are supplied with a separate calibration file, such a a .map file, or a world file with extension tfw, jpw or ers. If no calibration file is provided with the map (case of a scanned map sheet for example, or of a map obtained by a screenshot), it is possible to calibrate it manually.

A strong point of Multiplans is that it knowns about a large number of cartographic projections. Thanks to this, it is possible to have very accurate GPS positioning, correct down to a pixel, on all kinds of maps, be it a Swiss map (based on an oblique Mercator projection), and English Ordnance Survey map, or a map of any other country.

For maps whose projection is not known, it is possible to calibrate it approximately by entering a few calibration points; Multiplans then interpolates the coordinates between the given calibration points.

Multiplane accepts two types of calibration files:

• a .map calibration file (created for example by OziExplorer).
• a ref.txt calibration file, consisting in some simple text lines.

Calibration method 1: .map file

As many maps come with a .map calibration file, providing this file to Multiplans is often the easiest method. In the absence of .map file, you can conveniently create such a calibration file using OziExplorer (commercial program, but a demo version fully working for 1 hour is available). Note that though OziExplorer is a Windows program, the free program wine (see also winebottle and Play on Mac ) allows to run OziExplorer on MacOS without problems.

Warning: .map files are only partially supported. Multiplans uses currently always bilinear interpolation with maps that are calibrated via the a .map file method. The bilinear interpolation is performed using the four calibration points that are specified in the lines MMPXY and MMPLL in the .map file. If the map projection indicated during calibration in OziExplorer is "Lat / Long" (which is the most frequent case), the calibration will be as accurate in Multiplans as in OziExplorer. If the map uses a projection other than "Latitude / Longitude" (see line 9 in the .map file after keyword "Map Projection"), there may be differences between the calibration in Multiplans and the one in OziExplorer (especially if the map has a large extent). In the case where the automatic conversion of the .map calibration file did not produce good results, you need to calibrate the map by providing a calibration ref.txt file.

Apart from the case of (pseudo) projection "Lat / Long" (for which the .map calibration method is exact), we can expect, in general, that the .map file calibration method will be accurate if lines of constant longitude, and lines of constant latitude, show no significant curvature and their spacing is regular. The curvature of these lines appear typically on maps that have a geographical extent of more than 100 km.

Calibration method 2: ref.txt 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).

Note that the ref.txt calibration file for maps from some mapping web sites (for instance Google Maps, maps from the French, Swiss and English geoportals, etc..) can be generated automatically! See explanation on page Map viewers .

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 longitude, latitude 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.

Converting calibration files

There exists many different formats for map calibration.

Program MAPC2MAPC (£10, windows) can take a wide range of calibration files (MAP, ECW, GeoTIFF, JPR, various CAL,TAB,IMP,GUX,TFW,JPW,PGW calibrations and KMZ and KAP combined files) and image formats and write different outputs, including an osz map archive that can be imported directly into Multiplans. If needed, MAPC2MAPC reprojects the map to Mercator and cuts the image into tiles.

The following information can help to convert manually a calibration file in a format recognized by Multiplans.

• .map calibration file.MAP. Multiplans automatically recognizes .map calibration files that use the "Lat / Long" projection. If the .map uses another map projection, automatic conversion of the file by Multiplans may be inaccurate. In the latter case, open the .map file with a text editor to read calibration information. Alternatively, use OziExplorer to display the calibration information of the map (menu "Check calibration of map").
  
  
• Map in ECW: calibration information are contained within the file, and can be read using programs such as:
  • ECW header editor : a program for Windows.
  • ecwhed : command line tool for Linux
  • GDAL (Mac, Linux, Windows): Use the command-line tool gdalinfo. (See KyngChaos to install this library on Mac).
  Then simply use the information found in the header of the ECW file to write the ref.txt file, as explained in this example .
  
  
• GeoTIFF format map: Use eg gdalinfo to read the calibration information, and proceed as in the case of ECW maps.
  
  
• Map with a "world" calibration file .jpw, .tfw, .jgw, .jpegw or .bpw. These calibration files contain almost all the information needed to calibration. The structure of these files is:
  
  Calibration file .jpw, .tfw ...
  5.25
  0.0
  0.0
  -5.25
  6270000.00
  18262000.00
  

  <- Line 1: horizontal resolution (often in m/pixel)
  <- Line 2: rotation
  <- Line 3: rotation
  <- Line 4: vertical resolution (ignore the minus sign!)
  <- Line 5: X coordinate
  <- Line 6: Y coordinate (the upper-left corner of the map)
  
  A "world" calibration file can be easily converted into a ref.txt calibration file: write the coordinates of the top-left point calibration for pixel position 0, 0, and use the keyword "resolution" . The only difficult part is identifying the map projection used by the map, a piece of information that has to be entered on the first line of the file ref.txt. (See document geocoded TIFF & JPEG files for more information about calibration files).


• Calibration file ERS: A calibration file.ERS contains all the information necessary for referencing a map in an easily readable format.


• Map from a mapping website. If the website displays the coordinates of the point under the mouse, it is easy to determine calibration points on the map. Examples are given below. See also page Map Viewer that allows to generate automatically ref.txt calibration files.
  
  

Examples of map calibration

Reminder: page Map viewers can generate automatically the calibration file of some mapping web sites.

• Calibration of a Swiss topographic map: see above .


• Calibration of a french Geoportal map
  
  
  The French Geoportal uses a map projection that does not have currently an EPSG number, but it can be defined in Multiplans by writing the following line
  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
  on the first line of file ref.txt.
  View the above map in the geoportal by following the link Geoportal: Abondance map. For good accuracy, choose to display the coordinates in the Lambert II extended system. Also select the zoom tool to get the cross pointer, which is much more accurate than the hand pointer! We can determine the geographical coordinates of the two calibration points marked in the image above:
  • calibration point 1 (altitude 1317): X = 936113 Y = 2152873
  • calibration point 2 (altitude 1399): X = 939033 Y = 2151088.
  We cannot use directly these Lambert II coordinates in ref.txt calibration file, because the Geoportal maps do not actually use the Lambert Conic projection, but the equidistant cylindrical projection defined in the above line with keyword "PROJ." With the help of a coordinate converter , one can find the GPS coordinates of calibration points:
  • calibration point 1: longitude = 6.7011167, latitude = 46.292001 (pixel coordinates: 98, 34)
  • calibration point 2: = 6.7376587 longitude, latitude = 46.274502 (pixel coordinates: 797, 521)
  We also determined the pixel coordinates of the calibration points.
  (On MacOS, the pixel coordinates can be found by using the keyboard shortcut Command + Shift 4 which allow to make a copy of an area of ​​the screen; during the selection of the area, the pixel coordinates are displayed, press 'esc' to cancel the screenshot).

  Using the above information, we can write the following calibration file for this map:

  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: For a map of modest size as above, the method of bilinear interpolation would also have provided accurate results. The advantage of calibrating the map using the PROJ library is that this method works for maps as large as desired!
  
  
• Calibration of an English map of Ordnance Survey
  Let us calibrate the map above, which can be viewed using the full screen viewer of Peter Robins. The Ordnance Survey maps use a Transverse Mercator projection with EPSG number: 27700.
  Coordinates in meters of the point under the pointer can be read in the upper right corner of the map window (see the values ​​outlined in red in the picture above). We can determine the following coordinates:
  
  - Top-left corner of the map: X = 405284 Y = 259604
  - Bottom-right corner of the map: X = 649884 Y = 89404.
  
  The size of the map above is 1225 x 854 pixels. The calibration file of this map can be written as follows:
  EPSG: 27700
  0, 0 = 405284, 259604
  1225, 854 = 649 884, 89404
  Download this map: 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

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



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