Updating the VisionLib Package

Level: Basic

Updating to vlUnitySDK 20.10.1

Migration Guide - Deprecated the use of relative paths in URIs

The public base directory (which has been adjustable via the VLWorkerBehaviour) has been removed with this release. In relation to that, the use of relative paths when specifying the URI of the license file or tracking configuration has been deprecated. For users that already work with the VLTrackingConfiguration component, everything should be updated automatically without breaking existing Unity scenes.

To remove the deprecation warnings when using relative paths or to fix your paths when you had set a custom base directory before, please change them to refer to absolute locations. E.g. if you have been using a relative URI like Examples/ModelTracking/car.vl to start tracking, you can simply add the new streaming-assets-dir: scheme and the VisionLib/ folder in front of the uri: streaming-assets-dir:VisionLib/Examples/ModelTracking/car.vl. Like this, the path will be interpreted relative to Assets/StreamingAssets/VisionLib again. You can fix the license path of the VLWorkerBehaviour in the same way. The VLWorkerBehaviour will then look similar to this:

Alternatively, simply drag and drop the used tracking configuration, license and calibration files inside the VLTrackingConfiguration component in your scene and adjust their URIs if needed.

Updating to vlUnitySDK 20.3.1

This update contains some changes in the native interface. The application of these changes made some files obsolete. Additionally, some internal behaviour and default paths have changed.
To avoid complications when updating an existing project, please refer to the migration guides provided below.

Migration Guide - Obsolete Files

Please remove the following obsolete files (and their .meta files) from your project:

• Assets/VisionLib/Core/Scripts/Editor/VLDebugImageBehaviourEditor.cs
• Assets/VisionLib/Core/Scripts/Debug/VLDebugCameraBehaviour.cs
• Assets/VisionLib/Utilities/Prefabs/Debug/VLDebugCamera.prefab
• Assets/VisionLib/Utilities/UI/Templates/Notifications/Scripts/VLEventsNotification.cs

Migration Guide - Default License Path

To keep the places of files related to VisionLib at a minimum, we changed the default folder of the license from StreamingAssets to StreamingAssets/VisionLib.
If you never adjusted the license path in the VLWorkerBehaviour you might thus get an error that your license can not be found anymore.

• To fix this, move your license to StreamingAssets/VisionLib or adjust its path in the VLWorkerBehaviour (located in the scene hierarchy under VLTracking/VLCamera).

Migration Guide - VLDebugImage

The behaviour of the debug image has been changed internally. To be able to use it like before, do the following adjustments:

• Select the VLDebugImage in your canvas. On its component VLImageStreamFilter, select DebugImage if you want to see the grey image or CameraImage if you want to see the camera image for debugging.
• To be able to use the grey image, please set the debugLevel to 1 inside your tracking configuration. Don't forget to remove this line before your final deploy to increase performance.

"tracker": {
    "type": "modelTracker",
    "version": 1,
    "parameters": {
        "modelURI": "project-dir:VLMiniCar.obj",
            ...
        "debugLevel": 1
    }

Migration Guide - Access of Image Sequence Parameters

Image sequence parameters can now only be accessed when actually using an image sequence. Trying to access those parameters when using a camera for tracking will print warnings to your console. To fix this:

• Remove the VLImageSequenceParameters prefab from your scene hierarchy (under VLTracking)
• If you are using the ImageSourcePanel from the AdvancedModelTracking scene in your canvas, also remove all of its children except Enabled:
• You will still be able to pause and resume an image sequence by using the remaining enabled checkbox

Updating to vlUnitySDK 19.11.1 - Remove of 180° Flip & New Folder Structure

This update contains important changes regarding the 180° flip of models and the general folder structure of the VisionLib Unity package. To avoid complications when updating an existing project, please refer to the migration guides provided below.

Migration Guide - 180° Flip

Since 19.11.1 we now handle Unity’s coordinate system handedness automatically, so you don’t need to rotate your tracking target 180 degrees around the y-axis anymore. However, in order to use this update in older projects, you can easily turn back to the legacy behaviour. So you don’t need to make changes in your scene setup:

• Activate legacy support:
  • Select the VLCamera GameObject under VLTracking in the hierarchy
  • Browse to the VLWorkerBehaviour component in the inspector
  • Choose the Manually option for the parameter Flip Coordinate System Handedness
  • A warning box will appear, that tells you that this option is deprecated. You can ignore it for now, but keep in mind that this option might be removed in the future.

• Switch to new automatic mode:
  • The Automatically option is activated by default in the component described above
  • Remove the 180° rotation around the y-axis on all scene objects that have been used as augmentations in your scene
  • Update the initial pose. Either move the VLInitCamera in your scene or edit the init pose that is set in your tracking configuration, depending on which one you have used before

Background to the 180° Flip:

The coordinate system used for tracking by VisionLib is right-handed, while the coordinate system used by Unity is left-handed. This caused several issues, when using the same model for tracking and visualization. For example when moving the VLInitCamera, the movement direction in Unity did not match the movement direction of VisionLib. Thus, to match visualization and tracking, models had to be rotated 180° around the Y-axis.

With this release, VisionLib converts the coordinate system automatically in Unity. You are no longer required to manually rotate your models around the Y-axis. This change only affects Unity development; it does not apply for development with VisionLib outside of Unity.

Migration Guide - New Folder Structure

The new folder structure is not a breaking change. If you leave your project as it is and just import the new VisionLib package, Unity will keep your previous folders and will not use the updated structure. Anyway, if new files are added from the VisionLib package, they will appear under the new structure, which leads to an inconsistent mix of folders. Also, some references to .vl-files might break in the example scenes.

Therefore, we recommend to remove all VisionLib assets from your project to make a clean update afterwards.

Note: Please make a backup of your project before deleting assets
Note: Don't delete the entire folders but the single files if you have used the folders for your own assets

• Delete _Scenes folder that is containing the example scenes:
  
• Delete GUI folder (and it's subfolders "LoadingScreen" and "Parameters"):
  
• Delete Materials folder containing three assets:
  
• Delete Models folder containing two assets and two folders:
  
• Delete Scripts folder containing 13 scripts and the subfolder "BuildingBricks":
  
• Delete the VisionLib folder:
  
• Delete the VisionLib folder inside the StreamingAssets
  
• If you own an experimental package, also remove all "Experimental" folders and their contents
• Now you can import the latest vlUnitySDK package into your project. All previous set references should be restored.