[Artoolkit] ARToolKit's SDK Structure on Android

Most applications on Android are developed in Java, and Android provides a rich framework of classes to support this. It is, however, also possible to develop parts of an application in native C/C++ code using the Android NDK. This is intended for accessing existing C/C++ codebases or potentially optimizing performance critical functions.

The general approach is to build a native C/C++ shared library containing functions that are exposed using the JNI naming scheme. A Java application can then load the library and map the native functions to Java methods, which can then be called like any other method in Java. Using this approach it is now possible to create ARToolKit applications on Android.

Certain parts of these applications, must be implemented in Java, other parts can be written in C/C++. Therefore, applications will typically be a combination of C/C++, Java, and the “glue” in between.

This SDK includes components in both C/C++ and Java to permit the development of ARToolKit applications on Android. These components include:

• ARToolKit core modules. These are native static libraries which can be used to build a shared library.
• ARToolKitWrapper: a C++ wrapper around ARToolKit, providing high level access to ARToolKit functions and marker management, with C and JNI interfaces. This is a native shared library that can be included in an Android application.
• ARBaseLib: a Java Android library that communicates with ARToolKitWrapper. By using the classes provided ARBaseLib, an Android application gains easy access to the native functionality of ARToolKit.

With these components, several development strategies are possible, ranging in complexity:

• Native development by creating a new shared library that links to the ARToolKit static libraries.
• Native development by creating a new shared library that utilizes ARToolKitWrapper.
• Java development using the provided ARBaseLib (Java) and ARToolKitWrapper (native) libraries.

Video Capture on Android

The ARToolKit port includes almost all of the core modules; the notable exception being the video capture module, which in other ARToolKit versions provides a standard interface for accessing video capture on different platforms and hardware.

Android does not currently permit camera access from native code. Instead, only Java code can open the camera and capture frames. Additionally, a live camera preview must be included in the current Activity’s view for frames to be captured. This means that ARToolKit itself cannot initiate video capture, but must instead wait on the Java application to pass video information and frames using JNI.

Therefore, video capture requires coordination between corresponding libraries on either side of JNI. While this forces a slightly fragmented approach, ARToolKitWrapper and ARBaseLib libraries are provided to handle the issue. Alternatively, the ARNative example included in the SDK demonstrates how to pass video independently of these libraries.

至于校准，属于独立篇章，之后看。

Developing with ARToolKitWrapper and ARBaseLib

---

You can copy the entire libs directory from: android/libs

Please ensure that you run the build.sh and build native.sh prior to copying the directory.

Read the Android Native Development for more information. Note: There are subdirectories for each CPU architecture, including armeabi, armeabi-v7a, mips and x86. It is the same library built for different instruction sets. The appropriate version is automatically chosen at runtime.

##ARBaseLib ARBaseLib provides additional classes to simplify development.

ARBaseLib is an Android library, meaning that it isn't an Android application itself, but can make use of the Android framework. Android applications can reference the library, and AndroidStudio will take care of including the necessary files when the APK is built and deployed. This allows reusable components to be placed in the library and used in many different examples and applications.

To use ARBaseLib, import the ARBaseLib as new module to your AndroidStudio project:

. **File/Project Structure…**
. Add a new module with the **+** button at the top left of by pressing ⌘+N (OSX) Alt+Insert (Windows)
. Select **Import .JAR/.AAR Package** hit Next
. Select the file with the ... on the right of the first text field. The ARBaseLib.aar file is located in $ARTOOLKIT5ROOT/AndroidStuiodProjects/ARBaseLibProj/arBaseLib/build/outputs/aar/ 

Development

Referencing ARBaseLib gives the application access to several new classes. Some of the key ones are:

• • ARToolKit:  A singleton class that handles the native calls.
  • ARActivity: A base class for an AR based activity.
  • ARRenderer: A base class for rendering AR scenes.

ARActivity takes care of setting up the view hierarchy that will display the live augmented reality view. The AR view is created by layering an OpenGL surface over the live camera preview surface. By using a transparent background clear color in OpenGL, the live video shows through from below.

A FrameLayout is used to hold the views because children of a FrameLayout are stacked on top of each other – precisely the arrangement required. The following diagram illustrates how the user interface is composed to produce an AR view.

ARActivity must be subclassed to be used. Abstract methods need to be overridden in the subclass to provide ARActivity with the objects it needs to work with.

The first object is a FrameLayout, mentioned above, which will contain the camera and OpenGL views.

protected abstract FrameLayout supplyFrameLayout();

The second required object is a renderer for displaying the AR scene. The renderer must inherit from ARRenderer, another class in ARBaseLib.

protected abstract ARRenderer supplyRenderer();

获得生效的Marker：

int markerID = ARToolKit.getInstance().addMarker("single;/sdcard/AR/Data/patt.hiro;80");

For single markers: single;path_to_pattern_file;pattern_width
Example: single;/sdcard/AR/Data/patt.hiro;80

For multi markers: multi;path_to_multi_config_file
Example: multi;/sdcard/AR/Data/multi/marker.dat

　　

Developing directly with ARToolKit

For developers who want more control and direct access to ARToolKit functions, the core ARToolKit modules are available as static libraries:

