Unity

Quick Start Guide | Ultrahaptics Core Asset (UCA)

2389 views 19/02/2019 Nicci 7

Ultrahaptics Core Asset for Unity® (UCA) brings Ultrahaptics’ mid-air haptics technology to your Unity developed games and experiences.

  • The UCA Unity package includes a library of Ultrahaptics-designed Sensations, which can be integrated into your projects, along with a number of example Scenes.
  • Sensations can be easily played back and edited dynamically in the Unity Inspector, integrated into Unity’s Timeline window, or controlled via Unity’s C# scripting interface.
  • In addition to the included Sensations, UCA provides a Sensation Core Block Scripting Python API, with which to create your own Sensations from scratch.
  • Experiment with new haptic behaviour, share and refine Sensations with other Unity users in your team.
  • For examples or authoring Blocks, refer to the Python scripts included in StreamingAssets/Python.

Note: The UCA has been designed to work with the Leap Motion® Controller included with your Ultrahaptics Kit. To make use of the Leap Motion® Controller with UCA, you will also need to import the Leap Motion Core Asset for Unity.

New to Unity?

While our Ultrahaptics Core Asset (UCA) for Unity tutorials are not technically difficult to understand, we do make some assumptions about your familiarity and experience with Unity. If you are not familiar with Unity terminology and technicalities such as importing packages, Game Objects, “Unity World”, gizmos and C# scripting, we recommend that you have a look at some of the many excellent online resources for learning Unity.

Their beginner tutorials are a very good place to start.

Unity® (UCA) Tutorials quick links

Note: The Additional Content (Unity example scenes and Sensations) which accompanies the Tutorials below can be found on our Unity Examples Github Repo

Tutorial Description
UCA Tutorial #1: Hello (Sensation) World We introduce the basics of setting up a Unity® scene to use Ultrahaptics Core Asset and some key concepts – the Sensation Source and Sensation Emitter.
UCA Tutorial #2: Sensation Source Playback We look at the UCA’s Sensation Source Playback example. This introduces the Running property and shows how we can use helper functions, provided by the UCA, to control playback duration.
UCA Tutorial #3: Triggering Sensations with Hands In this tutorial we add “sensation” to a simple, moving shape.
UCA Tutorial #4: Sensation Core Library and Blocks We show how a UCA “sensation” is constructed from blocks of functionality provided by the Sensation Core Library (SCL).
UCA Tutorial #5: Hand Tracking and Transformations In this tutorial, we show you how to add hand tracking to our simple circle example.
UCA Tutorial #6: Hand Tracking Helper Functions In this tutorial we introduce helper functions that can be used to construct hand-tracked sensations, replacing much of verbose “boilerplate code” that we used in previous lessons.
UCA Tutorial #7: Sensation Animation and Sequencing We look at the Sensation Animation and Sensation Sequencing examples and how we can use Unity’s timeline editor with sensation parameters and playback.
UCA Tutorial #8: The Forcefield Sensation We look in detail at the “Forcefield” example and how we can use it to implement two-dimensional plane intersection.
UCA Tutorial #9: Building an interactive poster Learn how to pull all the elements of the previous lessons together to build an interactive poster, combining audio, visual and mid-air, haptic sensations.
UCA Tutorial #10: Polylines and 3D Shapes We look at more complex ways the UCA allows us to interact with shapes using Polylines.
UCA Tutorial #11: HMI controls Bring it all together to create a simple, touchless control interface with a button and slider.

Unity quick start guide

Getting Started

These steps walk you through the process of adding a haptic CircleSensation to your Scene:

1. Launch Unity, create a new Project or open an existing one.

2. Connect your Ultrahaptics Kit using the included USB cables (STRATOS Explore kit uses a separate cable for the Leap Motion® Controller).

3. Import the UltrahapticsCoreAsset .unitypackage into your current Project via Unity’s Assets > Import Package menu, by double-clicking the .unitypackage in your file browser, or by dragging the package into Unity’s Project browser.

4. In your Unity Project browser locate UltrahapticsCoreAsset/Prefabs and drag the UltrahapticsKit prefab into your scene’s tree browser.

