Getting Started with v0.1.6
The OVR Unity Framework enables designers to fully customize scent interactions within a Unity project. This guide outlines how to integrate the OVR Unity Framework into any VR Unity project.
Last updated
The OVR Unity Framework enables designers to fully customize scent interactions within a Unity project. This guide outlines how to integrate the OVR Unity Framework into any VR Unity project.
Last updated
OVR Unity Framework is compatible with Unity Scripting Runtime Version .NET 3.5 and the Experimental .NET 4.6. If you wish to connect the your OVR device via USB, you will need to compile your project under .NET 4.6 as 3.5 does not support System.IO.Ports.SerialPort. Once the OVR API is released, you will be able to connect over USB regardless of .NET version.
Move the Source folder provided into your Unity asset folder under OVR (or whatever you choose). Be sure to add aDisplayOdorantMessages axis underEdit - Project Settings - Input - Axes. This will let you toggle Odorant Messages on your display.
Add an Olfactory Epithelium component to the HMD observant game-object in your scene hierarchy.
Once added, make sure that the Odorant Log is in place. They can be found in OVR / Source / Prefabs.
Odorant Log is used to display odorant messages sent from the OVR Unity Framework to the device.
Offset will translate the position used for odorant detection relative to the HMD. This may need to be adjusted for different HMDs given their origin may differ (default value works well with HTC VIVE).
Note: It's recommended to enable Display Odorant Messages if you're new to the OVR Unity Framework or if you're debugging new Odorant Components you’ve created.
Notes:
It's recommended to enable Should Display Odorant Messages when starting out or debugging new Odorant Components you’ve created.
The Olfactory currently handles connecting to the device and only does so when your scene initially loads. The OVR Daemon is currently in development and will handle run-time device connectivity.
All Odorant Components require two things, Maximum Threshold and an Odorant Configuration.
Maximum Threshold grants designers the ability to adjust the users level of awareness of a particular odorant by setting the highest intensity an odorant can produce; distal scent interactions scale based on this upper ceiling.
Odorant Configurations are Unity scriptable objects that can be assigned to any Odorant Component instance. This configuration is necessary for mapping Odorant Components to odorant slots on the physical OVR device.
To create an Odorant Configuration: alternate-click anywhere in your projects folder structure in Unity, go to the Create list at the top; under OVR select Odorant Configuration. Name the Odorant Configuration and assign a slot.
Note: Odorant slot ids are zero based.
Add an Sphere component to any game-object you want to possess a radially based odor. When the Olfactory Epithelium is found within the inner radius, maximum activation of the odorant occurs. When the Olfactory Epithelium is found outside the outer radius, no activation occurs. When the Olfactory Epithelium is found between the two, Radial Scaler augments how the intensity of the odor increases from the outer radius to inner radius, that way designers are not limited to a liner intensity ramp. Note: Radial Scaler will typically start at [0.0, 1.0] and end at [1.0, 0.0]
Odorant Particle System is functionally the same as Odorant Sphere except it supports integration with a particle systems. Add a Odorant Particle System component to any game-object with a particle system that you want to have a radially based odor. Odor intensity calculations are done relative to particle locations.
Gizmo wire meshes will appear on your particle system game-object in the scene showing the inner and outer radii. Radii will scale automatically based on individual particle size as shown below. This system supports Local and WorldSpace particle system simulation.
Odorant Box is the most basic of all the odorant components and is generally used for background scents the user should only perceive on subconscious to just barely noticeable level. Because of this, making precise zones of ambient odors is not so important. To define this zone of odor, a Box Size is defined along with an Offset in the inspector. The Offset allows for one game-object to contain a collection of background odors with or without overlap. Maximum Thresholds for ambient scents should be relatively low as to not distract the user from other in-game interactions.
A gizmo wire box will appear in editor showing the odorant zone. Below you’ll see the “Forest” odorant component encapsulating a testing environment.
Odorant Cone was designed to accommodate the complicated nature of interacting with an object and intentionally smelling an odor effusing from said object. It may help to show a little math here to describe how it works. But first, let's take a look at some of the options that are unique to Odorant Cone . Odorant Vector determines two things: the size of the odor zone, just like the Outer Radius of Odorant Sphere; and it determines the direction of the scent. Inner Diffusion Angle defines a spherical sector. If the Olfactory Epithelium is within the inner spherical sector, the directional scale is set to one.
Outer Diffusion Angle defines a spherical sector. If the Olfactory Epithelium is anywhere outside of the outer spherical sector, the directional scale is set to zero.
Radial Scaler changes how the directional scaler interpolates between the inner and outer spherical sector.
Decay Seconds determines the life-span of the odor after activation. Activation can be done through code with OdorantSpecific.EmitOdorant(). After that, the countdown begins, and the odor gradually decays. Think of a trash can opening, or decanting a beverage. If Decay Seconds is set to a negative value, it will be continuously active, like an exhaust vent or a candle burning. No need to activate it through code.
OdorantIntensity = distanceScaler * decayScaler * directionalScaler * maximumThreshold
A set of gizmo lines will appear in editor on an Odorant Specific component based on the Odorant Vector and the Diffusion Angles. Blue lines represent the sides of the inner spherical sector and the cyan lines represent the sides of the outer spherical sector.
Designed to facilitate odorant interactions where the "speed of smell" is critical to the user experience. When OdorantBurst.Burst() is called, an expanding sphere of odor emanates from your gameobject based on the perimeters provided in the inspector.
Debug Radius can have a sphere mesh prefab assigned to it. This can be used to experiment with different perimeters. Note: It is assumed that the sphere mesh has a radius of 50cm.
Parent Transform when active, tells the Burst Component to run scent intensity calculations based on where the gameobject is currently. If inactive, intensity calculations will be run on the location Burst was activated with Burst().
A gizmo wire sphere will appear indicating the center of the Burst.
You can upgrade your version of OVR Unity Framework by deleting your old Source folder and copying the new Source folder into your project. While updating, you may lose some inspector values on component instances in your scenes along with inspector values in prefabs containing components in your project.
You can also pull the Unity Framework git repository directly into your project if you wish to receive updates more easily. If you already have your project under version control, be sure to add the OVR sub-directory to you projects ignore scheme.
If you prefer different colors, you can change the color scheme by editing the following properties in OVR\Source\Data\OvrColorScheme.cs
OvrColorScheme.primary
OvrColorScheme.inner
OvrColorScheme.outer
Occasionally, Windows Defender Firewall will show that Unity is allowed to send and receive packets, but in fact are still blocking incoming network traffic. To fix this issue, you'll need to go into Windows Defender Firewall > Advanced Settings > Inbound Rules.
The selected element near the bottom (Unity 2019.1.4f1 Editor) is an example of what Unity might give you after a fresh install. Feel free to either disable these rules or change the action to Allow.
Effusion Rate, in short, is a scalar describing how quickly a gas moves into another gas through a hole. Effusion Rate can be calculated with where is the effusion rate and is the molar mass of the molecules effusing. Burst will automatically calculate the diffusion tensor for you at run-time based on other run-time variables.