• libar: core AR functions
• libaricp: Iterative Closest Point functions (provided as a built binary only)
• libarmulti: multimarker support
• libeden: additional math and rendering functions
• libgl: OpenGL functions, particularly for video texturing

Android Examples

---

The examples are divided into 3 sets.

1. All Java-based: examples where all user-developed code is in Java, and is based on the provided ARBaseLib classes.
2. Mixed Java and native C/C++ using Android NDK: examples where user-developed code is split between the Java environment and native C/C++ environment. Code can use the provided ARBaseLib java classes while also addressing ARToolKit in C/C++ via the libARWrapper C/C++ API.
3. AR and rendering code in native C/C++ using Android NDK: examples where most of the user-developed code is native C/C++. These examples offer the greatest power to the AR developer and direct access to the full native ARToolKit API.

All Java-based

• **ARSimple**: An example that extends the ARActivity class in ARBaseLib to create a simple augmented reality application.
• **ARSimpleInteraction**: An example that adds simple interaction to ARSimple.
• **ARMulti**: An example that shows how to configure and use multi marker tracking.
• **ARDistanceOpenGLES20**: An example on how to measure the distance and draw a line between two markers. The line is drawn using OpenGL ES 2.0 library features.
• **ARMarkerDistance**: An example on how to measure the distance and draw a line between two markers. The line is drawn using OpenGL ES 1.0 library features.
• **ARSimpleOpenGLES20**: Pretty much the same as ARSimple with the extension of using OpenGL ES 2.0 features for drawing and coloring the cube.

Mixed Java and Native C/C++ Using Android NDK

• **ARSimpleNative**: An example that uses an additional native library to perform rendering in C rather than Java.
• **ARSimpleNativeCars**: An example that uses a native OBJ model loader.

AR and Rendering Code in Native C/C++ Using Android NDK

• **ARNative**: An example that uses the ARToolKit libraries directly and renders with OpenGL ES 2.0.
• **ARNativeES1**: An example that uses the ARToolKit libraries directly and renders with OpenGL ES 1.0.
• **ARNativeOSG**: An example that uses the ARToolKit libraries directly and loads and renders 3D model content using the advanced OpenSceneGraph framework.
• **nftSimple**: An example that performs NFT (texture tracking) and renders with OpenGL.
• **nftBook**: An example that performs NFT (texture tracking) and loads and renders 3D model content using the advanced OpenSceneGraph framework.
• **ARMovie**: An example that performs NFT (texture tracking) and loads and renders 2D video content on devices running Android 4.0.3 and later.

ARNative

Loads marker names from a configuration file. (Square markers only.) The tracking will automatically be set to match the types of square markers (template (pictorial) vs. matrix (barcode)) used in the configuration file. It is not recommended that template and matrix markers are mixed in the same application, as this lowers the tracking reliability of both types.

ARNativeOSG

Loads marker names from a configuration file. (Square markers only.) The tracking will automatically be set to match the types of square markers (template (pictorial) vs. matrix (barcode)) used in the configuration file. It is not recommended that template and matrix markers are mixed in the same application, as this lowers the tracking reliability of both types.

Management of OSG objects is encapsulated in a C-pseudoclass named VirtualEnvironment, which in turn acts through the API offered by the ARosg library. ARosg contains a reasonable amount of functionality for manipulating the scene graph. See the API documentation for libARosg.

nftSimple

Loads NFT dataset names from a configuration file.

The example uses the “Pinball.jpg” image supplied in the “Misc/patterns” folder. ARToolKit NFT requires a fast device, preferably dual-core for good operation, e.g. Samsung Galaxy SII or similar. Build/deployment for Android API 9 (Android OS v2.3) or later is recommended.

nftBook

Loads NFT dataset names from a configuration file.

The example uses the “Pinball.jpg” image supplied in the “Misc/patterns” folder. ARToolKit NFT requires a fast device, preferably dual-core for good operation, e.g. Samsung Galaxy SII or similar. Build/deployment for Android API 9 (Android OS v2.3) or later is recommended.

Management of OSG objects is encapsulated in a C-pseudoclass named VirtualEnvironment, which in turn acts through the API offered by the ARosg library. ARosg contains a reasonable amount of functionality for manipulating the scene graph. See the API documentation for libARosg.

ARMovie

Shows an example of playback of a video file on a marker surface. The example is NDK (native)-based. Movie playback is only supported by Android OS v4.0 (“Ice Cream Sandwich”) and later (Android API level 14), and support varies in quality and reliability from device to device. It is highly recommended that you provide alternate playback mechanisms for devices where playback in the AR environment cannot proceed, e.g. full screen playback.

Android Native Development

The ARToolKit SDK package and the git cloned GitHub local repository of “artoolkit5” includes prebuilt native libraries. It's advised that a local repository be used since the downloaded SDK package is rarely up-to-date with the repository. If you are not planning on altering any native code then you do not need to consult this section or install the Android NDK.

On the other hand, if you want to implement part of your AR application in native code, then you will need to build ARToolKit native C/C++ dependencies.

 貌似也没有什么太特别的东西。代码分析才有干货。