Notice! This content describes the deprecated Altus 1.0 (non-ARC) Engine features and data tools. These are superseded by Altus 2.0 and Altus Server tools. They are currently being tested with select groups. If you're interested please contact us at [email protected].

Tutorial 1 — First App

Creating the simplest Mapping App with the BA3 Altus Mapping Engine


The BA3 Altus Mapping Engine is a library that iOS developers use to add mapping functionality to their apps. If you simply add the mapping engine to an app and do nothing, the screen will be blank because there are no maps being displayed. The first step, therefore, is to get some kind of map into the mapping engine for it to display. This tutorial shows how to do this using a standard base map. Follow these steps to create the simplest possible app that can display a map with the BA3 Altus Mapping Engine:

Step 1

From a command prompt run these commands:

git clone https://github.com/ba3llc/BA3MappingEngineTutorials.git
cd BA3MappingEngineTutorials
git checkout blankslate

The BA3MappingEngineTutorials.git file is large — expect it to take a minute or two to download depending on the speed of your connection. If the git command is not working on your machine, see this page to turn it on.

Step 2

Open the project in Xcode and run it (Please make sure that OSX and Xcode have been updated to their latest versions). You will see an empty white screen. Everything in this blankslate state is set up properly for the BA3 Altus Mapping Engine to load a map (i.e. all libraries are linked in, etc.). But no map has been loaded, so the screen is white. Therefore, in the following steps you will:

  1. Create an MEMapViewController and an MEMapView. (You can learn more about these classes in the Documentation).
  2. Place them on the main view of the application.
  3. Load a single raster world map that was generated with TileMill, processed with METool and is embedded as a bundled file in the application.

Step 3

Edit the file ViewController.h, and make it look like this:

Step 4

Edit the file ViewController.m and add this function. This is standard code you will use in any app to initialize the BA3 Altus Mapping Engine:

Step 5

The blanksate app that you downloaded from Github contains a standard base map called world.mbtiles (look in the BundledMaps folder of the project in Xcode). This file contains a collection of TileMill tiles (from level 1 to level 6) that have been prepackaged as a single file by METool and added to the app as a resource. Add this function to ViewController.m to load and activate this base map:

You can learn more about the MEMBTilesMapInfo class and its attributes in the Documentation.

Step 6

Modify your viewDidLoad function to read like this:

Step 7

Run the application and you will see the planet earth. Pan and zoom. What you are looking at is a base map created from a set of TileMill tiles (levels 1 through 6) that have been downloaded by METool and packaged as a single file called "world.mbtiles". This file is bundled into the app and is therefore always available.

Why might you like to have a file like this bundled into your app? Because, especially if your app depends on maps streaming in over the Internet, there may be times when no Internet connection is available. This base map creates a bottom layer that is "always there". It provides the user with some basic geographical reference points. You can create any base map you like with METool — this one is provided as a convenience and is very small.

Step 8

If you get lost or wish to save yourself the typing, simply checkout tutorial1 using these commands:

git reset --hard
git checkout tutorial1

If you have any questions about the Altus Mapping Engine, any feature requests or suggestions for improving the Altus Mapping Engine, please send them to [email protected].