Skip to main content

Install on Android

MapCore ships for Android as an AAR. It contains both halves of the surface — the Java API in classes.jar, and the native engine as .so libraries under jni/ — so adding the AAR is the whole installation. There is no separate SDK to unpack and no NDK build of your own to configure.

The file is named differently depending on where you get it, which matters when you go looking for it:

Obtained fromFile name
The download archive mapcore-android-<version>-java-<abi>.zipmapcore7-release.aar (or mapcore7-debug.aar)
The Maven repositorymapcore-android-<version>-release.aar, per Maven's own convention

It is the same artifact either way — only the packaging renames it.

A debug build is published in parallel, whose native library is named with a D suffix. That distinction matters at run time, so it is covered under Load the library below.

Prerequisites​

ABIarm64-v8a only
AndroidAPI 21 or later (minSdkVersion 21)
LanguageJava (Kotlin interoperates normally), or C++ through the NDK — see Use MapCore from C++
warning

The release AAR carries arm64-v8a and nothing else. A 32-bit device will not run it, and neither will an x86 or x86_64 emulator — the usual desktop-emulator default. Test on an arm64 device, or on an arm64 system image.

Add the AAR​

MapCore 12.5.0. Downloads are credential-gated by Artifactory itself — the first one opens its sign-in page.

Downloads are not available on this network. Ask your administrator where to obtain MapCore releases.

MapCore Android (AAR)

Or declare com.mapcore:mapcore-android:12.5.0 as a Gradle dependency

implementation 'com.mapcore:mapcore-android:12.5.0'

Copy it into your module's libs/ directory and depend on the directory:

// app/build.gradle
android {
// MapCore's native libraries are arm64 only; without this, the build packages an
// APK that claims ABIs it has no libraries for.
defaultConfig {
ndk { abiFilters 'arm64-v8a' }
}
}

dependencies {
implementation fileTree(dir: 'libs', include: ['*.aar'])
}

Nothing else is needed to build: the AAR's classes.jar puts the whole Java API on your compile classpath, and its jni/arm64-v8a/ libraries are packaged into your APK automatically.

The libraries are aligned for devices whose kernel uses 16 KB memory pages. How your APK stores them is your build's part: if it packages native libraries uncompressed, use Android Gradle Plugin 8.5.1 or later, which aligns them inside the APK as those devices require.

From the Maven repository​

MapCore also publishes the AAR to a Maven repository, which needs the credentials issued to you — the same ones as for the Linux packages. The release and debug builds are the same artifact distinguished by a classifier, so the dependency needs both the classifier and @aar:

// settings.gradle (or the project build.gradle, for older Gradle)
repositories {
maven {
url 'https://mapcore.jfrog.io/artifactory/c4i-mapcore-maven-local'
credentials {
username = mapcoreUser // from ~/.gradle/gradle.properties,
password = mapcorePassword // never committed
}
}
}
dependencies {
implementation 'com.mapcore:mapcore-android:<version>:release@aar'
}

Swap the classifier to debug for the debug build — and remember to load the matching library name if you do. Keep the credentials in ~/.gradle/gradle.properties, outside the project, so they are neither committed nor shared with anyone who clones it.

What is inside​

classes.jar the Java API - com.elbit.mapcore.*
jni/arm64-v8a/libJniMapCore7.so the JNI wrapper: the library you load
jni/arm64-v8a/libMcSceneManager.so, libMcMapTerrain.so, libMcOverlayManager.so, ...
the engine, plus its render system and codec plugins
AndroidManifest.xml, res/ a minimal manifest and resources

The Java packages follow the C++ header layout: com.elbit.mapcore.Interfaces.Map for IMcMapDevice, IMcMapViewport, IMcMapTerrain and the layers, com.elbit.mapcore.Interfaces.Calculations for the queries and coordinate systems, com.elbit.mapcore.Structs for SMcVector3D and friends, and com.elbit.mapcore.General for MapCoreException and McGarbageCollector.

Load the library​

Load the JNI wrapper once, before any MapCore call. It pulls in the engine libraries it needs:

static {
System.loadLibrary("JniMapCore7");
}

That is the release name. A debug build of the wrapper is JniMapCore7D, and loading the wrong one fails at class-initialization time with an UnsatisfiedLinkError naming the library — so if that is what you are looking at, check which AAR you actually have before looking anywhere else.

Use MapCore from C++​

You can also call MapCore from your own native code, with the same C++ API as on Windows and Linux. For that, use two zips from the download archive instead of the AAR:

ZipContains
mapcore-android-<version>-cpp-<abi>.zipThe engine .so libraries, with libc++_shared.so beside them
mapcore-android-<version>-include-<build>.zipThe public C++ headers

Add the headers to your NDK build's include path, link your native library against the MapCore .so files, and package all of them in your APK — libc++_shared.so included. MapCore is built with the shared C++ runtime (c++_shared), so your native code must use it too.

The rules under Verify apply to C++ code as well: every MapCore call goes on the GL thread, and the viewport is created on your existing GL context.

Configuration files and map data​

MapCore reads plugins.cfg, resources.cfg and fxplugin.cfg from the directory named by SInitParams.strConfigFilesDirectory. On Android there is no useful default working directory, so this is not optional here — set it, and set strLogFileDirectory beside it, or device creation fails on a machine where nothing about your code changed.

Both those files and your map data have to be somewhere the app can read at a filesystem path. Push them to the device and point the init params at them:

adb push MapCore/ /sdcard/MapCore/

Verify​

There is no command-line tester on Android, so the first real check is your own code. The Quickstart's java tab is the shortest version, and it is worth knowing what makes Android different from every other platform before you write it:

  • Every MapCore call belongs on the GL thread. The thread that creates the device becomes MapCore's main thread, so device and viewport creation go in GLSurfaceView.Renderer's onSurfaceCreated(), not in Activity.onCreate() — and releasing belongs there too.
  • The viewport is created on your existing GL context, with hWnd = -1 (MC_HWND_CURRENT_GL_CONTEXT), bExternalGLControl = true, and uWidth/uHeight set, because there is no window for MapCore to measure.
  • ViewportResized(width, height) takes a size only on Android. Every other platform reads it from the window and rejects the arguments. The Java surface declares no argument-less overload at all, so this one is hard to get wrong.
  • McGarbageCollector.DisposeAll() is the last MapCore call on that thread. Nothing calls it for you. There is no per-frame Collect() to add, though — the JNI Render() does that itself.

If the surface stays black, read MapCore.log in your log directory before anything else.

Next steps​

Verified against MapCore 12.5.0

Written from Development/Jni/JavaMapCore/mapcore7/build.gradle, packaging/android/package_android.py, Development/Jni/JniMapCore7/SourceFiles/General/McBaseJNI.cpp, Development/Jni/JniMapCore7/SourceFiles/Map/McMapViewportJNI.cpp