documentation

Multi Model Tracking (Beta)

Level: Advanced

This tutorial page shows you how to track multiple models with VisionLib.

Note: This feature is still in beta, and might be modified in upcoming releases.

Preparations

Important: This feature depends on VisionLib's AutoInit. If you are not familiar with it, please read the AutoInit tutorial first.

Before implementing multi model tracking,

  • make sure to set up and test tracking with AutoInit for each of the models individually

Additionally,

  • tweak the tracking parameters to achieve a stable tracking (see vlUnitySDK_UnderstandingTrackingParameters)
  • calibrate your camera (not needed for iOS or ARCore enabled Android devices) (see Camera Calibration)
  • enable extendible tracking (ARKit/ARCore) inside the tracking configuration (.vl file) to improve initialization results (see External SLAM (ARKit/ARCore) Support)

Multi model tracking might get performance-intensive and can thus cause problems on older hardware. We recommend using hardware from 2018 or newer.
This feature is currently not supported on HoloLens.

1. Set up the Unity Scene

You can find an example implementation of multi model tracking with TrackingAnchors in the VisionLib.SDK.Examples-Unity.unitypackage. It contains the MultiModelTracking example Scene located at VisionLib Examples/ModelTracking/Multi.

To test the example Scene, use the tracking targets that are provided here: https://visionlib.com/resources.

The following steps allow you to add multi model tracking to an existing VisionLib Unity Scene.

Activate Multi Model Tracking in the VLCamera

Select the VLCamera, scroll down to its TrackingCamera component in the inspector and set the Coordinate System Adjustment dropdown to Multi Model Tracking.

Create Tracking Anchors

Drag a VLTrackingAnchor prefab from VisionLib SDK/Core/Prefabs/ModelTracking into the hierarchy. This object reflects one of your individual tracking targets and will manage all connections that are needed for it. So if you want to track three different models, you will need three VLTrackingAnchors in your Scene.

Now, give each of your tracking anchors an distinct name by setting the Anchor Name in the inspector of the GameObject.

Connect Visualization Models to the Tracking Anchors

Drag the model, that you wish to use to augment one of your tracking targets, into the hierarchy of your Scene. It is recommended to drop it under the according VLTrackingAnchor GameObject, but this is not mandatory. Make sure to keep its position at (0,0,0).

Now, with the VLTrackingAnchor selected, drag the model from the hierarchy inside the Augmentation parameter of the according TrackingAnchor. With this connection, the visualization model will be activated as soon as the tracking target is detected. Also, its transformation will be set to match the position of the real model.

Repeat this for all TrackingAnchors in your Scene.

Connect WorkSpaces to the Tracking Anchors

To add a WorkSpace to a TrackingAnchor, right click on the Augmentation GameObject in the hierarchy and select VisionLib > AutoInit > Create Simple / Advanced WorkSpace. This will create a WorkSpace which uses the selected GameObject as its destination in case of the SimpleWorkSpace. If the selected GameObject has a TrackingAnchor as its parent, the newly created WorkSpace will also be added to the list of WorkSpaces of that TrackingAnchor automatically. It will also create a VLWorkSpaceManager GameObject if it doesn't exist yet.

Repeat this for all of TrackingAnchors in your Scene.

The referenced WorkSpace(s) will later be used to automatically initialize the tracking target of that anchor.

If you copy an existing WorkSpace from a different Scene, make sure that references to Used Camera, Destination Object (and Origin Object for the AdvancedWorkSpace) reference objects in the current Scene. You also have to add a reference to the list of WorkSpaces in the corresponding TrackingAnchor.

Note: Using the same object as Destination Object in the WorkSpace as you use for the Augmentation in the TrackingAnchor works fine for the SimpleWorkSpace but leads to problems with the AdvancedWorkSpace, since the latter reads the transform of the destination object which will be changed by the TrackingAnchor during runtime.

Note: Keep in mind that a high count of origin points of the WorkSpaces may increase the initialization speed but also decrease the performance and should therefore be set carefully.

2. Adjust the Tracking Configuration

Find the file MultiModelTrackingConfiguration.vl from StreamingAssets/VisionLib/Examples/ModelTracking, copy and rename it. Put it in a folder inside StreamingAssets next to your tracking model files.

Open your copy of the tracking configuration in an editor. You will notice the following changes to a "simple" model tracker:

  • Multi Model Tracking is enabled, by setting the tracker "type" to "multiModelTracker" with version 1.
"tracker": {
"type": "multiModelTracker", // Enable Multi Model Tracking
"version": 1,


  • AutoInit is enabled, by adding "autoInit": true in the parameters section:
"parameters": {
"autoInit": true, // Enable AutoInit


  • References to your TrackingAnchors have to be set

This section inside the parameters body holds a list of trackingAnchors, each of which is defined by a name and a models section. The latter contains the file path of the according tracking target.

"anchors": [ // List of tracking anchors
{
"name": "VLCar", // Individual name of the TrackingAnchor in Unity
"models": [
{
"uri": "project-dir:/VLMiniCar.obj" // File path to tracking target
}
]
},
{
"name": "VLSportsCar",
"models": [
{
"uri": "project-dir:/VLSportsCar.obj"
}
]
}
]

Important: Change the name of the anchors to match the ones you have set in the Unity Scene before. The name of an anchor in the tracking configuration must be exactly the same like in the according VLTrackingAnchor GameObject.

After that, provide the filename of your tracking targets that are located inside the StreamingAssets folder. You can write project-dir:/myModel.obj as long as a copy of your model is inside the same path as the tracking configuration.

Note: Use a different model for each anchor. At the moment, it is not possible to track multiple instances of the same object.

Set specific tracking parameters

If you are using the example tracking configuration, all set tracking parameters will be applied to all tracking targets defined in anchors.
If you want to set varying parameters for the tracking targets instead, you can do so by inserting an additional parameters section for an anchor. This will overwrite the respective parameter for this specific anchor.

See an example for this below:

"anchors": [
{
"name": "VLCar",
"models": [
{
"uri": "project-dir:/VLMiniCar.obj"
}
],
"parameters": {
"laplaceThreshold": 80,
"keyFrameDistance": 52
}
}
]

3. Start Tracking multiple objects

As always, reference your used tracking configuration (.vl file) and license in the TrackingConfiguration component of the VLTracking object.

After setting up your TrackingAnchors and its references, you are now ready to start tracking. This works exactly like starting an AutoInit Scene, either automatically with the WorkSpaceManager(which is active by default), or by calling WorkSpaceManager.LearnWorkSpaceInitData() e.g. on a button click or from your script.

Wait some seconds (activate the progress bar in the WorkSpaceManager to show the learning progress) until all poses have been trained.
Now you can point your camera to one or multiple physical object(s) that match the defined tracking targets and they will be tracked.

License options

You can track up to three different models with a basic license e.g. the trial or developer license. If you want to extend the number of tracked models, please write us at reque.nosp@m.st@v.nosp@m.ision.nosp@m.lib..nosp@m.com.

Feedback

If you have issues or suggestions on how to enhance or integrate this feature, please do not hesitate to contact us on reque.nosp@m.st@v.nosp@m.ision.nosp@m.lib..nosp@m.com.