Question 5 - How do I prepare a raster file for use in METool and the Mapping Engine?
This document guides you through the process of taking an arbitrary image (chart, map, aerial photograph, etc.) and converting it into content that can be rendered by the BA3 Mapping Engine on iOS.
You will convert your source image into an image with an alpha channel, then convert that into a geo-referenced TIFF image (geotif) that can be processed by the BA3 Mapping Engine Tool (METool - see Question 2). Once processed, the file is ready for use in the BA3 Mapping Engine.
Pre-Requistes on OS X
- An image viewer that can give you pixel coordinates (you can even use Preview for this in a pinch) and can convert your source image into .tif format.
- The BA3 Mapping Engine command line tool (METool)
- Required OSX libraries used by the mapping engine tool. Download, expand, and install each of the packages below. These are created with macports and these exact versions are required by METool, otherwise you will have issues. (NOTE: An Ubuntu 12.01 version of metool is also available that works on that linux distro.)
Then, from a command line, execute this command to put the binaries from these packages on your path:
# cd ~/ # echo 'export PATH=/opt/local/bin:$PATH' > ~/.profile # . .profile
Convert your source image into a PNG (.png) image. Other formats may work, but PNG has been thoroughly tested. For this example, name the image myimage.png.
Look at your image in an image editor and find several landmarks on the image that correspond to landmarks with known geographic locations. You can get known geographic locations by looking at other maps, online (Google Maps, Bing Maps, or Open Street Maps), or using other software (i.e. Google Earth). This web site may also be helpful: http://www.getlatlon.com
Note the geographic coordinate (latitude and longitude) that corresponds to a pixel coordinate of the image. Consider the origin pixel (x=0, y=0) of your source image to be its top left pixel. Collect several points from around your image and their corresponding geographic coordinate. The more points you collect, the more accurately the image can be warped. In this example, we are geo-referencing the subway map for the San Francisco area, so the points and lat/lon locations might be:
x:828 y:2346 = lon:-122.5097898379812 lat:37.78062053164073 x:6072 y:1873 = lon:-122.3885018331454 lat:37.78811453911737 x:2494 y:5243 = lon:-122.4720624930206 lat:37.72683034536965 x:4284 y:5685 = lon:-122.4299839425239 lat:37.71814655820412 x:6566 y:4475 = lon:-122.3768717974501 lat:37.74019797177258
Open a command prompt and convert your image to a .tif using gdal_translate:
# gdal_translate -b 1 -b 2 -b 3 myimage.png myimage.tif
Now use gdal_translate to create a set of instructions (.vrt) by executing a command like this:
# gdal_translate -a_srs EPSG:4326 \ -gcp 828 2346 -122.5097898379812 37.78062053164073 \ -gcp 6072 1873 -122.3885018331454 37.78811453911737 \ -gcp 2494 5243 -122.4720624930206 37.72683034536965 \ -gcp 4284 5685 -122.4299839425239 37.71814655820412 \ -gcp 6566 4475 -122.3768717974501 37.74019797177258 \ -of VRT myimage.tif myinstructions.vrt
The parts that say "-gcp (x) (y) (lon) (lat)" are repeated for each of your reference points. The result is a file named myinstructions.vrt, a chunk of XML that describes the geographic orientation of the image, without actually touching the image itself. gdal_translate should output something like this:
Input file size is 7350, 6838
Now you will execute gdalwarp to perform the actual warping and bending of the image to its new shape:
# gdalwarp -r cubic -t_srs EPSG:4326 -dstalpha myinstructions.vrt mygeorefimage.tif
Open the created image, mygeorefimage.tif, in an image viewer to verify it has the colors you desire. If the image is grayscale go back through the steps above and make sure you didn’t miss anything. The image will likely appear transformed in some way, this is OK, as it has been reprojected. This image will then be fed into metool to generate a .map and .sqlite file that is compatible with the BA3 Mapping Engine.
Execute MEtool to process your geotif into content for the mapping engine:
./metool -geotif -inputfile mygeorefimage.tif -outputpath /Users/MyName/MEMaps -mapname mymap -complete -level 16
This tells metool that your input is a geotif and that you want to use the complete image to generate a map named mymap down to detail level 16.
This process can take some time, but you can start looking at the highest level generated tiles pretty early on and stop the process if you’re not liking the detail level.The level dictates the depth to which tiles are generated and generally depends on your map content. If you have very small fonts or very granular detail for a small geographic area you’d need a higher level (i.e. subway map) than if you were using less pixels for a larger geographic area (i.e. aviation map). The intermediate tile images will be generated and you can look at the highest level tiles to see if they meet your quality needs. You can experiment with this level setting as needed. The higher the level, the more tiles, and the bigger the map, but once you go past a certain point (where you are oversampling the data) there is nothing to gain and you will be wasting space. A good rule of thumb is to find a font on a high-detail tile to see how readable it is.
Once all tiles are generated, the fully opaque ones will be converted to high-quality .jpg images and any around the border will use PNG with an alpha channel. These will then be packaged into the .map file. Empty tiles (those with no lit pixels) will be optimized out. Data structures and meta-data needed by the mapping engine will be put in the corresponding .sqlite file. Both files are needed to display the map. In the future we may combine all of this into a single file.