Logo of the VisionLib Documentation Pages
› Go to visionlib.com

documentation
Migrating From 2.x to 3.0
Level: Basic

The VisionLib SDK 3.0 Release introduces major interface changes. Please make a backup of your project before upgrading to the new release and follow all sections below for migration guidance.

Migration Guide - Switch to Using Models From the Scene Hierarchy for Tracking

Affects: Unity model tracking scenes with tracking configurations that reference model files for tracking

Starting with VisionLib SDK 3.0, tracking models should no longer be specified in the tracking configuration file. Instead, models are added directly to the scene hierarchy from where new components forward them to VisionLib for tracking.

To migrate an existing scene to this new system, take the following steps:

  1. Add a new (empty) child GameObject (e.g. named ModelTrackingReference) under the SceneContent GameObject.
  2. Add your tracking model(s) to the hierarchy as children of the new ModelTrackingReference GameObject.
  3. Add a TrackingAnchor component to the ModelTrackingReference GameObject.
  4. Remove all TrackingModel components from your scene and reparent GameObjects containing a TrackingModel under the ModelTrackingReference GameObject.
  5. Move all models you want to use for tracking underneath the ModelTrackingReference GameObject.
  6. On the TrackingAnchor component:
    • Press the Tracking Geometry/Add TrackingMesh component to all models button. This will add a TrackingMesh component to all child models under the ModelTrackingReference. The TrackingMesh components enable the use of the individual models for tracking in VisionLib.
    • Set the Slam Camera field in the TrackingAnchor to the Camera.main.
    • Press the Use this tracking anchor as content button. This will add a RenderedObject component to this GameObject. The RenderedObject component is used for applying the tracking result to the Transform of its GameObject. This way, augmentation and init pose guide will be moved and placed correctly in the world. For more details, you can also consult Using Different Augmentation and Init Pose Guide.
  7. Open the tracking configuration currently specified in VLTracking/Tracking Configuration:
    • Remove the modelURI parameter.
    • Change the type of the tracker to multiModelTracker.
  8. Remove the VLInitCamera GameObject from your scene, if present. The InitCamera script is no longer used. Instead, the position of the TrackingAnchor relative to the MainCamera is used as the init pose by default. To obtain an initial estimation for the init pose, press the Center Object in Slam Camera button on the TrackingAnchor. This will center your object in the view of the camera that is used to initialize the tracking.
  9. Remove the WorkSpaceManager from your scene, if present. The TrackingAnchor will take care of adding the WorkSpaces to VisionLib itself. To display the AutoInit learning progress, add an AutoInitProgressBar to your scene.
  10. Move the Plane Constrained Mode component to the ModelTrackingReference GameObject.
  11. Remove the auto-generated TrackingAnchor from the GameObject where the Plane Constrained Mode component was previously located.

For further details on the TrackingAnchor and the scene setup, see Using Models from the Unity Hierarchy.

Migration Guide - Replace Obsolete XRTracker

Affects: AR Foundation scenes that use VisionLib tracking

In VisionLib SDK 3.0, the generic TrackingAnchor replaces the XRTracker.

  1. If you referenced an Init Camera in your XR Tracker (probably a game object called VLInitCamera), copy its transform into the ARCamera's transform.
  2. Add a TrackingAnchor component somewhere.
  3. Follow the migration guide "Use models from Unity scene for tracking" to adjust the scene to the new VisionLib interface.
  4. Make sure the AR Camera is referenced as the SLAM Camera in the TrackingAnchor.
  5. Remove the XRTracker component.
  6. Remove the VLInitCamera GameObject. Instead, the position of the TrackingAnchor relative to the AR Camera is used as the init pose by default. To obtain an initial estimation for the init pose, press the Center Object in Slam Camera button on the TrackingAnchor. This will center your object in the view of the camera that is used to initialize the tracking.

Migration Guide - Remove Unused HoloLens Tracker Component

Affects: HoloLens scenes that use VisionLib model tracking

