MappDemo — Reference Application


Once you have worked through some of the tutorials, you may have specific questions about the features and capabilities of the BA3 Altus Mapping Engine. A good starting point for exploration is the Mapp reference application. This application is used internally by engineers and developers at BA3 to exercise, test and demonstrate all of the mapping engine's functionality.

BA3 has two goals in making the reference application available: 1) developers who wish to explore the features and capabilities of the BA3 Altus Mapping Engine can easily try them out with Mapp, and 2) developers looking for specific pieces of sample code can extract them from the reference application to try in their own apps. The code in the reference app is not always transparently clear, but the full source code is always there. If you would like BA3 to create a tutorial that isolates and clarifies a specific feature, please send a request to [email protected]

NOTE: The reference application is not designed to be a shippable product. It is an internal test bed and demo platform. It is possible to do things with the reference application that may put the mapping engine into an inconsistent state. For example, it is possible to start two tests that simultaneously ask the camera to animate to different places. If Mapp seems to be misbehaving, kill it and restart.

To get source code for the reference application, clone the repository (or pull if you have already cloned it) and check out the ReferenceApplication branch:

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

Look for and open the Mapp.xcdoeproj file:

Then run the project in the simulator. It works on iPad or iPhone simulator 5.1 or newer. If you want to run it on hardware, you will need to add your own mobile provisioning profile and sign the application for deployment to your device.

The first time the application runs, it will extract and decompress Earth.map and Earth.sqlite from Earth.zip and render a world-wide terrain view. This is a low-resolution terrain layer that is bundled with the application. You may download higher resolution terrain from our map servers once Mapp is running (see the Download menu).

Various engine statistics are overlaid on the view, these include:

  1. FPS - Frames per second.
  2. DRC - Draw calls per frame.
  3. RAMo - Total memory in use by the application as reported by the kernel.
  4. RAMc - Internal use only. Will display 0.
  5. TC - Tile count: number of tiles being displayed.
  6. TIF - Tiles in flight.
  7. MTIF - Animated tiles in flight.
  8. QTotal - Number of work items running in the background.
  9. QSerialBg - Number or work items on a background priority serial queue.
  10. QSerialLo - Number or work items on a low priority serial queue.
  11. QSerialDef - Number or work items on a default priority serial queue.
  12. QSerialHi - Number or work items on a high priority serial queue.
  13. Center - Geographic center of the view.

Reference Application Buttons

  1. Tests: drops down a list of test categories.
  2. Downloads: brings up download window allowing you to select and download content from our map servers.
  3. Airplane icon: turns on GPS and syncs display to to current GPS coordinate
  4. Play: Starts playing back a pre-recorded flight path over Mt. Ranier
  5. Track Up: When in Play mode, turns on Track-Up Mode
  6. Maps: drops down a list of downloaded maps you can toggle on and off.

Some tests will require additional content which can be downloaded from our map server. Tap the Downloads button, make selections in the pop-up, then tap Download to bring the files down. When you are done, tap the Done button:

Some maps are downloaded as zip files and decompressed after they are downloaded.

You will need to download World from the WorldVector category to see a full-world dynamic vector map. Once you have downloaded a Map, it will appear in the Maps drop-down:

Test Categories

The reference application has been developed along with the mapping engine features. Each feature has a number of tests that can be executed in the reference application. A simple test harness and test management system serve as infrastructure for the various tests which you can experiment with. Source code for all tests in in the Mapp/METests folder.

Tests categories include:

  • Terrain Tests - Allows you to toggle 2/4 byte compression for downloaded terrain maps
  • Demos - Moves camera up and down and around earth with various map cycling modes.
  • Camera - Play back pre-recorded or scripted camera movements. Adjust zoom limits.
  • Perf Tests - Requires many on-board maps (downloaded from the server) to do various perf metrics.
  • Core - Low-level control of engine, start, stop, cache, threading, pan velocity, etc.
  • Internet Maps - Various spherical mercator maps and simple cache management system for raster tiles.
  • Internet Maps 2 Byte - Same as Internet Maps but forces RGB565 or RGBA4444 compression to be turned on.
  • World Vector - Required World Vector map to be downloaded and turned on. Dynamic restyling of vector map.
  • Vectors - Various dynamic vector map drawing routines.
  • Tile Providers - Low-level tile provider tests.
  • Misc - Various tests that don't cleanly fall into other categories.
  • Map ZOrder - Move a currently displayed map up / down in the stack.
  • Map Alpha - Change alpha of current displayed map.
  • Map Is Visible - Toggle map visibility
  • Scenarios - Various scenarios like route-rubber banding
  • Symbiotes - Test symbiote system. A symbiote is a UIView that is slaved to a map coordinate.
  • TAWs - Tests for dynamic terrain coloring based on altitude.
  • Animated Maps - Tests for the animated map system
  • MB Tiles - Tests for native support of Tile Mill maps
  • Markers - Tests for the marker system

Source code for all tests:

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