Quality Events
The holoride software stack consists of a variety of software that communicates with each other to provide localization
and graph data. Data that is required for a truly elastic experience.
Knowing how the key components work together helps to understand the system holistically. In case you have not already,
make sure to read the System Information page to get an overview of the holoride
software stack.
The ElasticSDK Quality Events are our way to communicate the different states of localization and graph data towards the content creator.
Quality Events: Generation Events
The Elastic Scene Generator component has a dedicated Events section, that provides the user with a variety of
UnityEvents.
These events are meant to be hooks where your program flow can execute different behavior based on the different states
of the generation process.
| Event | Description |
|---|---|
| OnGenerationStarted | The event which is invoked when the initial generation process has started. |
| OnGenerationFinished | The event which is invoked when the initial generation process is finished. |
| OnEnterGenerationOverdue | The event which is invoked when the GenerationOrigin, i.e. the Player, got too close to the latest finished generation context's InnerBounds, based on the given BoundsDistanceThreshold. |
| OnLeaveGenerationOverdue | The event which is invoked when the current generation left the overdue state. |
| OnUpdateStarted | The event which is invoked every time a generation process has started, except the first time. |
| OnUpdateFinished | The event which is invoked every time a generation process has finished, except the first time. |
Important
The OnEnterGenerationOverdue event is especially important. It will trigger whenever the Player approaches the bounds of the latest finished generation.
It can be used to identify and compensate poor content states before they actually happen.
There are various reasons why a generation can not finish in time and it is likely that there is more than one cause.
A poor internet connection can cause excessive download times for areas where no cached map data exists in the user's application.
This would ultimately stall the generation and the Player would approach the bounds because they cannot be updated.
Same could happen when the graph is too complex overall, the vehicle drives very fast or the extents of the Elastic Scene Generator are too small.
In general it is recommended that there is always a fallback solution, e.g. a separate graph independent scene transition, hooked up to this event.
The BoundsDistanceThreshold is a user-defined value on the Elastic Scene Generator,
that can be used to adjust the distance towards the bounds from where the Player will cause the event invokation.
Quality Events: Localization Events
Localization Events are located on a component with the same name in the Holoride Player prefab. These events are meant to be hooks where your program flow can execute different behavior based on the different states of the real-world localization data.
| Setting | Description |
|---|---|
| DistanceToStreetUntilOffRoad | The distance in meters from the street until the player is considered to be too far away from the road and the OnOffRoadMode event is triggered. |
| FireModeEventOnStart | When enabled this component will fire the localization mode event for the current state when Unity's Start method is called on this component. |
| Event | Description |
|---|---|
| OnLocalizationInitialized | The event which is invoked when the localization becomes available and the pivot is set. |
| OnLocalizationNormalMode | The event which is invoked when the localization is available and we are on the street (up to the road distance threshold). |
| OnOffRoadMode | This event which is invoked when the localization is available but we are not on the road and the distance to the road is larger than the threshold configured in DistanceToStreetUntilOffRoad. |
| OnLocalizationUnavailableMode | This event which is invoked when the localization is unavailable and thus the player won't move even though the vehicle in the real world might. |
| OnErrorOccured | This event which is invoked when any localization error occurs. |
This component handles different localization quality events and reduces them to three distinct states:
- Normal:
This state represents good localization where everything works as expected. - Off-road:
This state is active when the localization is available but due to inaccuracies in localization or outdated Map data, the Player might not be on the road which the content should handle accordingly. The distance to the road until the player is considered to be "off-road" is adjustable and should reflect the requirements of the individual content. - Unavailable:
This state means that no localization information is available.
Provisions should be made for the content of an experience to respond to different localization states:
Since the Unavailable state does not show any movement at all, even though the vehicle may in fact be moving, it is suggested not to show any indication of false movement that occurs when the Player's localization is not present but the VR headset's IMU interprets a turning car as a head rotation.
In many scenarios, this means that it is not even recommended to show the player a world . The experience should start in this mode until localization is available and Map data is ready.
Caution
Any experience must be designed to reflect this state at any point in time to comfort the user in those situations where valid data is not available to present an elastic environment. One suggestion is to fade out the world when this mode is activated and fade it in once another state becomes active.
The other interesting state is the Off-road state where there appears to be normal localization but due to limited GPS reception (e.g. in a tunnel) the Player might be off the road. In this case the experience should make sure that the player is not colliding with any objects. How this is handled depends very much on the experience that is built and could range from unloading objects that are too close to loading a different scene. The Distance To Street Until Off Road setting for this mode makes it possible to tighten or loosen the constraints for this mode, depending on the individual content.