Open topic with navigation

# 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

enum ZSTargetType

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.)

Open topic with navigation