5. In the Scene view, right-click and select Create Empty to create a new GameObject

6. Add a Sensation Source component to your GameObject by clicking its Add Component button in the Inspector, then select Sensation Source from the Components list.

Unity quick start guide

7. In the Sensation Block dropdown menu select CircleSensation, to set the Sensation Source:

Unity quick start guide

8. Set the Position values of your GameObject Transform X = 0, Y = 0.2, Z=0:

Unity quick start guide

9. Click the Running checkbox and ensure that the component is also enabled.

Unity quick start guide

10. Click the Play button in Unity to start the scene – you should feel the Circle Sensation haptic 20 cm above the array.

11. You can confirm the position of the haptics by clicking on the Gizmos button in the top-right of your Scene/Game view and ensuring that Sensation Emitter row is checked.

Unity quick start guide   

12. Modify the PositionRotation and Scale of your GameObject Transform, as well as the radius of Circle Sensation to control how the haptic is positioned and sized.

13. Other sensation-producing blocks can be selected from the Sensation Block dropdown menu.

14. To build and share your scene, click File -> Build Settings, add the open scene you wish to build, select your Target Platform and click Build.

Sensations

The UCA includes the following Sensations that can be added by entering the following names into the Sensation Block field of a Sensation Source Component:

Sensation Block Name Description Requires Hand Tracking?
CircleSensation A circular path haptic whose radius can be edited NO
DialSensation A sensation which behaves like a rotary dial, whose rate and size can be varied NO
ExpandingCircleSensation An animated circle path haptic whose radius varies between start and end radius over a given duration NO
FingerPatch A sensation which draws a Polyline around a patch of the fingers YES
Forcefield An interactive sensation which mimics the behaviour of your hand entering a virtual forcefield YES
HandScan A sensation which animates a line path across the hand YES
LineSensation A straight-line path haptic drawn between two endpoints NO
LissajousSensation A Lissajous curve path haptic with editable size and lobe frequency parameters NO
PalmTrackedPulsingCircle A circle path haptic that oscillates between start-end radius YES
PalmPresence A circle path haptic with low intensity which tracks the palm YES
PalmTrackedCircle A circle path haptic which tracks the Palm YES
PalmTrackedDial As per DialSensation but tracks the Palm YES
Point A ‘test’ haptic which outputs a fixed control point at 20cm above the array NO
Polyline6 A sensation which draws a Polyline haptic at 6 points specified by its 6 inputs NO

Example Scenes

A number of example Unity scenes can be found in UltrahapticsCoreAsset/Examples directory (also accessible via the Ultrahaptics > Example Scenes menu)

  • Forcefield – demonstrates how to use the Forcefield Sensation to produce a haptic boundary.
  • HandTriggeredHaptics – demonstrates the use of Sensation Trigger Box to trigger playback.
  • HandAsCursor – demonstrates the use of hand tracking to operate a haptic user interface, with palm tracked haptics including Presence, Dial and a ‘Click’ sensation, provided by the Unity timeline.
  • Polyline – demonstrates the use of the Polyline6 Sensation Block, allowing you to experiment with drawing of custom shapes.
  • Priority – demonstrates Sensation Source’s Priority property, which helps to manage multiple Sensation Sources that are asked to run at the same time.
  • SensationSourcePlayback – Basic demonstration of playing back Sensations PalmTrackedSensation – demonstrates the PalmTrackedPulsingCircle Sensation, which tracks the palm of the hand.
  • SensationAnimation – demonstrates animating the radius input of CircleSensation via C# and Unity’s Timeline window.
  • SensationSequencing – demonstrates how to animate the radius of a Circle Sensation using Unity’s Timeline window.

Double-click the Unity Scenes, hit play and follow the on-screen instructions or readme files, found within the example folder. Note that for some Scenes, you will need to add hand tracking for them to work.

Setup for Hand Tracking via Leap Motion

