Develop

Using Ultrahaptics APIs: Amplitude Modulation and Time Point Streaming

2282 views 29/07/2018 Nicci 1

The Ultrahaptics API is the gateway to using your Ultrahaptics emitter. Create mid-air haptics and sensation by sending Control Point data to the array. Ultrahaptics uses two modes of operation: Amplitude Modulation and Time Point Streaming (TPS).

The Amplitude Modulation API offers the most straightforward way to create sensation. The Ultrahaptics hardware modulates control point amplitude. The application updates position and intensity.

The Time Point Streaming API allows the application to create arbitrary modulation signals. This means it can modulate amplitude or position. Spatiotemporal Modulation: creating haptic sensation by moving Control Point position.

Tip: Download the SDK to read the full API documentation

Amplitude Modulation API

The Amplitude Modulation API only supports amplitude modulation. Control Points have intensity, position and modulation frequency. At any time, the application can send one or more Control Points to the emitter. Control Points will persist until the next update, or the emitter stops. The hardware uses sinusoidal modulation at the given frequency.

The pseudocode creates two control points. Each has a modulation frequency of 200 Hz and 10 cm above the array. The first is 3 cm left-of-centre with the maximum amplitude (1.0). The second is 3 cm right-of-centre with 0.5 amplitude.

// Create two control points at the given positions, amplitudes and frequencies
update([ 
        {x=0.03m, y=0.0m, z=0.1m, amplitude=1.0, frequency=200Hz}, 
        {x=-0.03m, y=0.0m, z=0.1m, amplitude=0.5, frequency=200Hz} ])
// These will continue to be emitted...
wait(1 second)
// ...until we say otherwise.
stop()

To make simple shapes, move the Control Points around. Here, we make a line by moving the Control Point in a loop.

loop:
    for x in [0.00, 0.02, 0.04, 0.06]:
        update([{x=x, y=0.0m, z=0.1m, amplitude=1.0, frequency=200Hz}])
        wait(10 milliseconds)

To maintain intensity, the hardware assigns control points to one of two groups. Each group of Control Points are out phase with the other. Note, more control points mean less energy per point.

Use the AmplitudeModulation emitter to use the AM API:

Ultrahaptics::AmplitudeModulation::Emitter
Tip: Try our Amplitude Modulation API tutorial

Time Point Streaming API

The Time Point Streaming API gives you the power to define the Control Point behaviour. Although harder to use, it provides much more control and flexibility. It allows for modulation of control point amplitude and position. The higher update rate enables real-time rendering of control point paths. Generate shape and texture with Spatiotemporal Modulation.

Time Point Streaming works in a similar way to multichannel USB audio. Your application provides a callback function to generate Control Point data. The hardware calls this function when the array requests new data. The Control Point data has position and instantaneous amplitude. Unlike the Amplitude Modulation API, this allows you to use any modulation envelope.

Time Point Streaming because the application defines the exact instance in time. This is like digital audio, which uses a stream of samples sent to a sound card and creating a waveform:

Use the TimePointStreaming emitter to use the TPS API:

Ultrahaptics::TimePointStreaming::Emitter
Tip: Try our Time Point Streaming API tutorial

Class list

This is a list of classes in the Ultrahaptics namespace included in Ultrahaptics SDK. The most important are AmplitudeModulation::Emitter and TimePointStreaming::Emitter. The top-level API also has additional utility classes for querying device status, handling alignment, logging, etc.

 Ultrahaptics The Ultrahaptics namespace contains everything in this library
   AmplitudeModulation AmplitudeModulation is the simplest way to create haptic feedback using a default 200 Hz modulation signal
     ControlPoint Point at which the air pressure is controlled, with position, intensity and frequency
     Emitter Emit haptic points using a simple interface and automatic sine-wave amplitude modulation
   TimePointStreaming TimePointStreaming provides explicit control of the haptic modulation signal
     ControlPointPersistent A control point that can be enabled or disabled and can belong to a control point group
     Emitter A timepoint streaming emitter to which control points can be sent
     OutputInterval Representation of an output time interval
     OutputIntervalIterator Iterator for the output interval
     TimePointOnOutputInterval     A point in time on which control points can be set
   Alignment Transformation matrix to convert between hand-tracking coordinates and Ultrahaptics array coordinates
   ControlPointBase Raw control point (unmodulated state)
   ControlPointPersistentBase    ControlPointBase that has a persistent ID
   DeviceInfo Return attached device information
   HostDuration A period of time. The difference between two HostTimePoints
   HostTimePoint A point in time
   LoggingExternalInterface Class to control logging
   Matrix3x3 A 3×3 transformation matrix
   Matrix4x4 A 4×4 transformation matrix
   Quaternion Quaternion class to represent rotations
   Transducer Data on individual transducers
   TransducerContainer Container for holding physical transducer data
   Transform A basis transformation
   UltrahapticsLibrary Represents the Ultrahaptics library
   Vector3 A simple vector class

Was this helpful?