The Ultrahaptics SDK comes with a folder of example code that you can build and use to familiarise yourself with the Ultrahaptics API. The examples cover the Amplitude Modulation (AM) and Time Point Streaming (TPS) schemes, as well as showing you how to use the Leap Motion® camera module and Alignment classes. Instructions for building these come with the SDK but you may need a few additional tips to help get you up and running. Apart from the Ultrahaptics SDK, you will need the Leap Motion® SDK and software build tools (CMake, XCode, Visual Studio, etc).
CMake
The examples come with a CMakeLists.txt file, for which you will need the CMake application to use. is an extensible, open-source system that manages the build process. It is used to create the platform make and project files needed to compile and run the examples. It can be installed directly by downloading from cmake.org/download or using Homebrew on Mac OS, or Chocolatey on Windows. Once installed, cmake can be run from the command line or via the GUI tool cmake-gui (preinstalled with Windows).
To install CMake with Homebrew on Mac OS, type:
brew install cmake
Verify the installation by typing:
cmake --version
Leap Motion® SDK
The examples use the Leap Motion® camera module, so you must download and install the correct Leap Motion® SDK for your platform. The SDK includes drivers, the Control Panel and Settings tool as well as build libraries and headers needed.
- macOS: Leap Motion® have dropped support for MacOS and Linux in later versions of their SDK but you can still download and use Leap Motion® SDK V2, which includes their C++ API as well as basic gesture recognition used in some of our examples.
- Windows: Leap Motion® Orion (V3). Please note that Leap Motion® has deprecated gesture tracking as well as their C++ API in later versions of Orion (V4+).
You will need to register and accept Leap Motion®’s terms and conditions before you can download their SDK. Once downloaded, unzip and run the installer. You will need to copy the LeapSDK folder to your workspace. Please see Leap Motion’s SDK Readme.txt file for further information.
macOS
Download and install XCode from the App Store or, to use the IDE of your choice, get the XCode Command Line Tools by typing the following from within a terminal:
xcode-select --install
Create a build directory where you want the example code to be built. This is where we will run all cmake commands from. Configure your build using the following commands. Make sure to replace path/to/Examples and path/to/LeakSDK with your Examples and LeapSDK path:
cd path/to/Examples mkdir build cd build cmake -DLEAP_ROOT=path/to/LeapSDK ..
The result of all this is a Makefile that we can use to make our examples. To build, type
make
You can speed things up by using make -j4 to take advantage of your Mac’s parallel processing.
Running the examples
If everything has worked your build directory will contain a cpp subfolder with executable files for each C++ example. Navigate to this directory, connect your Ultrahaptics hardware and run each from the command line, for example:
./AmplitudeModulation_Focus
Note that TimepointStreaming_Freeform and TimepointStreaming_FreeformTracking take an argument for a WAVE file. Please use Sample_Wave.wav in Examples/cpp.
./TimepointStreaming_Freeform ../../cpp/Sample_Wave.wav
To run the C# examples on your Mac, you can use the Mono framework. Run these from the csharp subfolder of your build with the mono command, for example:
mono CSharp_AmplitudeModulation_Focus.exe
Linux
The steps used to build for the Mac will also apply to Linux platforms, though you will have a different toolchain to XCode.
Windows
To build on Windows, install either Visual Studio or the Visual C++ build tools. These come with their own Developer Command Prompts, correctly configured with the appropriate environment. You should use these for any command line instructions listed here. Shortcuts to these should be in your Start Menu or can be found at C:\Program Files (x86)\Microsoft Visual C++ Build Tools.
You can use cmake from the command prompt, or the cmake-gui to generate project files for each example. We recommend using the cmake-gui which, when first started, will prompt you for the source path and your build directory (cmake-gui will create one if you haven’t done so yourself). Define the LEAP_ROOT path variable to point to the LeapSDK directory. This can be added as an entry in cmake-gui or as a command-line argument with cmake:
LEAP_ROOT: path\to\LeapSDK
In cmake-gui click configure. You will be prompted to select the build tools for your project from a drop-down box the first time you configure it.
Important: Select the correct build tools for your platform. You can find this by typing ‘cmake -G‘ in the command prompt, installed tools will have an asterisk ‘*’ to mark. Note that you must use the same compiler bit-architecture as the Ultrahaptics SDK you have installed, e.g. Visual Studio 15 2017 Win64 if you have the 64-bit SDK installed. Most build errors relate to selecting the wrong version of compiler in the tool.
If using cmake command line tool, run from the correct installed Visual Studio command prompt and configure your build using the following:
cd path\to\Examples mkdir build cd build cmake -G"Visual Studio <your compiler>" -DLEAP_ROOT="path\to\LeapSDK" ..
In cmake-gui, click generate to generate your project files:
This will generate the necessary project files for Visual Studio. You can open these in Visual Studio to build and run (ensure you have set the correct architecture for your platform from the drop-down box).
Visual C++ Build Tools
If you have only installed Visual C++ Build Tools, cmake can be used to generate NMake files by typing the following in the root of the Examples folder:
cmake -G"NMake Makefiles" -DLEAP_ROOT="full\path\to\LeapSDK" ..
after which, you can build from the command line by typing:
cmake --build . --config Release
The same command can be used if generating project files in cmake-gui.
Note that when building with Visual C++ Build Tools:
- You can only build a Release version of the code (there is no debugger).
- cmake-gui should be launched from the command prompt installed with the tools to pickup the correct tools paths.
Running the examples
The executable examples (C++) will be built to a subfolder under Examples/build/cpp/Release. Once your hardware is connected, you should be able to double-click each executable to run it, or run from the command line.
TimepointStreaming_Freeform and TimepointStreaming_FreeformTracking take an argument for a WAVE file. You can find Sample_Wave.wav in Examples/cpp.
Known issue
Version 2.6.1: On Windows, Leap.dll, Ultrahaptics.dll and libusb-1.0.dll should be copied to Examples/build/cpp/Release during the build. They are actually copied to Examples/build/cpp. Please move the DLLs to the Release folder. This bug will be fixed in a later release.
Most build problems can be rectified by ensuring your build is in a separate directory, which can then be deleted if something goes wrong. Alternatively you can delete the cache in cmake-gui from the menu to reset and start again.
NB: Time Point Streaming (TPS) examples will not function on the TOUCH Development Kit (UHDK5).
0 Comments