documentation

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 .vl file, 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.