Release Notes 2.0

Version 2.0.2

Info

Release date: 29.04.2021
Release info: Patch

Bugfixes

• Fixed compatibility issues between certain Unity and ARFoundation versions by increasing the package dependency to version 2.1.18.
• Fixed outdated links and descriptions in documentation.
• Fixed an error that appeared when switching to a different platform than Windows or UWP while having the VisionLib.SDK.HoloLens package imported.
• Removed Windows XR Loader assets from the VisionLib.SDK.HoloLens.Examples package.

Version 2.0.1

Info

Release date: 01.04.2021
Release info: Patch

Bugfixes

• Fixed model hash calculation in the license tool (issue only ocurred in 2.0.0).

Version 2.0.0

Info

Release date: 17.03.2021
Release info: Major Release

Summary

This is a major update for VisionLib which adds:

• Distribution of the VisionLib SDK for Unity as an UPM (Unity Package Manager) package. The examples as well as extensions for HoloLens and ARFoundation have been separated from the core SDK. For further details, see Install VisionLib Packages in Unity.
• Introduction of Semantic Versioning for VisionLib SDK versions, beginning with 2.0.0. Semantic Versioning expresses versions as MAJOR.MINOR.PATCH, where MAJOR introduces one or more breaking changes, MINOR introduces one or more backward-compatible API changes, and PATCH only introduces bug fixes with no API changes at all.
• Introduction of a Task based interface to control VisionLib via commands. This makes development with the asynchronous parts of the VisionLib interface easier to use and understand. For details, see Using Commands and Tasks.
• Major clean up of the VisionLib SDK for Unity, including naming changes and the introduction of namespaces and assembly definitions. The changes highly improve the readability and understandability of VisionLib components. Find more details below (Interface Changes > Unity).
• Simplification of the AutoInit setup process that makes it less error-prone. See AutoInit with WorkSpaces (Beta).
• Improvements to the log and notification management in the VisionLib SDK for Unity that makes it possible to control their frequency and display centrally.

Also, support for Unity versions below 2019.4 LTS has ended with this release.

Thank you to all our users for giving feedback.

Features

General

• Introduced the AutoInit Parameter maxImageSize to make the behavior of AutoInit independent of the size of the tracking image. It is set to 640 by default. To restore the previous behavior, increase the value to at least the size of your tracking image.
• When using the same model multiple times in a one tracker (in MultiPart- or MultiModelTracking), it will now be loaded and kept in memory only once, based on the URI of the model.

Unity

• The HostID and the current VisionLib SDK version can now be retrieved via the VisionLib > About window, which can be found in the main menu of the Unity Editor.
• Added the TrackerEventsProvider component, that lets you react to events like OnTrackerInitialized and OnTrackerStopped easily through the inspector, without the need to write code.
• Added the VLPosterTracker prefab that can be used to call poster tracker related commands.

Windows

• Added the new image source type azureKinect.

Enhancements / Bugfixes

General

• Removed internal implementation of extendible tracking. This feature is now only available with external camera tracking solutions (i.e. ARKit, ARCore, HoloLens or ARFoundation).
  • Removed the now obsolete parameter disableExternalSLAM, which used to enforce using the internal implementation of extendible tracking.
