Haptic API suite - user documentation 
- Getting started
- Content of the suite
- Testing applications
- Chai 3D - minimal
- Chai 3D - haptic benchmark
- Chai 3D - highlevel
- HDAL - minimal
- Metuunt
- JTouchToolkit - minimal
- libnifalcon - minimal
- HAPI - minimal
- H3DAPI - highlevel
- Installation prerequisites
- Disclaimer
back to Haptic API suite
Getting started
Last Haptic API suite version is available through a public subversion repository at svn://cgg.mff.cuni.cz/HapticApi.
Next milestone release will provide more ways of getting Haptic API suite (windows binaries, linux binaries, source code, Windows Installer).
If you wish to compile Haptic API suite from source, please visit developer documentation.
The suite is now fully supported only on Microsoft Windows XP (or newer) operating systems.
Linux and Mac OS X support is experimental - please see the Haptic API suite webpage for updates.
Content of the suite
The Haptic API suite tries to cover the most APIs usable with the Novint Falcon device.
Low-level APIs such as HDAL SDK and libnifalcon supports just the Novint Falcon device. High-level APIs supports various devices from Sensable, Force Dimension or HapticMaster.
The Schema 01 below shows system architecture layers starting from the Novint Falcon device at the top and ends with the scenegraph high-level APIs at the bottom.
Blue boxes represents APIs you can use in your application, green boxes are classes wrapping the driver or low-level API and red boxes represents abstract device class that you can use to communicate with different numerous haptic devices within the bigger software development kit or application programming interface.
Schema 1 - Haptic API suite system architecture layers
Haptic API suite provides minimalistic application with source code for every "blue" box API (some of them are still in progress). Minimialistic application has only one main functionality - print a position of the device and optionally send a force to the device (which is a three-dimensional vector when using 3-DOF {degrees of freedom} device). The purpose of such an applicaiton is to show basics of the API usage on a low-level access. In addition to minimalistic applications Haptic API suite provides test applications that use higher-level access to haptic device (use of haptic tool, haptic forces, ...).
Testing applications
As a part of the Haptic API survey, Haptic API suite presents wide platform and programming language scale of haptic APIs primarily intended for a Novint Falcon device.
Blue boxes in the Schema 2 below represents used APIs like the first schema.
Orange boxes represents availabe testing applications that are linked to the specific API.
Grey boxes were applications that were still in development and are now available in the the Haptic API suite.
Schema 2 - Haptic API survey testing applications
A table below shows current state of testing applications (projects) in the Haptic API suite. It consists type of applications (depends on API), programming language and platform where you can run the application (source specific). Platform infrmation enclosed in braces are still in the development process.
| Project | info | language/API | platform |
| CHAI3D - highlevel | scenegraph high-level | C++/CHAI3D | Win32, (experimental Win64, Linux, Mac OS-X) |
| Metuunt | low-level (integration into existing project), DirectX 9 | C++/CHAI3D (lowlevel) | Win32 |
| CHAI3D - minimal | low-level | C++/CHAI3D (lowlevel) | Win32, (experimental Win64, Linux, Mac OS-X) |
| CHAI3D - haptic benchmark | low-level | C++/CHAI3D (lowlevel) | Win32, (experimental Win64, Linux, Mac OS-X) |
| HDAL - minimal | low-level | C++/HDAL | Win32 |
| HAPI - minimal | low-level | C++/HAPI | Win32 |
| H3DAPI - highlevel | high-level | C++/H3DAPI | Win32 |
| JTouchToolkit - minimal | low-level | Java/JTouchToolkit | Win32 (HDAL wrapper) |
| libNiFalcon - minimal | Novint Falcon driver, low-level | C++/libNiFalcon | Win32, (experimental Win64, Linux, Mac OS-X) |
| CHAI3D | libnifalcon integration, libpng integration, bugfixes | C++/CHAI3D | Win32, (experimental Win64, Linux, Mac OS-X) |
CHAI 3D - minimal
Minimal applications prints to the standard output of the shell. Its purpose is to show the number of supported devices and if there's at least one device then pick the first one and print the position of the haptic device to the output every time the position changes.
CHAI 3D minimal uses CHAI 3D API low-level access to the haptic device so it technically wraps the manufacturer API.
After the succusseful initialization the application starts the loop within the main thread and prints the position.
User can quit the application by pressing the first button (please see the manufacturer manual of your haptic device) on the haptic device.
Part of the CHAI 3D API is the virtual device that can be used for debugging and testing the application on Microsoft Windows without the real haptic device.
CHAI 3D calls the virtual device every time it doesn't find any real haptic device.
If the file VirtualDevice.exe is present in the same directory as the application or if the VirtualDevice application is running, application will establish the connection to the virtual device.
Screenshot of the CHAI 3D minimal application running on Microsoft Windows.
Used API: CHAI 3D - www.chai3d.org
CHAI 3D - highlevel
CHAI 3D highlevel application has the ambition to show the potential of the CHAI 3D API.
This application has the concept of the 3D haptic scene prototyping application.
The main controller is the haptic device or numerous haptic devices.
As the application has the 2D graphical user interface at the bottom.
The need of two seperate cursors in separate dimension has arisen.
In two dimensions there's 2D cursor (as shown on the picture on the right).
In three dimensions there's a small white sphere representing the haptic tool.
In fact, there are two spheres connected with a line (marked area in the picture on the right).
The first sphere represents the current position of the haptic device.
The second sphere represents the tool proxy sphere position in the scene.
The proxy sphere can't move through static objects (like the main desk in this application) whereas the CHAI 3D virtual device has no force effect on your mouse.
This means that sometimes the real position of the haptic device and the tool represented by the proxy sphere has different positions and that's when you see two spheres connected with a line.
Application starts with the empty environment and the main desk.
To disable forces, hold the second button on the Novint Falcon device (the left button).
You can can add new objects to the environment by pressing the icon in the menu with the first button on the haptic device.
There's one extra haptic device in this application called debug virtual which emulates haptic device with your mouse.
You can change the dimension in which the debug virtual device is moving by pressing the space key or you can move the device by pressing W key and S key.
The main menu consists of three different type of objects: box, sphere and mesh, then the tool menu and camera menu.
Each object type represents its unique material, collision and rendering manipulation method.
The object menu offers a way how to manipulate with the object.
You can change its color, its size by scaling it in all three dimensions by moving the haptic device you've clicked on the icon (if you let the haptic device in the center, the scale will remain 1.0 in all three dimensions) or just delete the object (effects and compound tools are also available in the release).
The tool menu shows currently active haptic devices. You can enable/disable the haptic device by clicking the specific icon.
You can also change the center of the haptic tool workspace by clicking the center icon and moving the tool to the new center and pressing the first button on the haptic device you've pressed the center icon.
The menu is haptic sensitive. This means that if you want to change the center of the workspace for the first tool you have to click the center icon with the first haptic device.
The camera menu offers a variety ways of moving in the envirnment through the eye of the specific camera.
There are five different types of camera: default, static, observer, object and spectator.
The default camera is the camera set on the startup.
The static camera is the camera doesn't interact with anything in the scene. It doesn't move or look at specific item.
The observer camera observes the haptic tool from the last static position.
The object camera observes the selected object in the scene.
The spectator camera is free-fly camera that you control with all three dimensions of your haptic device.
By moving your haptic device you change the pitch, yaw and forward speed of the camera.
You can interact with the scene by your tool by grasping, colliding and selection.
To grasp an object, simply touch the object, hold the first button and move the tool.
You can see the spring line between your tool and the object.
Collision is the default interaction of the tool. You don't have to press any button on your haptic device to let the tool colide with objects in the scene.
To select the object (or more objects) please hold the first button on your device and try to collide with the object.
When you hold the button the collision is turned off and you should be able to select the object.
Selection is highlighted by yellow wireframe bounding box around the object.
When you select the object the object menu appears and you can manipulate it again.
In fact, you can manipulate all the selected objects at once (change their color, etc.).
Press ESC key to exit the application, use the right mouse button to view the display menu.
Please be very careful when playing with the mesh object.
Collision detection is not perfect and it may cause occasional strong force creation that could damage your device!
Used API: CHAI 3D - www.chai3d.org
JTouchToolkit - minimal
This Java application uses Mictosoft Windows specific Novint Falcon driver.
This application prints a number of compatible haptic devices and runs into the loop with the first available one.
You can quit the application by pressing any button on the haptic device.
If you're having problems with running this application with the supplied batch file you may have not set the Java bin directory to the PATH environment variable.
Known bug: calls FATAL ERROR - EXCEPTION_ACCESS_VIOLATION (Microsoft Windows 7 64-bit)
Please read the prerequisites during the installation of the Haptic API suite to run this application correctly!
Used API: JTouchToolkit - https://jtouchtoolkit.dev.java.net/
CHAI 3D - haptic benchmark
CHAI 3D - haptic benchmark is an application developed for a libnifalcon library performance testing.
The application uses the same functionality of CHAI 3D as CHAI 3D - minimal application
and the Boost library is used for the thread handling.
There are three tests in the benchmark.
The first test starts an extra thread for all available devices and measures the frequency of haptic loop for five seconds.
The second test creates a thread for every device.
Every thread wait for synchronization flag called threadHandler1 and then runs the haptic loop with frequency measuring.
The third test measurers the attainable position resolution for every device
by computing the distance in each iteration of the haptic loop that the haptic tool made in the workspace.
The user has to move with the haptic tool adequately to get right results.
Please read the prerequisites during the installation of the Haptic API suite to run this application correctly!
HDAL - minimal
HDAL minimal application prints a number of Novint Falcon haptic devices and runs the infinite loop ended by the user pressing any button on the Novint Falcon device.
If there's no haptic device to use then application simply exits.
Please read the prerequisites during the installation of the Haptic API suite to run this application correctly!
Screenshot of the HDAL minimal application running on Microsoft Windows.
Used API: HDAL SDK - http://home.novint.com/products/sdk.php
Metuunt
Project Metuunt is the simple 3D engine that uses haptic device to control the camera within the scene.
The engine uses Microsoft DirectX 9.0c to render the scene.
The purpose of this application was to try the implementation of a support of the haptic device to the existing project.
There are two haptic force modes in the Metuunt.
You can activate them by pressing the first button and the second button on your haptic device.
The first mode returns the force by the speed of the camera and use very simple interaction with some objects in the scene.
The second mode tries to emulate random force creation in the high speed of the camera.
The user interface consists of the main rendering viewport and the haptic viewport in the bottom right corner.
The haptic viewport shows the current position of the device represented by the small red sphere and shows the simple object collision forces (not all forces sent to the device).
Please read the prerequisites during the installation of the Haptic API suite to run this application correctly!
Screenshot of the project Metuunt running on Microsoft Windows.
Used API: CHAI 3D - www.chai3d.org
libnifalcon - minimal (CLI)
Libnifalcon minimal testing applcation uses the CLI base utility of the libnifalcon API that provides automatic command line options parsing.
You can run the application with the argument --help to see the usage of the applicaiton.
As all others minimal applications it simply prints the current position of the haptic device here defined by the argument device_index.
This application doesn't show the grip functionality of the haptic device (will be available in the libnifalcon - minimal testing application) so you have to exit the application manually.
Please read the prerequisites during the installation of the Haptic API suite to run this application correctly!
Screenshot of the libnifalcon minimal CLI application running on Microsoft Windows.
Used API: libnifalcon - http://qdot.github.com/libnifalcon/
HAPI - minimal
HAPI - minimal application is the smallest low-level haptic API application (in a source code length).
The HAPI library contains an AnyHapticsDevice class that initializes any available haptic device by calling initDevice and enableDevice methods.
HAPI::HAPIHapticsDevice::DeviceValues structure is then used to work with the haptics data.
Please read the prerequisites during the installation of the Haptic API suite to run this application correctly!
H3DAPI - minimal
H3DAPI - highlevel application shows the basic use of X3D and Python interface of H3D API.
The application uses AnyDevice X3D node to work with haptic device and God-object algorithm to render haptic shapes.
The scene contains one animated sphere with frictional surface effect and one mouse proxy sphere.
The haptic tool defined as stylus is also represented as a sphere.
Please read the prerequisites during the installation of the Haptic API suite to run this application correctly!
Prerequisites
Novint Falcon drivers
Haptic API suite is primarily focused on Novint Falcon device. You'll not be able to run some test applications if you do not have Novint Falcon drivers.
You can download Novint Falcon drivers here:
https://backup.filesanywhere.com/fs/v.aspx?v=8e6d6b8e5e6473bc9d6b
Compatible tested drivers: setup.Falcon.v3.1.4.a_090407.exe
You can try to download latest Novint Falcon drivers here:
http://home.novint.com/support/download.php
Microsoft DirectX
Haptic API suite contains one testing application that uses Microsoft DirectX SDK (August 2009). I haven't included DirectX redistributables into this setup so if you wish to run a testing application follow the link bellow and install the latest End-User Runtime (or SDK if you plan to compile Haptic API suite).
Microsoft DirectX web page here:
http://www.microsoft.com/windows/directx/
Oracle Java
There's a Java testing application in the Haptic API suite and you need to download the latest end-user Java in the link bellow for that application to run.
Oracle Java download here:
http://www.java.com/getjava/
If you plan to compile Java testing application that uses JTouchToolkit you have to download Java Development Kit.
Oracle JDK SE download here:
http://java.sun.com/javase/downloads/index.jsp
Python 2.5
H3D API - highlevel application needs a Python 2.5 installed.
Python 2.5 download here:
http://www.python.org/download/releases/2.5.5/
D2XX drivers
If you do not wish to install Novint Falcon drivers and you just want to try libnifalcon, you should still install D2XX drivers that allow direct access to the USB device through a DLL.
D2XX drivers download here:
http://www.ftdichip.com/Drivers/D2XX.htm
Compatible tested drivers: 2.06.00, 3rd November 2009
System settings
It is recommended to use Chai 3D high-level application with the vertical synchronization (V-Sync) system settings turned on. You can specify that in your graphics card vendor driver controller. V-Sync is turned on as a default setting in most cases so if you haven't changed anything application should run fine.
Please run the CHAI 3D high-level application with a high CPU priority.
An odd behavior of ODE dynamics in CHAI 3D high-level application was discovered on older machines and computers with not enough free CPU time.
Disclaimer
The Haptic API suite provided by Petr Kadlecek may be freely distributed, provided that no charge above the cost of distribution is levied, all licenses of subprograms are preserved and that the disclaimer below is always attached to it.
Many testing applications were inspired by examples provided by external API authors.
The Haptic API suite is provided as is without any guarantees or warranty.
Although the author has attempted to find and correct any bugs in the Haptic API suite, the author is not responsible for any damage or losses of any kind caused by the use or misuse of the applications.
The author is under no obligation to provide support, service, corrections, or upgrades to the Haptic API suite.
For more information, please contact the author.
2010 (beta), under heavy construction, Petr Kadlecek