Using metool
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:
- Raster maps - from any geo-tif or your own raster imagery
- Marker maps - from tab delimited marker data. Markers data can also be 'injected' into existing sqlite databases.
- 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 https://github.com/ba3llc/BA3MappingEngineTutorials.git 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:
- ImageMagick: http://dev1.ba3.us/public_sdk/3rdParty/ImageMagick-6.7.9-0.mpkg.zip
- GDAL 1.91. : http://dev1.ba3.us/public_sdk/3rdParty/gdal-1.9.1.mpkg.zip
- GEOS 3.3.5 : http://dev1.ba3.us/public_sdk/3rdParty/geos-3.3.5.mpkg.zip
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:
- Downloaded all the NASA SRTM 3 data
- Downloaded our SRTM water imagery from http://dev1.ba3.us/public_sdk/3rdParty/srtmwater.zip and placed all of those files with the SRTM3 height data
- Downloaded all the GTOPO terrain data
- Downloaded our GTOPO headers from http://dev1.ba3.us/public_sdk/3rdParty/GTOPO/header.txt 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: http://dev1.ba3.us/public_sdk/countries.txt. 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
OPTIONS:
-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
display.
-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,
TAC.
-gtopopath ARG Location of NASA GTOPO data.
-h Show usage.
-injectmarkers Inject marker data into an existing Sqlite
database.
-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
-converttopvr
-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
value.
-markerselectsql ARG SQL statement that returns markerid, . Use with
-injectmarkers
-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
generated.
-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
adjusted.
-usecutline If set, looks for input.tif-cutline/cutline.shp
file, then creates two output files, name.map and
name_collr.map. Use -nocollar to disable collar
generation.
-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