In VisionLib SDK 3.0, the TrackingAnchor and the HoloLensGlobalCoordinateSystem together replace the HoloLensTracker component.

  1. Add a TrackingAnchor component somewhere.
  2. Follow the migration guide "Use models from Unity scene for tracking" to adjust the scene to the new VisionLib interface.
  3. Make sure the previous HoloLens Camera is referenced as the SLAM Camera in the TrackingAnchor.
  4. Replace the HoloLensTracker component with a HoloLensGlobalCoordinateSystem component.
  5. Remove the HoloLensInitCamera GameObject. Instead, the position of the TrackingAnchor relative to its SLAM Camera is used as the init pose by default. To obtain an initial estimation for the init pose, press the Center Object in Slam Camera button on the TrackingAnchor. This will center your object in the view of the camera that is used to initialize the tracking.

Migration Guide - Discontinued Component: InitCamera - Use Pose From Tracking Config

In 3.0 the init pose is no longer set using the InitCamera (or HoloLensInitCamera) component. Instead, the pose of a TrackingAnchor's GameObject is now treated as the init pose.

For cleaner data flow, TrackingAnchors no longer allow the use of init poses from tracking configuration files. Instead, the now legacy option to load init poses from config files has been moved to a separate component: InitPoseFromTrackingConfig. If you would like to migrate an existing project and continue to store your init pose in the tracking configuration file, first follow the migration guide "Use Models from Unity Scene for Tracking", then set up init pose loading as follows:

  1. Find the GameObject containing the TrackingAnchor (named ModelTrackingReference in the example above)
  2. Add a new component of type InitPoseFromTrackingConfig to this GameObject
  3. Reset all values in the SLAM Camera's transform to zero. (This camera is referenced in the TrackingAnchor.)

Note: To persistently apply the init pose retrieved by the InitPoseFromTrackingConfig component, you can copy the values in the transform of the TrackingAnchor's GameObject during play mode in the editor. After this, you stop the scene and paste the values into the GameObject's transform. Now you can save the scene with the init pose that was previously stored in your Tracking Configuration as the Transform of the TrackingAnchor. After this, you may remove the InitPoseFromTrackingConfig component and delete the init pose from your Tracking Configuration file. Both are no longer required.

Migration Guide - Discontinued Component: TrackingModel

In 3.0 the TrackingModel component has been removed. Please remove any references to this script from your scene. To use the model injection feature follow the Migration Guide - Switch to Using Models from The Scene Hierarchy for Tracking.

Migration Guide - Display AutoInit Learning Progress

In 3.0, the WorkSpaceManager has been removed since the TrackingAnchor now handles the learning process itself. To display the AutoInit learning progress, add an AutoInitProgressBar to your scene.

Migration Guide - Plane Constrained Mode

This guide applies to scenes where a tracking target was previously constrained to a plane.

Plane Constrained Mode components must now be located on the same GameObject as the TrackingAnchor they constrain. In each affected scene, move the existing Plane Constrained Mode component accordingly. Then remove the auto-generated TrackingAnchor from the GameObject where the Plane Constrained Mode component was previously located.

Migration Guide - Tracking Anchor: Using Keep Upright With Old Image Sequences

The "keep upright" option on the TrackingAnchor holds the associated models upright with respect to the world up direction, regardless of camera movement. In image sequences with SLAM pose data recorded on iOS and Android with VisionLib versions prior to 3.0, the SLAM up vector is upside down w.r.t. Unity's world up direction. When using "keep upright" with these sequences, you must invert the World Up Vector parameter in all TrackingAnchors under Keep Upright/Advanced. Otherwise, the model will be held upside down. In the default case, this would mean changing the parameter from (0,1,0) to (0,-1,0).

In 3.0, we rotated the SLAM coordinate system on Android and iOS such that the SLAM up direction aligns with Unity's world up direction (see Release Notes 3.0). The workaround described above is therefore no longer required with image sequences newly recorded using the current VisionLib version.

Migration Guide - Migrate to New InitData Naming Convention

We have changed the naming schemes for init data with this release. To read data from old projects, rename the files according to the tables in Release Notes 3.0.

Migration Guide - Retain Predicted Pose Indefinitely

