Image Tracker iOS Tutorial

1. Overview
2. iOS Development
2.1 Create Instants
2.2 Start / Stop Tracker
2.3 Use Tracking Information
2.4 Set Target Image
2.5 Add / Replace Target Image
2.6 Train Target Image Instantly
2.7 Change Tracking Mode
3. Reference
3.1 API Reference
3.2 Sample


1. Overview

Start developing MAXST ARSDK Image Tracker on iOS 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. iOS 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. iOS Development

Start developing on xCode using Swift. Refer to Requirements & Supports to find out which devices are supported.

ARSDK has to properly integrate on iOS UIViewController. Refer to Life Cycle documents for detail.


2.1 Create Instants

ImageTrackerViewController.swift

var cameraDevice:MasCameraDevice = MasCameraDevice()
var trackingManager:MasTrackerManager = MasTrackerManager()

2.2 Start / Stop Tracker

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

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

ImageTrackerViewController.swift

@objc func resumeAR()
{
    ...
    trackingManager.start(.TRACKER_TYPE_IMAGE)
}

@objc func pauseAR()
{
    trackingManager.stopTracker()
    ...
}

2.3 Use Tracking Information

In the folder where SDK is installed, go to ‘data > SDKSample > Original > 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.

※ startTracker() should be called before

ImageTrackerViewController.swift

override func glkView(_ view: GLKView, drawIn rect: CGRect) {
        ...
        let trackingState:MasTrackingState = trackingManager.updateTrackingState()
        let result:MasTrackingResult = trackingState.getTrackingResult()

       let backgroundImage:MasTrackedImage = trackingState.getImage()
        let backgroundProjectionMatrix:matrix_float4x4 = cameraDevice.getBackgroundPlaneProjectionMatrix()
        
        glEnable(GLenum(GL_DEPTH_TEST))
        
        let projectionMatrix:matrix_float4x4 = cameraDevice.getProjectionMatrix()
        
        let trackingCount:Int32 = result.getCount()
        
        if trackingCount > 0 {
            for i in stride(from: 0, to: trackingCount, by: 1) {
                let trackable:MasTrackable = result.getTrackable(i)
                
                if trackable.getName() == "Lego" {
                    if videoCaptureController.getState() == MEDIA_STATE.PLAYING {
                        videoCaptureController.play()
                        videoCaptureController.update()
                        
                        videoPanelRenderer.setProjectionMatrix(projectionMatrix: projectionMatrix)
                        videoPanelRenderer.setPoseMatrix(poseMatrix: trackable.getPose())
                        videoPanelRenderer.setTranslation(x: 0.0, y: 0.0, z: 0.0)
                        videoPanelRenderer.setScale(x: 0.26, y: -0.15, z: 1.0)
                        videoPanelRenderer.draw(videoTextureId: videoCaptureController.getOpenglesTextureId())
                    }
                } else if trackable.getName() == "Blocks" {
                    if chromakeyVideoCaptureController.getState() == MEDIA_STATE.PLAYING {
                        chromakeyVideoCaptureController.play()
                        chromakeyVideoCaptureController.update()
                        
                        chromakeyVideoPanelRenderer.setProjectionMatrix(projectionMatrix: projectionMatrix)
                        chromakeyVideoPanelRenderer.setPoseMatrix(poseMatrix: trackable.getPose())
                        chromakeyVideoPanelRenderer.setTranslation(x: 0.0, y: 0.0, z: 0.0)
                        chromakeyVideoPanelRenderer.setScale(x: 0.26, y: -0.18, z: 1.0)
                        chromakeyVideoPanelRenderer.draw(videoTextureId: chromakeyVideoCaptureController.getOpenglesTextureId())
                    }
                } else if trackable.getName() == "Glacier" {
                    textureCube.setProjectionMatrix(projectionMatrix: projectionMatrix)
                    textureCube.setPoseMatrix(poseMatrix: trackable.getPose())
                    textureCube.setTranslation(x: 0.0, y: 0.0, z: -0.025)
                    textureCube.setScale(x: 0.15, y: 0.15, z: 0.05)
                    textureCube.draw()
                } else {
                    coloredCube.setProjectionMatrix(projectionMatrix: projectionMatrix)
                    coloredCube.setPoseMatrix(poseMatrix: trackable.getPose())
                    coloredCube.setTranslation(x: 0.0, y: 0.0, z: -0.025)
                    coloredCube.setScale(x: 0.15, y: 0.15, z: 0.005)
                    coloredCube.draw()
                }
            }
        }
        else {
            videoCaptureController.pause()
            chromakeyVideoCaptureController.pause()
        }
        
        glDisable(GLenum(GL_DEPTH_TEST))
        
    }

2.4 Set Target Image

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

ImageTrackerViewController.swift

func startEngin()
{
    ...
    let blocksTrackerMapPath:String = Bundle.main.path(forResource: "Blocks", ofType: "2dmap", inDirectory: "data/SDKSample")!
    let glacierTrackerMapPath:String = Bundle.main.path(forResource: "Glacier", ofType: "2dmap", inDirectory: "data/SDKSample")!
    let legoTrackerMapPath:String = Bundle.main.path(forResource: "Lego", ofType: "2dmap", inDirectory: "data/SDKSample")!
        
    trackingManager.start(.TRACKER_TYPE_IMAGE)
    trackingManager.setTrackingOption(.NORMAL_TRACKING)
    trackingManager.addTrackerData(blocksTrackerMapPath)
    trackingManager.addTrackerData(glacierTrackerMapPath)
    trackingManager.addTrackerData(legoTrackerMapPath)
        
    trackingManager.loadTrackerData()
}

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

  4. Set a target image.


2.6 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 like below.

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

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 ().


2.7 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.
trackingManager.setTrackingOption(.NORMAL_TRACKING)
  • EXTENDED_TRACKING: Track even at far distance from the target image.
trackingManager.setTrackingOption(.EXTENDED_TRACKING)
  • MULTI_TRACKING: Recognize and track up to three target images at the same time.
trackingManager.setTrackingOption(.MULTI_TRACKING)
  • JITTER_REDUCTION_ACTIVATION: Jitter reduction.
trackingManager.setTrackingOption(.JITTER_REDUCTION_ACTIVATION)
  • JITTER_REDUCTION_DEACTIVATION: Disable the jitter reduction option.
trackingManager.setTrackingOption(.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

ImageTrackerViewController.swift