Space Fusion 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 Map
2.5 Add / Replace Map
3. Reference
3.1 API Reference
3.2 Sample


1. Overview

Start developing MAXST ARSDK Space Fusion Tracker on iOS Platform. Refer to Space Tracker Introduction for detailed information.

Generate 3D Mapfile of the target for Space Tracker via MAXSCAN. The Space Tracker loads the map file and renders 3D space on it. Refer to Visual SLAM Learning Guide to create a map more precisely while scanning 3D space.
Refer to Tracker Coordinate System to better understand 3D coordinate system of Space Fusion Tracker iOS Tutorial .

The Space Tracker loads the map file and renders 3D space on it.
After target recognition and initial poses are acquired through the MAXST SDK, use AR Kit for tracking.

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

Prerequisites
Space Tracker Introduction
Visual SLAM Tool
Tracker Coordinate System
Visual SLAM Learning Guide


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

SpaceFusionTrackerViewController.swift

var trackingManager:MasTrackerManager = MasTrackerManager()

2.2 Start / Stop Tracker

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

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

SpaceFusionTrackerViewController.swift

func startEngine() {
     ...
        
if(trackingManager.isFusionSupported()) {
     trackingManager.start(.TRACKER_TYPE_SPACE_FUSION)
     let spaceTrackerMapPath:String = Bundle.main.path(forResource: "obj_190712_7", ofType: "3dmap", inDirectory: "data/SDKSample")!
     trackingManager.addTrackerData(spaceTrackerMapPath)
     trackingManager.addTrackerData("{\"space_fusion\":\"set_length\",\"space_name\":\"obj_190712_7\", \"length\":0.53}");
     trackingManager.loadTrackerData()
     }
}

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

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

On the first call to addTrackerData (), the parameter must be passed the path of the 3dmap.
The addTrackerData () in the second call is used to determine the actual size of the 3dmap. (Unit: m)
Space_name is the file name of the 3dmap.
Length is the actual size of the two anchors you marked last when creating the 3dmap. (Please refer to Visual SLAM Tool.)
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 ().


2.3 Use Tracking Information

To use the Tracking information, refer to the following code.

SpaceFusionTrackerViewController.swift

func draw(in view: MTKView) {
    ...
    
    let trackingState:MasTrackingState = trackingManager.updateTrackingState()
    let result:MasTrackingResult = trackingState.getTrackingResult()
    
    let backgroundImage:MasTrackedImage = trackingState.getImage()
    var backgroundProjectionMatrix:matrix_float4x4 = cameraDevice.getBackgroundPlaneProjectionMatrix()
    
    let projectionMatrix:matrix_float4x4 = cameraDevice.getProjectionMatrix()
    
    if let cameraQuad = backgroundCameraQuad {
        cameraQuad.setProjectionMatrix(projectionMatrix: backgroundProjectionMatrix)
        cameraQuad.draw(commandEncoder: commandEncoder, image: backgroundImage)
    }
    
    let trackingCount:Int32 = result.getCount()
    
    for i in stride(from: 0, to: trackingCount, by: 1) {
        let trackable:MasTrackable = result.getTrackable(i)
        let poseMatrix:matrix_float4x4 = trackable.getPose()
        
        textureCube.setProjectionMatrix(projectionMatrix: projectionMatrix)
        textureCube.setPoseMatrix(poseMatrix: poseMatrix)
        textureCube.setTranslation(x: 0.0, y: 0.0, z: -0.15)
        textureCube.setScale(x: 0.3, y: 0.3, z: 0.3)
        textureCube.draw(commandEncoder: commandEncoder)
    }
    ...
}

2.4 Set Map

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

SpaceFusionTrackerViewController.swift

func startEngin()
{
    ...
    trackingManager.addTrackerData(spaceTrackerMapPath)
    trackingManager.loadTrackerData()
}

Note - Map Compatibility
Starting with Visual Slam Tool 5.1.0, the file format for 3dmaps has changed. 3dmaps created in Visual Slam Tool 5.1.0 or later are supported by AR SDK 6.2.x or later. If you want to continue using AR SDK 6.0.x or earlier, please use Visual Slam Tool 5.0.8 Android.
Also, you can only add 3dmaps from the same version to Object Tracker.


2.4.1 Set Package

If you are using multiple object maps, packaging them in a 3dpkg file will greatly improve map loading speed and recognition speed.
Create a 3dpkg with MapPackager, call AddTrackerData() to register the package file, and call LoadTrackerData() to track the target object.

func startEngin()
    ...    
    let packagePath:String = Bundle.main.path(forResource: "package", ofType: "3dpkg", inDirectory: "data/SDKSample")!

    trackingManager.addTrackerData(packagePath)
    trackingManager.loadTrackerData()
    ...
}

※ Object Package(3dpkg) is available from AR SDK 6.1.0.
※ Only 3dmaps created in Visual Slam Tool 5.1.0 or later can be packaged as 3dpkg.
※ Only one 3dpkg can be added to Object Tracker.

2.5 Add / Replace Map

※ You can add multiple 3Dmaps to recognize one of multiple spaces. We recommend to add up to three maps.

  1. Create a map file refer to Visual SLAM Tool.

  2. Copy the received map file to the desired path.

  3. Set a map.

  4. If you have an existing map file, call function 'addTrackerData' and function 'loadTrackerData' after calling trackingManager.removeTrackerData()


3. References

These are additional references to develop Space Fusion Tracker


3.1 API Reference

Following documents explain classes and functions used to run Space Fusion tracker.

MaxstAR Class

TrackerManager Class

CameraDevice Class


3.2 Sample

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

SpaceFusionTrackerViewController.swift