If the model tracking gets lost and extendibleTracking is activated, VisionLib predicts the pose of the object in the world via the SLAM transform. In this situation, drift in the SLAM pose might then predict the pose slightly beside the real object, which might prevent reinitialization of the tracking. To be able to automatically reset the tracking after a certain amount of reinitialization attempts, we introduced the parameters allowedNumberOfFramesSLAMPrediction and allowedNumberOfFramesSLAMPredictionObjectVisible in 2.3 (see also Model Tracker). The second of these parameters limits the number of frames for which purely SLAM pose predictions may keep tracking alive while the SLAM-predicted object location is inside the camera's field of view. In 3.0 the default value of this parameter has been changed from -1 (limit deactivated) to 180. It also has been set to 45 in all HoloLens example scenes.

To deactivate that limit again (keep tracking alive indefinitely long):

  1. Open the tracking configuration file used in your scene.
  2. Add the parameter allowedNumberOfFramesSLAMPredictionObjectVisible in the parameters section of the tracker.
  3. Set the value of this parameter to -1 (deactivated).

Migration Guide - Removed Deprecated Parameters

Affects: Tracking configurations created before 2.0.0

We deprecated a number of parameters and behaviors in VisionLib SDK version 2.0. Their future removal was communicated through obsolescence warnings. Some of the obsolete parameters have now been removed with VisionLib SDK version 3.0. The removed parameters are listed in the following, along with their respective replacements:

Removed parameter name New Parameter name Additional adjustments
metaioLineModelURI lineModelURI Metaio line models can be rotated 180 degrees around the y-axis to create VisionLib line models
type: metaio in initPose no type necessary anymore To use a metaio init pose as a VisionLib init pose, you have to apply a 180 degree rotation around the y-axis from the right and a 180 degree rotation around the x-axis from the left.
scheme name with underscore (like project_dir, local_storage_dir, etc.) Corresponding name with hyphens instead of underscores
usePoseFiltering use poseFilteringSmoothness instead This parameter defines the smoothness of the pose filter. Lower values will make the filter very smooth. Higher values will make the filter less lagged. Setting the value to 0 turns off the filter.
showLineModelTracked use "showLineModel": {"enabled": {"tracked": true}} instead This option allows you to draw the line-model into the camera image while the objects gets tracked successfully.
showLineModelTrackedColor use "showLineModel": {"enabled": {"tracked": true}, "color": {"tracked": [0,255,0]}} instead This color option can be used to change the color used for drawing the line-model while the objects gets tracked successfully.
showLineModelCritical use "showLineModel": {"enabled": {"critical": true}} instead This option allows you to draw the line-model into the camera image while the tracking is critical.
showLineModelCriticalColor use "showLineModel": {"enabled": {"critical": true}, "color": {"critical": [0,255,0]}} instead This color option can be used to change the color used for drawing the line-model while the tracking is critical.
showLineModelLost use "showLineModel": {"enabled": {"lost": true}} instead This option allows you to draw the line-model into the camera image while the tracked object is lost.
showLineModelLostColor use "showLineModel": {"enabled": {"lost": true}, "color": {"lost": [0,255,0]}} instead This color option can be used to change the color used for drawing the line-model while the tracked object is lost.
showLineModelTrackedInvalid use "showLineModel": {"color": "perCorrespondency"} instead This option allows you to draw the color-coded visualization of the tracking status of each correspondence as a line model in the camera image.

Migration Guide - Using Multiple Tracking Anchors with the Same Name

With Version 3.0.0, the TrackingAnchor component now manages its representation in the backend and requires a one-to-one mapping.

Previously, it was possible to define a single anchor in the tracking configuration file and use multiple TrackingAnchor components (for example, to achieve different smoothing rates) with the name of that anchor.

To achieve the same behavior, you now need to use a single TrackingAnchor but multiple RenderedObject components, each referencing this TrackingAnchor. Since Smooth Time is a property of the RenderedObject, the old behavior can still be achieved.

For more detailed information about the RenderObject component, please consult Using Different Augmentation and Init Pose Guide.