documentation
This tutorial page shows you how to use models from the Unity hierarchy for tracking. Model tracking (especially when tracking multiple models at once) might get performance-intensive and can thus cause problems on older hardware.
Before adding model tracking to your scene, we recommend you to calibrate your camera (not needed for iOS, ARCore enabled Android devices or HoloLens) (see Camera Calibration).
To add VisionLib tracking to a scene for the first time, please add the following prefabs to your scene:
VLDefaultTrackingConfiguration.prefabVLCamera.prefab as a child of this prefab.Add the license file to the Tracking Configuration component in the VLDefaultTrackingConfiguration.prefab.
If you want to start the tracking as soon as the scene is opened, activate the Auto Start Tracking option in the Tracking Configuration component in the VLDefaultTrackingConfiguration.prefab. As an alternative, you can start the tracking at a later point in time (e.g. when pressing a Buttons OnClick event) by calling TrackingConfiguration.StartTracking. To stop the tracking, you have to call the StopTracking function on the AsynchronousTrackingManager component (located on the VLCamera.prefab).
The TrackingAnchor is the main component for VisionLibs model tracking in Unity. This component reflects one of your individual tracking targets and will manage all connections that are needed for it. Further details about the TrackingAnchor component can be found in the section below.
To add a new tracking anchor in Unity, drag the VLTrackingAnchor.prefab from VisionLib SDK/Core/Prefabs/ModelTracking into the hierarchy.
Now, give each of your tracking anchors an distinct name by setting the Anchor Name in the inspector of the GameObject.
Drag the model, that you want to track into the hierarchy of your Scene under the according VLTrackingAnchor GameObject. Select the TrackingAnchor. It will show a problem, that no TrackingMesh components could be found in the subtree. Press Add TrackingMesh components to all models to solve this issue. More information about the TrackingMesh component can be found in the Model Parts Tracking in Unity page.
After adding a tracking geometry, you also have to decide about the augmentation and the init pose guide. A more detailed explanation about this topic can be found in the Using Different Augmentation and Init Pose Guide page. For the beginning, we recommend using the same model for augmentation and init pose guide, which is also used as tracking geometry. This can be done by adding a RenderedObject component to the same GameObject holding the TrackingAnchor. The VLTrackingAnchor.prefab already contains a RenderedObject on the same GameObject, so nothing has to be done here.
In the final step, the initial tracking pose (init pose) has to be adjusted. This is the relative pose between the camera and the real tracked object at which tracking will be initialized. The real camera will later have to be moved to this pose relative to the real object to engage tracking. To adjust this pose for the new model:
Center in Slam Camera button on the TrackingAnchor. This will move the TrackingAnchor to a position where it is fully visible in the Game view window. Pressing the button will also adjust the near and far plane of the selected camera if this is necessary to keep the model entirely visible.TrackingAnchor's pose until you have found a satisfactory initial pose.For more information about this topic please consult Setting an Init Pose.
If you want to test the AutoInit feature, you can consult AutoInit with WorkSpaces (Beta) for further steps.
In the default case, all tracking parameters will be applied to all tracking targets.
If you want to set varying parameters for the tracking targets instead, you can do so by modifying the TrackingConfiguration. This will overwrite the respective parameter for this specific anchor.
To do so, find the file DefaultTrackingConfiguration.vl from StreamingAssets/VisionLib/Examples/ModelTracking, copy and rename it. Put it in a folder inside StreamingAssets next to your tracking model files. Reference this new file in your VLTracking/Tracking Configuration component in your scene as the Tracking Configuration file.
Open your copy of the tracking configuration in an editor. Add a "anchors" section inside the parameters body For every TrackingAnchor in the scene, which requires individual parameter, you have to add an entry in the "anchors" list:
Important: The name of an anchor in the tracking configuration must be exactly the same like in the according VLTrackingAnchor GameObject. Otherwise the parameter will not be applied.
The TrackingAnchor is the main component for VisionLibs model tracking in Unity. This component reflects one of your individual tracking targets and will manage all connections that are needed for it. You can have several TrackingAnchors in your scene. They will be tracked independently from each other. 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 sales@visometry.com.
The settings on the TrackingAnchors control the behaviour of this tracking target, as explained in the following sections.
Every anchor requires a unique name. Having a speaking name will also help during setup, since problems regarding this anchor will often use its name.
The Slam Camera will be set to the Camera.main of the scene. It has to point to the virtual camera, which is moved by SLAM tracking. In the default setup this is the GameObject containing the TrackingCamera. Using VisionLib in combination with ARFoundation, ImageInjection, or on HoloLens or Magic Leap 2 might require a different setup.
To get an initial guess for the init pose, you can use the Center in Slam Camera button. Pressing this button will move the TrackingAnchor at a position, in which all meshes inside the TrackingAnchor and its children are fully visible. This will not adjust the rotation of the object.
The default way of initializing VisionLibs tracking is to align the virtual model with the physical object. You can deactivate this initialization mechanism (e.g. when using InitData or AutoInit) by unchecking this option. Keep in mind that deactivating this feature while displaying an init pose guide might confuse the user, since aligning virtual model with physical object will not have any effect.
When using extendible tracking (see extendibleTracking in Optional Tracking Parameters), it is often more convenient to not use a fixed init pose but to always keep the model aligned with a specific axis. Activating the Keep Upright feature holds the associated models upright with respect to the world up direction, regardless of camera movement. You can specify a specific axis of the model, which will always point upwards (Model Up Vector).
It is also possible to adjust the World Up Vector. Per default this is the Unity up vector (axis pointing in y-direction). This value should only be adjusted in very specific scenarios (e.g. when using image sequences recorded with VisionLib versions prior to 3.0).
Note: This feature will only be active during initialization. If you want to keep the model upright even during tracking, add a Plane Constrained Mode component to the same GameObject as the TrackingAnchor.
The Tracking Geometry can assist you to set up your tracking geometry. It displays the current size of the models, which are used for tracking in this TrackingAnchor. It is crucial, that these dimensions match the physical object you want to track. For more information about this, please consult the Metric section in the Mandatory Initial Parameters page.
This section provides you with some helper functions:
Add TrackingMesh components to all models will add a TrackingMesh component to all child GameObjects containing a MeshRenderer.Make all models (in)visible in the game view will (de)activate the MeshRenderer components on all child GameObjects. This is isn't very relevant if you are using the same model as tracking mesh and as augmentation, but will be more important in case you are using different augmentation and init pose guide.Remove TrackingMesh components from all models will remove a TrackingMesh component from all child GameObjects.Copy Model License Features will copy the model hashes from all meshes currently used for tracking. This is relevant, if you want to get a license, which is bound to a specific model.The TrackingMesh component and the Scene Hierarchy can best be explained in the context of Model Parts Tracking in Unity.
The Augmented Content contains some helper functions for setting up content, which will be displayed during initialization and tracking of this TrackingAnchor. More information about these helper functions and the corresponding RenderedObject components, which are listed here, can be found in Using Different Augmentation and Init Pose Guide.
The Augmented Content also has the possibility to add and remove Init Pose Interaction. These components allow the user to adjust the init pose during runtime. Please consult Setting an Init Pose for more information on this topic.
The Tracking Events can assist you in adjusting your scene depending on the state of this TrackingAnchor. For further details, please consult Tracking States in Unity.
The list of WorkSpaces are relevant for the AutoInit feature. Workspaces created as children of this gameobject are automatically referenced here. For further details, please consult AutoInit with WorkSpaces (Beta).