Your Ultrahaptics product includes a Leap Motion® camera module to provide hand-tracking data. To add tracking to Unity with the Leap Motion camera module, you’ll need to do the following:

  1. Download and Install Leap Motion Orion 4.0.0 SDK,
  2. Download Leap Motion Unity Core Assets 4.4.0,
  3. Import the Leap Motion Unity Core Asset (from Step 2) into your Unity project,
  4. From LeapMotion/Core/Prefab, add the LeapHandController prefab to your Scene,
  5. In the LeapHandController Hand Model Manager component, type ‘2’ into the Model Pool > Size field, ensure that both “Is Enabled” boxes are checked and add the following objects to the Graphics and Physics Hands sections, as shown below:
    • HandModelsNonHuman/Capsule Hand Left
    • HandModelsNonHuman/Capsule Hand Right
    • HandModelsPhysical/RigidRoundHand_L
    • HandModelsPhysical/RigidRoundHand_R

Leap Motion Prefab UCA

Configuring your Array and Tracking Origin

Depending on the Ultrahaptics kit you are using, you will need to configure the positions of your array and tracking origins in Unity, to ensure that Sensations are experienced in the desired location.

The easiest way to do this is to add an UltrahapticsKit prefab to your Unity scene. If you are using a Leap Motion camera module in its cradle location, then it is recommended that you add the Leap Hand Controller Prefab as a Child of the UltrahapticsKit Prefab in your scene like so:

The Array Transform and Tracking Transforms that you need to set in Unity are dependent on the Ultrahaptics Kit you are using. Assuming that you are using the Unity Scene tree shown above and your LeapHandController has a position and rotation of (0,0,0), the Unity Transform values for different the Ultrahaptics Array and Tracking Origin are shown below:

Ultrahaptics Product Array
Position (x,y,z)
Array
Rotation (x,y,z)
Tracking Position (x,y,z) Tracking Rotation (x,y,z)
STRATOS Inspire (0, 0, 0) (-40, 0, 0) (0, -0.0006, -0.089) (0, 0, 0)
STRATOS Explore (0, 0, 0) (0, 0, 0) (0, 0, 0.121) (0, 0, 0,)

Troubleshooting

Why can’t I feel haptics from my Ultrahaptics Device?

Here are a few things to check if you can’t feel haptics:

  1. Check that your Ultrahaptics kit is connected properly via USB and powered on, open the Ultrahaptics > Hardware Info window and if necessary, click the Refresh button – you should see device info for your connected device.
  2. Check that a Sensation Emitter and Sensation Core Component exists in your Scene and is enabled (this is provided on the UltrahapticsKit prefab).
  3. Check that another Ultrahaptics process is not using your emitter (e.g. Sensation Editor, Ultrahaptics SDK, or another Ultrahaptics demo).
  4. Confirm that the Sensation Source Component you wish to play is enabled in the Unity inspector and has its Running property checked.
  5. Enable the Sensation Emitter Gizmo – you should be able to see where control points are positioned.
  6. If you’re still unable to establish a connection with your array, please contact support.

I’m unable to open my Unity project, how do I fix this?

If you are experiencing errors referring to missing files when opening your projects, you may be missing some of UCA’s required libraries. To fix this, quit Unity, locate your project in the file browser and delete the Library sub-folder. Restart Unity and the Library folder will be rebuilt.

What are Sensation Blocks? How do I add new Sensation Blocks to my Unity Project?

Sensations Blocks are the source or essence from which Sensations are produced in UCA.

When a Sensation Block is “Sensation Producing”, it will appear in the Sensation Block drop-down of the Sensation Source Component.
To create new Sensation Blocks for UCA, you create a new Python file (e.g. MySensation.py) then add code to produce Sensation output.
The best place to start looking at writing your own Sensation Blocks is Introducing Sensation Core Library and Blocks.
You can also examine other Python files in StreamingAssets/Python (e.g. CircleSensation.py) to gain more understanding on the process.
Additional examples for Python Blocks can also be found in the UCA Additional Content download

The Sensation feels like it’s in the wrong position, how do I fix this?

If your Unity Scene is using the Leap Motion camera module to provide hand tracking, you will need to ensure that the Tracking Origin is offset correctly in Virtual space for your Ultrahaptics Kit. Read the sections on setting up hand tracking and configuring the tracking origin above.

For any other issues please contact support.

Begin the tutorials: Hello (Sensation) World

Was this helpful?