Tracker Target API

Detailed Description

Upon initialization, the zSpace Core SDK creates instances of the Tracker Target API and registers them to the tracker device. The zSpace display's built-in tracking cameras are an example of a tracker device. The zSpace stylus and polarized glasses are examples of tracker targets. Other peripheral devices, such as mice, can also be tracker targets.

Note:
For brevity, most of the code examples in this section omit getting the handle for the target. For a complete example, refer to zsFindTargetByType().

List of Functions

ZSError  zsGetNumTargets (ZSHandle deviceHandle, ZSInt32* numTargets)
ZSError  zsGetNumTargetsByType (ZSContext context, ZSTargetType targetType, ZSInt32* numTargets)
ZSError  zsFindTarget (ZSHandle deviceHandle, ZSInt32 index, ZSHandle* targetHandle)
ZSError  zsFindTargetByName (ZSHandle deviceHandle, const char* targetName, ZSHandle* targetHandle)
ZSError  zsFindTargetByType (ZSContext context, ZSTargetType targetType, ZSInt32 index, ZSHandle* targetHandle)
ZSError  zsGetTargetName (ZSHandle targetHandle, char* buffer, ZSInt32 bufferSize)
ZSError  zsSetTargetEnabled (ZSHandle targetHandle, ZSBool isEnabled)
ZSError  zsIsTargetEnabled (ZSHandle targetHandle, ZSBool* isEnabled)
ZSError  zsIsTargetVisible (ZSHandle targetHandle, ZSBool* isVisible)
ZSError  zsSetTargetMoveEventThresholds (ZSHandle targetHandle, ZSFloat time, ZSFloat distance, ZSFloat angle)
ZSError  zsGetTargetMoveEventThresholds (ZSHandle targetHandle, ZSFloat* time, ZSFloat* distance, ZSFloat* angle)
ZSError  zsGetTargetPose (ZSHandle targetHandle, ZSTrackerPose* pose)
ZSError  zsSetTargetPoseBufferingEnabled (ZSHandle targetHandle, ZSBool isPoseBufferingEnabled)
ZSError  zsIsTargetPoseBufferingEnabled (ZSHandle targetHandle, ZSBool* isPoseBufferingEnabled)
ZSError  zsGetTargetPoseBuffer (ZSHandle targetHandle, ZSFloat minDelta, ZSFloat maxDelta, ZSTrackerPose* buffer, ZSInt32* bufferSize)
ZSError  zsResizeTargetPoseBuffer (ZSHandle targetHandle, ZSInt32 bufferSize)

List of Data Structures

struct   ZSTrackerPose
  Struct representing tracker pose information. More...

List of Enumerations

enum   ZSTargetType {
  ZS_TARGET_TYPE_HEAD = 0,
  ZS_TARGET_TYPE_PRIMARY = 1,
  ZS_TARGET_TYPE_SECONDARY = 2
}

Function Descriptions

ZSError zsFindTarget ( ZSHandle  deviceHandle,
ZSInt32  index,
ZSHandle*   targetHandle 
)

Gets the handle to a tracker target based on a specified index. Always start with an index equal to 0. This should be used in conjunction with zsGetNumTargets().

Parameters:
[in] deviceHandle A handle to the tracker device
[in] index Index into the underlying list of targets owned by the specified device.
[out] targetHandle A handle to the tracker target.
ZSError zsFindTargetByName ( ZSHandle  deviceHandle,
const char*   targetName,
ZSHandle*   targetHandle 
)

Gets the handle to a tracker target by name.

Parameters:
[in] deviceHandle A handle to the tracker device.
[in] targetName Name of the tracker target.
[out] targetHandle A handle to the tracker target.
ZSError zsFindTargetByType ( ZSContext  context,
ZSTargetType  targetType,
ZSInt32  index,
ZSHandle*   targetHandle 
)

Gets the handle to a tracker target based on a specified type and index. Always start with an index equal to 0. This should be used in conjunction with zsGetNumTargetsByType().

Parameters:
[in] context A handle to the internal state of the zSpace SDK.
[in] targetType The type of tracker target to query.
[in] index Index for the tracker target in the underlying list of all targets of the specified type.
[out] targetHandle A handle to the tracker target.
Example:
 ZSContext context = ...;

 // Attempt to grab a handle to the first (index 0) primary hand target.
 ZSHandle primaryTargetHandle;
 zsFindTargetByType(context, ZS_TARGET_TYPE_PRIMARY, 0, &primaryTargetHandle);
ZSError zsGetNumTargets ( ZSHandle  deviceHandle,
ZSInt32*   numTargets 
)

Gets the number of tracker targets owned by a specified tracker device.

Parameters:
[in] deviceHandle A handle to the tracker device.
[out] numTargets The number of tracker targets for the specified device.
ZSError zsGetNumTargetsByType ( ZSContext  context,
ZSTargetType  targetType,
ZSInt32*   numTargets 
)

Gets the number of tracker targets of a specified type.

Parameters:
[in] context A handle to the internal state of the zSpace SDK.
[in] targetType The type of tracker target to query.
[out] numTargets The number of tracker targets of the specified type.
ZSError zsGetTargetMoveEventThresholds ( ZSHandle  targetHandle,
ZSFloat*   time,
ZSFloat*   distance,
ZSFloat*   angle 
)

Gets the thresholds that control the frequency of move events for the tracker target.

