tangram-es is a C++ library for rendering 2D and 3D maps from vector data using OpenGL ES, it is a counterpart to tangram focused on mobile and embedded devices.
This repository contains both the core rendering library and sample applications that use the library on Android, iOS, Mac OS X, Ubuntu, and Raspberry Pi.
tangram-es is in active development and is not yet feature-complete
This project uses CMake (minimum version 3.0), you can download it here or use your favorite installation package tool like homebrew.
brew install cmake
Make sure to update git submodules before you build:
git submodule update --init --recursive
Currently we are targeting five platforms: OS X, Ubuntu Linux, iOS, Android, and Raspberry Pi.
To build a runnable OS X application bundle, run:
make osx
And open the application with:
open build/osx/bin/tangram.app
For running on OS X from Xcode you will need Xcode version 6.0 or higher. Generate and compile an Xcode project:
make xcode
Then just open the Xcode project and run/debug from there:
open build/xcode/tangram.xcodeproj
Note that any Xcode configuration change you make to the project won't be preserved when CMake runs again. Build configuration is defined only in the CMakeLists file(s).
You can easily run and debug from CLion if you prefer.
After cloning and updating your git submodules, open CLion and Import Project from Sources. Select the root of this repo. Choose Open Project. Do not overwrite CMakeLists.txt.
CLion will automatically set everything up, all you have to do is wait a minute for the project to get initialized. Then, select the tangram target and hit run / debug.
To build on Ubuntu you will need a C++ toolchain with support for C++14. GCC 5 (or higher) and Clang 3.4 (or higher) are known to work.
You will also need to install development packages for libcurl, x11, and opengl:
sudo apt-get install libcurl4-openssl-dev xorg-dev libgl1-mesa-dev
Then build an executable:
make linux
And run it from the output folder:
cd build/linux/bin/ && ./tangram
For running on the iOS simulator, generate and compile an Xcode project:
make ios-sim
Then just open the Xcode project and run/debug from there:
open build/ios-sim/tangram.xcodeproj
Note that any Xcode configuration change you make to the project won't be preserved when CMake runs again. Build configuration is defined only in the CMakeLists file(s).
For running on iOS devices you will need an iOS developer account, a valid code signing certificate, and a valid provisioning profile. Help on these topics can be found at Apple's developer website.
First generate an Xcode project without compiling:
make cmake-ios
Then open the Xcode project and set up your developer account information to run on a device:
open build/ios/tangram.xcodeproj
If you run into problems deploying to an iOS device, see this note.
EXPERIMENTAL
An iOS binary framework bundle targeted for ARM architectures can be produced by following the instructions for iOS Devices above, and then copying the Xcode project out of the /ios
directory and overwriting the CMake produced project. Then, copy the tangram_framework
folder out of /ios
and drop that in the same directory as the Xcode project. This will allow you to open the Xcode project and build the tangram_framework
target in Xcode.
Future releases will include simulator support, and a more streamlined / automated system for moving files into place.
To build for Android you'll need to have installed both the Android SDK and the Android NDK. Set an ANDROID_HOME
environment variable with the root directory of your SDK and an ANDROID_NDK
environment variable with the root directory of your NDK.
Build an APK of the demo application and optionally specify an architecture (default is armeabi-v7a):
make android [ANDROID_ARCH=[x86|armeabi-v7a|armeabi]]
Then install to a connected device or emulator. You can (re)install and run the APK with a small script:
./android/run.sh
To build on Rasberry Pi you will need a C++ toolchain with support for C++14. GCC 4.9 (or higher) is known to work (refer here for instructions on getting GCC 4.9).
First, install CMake and libcurl:
sudo apt-get install cmake libcurl4-openssl-dev
Before compiling, choose which compiler to use:
export CXX=/usr/bin/g++-4.9
Then compile and run:
make rpi
cd build/rpi/bin
./tangram
Tangram will be rendered directly to the screen without a window manager, if you want see the mouse cursor run the application with the -m
argument like this:
cd build/rpi/bin
./tangram -m
You can also move the map with w
, a
, s
, and z
, zoom in and out with -
and =
, and quit with q
.
To build in RELEASE
or DEBUG
run the following:
make [platform] DEBUG=1
or
make [platform] RELEASE=1
In general, code changes should follow the style of the surrounding code.
When in doubt, you can use the provided clang-format style file for automatic styling.
Install clang-format (available through brew or apt-get):
brew install clang-format
or
sudo apt-get install clang-format
Run clang-format with specified style (use -i to modify the contents of the specified file):
clang-format -i -style=file [file]