Usage¶
Please complete steps in the Setup section before building your application.
Before Start¶
There are some steps that is required before start the detection:
- Make sure to accquire camera permission before staring detection.
- Call
GestureInterface.UseExternalTransform
function if needed.
Start Detection¶
Call GestureInterface.Start
function to start hand detection.
This function is non-blocking, detection will be started in a background thread.
The function accepts a GestureOption
parameter, which can be used to change max raw detectoin fps.
Option is modified to return what mode is selected in current detection.
The return value of the function indicates if any error occured during the start.
Calling this function when detection is already started is an no-op.
The return value is always GestureFailure.None
, option is modified to return current running mode.
Set HMD Transform¶
If you have called GestureInterface.UseExternalTransform(true)
before start,
you need to call GestureInterface.SetCameraTransform
function every frame to provide HMD transform.
Tip
It’s recommended to start calling GestureInterface.SetCameraTransform
function before detection start.
This can make sure the first detection frame is using correct HMD transform.
Fetching Detection Result¶
Since detection is running in a background thread, the caller need to fetch detection result periodically. We suggest to fetch results in higher frequency than detection speed based on platform and modes. Fetching results in same speed as rendering is recommended.
Fetching detection can be done with the GestureInterface.UpdateResult
function.
The function is blocking until latest results is copied to GestureInterface
class.
The results can be read using the functions described in the next section.
GestureInterface.GetFrameIndex
function can be used to check hand detection status or as a hint on fetching the results:
- If the index value is 0, this means detection is starting, no results are ready yet.
- If the index value has increased, new hand results are updated.
- If the index value does not change, this means new hand results are not ready yet, results remains same as the ones before you fetch.
- If the index is negative, this means detection has stopped due to error occurs. You should stop fetching and restart detection.
Note
Detection results do not change until you fetch latest detection result again.
Using Detection Result¶
Use GestureInterface.GetLeft
and GestureInterface.GetRight
function for left/right hand detection result.
The returned hand results are GestureResult
class which contains gesture type, joint position/rotation, pinch level/ray and confidence.
Before using hand result, you should first check if left/right hand is visible in the camera.
This can be done using GestureResult.valid
field.
Hand result fields are only meaningful when the hand is valid.
Note
The points are returned in Unity3D coordinate system, i.e. +x is right, +y is up, +z is forward, unit is meter. You may need to convert them to your coordinate system before use.
Stop detection¶
Call GestureInterface.Stop
function to stop hand detection.
This function is blocking, it returns after the detection is stopped.
Calling this function when detection is not started is an no-op.