Parameters:
[in] targetHandle A handle to the tracker target.
[out] time The time threshold in seconds.
[out] distance The distance threshold in meters.
[out] angle The angle threshold in degrees.
ZSError zsGetTargetName ( ZSHandle  targetHandle,
char*   buffer,
ZSInt32  bufferSize 
)

Gets the tracker target's name.

Parameters:
[in] targetHandle A handle to the tracker target.
[out] buffer The user allocated character buffer to store the target's name.
[in] bufferSize The size of the user allocated buffer.
ZSError zsGetTargetPose ( ZSHandle  targetHandle,
ZSTrackerPose*   pose 
)

Gets the tracker target's last valid tracker-space pose.

Parameters:
[in] targetHandle A handle to the tracker target.
[out] pose The last valid tracker-space pose.
Example:
 ZSHandle stylusHandle;

 // Get the stylus' last valid pose. 
 ZSTrackerPose stylusPose;
 zsGetTargetPose(stylusHandle, &stylusPose);
ZSError zsGetTargetPoseBuffer ( ZSHandle  targetHandle,
ZSFloat  minDelta,
ZSFloat  maxDelta,
ZSTrackerPose*   buffer,
ZSInt32*   bufferSize 
)

Gets the tracker target's pose buffer for the specified time period.

Parameters:
[in] targetHandle A handle to the tracker target.
[in] minDelta A timestamp relative to the current time, in seconds.
[in] maxDelta A timestamp relative to the current time, in seconds.
[out] buffer A user allocated buffer of ZSTrackerPoses.
[in] bufferSize The size of the user allocated pose buffer.
Example:
 ZSContext context = ...;

 ZSHandle stylusHandle = NULL;
 zsFindTargetByType(context, ZS_TARGET_TYPE_PRIMARY, 0, &stylusHandle);

 // Enable pose buffering. 
 zsSetTargetPoseBufferingEnabled(stylusHandle, true);

 // Get all target poses between 0.1 and 0.2 seconds ago. 
 ZSTrackerPose poseBuffer[10];
 ZSInt32 poseBufferSize = sizeof(poseBuffer);
 zsGetTargetPoseBuffer(stylusHandle, 0.1f, 0.2f, poseBuffer, &poseBufferSize);

 // Iterate over all of the poses. 
 for (ZSInt32 i = 0; i < poseBufferSize; ++i)
 {
   // Do something with the pose at index i: poseBuffer[i]
 }
ZSError zsIsTargetEnabled ( ZSHandle  targetHandle,
ZSBool*   isEnabled 
)

Checks whether a tracker target is enabled.

Parameters:
[in] targetHandle A handle to the tracker target.
[out] isEnabled True if enabled, false otherwise.
ZSError zsIsTargetPoseBufferingEnabled ( ZSHandle  targetHandle,
ZSBool*   isPoseBufferingEnabled 
)

Checks whether pose buffering is enabled.

Parameters:
[in] targetHandle A handle to the tracker target.
[out] isPoseBufferingEnabled True if enabled, false otherwise.
ZSError zsIsTargetVisible ( ZSHandle  targetHandle,
ZSBool*   isVisible 
)

Checks whether a tracker target is visible. For a zSpace-specific tracker target, this checks whether or not the target is currently visible and tracked by the zSpace tracking cameras.

Parameters:
[in] targetHandle A handle to the tracker target.
[out] isVisible True if visible, false otherwise.
ZSError zsResizeTargetPoseBuffer ( ZSHandle  targetHandle,
ZSInt32  bufferSize 
)

Resizes the pose buffer.

Parameters:
[in] targetHandle A handle to the tracker target.
[in] bufferSize The new size of the pose buffer.
ZSError zsSetTargetEnabled ( ZSHandle  targetHandle,
ZSBool  isEnabled 
)

Sets whether or not the tracker target is enabled. Disabling a tracker target causes it to no longer update its pose information.

Parameters:
[in] targetHandle A handle to the tracker target.
[in] isEnabled True to enable, false otherwise.
ZSError zsSetTargetMoveEventThresholds ( ZSHandle  targetHandle,
ZSFloat  time,
ZSFloat  distance,
ZSFloat  angle 
)

Sets the thresholds that control the frequency of move events for the tracker target. Use this function to increase or decrease the target's sensitivity when generating events for physical movement.

For some change in time 't', distance 'd', and angle 'a' since the last move event, thresholds are applied in the following logical manner to generate new events:

(t >= time) && ((d >= distance) || (a >= angle))

Parameters:
[in] targetHandle A handle to the tracker target.
[in] time The time threshold in seconds.
[in] distance The distance threshold in meters.
[in] angle The angle threshold in degrees.
ZSError zsSetTargetPoseBufferingEnabled ( ZSHandle  targetHandle,
ZSBool  isPoseBufferingEnabled 
)

Enables or disables pose buffering. Each buffered pose is timestamped so that the tracker target's movement can be queried over a specified time interval.

Parameters:
[in] targetHandle A handle to the tracker target.
[in] isPoseBufferingEnabled True to enable pose buffering, false otherwise.

Enumeration Descriptions

Defines the types of tracker targets.

Enumerator:
ZS_TARGET_TYPE_HEAD 

The tracker target corresponding to the user's head.

ZS_TARGET_TYPE_PRIMARY 

The tracker target corresponding to the user's primary hand.

ZS_TARGET_TYPE_SECONDARY 

The tracker target corresponding to the user's secondary hand. (Reserved for future use.)