Tangible Engine Service
The Tangible Engine v2 is a windows service that runs in the background, awaiting the connection of client apps that require tangible recognition capabilities. A service model was chosen to enable Ideum to create and deploy fixes and new features without requiring clients to rebuild their own apps. All of the controls and settings can be accessed via a system tray icon that will open a simple user interface. Client applications connect to the service via a TCP connection, provide touch point information and receive tangible information in return. On all supported Ideum touch tables, Tangible Engine recognizes all of the standard Ideum tangibles by default, while also allowing for users to provide recognition of custom tangibles.
Overview
The Tangible Engine service will launch at computer start-up and will run silently in the background while it waits for client applications to request a connection.
In order to recognize tangibles, the service uses a Tangible Engine profile that contains pattern information and engine settings. During installation, a default profile specific to the size of the table is selected. This profile contains all of Ideum's standard tangible patterns and engine settings that best optimize recognition. Users are able to switch to a custom profile in the user interface if they so choose. See Profiles section for more information.
The service uses a local TCP connection to communicate with client applications (see API section for details). The port used by this connection can be configured in the user interface while the service is not running. Client applications must use the same port number when attempting to connect to the service in order for the connection to be successful.
Installation
Installation of Tangible Engine v2 is simple and quick. Simply run the installer TE2.8_Installer.exe and the installation wizard will guide you through the process.
After installation is complete, the wizard will ask you to select a default profile. Your selection should reflect the size of the table Tangible Engine will be installed on. For example: if you are using a 55 inch Platform Table, select 55_profile.json as your default profile. To change the default profile after installation, see the troubleshooting section.
Interface
The Tangible Engine Service interface can be accessed by left clicking on the system tray icon present in the bottom right-hand corner of the screen.
This will open the above interface which exposes the following controls:
- Start and stop the service
- Toggle between the default profile and a custom profile (toggling to custom will open a file dialog)
- Change the socket port (only available while service is not running)
- Launch the Tangible Engine Visualizer (see Visualizer documentation)
- Launch the Tangible Engine Trainer (see Trainer documentation)
- Open the online documentation
- Exit and close Tangible Engine
API
Client applications connect to the Tangible Engine service through a TCP socket and must send messages across the connection to receive tangible information. Below is an overview of the messages that the service expects to receive and the responses client applications can expect back. Client and service messages are serialized to JSON strings.
Client Messages:
Patterns: This message requests the list of tangible patterns defined in the current Tangible Engine profile. In most cases this should only be sent once to create a list that can be used to reference incoming tangible matches.
Update: This message is sent along with all current touch points and is generally sent every frame and informs the service to process the touch points and search for tangible matches.
Reset: This message will reset the Tangible Engine instance, clearing all current matches.
Error: This message is exclusively for debug purposes. It tells the service to log an error to its output log.
Service Messages:
Patterns: This message contains a list of patterns defined by the active Tangible Engine profile.
Update: This message contains a list of any recognized tangibles present on the table.
In-depth details and examples can be found in the documentation for the Unity and Qt bindings.
Profiles
Profiles are what Tangible Engine uses to determine what patterns to look for and what settings to use when looking for those patterns. Each profile is a JSON file that contains a list of pattern descriptions, and a list of configurations. By default, Tangible Engine is configured at installation with a profile that contains all of Ideum's standard tangibles and is optimized for the size of the table.
For most users, the default profile is all that is needed and no additional steps are needed.
If the user wants to use custom tangibles outside of the Ideum standard set, a custom profile must be used. This can be set in the user interface. Custom profiles can be created with the Trainer Utility.
Troubleshooting
Below are a few ways to troubleshoot problems with Tangible Engine v2. If none of these options solve your problem, you can submit a support ticket at our support support site.
Check the Service Log:
While running, the Tangible Engine service will write events to a log, including start-up, client connection/disconnection, shut-down, and any errors it might encounter. This log can be found in the Appdata/Roaming/Ideum/TangibleEngine/Logs directory. This is the best starting point when the service is not behaving as expected.
Profile Problems:
If tangibles are not being recognized, it might be a problem with the current profile. To check the profile, open the user interface window. If you're using a custom profile, make sure the file name in the profile box matches the file name of your custom profile. If not, make sure the Table Profile toggle is set to Using Default.
If you are using the default profile and tangibles are not being recognized, you should next check that the default profile is the correct one for your table size. This can be done by opening the file browser and selecting the correct profile, or navigating to Appdata/Roaming/Ideum/TangibleEngine and opening the settings.json file.
If you are not using a custom profile, the currentProfile entry should be empty, as depicted above. The defaultProfile entry should have a profile with a number that matches the size of your table.
Port Mismatch:
If a client application is failing to connect to the service, a difference in ports might be the cause. To check this, identify what port the service is using by opening the user interface and checking the port number. Verify that this is the same port used in your application.
To change the port the service uses, click on the pencil edit button and change the port to one that is not in use. Then press the save button.
If the port is available, the service will restart itself using that new port.