# Tangible Engine v1.5 (Legacy)

# Overview

The Tangible Engine is a library that processes discrete touch events passed in by the user and recognizes tangible patterns. Once a known pattern is recognized, the user begins receiving notifications of the tangible's state until the end of the tangible's lifetime. When using the Tangible Engine, the user must point the library to a patterns file that contains the patterns of trained tangibles and their names. The Tangible Engine supports a range of Ideum multitouch tables each with different pixel densities. For each table there exists a preset tangible patterns file that contains the standard patterns that come with the Tangible Engine. If you are not making your own patterns as described in the 3d printing section, then these preset files are the only ones you will need.

The SDK is divided into the following directories:

  • bin contains the DLLs required to use the Tangible Engine
  • tangible_trainer_qt contains the binaries for the Tangible Engine Configuration Utility
  • doc contains documentation
  • bindings contains the QML, Unity and C++ bindings
  • pattern_file_presets contains pattern files for the range of tables supported by the Tangible Engine.
  • demos contains example projects illustrating how the different bindings are used

# Using the Tangible Engine from C/C++

The primary method of writing an application that uses the Tangible Engine is through the provided C++ bindings, although it is possible to create bindings for other languages using the DLL. To use the Tangible Engine, perform the following steps:

  • Add tangible_tracker.h and tangible_tracker.lib to your project
  • Direct the tracker to a patterns file using the TE_SetPatternsFromFile function
  • Pass touch data to the Tangible Engine using the TE_ProcessTouchEvent function
  • Use the function TE_GetTangibles to get the current state of all tracked tangibles

# Using the Tangible Engine from QML

The QML API is identical to the C API. To use the Tangible Engine, perform the following steps:

  • Add tangible_engine.h from the QML bindings folder to your project. Add tangible_tracker.lib, tangible_tracker.dll, and your patterns file to your build directory.
  • Include tangible_engine.h in your project and obtain an instance of the Tangible Engine through TangibleEngine::getInstance. Register this instance as a singleton with QML.
  • Direct the tracker to a patterns file using the method TangibleEngine.setPatternsFromFile.
  • Pass touch data to the Tangible Engine using the method TangibleEngine.processTouchEvent.
  • Use the TangibleEngine.getTangibles function to get the current state of all tracked tangibles.

See the QML demo for more details.

NOTE

The QML demo was built with Qt5.7 and the Microsoft Visual C++ 2013 compiler. If you are using a different version of either tool, a different build directory will be created. You must place the tangible_tracker.lib, tangible_tracker.dll, and the patterns file in this new folder.

# Using the Tangible Engine from C#

The Unity bindings for the Tangible Engine consists of two files, TangibleEngine.cs and Tangible.cs. To use the Tangible Engine with Unity, perform the following steps:

  • Add TangibleEngine.cs, Tangible.cs, tangible_tracker.dll and your patterns file to your Unity project's asset folder
  • Create a game object in your Unity scene, name it TangibleEngine. and add the script TangibleEngine.cs to it. Set the Patterns File property of the TangibleEngine game object to the path of your patterns file. The default value is Assets/tangible_patterns_49.json.
  • Add the script Tangible.cs to any object that you want to be controlled by a tangible. Set the patternName property of the Tangible script to the name of the pattern you want to associate with your game object.

For a working example, see the Unity demo that comes with the SDK.

# Using the Tangible Engine from Electron

The Node.js binding to Tangible Engine consists of a single file tangible_engine.js, which defines a single function named getTangibleEngine. The getTangibleEngine function depends on the ffi and ref-array addons. To install these, add ffi and ref-array to your Electron app's package dependencies and run npm install. Since Electron uses a different version of V8 than Node.js, any native addons used by your Electron app must be recompiled to target Electron's runtime. To do this, run the following commands:

npm install --save-dev electron-rebuild
node_modules\.bin\electron-rebuild.cmd.

See the Electron demo for more info.

# The Node.js API

The function getTangibleEngine takes the path of the tangible tracker DLL and returns an object with methods to access the Tangible Engine.

For example, using the Tangible Engine with an HTML5 canvas might look like:

var TangibleEngine = getTangibleEngine();

TangibleEngine.init();
TangibleEngine.setPatternsFile('tangible_patterns_55.json');
// ... on touchstart
TangibleEngine.processTouchEvent(true, touch.identifier, touch.clientX, touch.clientY)
// ... on touchmove
TangibleEngine.processTouchEvent(true, touch.identifier, touch.clientX, touch.clientY)
// ... on touchend
TangibleEngine.processTouchEvent(false, touch.identifier, touch.clientX, touch.clientY)
// ... in an update loop that is called frequrently (e.g. 30hz, 60hz)
var tangibles = TangibleEngine.getTangibles();
// do something with tangibles
Last Updated: 8/3/2018, 4:57:22 PM