Setting up for developing an artoolkitX for Android app - hipandayu/artoolkitx GitHub Wiki

artoolkitX can be integrated into Android applications. This can be done either using the artoolkitX for Android module (Java) or integrating the native artoolkitX C library (NDK and C/C++ development). This article will focus on integrating artoolkitX for Android using the module (the Java way).

Integrating artoolkitX for Android module

Let us assume that you have an existing Android application and would like to add an Augmented Reality feature using artoolkitX. For demonstration I'm creating an empty Android project using the Android Studio Wizard. I name the project SimpleAr with the package org.artoolkitx.arx.simplear. The minimum SDK needs to be set to Phone and Tablet version API 21: Android 5.0 (Lollipop) or higher. Also, I'll add an Empty Activity called MainActivity to the project.

Due to some errors inside the automatically generated project setup I needed make some changes to the configuration of the project. Inside the module build.gradle I change the dependencies to look like this:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'com.android.support:appcompat-v7:27.1.1'
    implementation 'com.android.support.constraint:constraint-layout:1.1.0'
}

Additionally I needed to adjust the gradle version inside the gradle-wrapper.properties to this

distributionUrl=https\://services.gradle.org/distributions/gradle-4.4-all.zip

After that the project compiled and is ready to go.

Add the artoolkitX module

To use the artoolkitX library you need to download and add arxj module to your project. You can get the arxj library as part of the artoolkitX-Android package from http://www.artoolkitx.org/docs/downloads/ or you git clone this repository and build it from source. See The artoolkitX build system.

Once you have downloaded/built artoolkitX for Android locate the file arxj-release.aar. This file needs to be included into your Android project.

The easiest way is to right click your project in the Android-View and select Open Module Settings. Select the + on the top left above the menu. Then select arxj-release.aar from the file dialog.

Important: Theoretically this should setup the Grade configuration with everything you need and add the library to your project. However, for me that fails regularly. Because of that I explain another way to do that.

Alternative way to import artoolkitX library

Open the Module build.gradle file (the one that contains compileSdkVersion and minSdkVersion). Add the following to the root of the JSON structure:

allprojects {
    repositories {
        jcenter()
        flatDir {
            dirs 'src/main/libs'
        }
    }
}

Change the path of dirs to the location where your arxj-release.aar file is located. Basically this tells gradle to integrate this directory into its search path when it tries to resolve library dependencies. For this example I've created a directory libs inside src/main and copied arxj-release into this directory.

Inside the same build.gradle file should be a section called dependencies into this section you need to add

implementation(name:'arxj-release', ext:'aar')

This line make arxj-release.aar a dependency of your project.

Now you need to update your Android project. To do that select Sync now.

artoolkitX is not part of your project and you can use the API to integrate it.

Create basic ar app

To create a basic ar app you need to access the camera, maybe render the video stream and diplay some kind of content that overlays the video stream. The detailed integration depends on your use case so I'll only outline the very basics here.

First you need an activity that extends from ARActivity. In my simple example this activity is called MainActivity and had been automatically created by the Android Studio wizard when I selected Empty Activity. Change your activity to extend ARActivity. This means you also need to implement supplyRenderer and supplyFrameLayout.

Frame layout

artoolkitX needs a frame layout which it uses to render the video background to. The function supplyFrameLayout is used to provide this frame layout to artoolkitX. To do so implement the function like this:

protected FrameLayout supplyFrameLayout() {
    return (FrameLayout) this.findViewById(R.id.mainFrameLayout);
}

The frame layout needs to be defined inside the layout xml file in my case that file is called activity_main.xml. Inside this file define a frame layout like this:

<?xml version="1.0" encoding="utf-8"?>
    <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
            android:layout_width="fill_parent"
            android:layout_height="fill_parent"
            android:orientation="vertical"
            android:baselineAligned="false"
            android:id="@+id/mainFrameLayout"
            android:layout_gravity="center"
            android:layout_weight="1">
    </FrameLayout>

Important is the definition of the android:id because this id is used to find the view and pass it to artoolkitX using R.id.mainFrameLayout.

ARRenderer

Next piece to implement is supplyRenderer() this function passes the renderer used to create the ar content to artoolkitX. Implementing this function can be as simple as this.

    protected ARRenderer supplyRenderer() {
        return new ARSimpleRenderer();
    }

However, this implies that you previously created a class that implements ARRenderer

Todo so create a new class and make it extend ARRenderer. ARRenderer is an abstract class and you need to override at least the following functions: You can see how these functions could be implemented by looking at the implementation of ARSquareTrackingRenderer

configureARScene is used to load the trackables

onSurfaceCreated instantiates the shader program and the content that should be rendered

draw is called for every video frame. It basically itterates over all trackables, evaluates if a trackable is visible, reads the modelview- and projection matrix and uses this to draw the content.

Loading assets

There is a one-off initialization that needs to be done to load the camera parameters and the used trackable pattern files. This initialization needs to be called when the app is started. A good place to call this initialization function is the onCreate lifecycle function. The implementation of the initialization function should look like this:

protected void initializeInstance() {

    // Unpack assets to cache directory so native library can read them.
    // N.B.: If contents of assets folder changes, be sure to increment the
    // versionCode integer in the modules build.gradle file.
    AssetHelper assetHelper = new AssetHelper(getAssets());
    assetHelper.cacheAssetFolder(this, "Data");
    assetHelper.cacheAssetFolder(this, "cparam_cache");
}

When you follow these steps you should be able to integrate artoolkitX into an existing Android application. Let us know if you face any issues by creating an issue.