• Changed the default value of the ModelTracker parameter lineModelRenderSize from 0 to 1024. To restore the old behavior and use the size of the tracking image for the lineModelImage, set the lineModelRenderSize to 0 manually.
• Scheme names can now be used case insensitive.
• The file URI scheme now works correctly with absolute file paths on Windows (e.g. file:///c:/models/model.obj will internally get resolved to C:\models\model.obj).
• Fixed a bug where floats added to the tracking configuration as query parameters have been parsed as integers.
• Added vlErrorCode::VL_ERROR_FILE_SYNTAX_ERROR. This is thrown if there is a syntax error in the loaded .vl file.
• Added messages that arise when a command is not supported by the current active tracking pipeline.
• The iOS and macOS builds will now wait for the camera authorization before starting the tracking. If camera access was denied, then an vlErrorCode::VL_ERROR_NO_CAMERA_ACCESS error will get produced. Previously, the tracking would start, but only generate black camera images without reporting an error.

Unity

AutoInit Setup Improvements

• Added the SimpleWorkSpace as a simple mode to define the WorkSpace for AutoInit.
  • It allows to limit incident angles from which models should be detected, in the same way the sphere geometry of the AdvancedWorkSpace does.
  • It sets the radius of the sphere automatically, base on the cameras field of view and the bounding box of the destination object.
• Added context menu entries to create both, Advanced- and SimpleWorkSpaces. The WorkSpace will use the selected GameObject from the hierarchy as its destination and add itself to a TrackingAnchor in its parents, if one exists. If there is no WorkSpaceManager in the scene, it will be created automatically when using one of those context menu entries.
• Added Handles to allow direct visual editing of the sphere segments in the scene view. This applies for the SimpleWorkSpace and the Sphere geometry of the AdvancedWorkSpace.
• Viewpoints of the AdvancedWorkSpace will no longer be adjusted to fill the whole image if put to far away and will instead be used as provided by the user.

Logs and Notifications Improvements

• Added the NotificationDisplay component, which activates UI notifications in addition to the console logs and is part of the new VLNotifications prefab. Its position in the hierarchy defines in which canvas the notifications will be displayed.
• Notifications are not displayed in the UI by default anymore.
• Added the GeneralSettings component that can be used to control the global log level of notifications and console logs.
• All notifications and console logs are now affected by the global log level of the GeneralSettings component. Use the log level Info to receive additional information during development, e.g. the selected cameras deviceID and tracking events.
• Initialization issues and VisionLib events are now shown automatically depending on the log level.
• If applicable, console logs will now highlight the GameObject which is the source of the message in the scene when selecting the log.
• Identical notifications will now be displayed collapsed.

Others

• Added the HoloLens input prefabs VLHoloLensModelTrackingInput, VLHoloLensPosterTrackingInput and VLHoloLensImageRecorderInput. Each of them contains sets of voice commands and key codes to trigger general VisionLib events without the need to set in-scene references manually.
• Enabling and disabling the TrackingManager (former VLWorkerBehaviour) will now pause and resume tracking if the tracking was already initialized.
• The VisionLib SDK scripts have been grouped within assembly definitions.
• The InitCamera component (former VLInitCameraBehaviour) will now also work when it is enabled while the tracker is already running.

Android

• Removed support for old Android devices not supporting float textures in the rendering system.

Interface Changes

General

Deprecated

• Since some used schemes have not been RFC 3986 conform, they will be deprecated with this release.

Removed

• Removed possibility to supply mesh-indices as a fragment with model uris.
• Removed baseTransform property of models. Transformations can still be set by using the transform property. If you used both before, multiply them together like this:

  transform_new = transform_old * base_transform_old

• Removed support for metaioModelURIs. See Model Tracker, parameter metaioLineModelURI for further usage.

Unity

• Ended support for Unity versions below 2019.4 LTS.

Renamed

Scripts

• Removed the VL prefix and the Behaviour or Wrapper postfix of several scripts
• Several scripts have been renamed further to better fit their purpose:

Former Name	New Name
VLWorkerBehaviour	TrackingManager
VLWorkerReferenceBehaviour	TrackingManagerReference
VLModelTrackableBehaviour	TrackingModel
VLTrackedObjectBehaviour	TrackingStateProvider
CameraCalibrationExampleBehaviour	CameraCalibration
VLRenderBackgroundImageBehaviour	BackgroundImageRenderer
VLDetectScreenChangeBehaviour	ScreenOrientationObserver
VLCameraCalibration	CameraCalibrationResult
VLInitIssuesToEventsAdapter	IssuesToEventsAdapter
VLGeometry	WorkSpaceGeometry
VLWebCamBehaviour	WebCamInputDevice
VLUnitySdk	VLSDK
ChangeModelBehaviour	ModelSwitcher
SetTextBehaviour	InvariantCultureTextField
WindowsSpeechRecognitionBehaviour	WindowsSpeechInput
KeyDownEventDispatcher	KeyboardInput

Methods and Parameters

• Renamed VLWorkerReferenceBehaviour.workerBehaviour to TrackingManagerReference.trackingManager
• Renamed VLUnitySdk.LogLevel.Fatal to VLSDK.LogLevel.Error according to the new naming in the native sdk
• Renamed VLModelTrackableBehaviour.UpdateTransformation to TrackingModel.UpdateModelProperties
• Renamed VLModelTrackableBehaviour.UpdateModel to TrackingModel.AddModelData
• Renamed VLAnchorCommand to AnchorSetWorkSpaceCommand to better fit its purpose

Prefabs

• Renamed VLModelTracker_v1.prefab to VLModelTracker.prefab
• Renamed VLRuntimeParameters_ModelTracker_v1.prefab to VLModelTrackerParameters.prefab

Others

• Renamed the MutableModelTracking example scene to ModelPartsTracking
• Renamed the example tracking configurations (.vl files) to be more descriptive (e.g. car.vl -> SimpleModelTrackingConfiguration.vl)
• Renamed the public events of the TrackingStateProvider (former VLTrackedObjectBehaviour):
  • justTrackedEvent -> tracked
  • justCriticalEvent -> trackingCritical
  • justLostEvent -> trackingLost

Moved

• Anchor related commands like EnableAnchorCommand are now located in the MultiModelTrackerCommands namespace.
• Moved functions related to camera calibration from the former VLWorkerBehaviour to CameraCalibration.
• Moved VLHoloLensModelTrackerCommands.SetGlobalObjectPoseCmd to ModelTrackerCommands.SetGlobalObjectPoseCmd

Removed

• Removed VLInitIssueNotifications and VLLogEventsBehaviour. The corresponding logs are now shown automatically.
• Removed VLLogTrackingInfoBehaviour. Add the VLTrackingInfoList prefab as a child of your canvas instead.
• Removed the log level Notice.
• Removed LogInitPoseBehaviour since the init pose can be investigated via the InitCamera.
• Removed the public events trackedEvent, criticalEvent and lostEvent of the TrackingStateProvider (former VLTrackedObjectBehaviour) that have been fired continuously. Please use the events tracked, trackingCritical and trackingLost instead, that will only be fired once on a tracking state change.
• Removed deprecated scripts:
  • VLAbstractApplicationWrapper
  • StartTrackingWithCameraSelectionBehaviour
  • AutoStart
  • LogTrackingEventsBehaviour
  • ShowInitWarningEventBehaviour
  • CameraResolutionSelector
  • VLEventsToTextAdapter
  • VLIssues
  • VLTrackingIssues
  • VLWorkSpaceManagerEditor
  • VLWorkerBehaviourEditor

Others

• All scripts are now contained in namespaces. For details, see vlUnitySDK. The most common namespaces that you will interact with while developing are:
  • Visometry.VisionLib.SDK.Core: Contains components that are used to add tracking functionality and to setup or interact with VisionLib's tracking.
  • Visometry.VisionLib.SDK.Core.API: Contains classes that are used to directly communicate with the VisionLib engine, e.g. command classes.
• When using dynamic model tracking in a HoloLens scene, you will now need to set its root transform (e.g. the SceneContent GameObject) in the inspector of the TrackingModel (former VLModelTrackableBehaviour) component, because it will no longer be set automatically from the content parameter of the HoloLensTracker component.
• When a MonoBehaviour derives from the TrackingManagerReference (former VLWorkerReferenceBehaviour) and tries to access the trackingManager or worker parameter, the according reference will now be searched automatically. If the reference was not found, a TrackingManagerNotFoundException or WorkerNotFoundException will be thrown respectively. The former process of calling InitWorkerReference to find the references has been deprecated.
• All events which previously used a boolean as variable indicating the success (e.g. OnTrackerStopped, OnTrackerRunning, OnTrackerResetHard) have been changed to only be fired on success.
• The event TrackingManager.OnTrackerStopped will now also trigger, if the initialization of the tracker failed.
• Several functions have been changed to use the above mentioned asynchronous interface. They are now async functions, so you can either await them before continuing the execution or - by default - execute them in a separate thread:
  • HoloLensGlobalCoordinateSystem.SetGlobalCoordinateSystem
  • HoloLensInitCamera.GetInitPose
  • HoloLensInitCamera.SetInitPose
  • InitCamera.GetInitPose
  • InitCamera.SetInitPose
  • ImageRecorder.PauseRecording
  • ImageRecorder.ResumeRecording
  • ImageRecorder.ResetRecording
  • ModelTracker.GetModelProperty
  • ModelTracker.ReadInitData
  • ModelTracker.RemoveModel
  • ModelTracker.SetModelProperty
  • ModelTracker.SetModelURI
  • ModelTracker.WriteInitData
  • PlainConstrainedMode.DisableConstraintInTracker
  • PlainConstrainedMode.SetConstraintInTracker
  • RuntimeParameter.GetAttribute
  • RuntimeParameter.SetAttribute
  • ScreenOrientationObserver.SetDeviceOrientation
  • TrackingAnchor.DisableAnchor
  • TrackingAnchor.EnableAnchor
  • TrackingManager.CreateTracker
  • TrackingManager.ResetTrackingHard
  • TrackingManager.ResetTrackingSoft
  • TrackingManager.RunTracker
  • TrackingManager.RunTrackingOnce
  • TrackingManager.SetCameraCalibrationState
  • TrackingManager.SetFPS
  • TrackingManager.WriteCameraCalibration
  • TrackingModel.UpdateModel
  • TrackingModel.UpdateTransformation
  • UEyeParameter.LoadParametersFromEEPROM
  • UEyeParameter.ResetParametersToDefault
  • UEyeParameter.SaveParametersToEEPROM
  • WorkSpaceManager.PushWorkSpaces
  • XRTracker.GetInitPose
  • XRTracker.SetInitPose
• The Camera Calibration now operates statelessly. Most related commands are therefore now available at any time. For more details see Migrating From 20.10.x to 2.0 under the section "Updating Camera Calibration"
• The former VLWorkerBehaviour.OnIssuesTriggered event has been changed to TrackingManager.OnIssueTriggered. This event will be sent for each Issue (Visometry.VisionLib.SDK.Core.API.Issue) that arose. TrackingManager.OnIssueTriggered now provides the specific Issue itself instead of a list of warnings and errors, like VLWorkerBehaviour.OnIssuesTriggered previosuly did.
• The command classes for communicating with VisionLib via VLWorker.pushCommand are now private. Please use the corresponding async Task function. These functions also provide the correct result of the command as the Task template parameter. For details see Migrating From 20.10.x to 2.0
• Changed the prefix of VisionLib logs from [vlUnitySDK] to [VisionLib]. Logs that originate from the native VisionLib engine will now have the prefix [VisionLib-Native] instead of [VisionLib].

Native

Renamed

• Renamed the log level vlLogLevel::VL_LOG_FATAL to vlLogLevel::VL_LOG_ERROR, which better fits general naming conventions.

Removed

• Removed deprecated AbstractApplicationWrapper and all related functions from vlSDK.
• Removed log levels vlLogLevel::VL_LOG_INFO and vlLogLevel::VL_LOG_NOTICE. vlLogLevel::VL_LOG_DEBUG will now have value 3.
• It is no longer possible to encode model transformations as query strings attached to the model uri. Please use models and json objects to define the transformation instead.

Others

• Json commands now have a unified interface. The error json object now always contains:
  • "errorCode" (see Initialization Issues)
  • "command" (the name of the command triggering the error)
  • "info" (detailed information of the specific error)
  • "message"
• Changed interface of vlNew_Worker and vlNew_SyncWorker. The functions no longer require an AbstractApplicationWrapper or nullptr.
• Json commands, which are queued during (re)start of the tracker will now trigger the callback with an error stating the cancellation of this command.
• All commands of the ImageRecorder (start, stop and reset) no longer return any values.
• The write jsonCommand of the camera calibration now requires the uri parameter inside a param object.
• The getModelData jsonAndBinaryCommand now returns the model descriptions (models) in the result object.
  • Submodels will no longer contain a name and an updateCount.
• The addModelData jsonAndBinaryCommand
  • Will no longer update existing models if supplied the name of an existing model. Instead, it will return an error, stating that the model name was already used.
  • Now returns the model ids in a addedModels object inside the result object.
  • Reads the model definitions from param.models instead of models.
  • Will no longer work without binary data. Use the new setModelProperties or setMultipleModelProperties commands instead if you just want to update the data. See Model Parts Tracking
  • Will no longer work if a url is supplied with the model definition.
• The interface for mutable model tracking (commands addModel, removeModel, setModelProperty) changed. Please refer to Model Parts Tracking .
  • Renamed jsonCommand setModelProperty to setModelProperties and changed its parameters.
  • Added jsonCommand setMultipleModelProperties to set multiple model properties at once.
• The CameraCalibration pipeline's interface changed. This has implications on applications that allow end users to calibrate their own camera. If this applies to your application, see Migrating From 20.10.x to 2.0 for details.
  • Commands performed during CameraCalibration no longer return a stateChanged object in the result.
  • Removed the state machine in the camera calibration pipeline. The TrackingState no longer contains a state string.
  • The resulting json object of the getResults command has been changed. The former calibration object is now the root json object.
• The interface of commands has been unified.
  • Every command which has one or more parameters now has to specify a param json object.

CommandName	param value until 20.11.1	param value since 2.0
createTracker	"param": FILE_URI	"param": {"uri": FILE_URI}
setTargetFPS	"param": FPS	"param": {"targetFPS": FPS}
getAttribute	"param": ATTRIBUTE_NAME	"param": {"att": ATTRIBUTE_NAME}
writeInitData	"param": INIT_DATA_URI	"param": {"uri": INIT_DATA_URI}
readInitData	"param": INIT_DATA_URI	"param": {"uri": INIT_DATA_URI}
removeModel	"param": MODEL_NAME	"param": {"modelName": MODEL_NAME}
enableAnchor	"param": ANCHOR_NAME	"param": {"anchorName": ANCHOR_NAME}
disableAnchor	"param": ANCHOR_NAME	"param": {"anchorName": ANCHOR_NAME}

Others

Licensing Changes

• Added Azure Kinect Sensor SDK License.

Documentation Changes

• Added a page that explains the different packages of the VisionLib SDK and how to use them: Install VisionLib Packages in Unity.
• Added a page that explains the use of commands with the task interface in Unity : Using Commands and Tasks.
• Added an overview of the commands that can be used as an interface to the VisionLib tracker : Command Reference.