Image Fusion Tracker Android Tutorial

1. Overview
2. Android Development
2.1 Start /Stop Tracker
2.2 Use Tracking Information
2.3 Set Target Image
2.4 Add / Replace Target Image
2.5 Train Target Image Instantly
3. Reference
3.1 API Reference
3.2 Sample


1. Overview

Start developing MAXST ARSDK Image Fusion Tracker on Android Platform. Refer to Image Tracker Introduction for detailed information.

Generate 2D Mapfile of the Target from Target Manager to specify the target of Image Fusion Tracker. Refer to Target Manager and Recommended Conditions for Target Images to create 2D Mapfile.

Once 2D Mapfile is successfully generated, continue to 2. Android Development

Refer to Tracker Coordinate System to better understand 3D coordinate system of Image Tracker.

After image recognition and initial poses are acquired through the MAXST SDK, use ARCore for tracking.

※To use the AR Core, you must enter the actual size. (See Start / Stop Tracker)

Prerequisites
Image Tracker Introduction
Target Manager
Recommended Conditions for Target Images
Tracker Coordinate System

2. Android Development

Start developing on Android Studio using Java. Please refer to Requirements & Supports to find out which devices are supported.

ARSDK has to properly integrate on Android Activity. Refer to Life Cycle documents for details.


2.1 Start / Stop Tracker

TrackerManager.getInstance().IsFusionSupported()
This function checks whether or not your device supports Fusion. Return value is bool type. If true, it supports the device in use. If it is false, it does not support the device.

TrackerManager.getInstance().GetFusionTrackingState()
Pass the tracking status of the current Fusion.
The return value is an int of -1, which means that tracking isn't working properly, and 1 means that it's working properly.

To start / stop the tracker after loading the map, refer to the following code.

ImageFusionTrackerActivity.Java


@Override
protected void onCreate() {
    ...
  
TrackerManager.getInstance().startTracker(TrackerManager.TRACKER_TYPE_IMAGE_FUSION);
TrackerManager.getInstance().addTrackerData("ImageTarget/Blocks.2dmap", true);
TrackerManager.getInstance().loadTrackerData();

    ...
}

@Override
protected void onResume() {
    ...
    TrackerManager.getInstance().startTracker(TrackerManager.TRACKER_TYPE_IMAGE);
    ...
}

@Override
protected void onPause() {
    ...
    TrackerManager.getInstance().stopTracker();
    ...
}

When creating a 2dmap, the actual size must be entered correctly. (Unit: m)
You must enter the actual size of the target. If you do not enter the correct actual size, the content will not be augmented properly.
It must be run in the following order: startTracker (), addTrackerData (), loadTrackerData ().

ImageFusionTrackerRenderer.Java

@Override
Public void onSurfaceCreated(…){
   …
   …
   CameraDevice.getInstance().setARCoreTexture();
}

The setARCoreTexture () function call must be made from glThread.
setARCoreTexture () must be executed. If the function is not executed, no screen is displayed.


2.2 Use the Tracking Information

In the folder where SDK is installed, go to 'assets > ImageTarget' folder, and there is sample target image. Print the image.

If you use the sample code, the following content will be augmented for each image.

  • Blocks.jpg: The alpha video is augmented.
  • Lego.jpg: The normal video is augmented.
  • Glacier.jpg: The cube with the texture is augmented.

To apply tracking results to augmented objects, refer to the following code.

ImageFusionTrackerRenderer.Java

public void onDrawFrame(GL10 unused) {
    ...
    TrackingState state = TrackerManager.GetInstance().UpdateTrackingState();
    TrackingResult trackingResult = state.GetTrackingResult(); 
    for (int i = 0; i < trackingResult.getCount(); i++) {
        Trackable trackable = trackingResult.getTrackable(i);
        if (trackable.getName().equals("Lego")) {
            ...
            videoQuad.draw();
        } else if (trackable.getName().equals("Blocks")) {
            ...
            chromaKeyVideoQuad.draw();
        } else if (trackable.getName().equals("Glacier")) {
            ...
            texturedCube.draw();
        } else {
            coloredCube.setProjectionMatrix(projectionMatrix);
            coloredCube.setTransform(trackable.getPoseMatrix());
            coloredCube.setScale(0.3f, 0.3f, 0.01f);
            coloredCube.draw();
        }
    }
    …
}

2.3 Set Target Image

By calling addTrackerData () to register the map file and calling loadTrackerData (), the target image can be tracked. To set a target image, refer to the following code.

ImageFusionTrackerActivity.Java

onCreate() {
    ...    
    TrackerManager.getInstance().addTrackerData("ImageTarget/Blocks.2dmap", true);
    TrackerManager.getInstance().addTrackerData("ImageTarget/Glacier.2dmap", true);
    TrackerManager.getInstance().addTrackerData("ImageTarget/Lego.2dmap", true);
    TrackerManager.getInstance().loadTrackerData();
    ...
}

2.4 Add / Replace Target Image

  1. Create a map file refer to Target Manager

  2. Download the file you created.

  3. Unzip the downloaded file and copy it to the desired path. The way to copy maps to the assets folder and to the external storage is different.

  • When copying to the assets folder, set the second parameter to true to indicate that it is a relative path and a file in the assets folder.
TrackerManager.getInstance().addTrackerData("ImageTarget/Blocks.2dmap", true);
  • If copying to external storage, enter the full path and set the second parameter to false.
TrackerManager.getInstance().addTrackerData(mapFile.getAbsolutePath(), false);

※ You must call loadTrackerData () after calling addTrackerData ().


2.5 Train Target Image Instantly

If you want to use a raw image file as an image target without an offline training process via Target Manager, enter a JSON object as the first parameter of addTrackerData().

A sample JSON format is like below.

{
    "image":"add_image",
    "image_path":"ImageTarget/Blocks.png",
    "image_width":0.26,
}

The "image":"add_image" pair should be located at first. The value of "image_path" is an image path and the value of "image_width" is a real width (meter unit) of an image target.

A sample code is as follows

TrackerManager.getInstance().addTrackerData("{\"image\":\"add_image\",\"image_path\":\"ImageTarget/Blocks.png\",\"image_width\":0.26}", true);

When copying to the assets folder, set the second parameter to true to indicate that it is a relative path and a file in the assets folder. If copying to external storage, enter the full path and set the second parameter to false. The instant training permits only jpg and png formats. An image width as a pixel size should be more than 320 and the best is 640.

※ Instant training of an image takes twice as much time as loading a 2dmap.
※ You must call loadTrackerData () after calling addTrackerData ().


3. References

These are additional references to develop Image Fusion Tracker


3.1 API Reference

Following documents explain classes and functions used to run Image Fusion Tracker.

MaxstAR Class

TrackerManager Class

CameraDevice Class


3.2 Sample

For information regarding sample build and run of Image Fusion Tracker, refer to Sample

ImageFusionTrackerActivity.Java

ImageFusionTrackerRenderer.Java