Using metool

From BA3 Mapping Engine Wiki
Jump to: navigation, search

The Altus Mapping Engine is quite happy to consume raster tiles in spherical mercator format from a number of online sources and then reproject them automatically for you onto the sphere. There are several demonstrations in the Internet Maps section of the Reference Application.

Sometimes you need more performance or you want a map to be downloaded to the device for offline access. In the Reference Application, you'll note that there are several maps available for download from our map servers. Once maps are downloaded to the device you no longer need to be on internet to access them.

The maps that are available for download are produced by the Altus Mapping Engine tool, or metool. This is a powerful command line program for processing a variety of source map data into a format optimized for the Altus Mapping Engine.

The current publicly available version can create optimized:

  1. Raster maps - from any geo-tif or your own raster imagery
  2. Marker maps - from tab delimited marker data. Markers data can also be 'injected' into existing sqlite databases.
  3. Terrain and water maps - from NASA SRTM height and SWBD water data and GTOPO height data

Downloading METool

To get current binaries for metool, clone the repository (or pull if you have already cloned it).

git clone
cd BA3MappingEngineTutorials
git checkout ReferenceApplication

If you are on OSX, you will also want to install a few 3rd Party libraries that metool relies upon. You'll need:

  1. ImageMagick:
  2. GDAL 1.91. :
  3. GEOS 3.3.5 :

Then from a command line, ensure the utilities in these packages are on your path like so:

cd ~/
echo 'export PATH=/opt/local/bin:$PATH' > ~/.profile
. .profile

Unzip and install each of these libraries.

If you are on Ubuntu 12.04 LTS (our currently supported Linux version), you'll want to install these packages:

sudo apt-get install geotiff-bin
sudo apt-get install imagemagick
sudo apt-get install gdal-bin
sudo apt-get install libglu1-mesa

METool Examples

Here are some example command lines and what they do.

Convert the FAA Charlotte Sectional from geo-tif format to a map layer for the Altus Mapping Engine:

metool -geotif -inputfile "/FAA/Sectional/Charlotte 91 North.tif" \
     -outputpath /Users/Bruce/dump \
     -mapname CharlotteNorth \
     -complete \
     -level 10

Create the Earth base terrain and water map you see in the reference application:

metool -terrain -complete -mapname Earth -level 6 \
     -gtopopath "/mydata/GTOPO30" \
     -srtm3path "/mydata/NASA/SRTM3" \
     -outputpath /mymaps

NOTE: The previous example has several pre-requisites:

  1. Downloaded all the NASA SRTM 3 data
  2. Downloaded our SRTM water imagery from and placed all of those files with the SRTM3 height data
  3. Downloaded all the GTOPO terrain data
  4. Downloaded our GTOPO headers from and placed that file with the GTOPO data.

If you need any help getting all the data set up, please contact us at [email protected] for assistance.

Create an optimized, clustered marker map, from a tab-delimited file:

metool -markers -mapname WorldCountries -zorder 100 \
     -maxlevel 8 \
     -clusterdistance 40 \
     -inputfile countries.txt \
     -outputpath mymaps

NOTE: For the previous example you can download countries.txt from our server: See the documentation below for an explanation of the columns in the tab-delimited text file for marker data.

Inject markers into an existing sqlite database where you already have a table named 'mytable' that has columns for something that can represent a geographic marker:

-injectmarkers -inputsqlitefile "MyDatabase.sqlite" \
     -tablenameprefix markers_ \
     -markerselectsql "select ident, lon, lat, priority from mytable" \
     -zorder 22 \
     -clusterdistance 50 \
     -maxlevel 20

Vector data processing features and connecting to PostGIS are not currently exposed in the public version of metool. Contact us if you have any questions or would like to discuss using our vector pipeline for your needs.

Command Line Options in METool

If you run metool -h you'll see something like this:

metool - BA3 Mapping Engine Tool
Note:This program requires ImageMagick
USAGE: metool -OPTION_1 argument -OPTION_n argument
-clusterdistance ARG          When creating a marker map, specifies the distance
                              in pixels as measured from the center of markers
                              where marker weight is used to decide which to
-complete                     Make a map the encompasses all source data.
-converttopvr                 Converts an existing map generated from a geotif
                              to one containing PVR-only textures. When used,
                              you must specify -mappath. PVRTexTool must exist
                              on your path.
-donothing                    Check the command line, but don't generate the
                              map. Useful for debugging command line options.
-extracttiles                 Extracts all the tiles from the .map file. Useful
                              for debugging.
-generatewatertiles           Creates SRTM3 water sample tiles in the same
                              folder as your SRTM3 data.
-geotif                       Process geo-tif file. For example FAA sectional,
-gtopopath ARG                Location of NASA GTOPO data.
-h                            Show usage.
-injectmarkers                Inject marker data into an existing Sqlite
-inputfile ARG                Name of input file. Required for if -geotif or
                              -markers option is specified.
-inputpath ARG                Input tile path where files begin with coordinates
                              (i.e. W060.75xN47.25)
-inputsqlitefile ARG          Database into which marker tables should be added.
                              Use with -injectmarkers
-level ARG                    Output detail level. Higher means more detail.
                              Level 11 works well for sectionals.
-mapname ARG                  Filename for the .map and .sqlite files for the
                              generated map. (i.e. Midwest)
-mappath ARG                  Path (minus the .map extension) to an existing map
                              file. Used for post-processing functions like
-markers                      Create a marker map. Input file will be a tab
                              delimited text file with these columns: 1) Marker
                              ID (string), 2) Latitude (double), 3) Longitude
                              (double), 4) Weight (double) 5) Minimum level.
                              Columns 4 and 5 are optional and will default to
                              0. If you set this option you should also set the
                              -clusterdistance option to a positive integer
-markerselectsql ARG          SQL statement that returns markerid, . Use with
-max_lat ARG                  North-most latitude (60.5). Ignored if -complete
                              is set.
-max_lon ARG                  East-most longitude (-30.5). Ignored if -complete
                              is set.
-maxlevel ARG                 When creating a marker map, specifies the maximum
                              level of the marker tree.
-min_lat ARG                  South-most latitude (59.5). Ignored if -complete
                              is set.
-min_lon ARG                  West-most longitude (-78.5). Ignored if -complete
                              is set.
-nocollar                     Applies if -usecutline is set. Prevents generation
                              of a collar.
-outputpath ARG               Output path (i.e. /Users/JohnDoe/mapdata)
-skipgeneration               Do everything except generate tiles and map files.
                              This is useful for seeing stats of the input data
                              and the number of tiles that would have been
-srtm3path ARG                Location of SRTM3-style height data.
-swbdpath ARG                 Location of NASA SWBD data.
-tablenameprefix ARG          Prefix all generated tables with this prefix. Use
                              with -injectmarkers
-terrain                      Create a terrain map.
-tilepostprocesscommand ARG   Name of program or shell script to run to process
                              a tile before packing .map file. The program will
                              be called with a single argument, the name of the
                              tile. When finished the same file must exist (.jpg
                              or .png) but the internals of the file may be
-usecutline                   If set, looks for input.tif-cutline/cutline.shp
                              file, then creates two output files, and
                     Use -nocollar to disable collar
-zorder ARG                   Set z-order of generated map. If not specified,
                              defaults to 2.
metool 0.24.0  Copyright (C) 2013 BA3 LLC. ALL RIGHTS RESERVED
You need to tell metool what to do: -geotif, -markers, or -terrain
Personal tools