Image 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
2.6 Change Tracking Mode
3. Reference
3.1 API Reference
3.2 Sample


1. Overview

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

To specify a target for Image Tracker, You should generate 2D Mapfile of the target using Target Manager. Refer to Target Manager and Recommended Conditions for Target Images.

Once 2D Mapfile is created, proceed to 2. Android Development to continue the tutorial.

Also, refer to Tracker Coordinate System to better understand 3D coordinate system of Image Tracker.

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


2. Android Development

Proceed to this tutorial using Java on Android Studio. Supported version are listed on Requirements & Supports.

ARSDK has to be properly integrated on Android Activity. Refer to Life Cycle documents for detail.


2.1 Start / Stop Tracker

Refer to the following code to Start/Stop Tracker

※ To change the tracker, destroyTracker() should be called before

ImageTrackerActivity.Java

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

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

2.2 Use Tracking Information

Sample target images are in SDK directory > assets > ImageTarget. Print those images to get real tracking targets.

※ startTracker() should be called before

Following content will be augmented for corresponding sample images.

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

To augmented objects using tracking information, refer to the following code.

ImageTrackerRenderer.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

You should call addTrackerData () to register map files and call loadTrackerData () to load registered map files on the tracker.

ImageTrackerActivity.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 following Target Manager

  2. Download the map file you created.

  3. Unzip the downloaded file and copy it to assets folder or any other folder in a external storage. Be aware that using maps in assets folder or external storage is different.

  • To use map files in assets folder, set the second parameter to true to indicate that first parameter is a relative path and the map files are in the assets folder.
TrackerManager.getInstance().addTrackerData("ImageTarget/Blocks.2dmap", true);
  • To use map files in external storage, set absolute path on first parameter and set the second parameter to false.
TrackerManager.getInstance().addTrackerData(mapFile.getAbsolutePath(), false);

※ You should 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, feed a JSON object as the first parameter of addTrackerData().

A sample JSON format is as follows

{
    "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 below.

TrackerManager.getInstance().addTrackerData("{\"image\":\"add_image\",\"image_path\":\"ImageTarget/Blocks.png\",\"image_width\":0.26}", true);
  • To use map files in assets folder, set the second parameter to true to indicate that first parameter is a relative path and the map files are in the assets folder

  • To use map files in external storage, set absolute path on first parameter 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 ()


2.5 Change Tracking Mode

5 Tracking Modes of Image Tracker:

  • NORMAL_TRACKING
  • EXTENDED_TRACKING
  • MULTI_TRACKING
  • JITTER_REDUCTION_ACTIVATION
  • JITTER_REDUCTION_DEACTIVATIO
  • NORMAL_TRACKING: Default Setting. Track one target image.
TrackerManager.getInstance().setTrackingOption(TrackerManager.TrackingOption.NORMAL_TRACKING);
  • EXTENDED_TRACKING: Track even at the far distance from the target image.
TrackerManager.getInstance().setTrackingOption(TrackerManager.TrackingOption.EXTENDED_TRACKING);
  • MULTI_TRACKING: Recognize and track up to three target images at the same time
TrackerManager.getInstance().setTrackingOption(TrackerManager.TrackingOption.MULTI_TRACKING);
  • JITTER_REDUCTION_ACTIVATION: Jitter reduction.
TrackerManager.getInstance().setTrackingOption(TrackerManager.TrackingOption.JITTER_REDUCTION_ACTIVATION);
  • JITTER_REDUCTION_DEACTIVATION: Disable the jitter reduction option.
TrackerManager.getInstance().setTrackingOption(TrackerManager.TrackingOption.JITTER_REDUCTION_DEACTIVATION);

3. References

These are additional references to develop Image Tracker


3.1 API Reference

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

MaxstAR Class

TrackerManager Class

CameraDevice Class


3.2 Sample

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

ImageTrackerActivity.Java

ImageTrackerRenderer.Java