SolitonReach SDK Manual v0.6.6.0
Covers v0.8.5.1 of the SDK
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Contents Page i
Contents Definitions Page 1
Tutorial Page 5
Summary of Steps Page 13
SDK Variables and Functions Page14
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Definitions Page 1 of 19 Definitions
User: Person or object with limbs wearing Solitons in the real world
User Limbs: Limbs of the user to which Solitons are attached
Solitos
User Limbs
Mesh: Skeletal mesh consisting of mesh limbs in the game world
Mesh Limbs: Limbs of the skeletal mesh in the Game World.
Mesh Limbs
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Definitions Page 2 of 19 Roll axis of a limb: Axis of rotation along the length of a limb. Roll rotation and axis (blue arrows) are illustrated below for two limbs, biceps and forearm.
Reference Limb: Any one of the limbs among all the limbs can be chosen as the reference. There is only one reference limb. The Soliton on this limb can only be oriented in two ways, parallel to the roll axis of the limb or perpendicular, as shown below. Perpendicular Orientation
Parallel Orientation
Soliton
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Definitions Page 3 of 19 Solitons on non‐reference limbs: The placement of Solitons on all the limbs except for the reference limb is not critical. Solitons on all the non‐reference limbs can be placed in any orientation as shown below.
Real World: User's world
Game World: Unity's world
Real World Coordinate System: The coordinate system determined by the Soliton mounted on the Reference Limb of the user while the user is in Starting Pose (see definition of starting pose)
Game World Coordinate System: Unity's coordinate system
Soliton Address or ID: Each Soliton has a unique address (also known as its ID). This address is hand printed on every Soliton's back in Hexadecimal Notation. It is important to note that as far as the Soliton SDK Script is concerned all Soliton IDs are displayed in Decimal Notation. Also all IDs should be converted to Decimal Notation before entering into the Inspector.
Soliton's and Unity's North: Solitons report their orientation data with respect to the North compass direction. SolitonReach Script assumes that North is aligned with Unity's z‐axis.
Starting a new motion capture session: Once a motion capture session is under way the user may want to stop this session and start a new motion capture session which starts with the user facing in a different direction, without restarting the Unity game. To start a new session, the user faces in the new direction and the keyboard key "p" is pressed, there is no need to restart the Unity game. After this key is pressed the user can move her/his limbs freely and turn in any direction, the mesh limbs should follow the user's limbs.
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Definitions Page 4 of 19 Starting Pose: During motion capture the motion of the limbs of a user (in real world) are faithfully mimicked by the limbs of a skeletal mesh (in the game world). At the start of motion capture we want to be able to choose the starting facing direction of the skeletal mesh (in the game word) independently of the starting facing direction of the user (in the real world). This is made possible by the notion of starting poses. There is a starting skeletal mesh pose and a corresponding user starting pose which the user assumes at the start of motion capture. The skeletal mesh and user can face in independent directions in the game world and the real world at the start of motion capture. Invocation of an SDK function (mapped to the keyboard key "p" by default) at the start of motion capture, while the user is in the user starting pose, establishes the necessary coordinate transformations between the game and the real world coordinate systems
Two practice skeletal meshes (shown below) with two starting poses are provided in the Soliton Script Package. The figure above shows the corresponding user starting poses in the real world. Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Tutorial Page 5 of 19 Tutorial
Unzip SolitonReach_UnityPkg.zip to extract the Unity package SolitonReach_UnityPkg.unitypackage. Save it in a folder of your choice.
Start a new Unity project
Put the editor in default layout using the Default menu
Important: Follow Edit‐>Project Settings ‐> Player and under Optimization choose .NET2.0. Failure to follow this step will result in errors with messages like "the namespace named Ports cannot be found"
Follow Assets‐>Import Package‐> Custom Package… and import the SolitonReach_UnityPkg. Import the whole package. A folder name SolitonReach will be created under Assets
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Tutorial Page 6 of 19 The project looks like this in list view
The C# Soliton SDK Script is named SolitonScript. Check out the SDK's version number in the Inspector after clicking on this script
Use GameObject‐>Create Empty to create an empty game object in the Hierarchy. Rename this object "Soliton"
Selecting "Soliton" in the Hierarchy will display this in the Inspector
With "Soliton" selected in the Hierarchy drag the script "SolitonScript" from the SolitonReach folder into the Inspector (associated with "Soliton")
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Tutorial Page 7 of 19 Here is how the Soliton Script portion of the Inspector for "Soliton" will look like:
This is the main interface of the Soliton SDK Script (SolitonScript). Into this interface we will drag mesh limbs from the skeletal mesh, associate Solitons to limbs and set up the reference limb.
We will call this part of Inspector belonging to SolitonScript the "SolitonSDK Inspector Interface".
Before following this tutorial further please have a look at the section "Summary of Steps" in this document
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Tutorial Page 8 of 19 Plug the SolitonStation into an available USB port
Go to the Device Manager on your PC from the Control Panel (Control Panel ‐> System and Security ‐> System)
Look for the USB Serial Port name under Ports(COM & LPT). And enter the port name in the SolitonSDK Inspector Interface
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Tutorial Page 9 of 19 We will start practicing by using PracticeMesh_StartingPose2 in this tutorial. Drag this mesh into the scene
The mesh appears in the Hierarchy. Here is how it should look like after expanding a few nodes:
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Tutorial Page 10 of 19 Select "Soliton" in the Hierarchy to reveal the SolitonSDK Inspector Interface (you may want to lock the inspector) and drag r_sholder, r_elbow and r_wrist from PracticeMesh_startingPoe2 in the Hierarchy to the SolitonSDK Inspector Interface. These joints correspond to the biceps, forearm and hand limbs respectively.
Biceps
Forearm
Hand
Unlock the inspector. Before going any further we need to understand the "Soliton‐Limb Association" list. This list contains the IDs of Solitons corresponding to the "Limbs to Control" list and in the same order. Beside Soliton IDs, the element in this list can also contain an integer 0 or ‐1. Here are the permissible values for these fields:
‐1: implies that the corresponding limb will not be used for motion capture, independent of whether a Soliton is mounted on that limb or not, or if it is turned on or not. Use this value if you want to capture the motion of only two limbs or perhaps only one limb (for testing purposes)
0: implies that the Soliton SDK Script will automatically (and randomly) select an ID from among all the unassociated Solitons (which have already been turned on) and associate that Soliton's ID with this limb, without the user having to manually enter this value. Changes at runtime will take effect immediately, otherwise at game startup. IDs are in Decimal Notation.
Soliton ID: implies that there is an existing Soliton ID value in this field (this value could have either been entered directly by the user or automatically by the Soliton SDK Script after encountering a 0 in this field). This value will be remembered even when the game is stopped and then started again. To change this value, either put a new Soliton ID (Decimal Notation) in this field manually or put a 0 in this field (in which case a new value will be automatically chosen by the Soliton SDK Script). Changes at runtime will take effect immediately, otherwise at game startup.
Note that if changes are made to these fields at runtime (while the game is running) then these changes will take effect at once and also be saved by the Soliton SDK Script as Player Preferences. However when you stop the game then, as indicated by the Inspector, it will appear as if these change have been lost, however this is not true. The Soliton SDK Script saves these changes at runtime as Player Preferences and to get them back simply click on the gear icon (see figure below) and choose "Load Soliton Player Preferences" from the dropdown menu, this will recover the field values changed during runtime. Therefore it is good practice to choose "Load Soliton Player Preferences" before restarting a game after changes have been made dynamically at runtime.
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Tutorial Page 11 of 19 Fill out the "Soliton‐Limb Association" list appropriately. In this example we will track the motion of two limbs only, the biceps and the forearm, therefor we will fill the list as follows:
Biceps
Forearm
Hand
Since we are tracking the motion of only two limbs in this tutorial we will need two calibrated Solitons with charged batteries. Place each Soliton on a flat surface at least a foot away from ferromagnetic materials and devices which produce magnetic fields such as computers (take your watch off). Turn each Soliton on and wait for the red LED to start blinking rapidly. Give it a few more seconds of staying still before physically moving the it.
Start the Unity game and note that the "Soliton‐Limb Association" list will get populated automatically as follows (IDs are in Decimal Notation not Hexadecimal):
Reference Limb
In this tutorial we will be choosing the forearm as the reference limb. Make sure that the user is not wearing a watch or other ferromagnetic jewelry on the arm. Place the Soliton associated with the reference limb on the reference limb of the user in Parallel or Perpendicular orientation and choose the appropriate orientation in the SolitonSDK Inspector Interface. Enter the Soliton ID associated with the reference limb in the "Ref Soliton" field as follows:
Mount the remaining Solitons on the remaining limbs (only the biceps in this example). Note that these Solitons can be mounted in any orientation, not necessarily in strict parallel or perpendicular orientations, as discussed in the "Definitions" section of this document
We are now ready to enter the "Mesh Roll Axis" settings. Recall that Unity's z‐axis is special since SolitonReach Script associates the North direction with this axis. What we need to enter into the Mesh Roll Axis fields are the rotation angles required to align the roll axis direction of the reference limb (in mesh starting pose) with Unity's z‐axis. Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Tutorial Page 12 of 19 Observe the skeletal mesh in the scene (shown above). Assume that we want this pose to be the mesh starting pose. Note that the roll axis direction of the reference limb (forearm) is along the x‐
axis, which makes an angle of 90 degrees with Unity's z‐axis. To align "x" with "z" we need to rotate by 90 degrees around the y‐axis. Therfore we should fill these fields as shown below.
Make sure that "Easy Startup" is enabled. Among other things, this setting sets the mesh starting pose to be whatever pose the skeletal mesh happens to be in when the UNITY game is started and remembers it as the existing mesh starting pose. Start the Unity game. The procedure for motion capture is as follows: To start a new session, the user faces in the desired direction wile assuming the starting pose and the keyboard key "p" is pressed; just follow these steps whenever the user wants to start a new motion capture session by starting facing in a new direction, there is no need to restart the Unity game. After the key is pressed the user can move her/his limbs freely and turn in any direction throughout the duration of the motion capture session, the mesh limbs should mimic the user's limbs
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
Summary of Steps Page 13 of 19 Summary of Steps
Set Unity to use .NET2.0 and import the SolitonReach_UnityPkg package
Plug in the SolitonStation and enter the port info into the SolitonSDK Inspector Interface
Drag the skeletal mesh into the scene and arrange it in the starting pose if it is not already in this pose. Drag the mesh limbs from the Heierarchy into the SolitonSDK Inspector Interface
Fill out the Solition‐Limb Association list, turn on (calibrated) Solitons, wait for the red LED to start flickering (and a few seconds more) before moving the Solitons. Start the game and let the association list populate itself automatically as discussed in the Tutorial.
Choose one of the limbs as the reference limb and enter its ID in the "Ref Soliton" field in the SolitonSDK Inspector Interface.
Place a Soliton on the reference limb in parallel or perpendicular orientation and set the appropriate orientation in the SolitonSDK Inspector Interface
Note the roll axis direction of the reference mesh limb when the skeletal mesh is in the starting pose and enter the desired rotation into the SolitonSDK Inspector Interface. Recall that Unity's z‐
axis is special since SolitonReach Script associates the North direction with this axis. What we need to enter into the SolitonSDK Inspector Interface is the rotation angles required to align the roll axis direction of the reference limb (in mesh starting pose) with Unity's z‐axis. The above three steps are only necessary for the reference limb. The procedure for mounting Solitons on the rest of the limbs is simpler. No special care needs to be exercised in mounting Solitons in parallel or perpendicular orientations and no further information needs to be entered into the SolitonSDK Inspector Interface At the start of a motion capture session the user should be in the user starting pose facing in the desired direction. While the user is in this pose the keyboard key "p" should be pressed to establish the proper coordinate transformation between the user and game systems
After the key is pressed the user can move her/his limbs freely and turn in any direction throughout the duration of the motion capture session, the mesh limbs should mimic the user's limbs Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
SDK Variables and Functions Page 14 of 19 SDK Variables and Functions
Public Variables
public SOLITON_STATUS_CODE solitonStatusCode
public enum SOLITON_STATUS_CODE
{
NO_ERROR,
STATION_READY,
SESSION_STARTED,
SESSION_ENDED,
STATION_DISCONNECTED,
NO_SLTN_CONNECTED,
ERR_SERIAL_OBJ_NOT_FOUND,
ERR_SERIAL_CANNOT_OPEN,
ERR_SERIAL_CANNOT_CLOSE,
ERR_SERIAL_WRITE_ERR,
ERR_SERIAL_READ_ERR,
ERR_READ_NO_THREAD,
ERR_READ_PROCESS_ERR,
ERR_CANNOT_CONNECT_STATION,
ERR_REFPOSE_CANNOT_FIT,
ERR_REFPOSE_HOTKEY_NOT_DEFINED,
ERR_PRESET_INDEX_OUT_OF_BOUND,
}
While the game is running the current status of the game is stored in this variable. This variable is also exposed in the Inspector by the Soliton SDK Script at runtime:
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
SDK Variables and Functions Page 15 of 19 Public Functions
public void ConnectSolitonStation()
Attempts to connect to a Soliton Station via serial interface
If no serial port object exists then this function will try to create a new serial object with variable name portName
A number of configuration parameters are sent to the Soliton Station once the connection is established
The serial port is closed at the end of this function call
SolitonStatusCode changes to STATION_READY on successful connection Status Codes:
NO_ERROR
ERR_SERIAL_OBJ_NOT_FOUND
ERR_SERIAL_CANNOT_OPEN
ERR_SERIAL_WRITE_ERR
STATION_READY
public void StartReadingSolitons()
Opens serial port and starts reading from Solitons SolitonStatusCode changes to SESSION_STARTED if the read operation performed correctly
Status Codes:
NO_ERROR
ERR_SERIAL_CANNOT_OPEN
ERR_READ_PROCESS_ERR
SESSION_STARTED
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
SDK Variables and Functions Page 16 of 19 public void StopReadingSolitons()
Stops reading from Solitons. SolitonStatusCode changes to SESSION_ENDED if the stop operation performed properly.
Note that the serial port remains open even after this function call.
Status Codes:
SESSION_ENDED
public void DisconnectSolitonStation()
Stops reading Solitons and disconnects from the Soliton Station
SolitonStatusCode changes to STATION_DISCONNECTED
Status Codes:
NO_ERROR
ERR_SERIAL_CANNOT_CLOSE
STATION_DISCONNECTED
public void PrepareSolitons()
This function must be called after StartReadingSolitons() and before using Solitons to control objects
Status Codes:
NO_ERROR
NO_SLTN_CONNECTED
public void SetCurrentMeshPoseAsRef()
Sets current skeletal mesh pose as the mesh reference pose
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
SDK Variables and Functions Page 17 of 19 public void SetRefLimbRollAxis(Vector3 rollAxisDir_euler)
public void SetRefLimbRollAxis(Quaternion rollAxisDir_quat)
Sets reference roll axis value
public void SetManualSolitonAssociation(int sltnAddrs, int index)
Sets an element in the "Manual Soliton Association" list.
SltnAddr
Address of the Soliton in integer format. 0 implies no Soliton control on the corresponding limb
Index
nth element in the list. Range is 0 to 2
public void SaveConnectedSolitonList()
Saves current connected Soliton list as manual association list
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
SDK Variables and Functions Page 18 of 19 Quick‐Set Utility Functions
public virtual void EasyStart()
This function is called at the startup of the Unity game if EasyStartUp variable is true
It automatically handles a series of configuration steps to get the Soliton system running, including:




Processing user reference limb settings
Calling SetCurrentMeshPoseAsRef()
Calling ConnectSltnStation()
Calling StartReadingSolitons()
Note that Solitons will not be associated with the limbs until the user presses the "mapping short key" on the keyboard or invokes the PrepareSolitons() function
Since it is a virtual function its behavior can be overridden
public virtual void QuitSoliton()
In the Soliton SDK Script this function is called in Unity’s OnApplicationQuit()
It saves the "Manual Soliton Association" list and the "reference Soliton ID" into Unity’s player preferences
Since it is a virtual function its behavior can be overridden
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK
SDK Variables and Functions Page 19 of 19
Unity Player Preferences
The following variables are stored in Unity's Player Preferences as key‐value pairs
RefSltnAddr (Reference Soliton ID)
The following three correspond to the "Manual Soliton Association" list in the inspector
PresetSltnAddr_0 (Element0)
PresetSltnAddr_1 (Element1)
PresetSltnAddr_2 (Element2)
Copyright ©2016 SolitonReach Inc. All Rights Reserved
SolitonReach SDK