# SoftBank Robotics documentation What's new in NAOqi 2.8?

# ALTracker API

Overview | API | Tutorial or samples

Namespace : AL

    #include <alproxies/altrackerproxy.h>

## Method list

As any module, this module inherits methods from ALModule API. It also has the following specific methods:

class `ALTrackerProxy`

- `ALTrackerProxy::getActiveTarget`
- `ALTrackerProxy::getAvailableModes`
- `ALTrackerProxy::getEffector`
- `ALTrackerProxy::getExtractorPeriod`
- `ALTrackerProxy::getMaximumAcceleration`
- `ALTrackerProxy::getMaximumDistanceDetection`
- `ALTrackerProxy::getMaximumVelocity`
- `ALTrackerProxy::getMode`
- `ALTrackerProxy::getMoveConfig`
- `ALTrackerProxy::getRegisteredTargets`
- `ALTrackerProxy::getRelativePosition`
- `ALTrackerProxy::getRobotPosition`
- `ALTrackerProxy::getSearchFractionMaxSpeed`
- `ALTrackerProxy::getSupportedTargets`
- `ALTrackerProxy::getTargetCoordinates`
- `ALTrackerProxy::getTargetPosition`
- `ALTrackerProxy::getTimeOut`
- `ALTrackerProxy::initialize`
- `ALTrackerProxy::isActive`
- `ALTrackerProxy::isNewTargetDetected`
- `ALTrackerProxy::isSearchEnabled`
- `ALTrackerProxy::isTargetLost`
- `ALTrackerProxy::lookAt`
- `ALTrackerProxy::pointAt`
- `ALTrackerProxy::registerTarget`
- `ALTrackerProxy::setEffector`
- `ALTrackerProxy::setExtractorPeriod`
- `ALTrackerProxy::setMaximumAcceleration`
- `ALTrackerProxy::setMaximumDistanceDetection`
- `ALTrackerProxy::setMaximumVelocity`
- `ALTrackerProxy::setMode`
- `ALTrackerProxy::setMoveConfig`
- `ALTrackerProxy::setRelativePosition`
- `ALTrackerProxy::setSearchFractionMaxSpeed`
- `ALTrackerProxy::setTargetCoordinates`
- `ALTrackerProxy::setTimeOut`
- `ALTrackerProxy::stopTracker`
- `ALTrackerProxy::track`
- `ALTrackerProxy::trackEvent`
- `ALTrackerProxy::toggleSearch`
- `ALTrackerProxy::unregisterAllTargets`
- `ALTrackerProxy::unregisterTarget`
- `ALTrackerProxy::unregisterTargets`

Deprecated Methods

- `ALTrackerProxy::addEffector` (deprecated, use setEffector instead)
- `ALTrackerProxy::addTarget` (deprecated, use registerTarget instead)
- `ALTrackerProxy::getManagedTargets` (deprecated, use getRegisteredTargets instead)
- `ALTrackerProxy::getTargetNames` (deprecated, use getSupportedTargets instead)
- `ALTrackerProxy::removeAllTargets` (deprecated, use unregisterAllTargets instead)
- `ALTrackerProxy::removeEffector` (deprecated, use setEffector(“None”) instead)
- `ALTrackerProxy::removeTarget` (deprecated, use unregisterTarget instead)
- `ALTrackerProxy::removeTargets` (deprecated, use unregisterTargets instead)

## Methods

void `ALTrackerProxy::``addEffector`(const std::string& Effector)

  Deprecated since version 1.22: use `ALTrackerProxy::setEffector` instead.

  Add an end-effector to move for tracking. Tracker always use the Head.

  Parameters: | Effector – Name of the effector. Could be: “Arms”, “LArm” or “RArm”.

void `ALTrackerProxy::``addTarget`(const std::string& TargetName, const AL::ALValue& Param)

  Deprecated since version 1.22: use `ALTrackerProxy::registerTarget` instead.

  Add the predefined target with parameters (RedBall: diameter of ball). Subscribe to corresponding extractor and stock the last position if tracker is running. If the target is already added, only parameters are updated.

  Parameters: | TargetName – a predefined target name. See: Target names. Param – target parameters.

std::string `ALTrackerProxy::``getActiveTarget`()

  Get active target name set with `ALTrackerProxy::track`. See: Target names. Or event name set with `ALTrackerProxy::trackEvent`.

  Returns: | Tracked target name.

std::vector<std::string> `ALTrackerProxy::``getAvailableModes`()

  Get available modes. See: Tracking modes.

  Returns: | A list of available mode names.

std::string `ALTrackerProxy::``getEffector`()

  Get the current effector name. Use `ALTrackerProxy::setEffector` to set this value.

  Returns: | Active effector name. Could be: “Arms”, “LArm”, “RArm” or “None”.

int `ALTrackerProxy::``getExtractorPeriod`(const std::string& TargetName)

  Get the current period of the extractor corresponding to the given target name. See: Modules to launch. Only works if the corresponding target name is tracked (call `ALTrackerProxy::track` before). Use `ALTrackerProxy::setExtractorPeriod` to set this value.

  Parameters: | TargetName – a predefined target name. See: Target names.
  Returns: | Current period in milliseconds of the extractor corresponding to the given target name.

std::vector<std::string> `ALTrackerProxy::``getManagedTargets`()

  Deprecated since version 1.22: use `ALTrackerProxy::getRegisteredTargets` instead.

  Get managed targets names.

  Returns: | A list of managed targets names. See: Target names.

float `ALTrackerProxy::``getMaximumAcceleration`()

  Get head maximum acceleration.

  Use `ALTrackerProxy::setMaximumAcceleration` to set this value.

  Returns: | maximum acceleration in rad.s^-2.

float `ALTrackerProxy::``getMaximumDistanceDetection`()

  Get target maximum distance detection. If the distance to the target is greater than the distance presented here, the target is considered lost. By default, this parameter is set to a very high value, so no target will be considered lost with this setting. Use `ALTrackerProxy::setMaximumDistanceDetection` to set this value.

  Returns: | maximum distance in meter for target detection.

float `ALTrackerProxy::``getMaximumVelocity`()

  Get head maximum velocity. Use `ALTrackerProxy::setMaximumVelocity` to set this value.

  Returns: | maximum velocity in rad.s^-1.

std::string `ALTrackerProxy::``getMode`()

  Get the current mode defined with `ALTrackerProxy::setMode`.

  Returns: | The current tracker predefined mode. See: Tracking modes.

AL::ALValue `ALTrackerProxy::``getMoveConfig`()

  Get the move config set with `ALTrackerProxy::setMoveConfig`. For further details, see: Move config.

  Returns: | The move config used when Move is activated.

std::string `ALTrackerProxy::``getRegisteredTargets`()

  Get registered targets names. Use `ALTrackerProxy::registerTarget` to register a target.

  Returns: | A list of registered targets names. See: Target names.

AL::ALValue `ALTrackerProxy::``getRelativePosition`()

  Get the robot position relative to target in Move mode. Use `ALTrackerProxy::setRelativePosition` to set this value.

  Returns: | Final goal of the tracking: [coordX, coordY, coordWz, thresholdX, thresholdY, thresholdWz].

std::vector<float> `ALTrackerProxy::``getRobotPosition`()

  Only available with LandMarks target name. Get the [x, y, z, wx, wy, wz] position of the robot in coordinate system set with `ALTrackerProxy::setTargetCoordinates`. This is done assuming an average target size, so it might not be very accurate.

  Returns: | Vector of 6 floats corresponding to the robot position 6D.

float `ALTrackerProxy::``getSearchFractionMaxSpeed`()

  Get search process fraction max speed.

  Returns: | Search process movement fraction max speed.

std::vector<std::string> `ALTrackerProxy::``getSupportedTargets`()

  Get supported target names.

  Returns: | Array of supported target names. See: Target names.

std::vector<std::string> `ALTrackerProxy::``getTargetNames`()

  Deprecated since version 1.22: use `ALTrackerProxy::getSupportedTargets` instead.

  Get valid target names. See: Target names.

  Returns: | Array of valid target names

AL::ALValue `ALTrackerProxy::``getTargetCoordinates`()

  Only work with LandMarks target name. Get objects coordinates set with `ALTrackerProxy::setTargetCoordinates`.

  Returns: | Objects coordinates. Could be: [[first object coordinate], [second object coordinate]] [[x1, y1, z1], [x2, y2, z2]].

std::vector<float> `ALTrackerProxy::``getTargetPosition`(const int& Frame)

  Get the [x, y, z] position of active target in desired frame. This is done assuming an average target size, so it might not be very accurate.

  Parameters: | Frame – position frame {FRAME_TORSO = 0, FRAME_WORLD = 1, FRAME_ROBOT = 2}.
  Returns: | Vector of 3 floats corresponding to the target position 3D.

std::vector<float> `ALTrackerProxy::``getTargetPosition`()

  Deprecated since version 1.22: use ALTrackerProxy::getTargetPosition with frame in parameters instead.

  Get the [x, y, z] position of active target in FRAME_TORSO. This is done assuming an average target size, so it might not be very accurate.

  Returns: | Vector of 3 floats corresponding to the target position 3D.

int `ALTrackerProxy::``getTimeOut`()

  Get the current target lost timeout value.

  Returns: | timeout value in milliseconds.

void `ALTrackerProxy::``initialize`()

  Initialize all tracker parameters with default values.

bool `ALTrackerProxy::``isActive`()

  Return true if Tracker is running.

  Returns: | True if tracker is running.

bool `ALTrackerProxy::``isNewTargetDetected`()

  Return true if a new target was detected since the last `ALTrackerProxy::getTargetPosition`.

  Returns: | True if a new target was detected.

bool `ALTrackerProxy::``isSearchEnabled`()

  Return true if the target search process is enabled. Use `ALTrackerProxy::toggleSearch` to set this value.

  Returns: | True if the target search process is enabled.

bool `ALTrackerProxy::``isTargetLost`()

  Return true if the target is lost.

  Returns: | True if the target was lost.

void `ALTrackerProxy::``lookAt`(const std::vector<float>& Position, const int& Frame, const float& FractionMaxSpeed, const bool UseWholeBody)

  Look at the target position with head in desired frame. If tracker is active, it’s stopped and restarted at the last location of active target after lookAt. This is a blocking call.

  Parameters: | Position – position 3D [x, y, z]. Frame – position frame {FRAME_TORSO = 0, FRAME_WORLD = 1, FRAME_ROBOT = 2}.. FractionMaxSpeed – a fraction. UseWholeBody – if true, use whole body constraints.

void `ALTrackerProxy::``lookAt`(const std::vector<float>& Position, const float& FractionMaxSpeed, const bool UseWholeBody)

  Deprecated since version 1.22: use ALTrackerProxy::lookAt with frame in parameters instead.

  Look at the target position with head. If tracker is active, it’s stopped and restarted at the last location of active target after lookAt. This is a blocking call.

  Parameters: | Position – position 3D [x, y, z] in FRAME_TORSO. FractionMaxSpeed – a fraction. UseWholeBody – if true, use whole body constraints.

void `ALTrackerProxy::``pointAt`(const std::string& Effector, const std::vector<float>& Position, const int& Frame, const float& FractionMaxSpeed)

  Point at the target position with arms in desired frame. If tracker is active, it’s stopped and restarted at the last location of active target after pointAt. This is a blocking call.

  Parameters: | Effector – effector name. Could be “Arms”, “LArm”, “RArm”. Position – position 3D [x, y, z]. Frame – position frame {FRAME_TORSO = 0, FRAME_WORLD = 1, FRAME_ROBOT = 2}. FractionMaxSpeed – a fraction.

void `ALTrackerProxy::``pointAt`(const std::string& Effector, const std::vector<float>& Position, const float& FractionMaxSpeed)

  Deprecated since version 1.22: use ALTrackerProxy::pointAt with frame in parameters instead.

  Point at the target position with arms. If tracker is active, it’s stopped and restarted at the last location of active target after pointAt. This is a blocking call.

  Parameters: | Effector – effector name. Could be “Arms”, “LArm”, “RArm”. Position – position 3D [x, y, z] in FRAME_TORSO. FractionMaxSpeed – a fraction.

void `ALTrackerProxy::``registerTarget`(const std::string& TargetName, const AL::ALValue& Param)

  Register the predefined target with parameters (RedBall: diameter of ball). Subscribe to corresponding extractor and stock the last position if tracker is running. If the target is already registered, only parameters are updated.

  Parameters: | TargetName – a predefined target name. See: Target names. Param – target parameters.

void `ALTrackerProxy::``removeAllTargets`()

  Deprecated since version 1.22: use `ALTrackerProxy::unregisterAllTargets` instead.

  Remove all registered targets and unsubscribe from all extractors.

void `ALTrackerProxy::``removeEffector`(const std::string& Effector)

  Deprecated since version 1.22: use `ALTrackerProxy::setEffector` instead.

  Remove an end-effector from tracking.

  Parameters: | Effector – Name of the effector. Could be: “Arms”, “LArm” or “RArm”.

void `ALTrackerProxy::``removeTarget`(const std::string& TargetName)

  Deprecated since version 1.22: use `ALTrackerProxy::unregisterTarget` instead.

  Remove a predefined target and unsubscribe from corresponding extractor.

  Parameters: | TargetName – a predefined target name. See: Target names.

void `ALTrackerProxy::``removeTargets`(const std::vector<std::string>& TargetNames)

  Deprecated since version 1.22: use `ALTrackerProxy::unregisterTargets` instead.

  Remove predefined targets and unsubscribe from corresponding extractors.

  Parameters: | TargetNames – array of predefined target names. See: Target names.

void `ALTrackerProxy::``setEffector`(const std::string& Effector)

  Set an end-effector to move for tracking. Tracker always used the Head. Use `ALTrackerProxy::getEffector` to get this value.

  Parameters: | Effector – Name of the effector. Could be: “Arms”, “LArm”, “RArm” or “None”..

void `ALTrackerProxy::``setExtractorPeriod`(const std::string& TargetName, const int& Period)

  Set the period of the extractor corresponding to the given target name. See: Modules to launch. Only works if the corresponding target name is tracked (call `ALTrackerProxy::track` before). Use `ALTrackerProxy::getExtractorPeriod` to get this value.

  Parameters: | TargetName – a predefined target name. See: Target names. Period – a period in milliseconds.

void `ALTrackerProxy::``setMaximumAcceleration`(float MaxAcceleration)

  Set the maximum absolute acceleration for head.

  Parameters: | MaxAcceleration – acceleration, positive, in rad.s^-2.

void `ALTrackerProxy::``setMaximumDistanceDetection`(const float& MaxDistance)

  Set the maximum absolute distance for target detection. If the distance to the target is greater than the distance presented here, the target is considered lost.

  Parameters: | MaxDistance – distance, positive, in meter.

void `ALTrackerProxy::``setMaximumVelocity`(float MaxVelocity)

  Set the maximum absolute velocity for head.

  Parameters: | MaxVelocity – velocity, positive, in rad.s^-1.

void `ALTrackerProxy::``setMode`(const std::string& Mode)

  Set the tracker in the predefined mode. Use `ALTrackerProxy::getMode` to get this value.

  Parameters: | Mode – a predefined Tracking modes.

void `ALTrackerProxy::``setMoveConfig`(const AL::ALValue& Config)

  Set a move config to be used when the Move mode is activated. Use `ALTrackerProxy::getMoveConfig` to get this value.

  Parameters: | Config – An ALValue with the custom move configuration. For further details, see: Move config.

void `ALTrackerProxy::``setRelativePosition`(const AL::ALValue& Target)

  Set the robot position relative to target in Move mode. Use `ALTrackerProxy::getRelativePosition` to get this value.

  Parameters: | Target – Final goal of the tracking: [coordX, coordY, coordWz, thresholdX, thresholdY, thresholdWz].

void `ALTrackerProxy::``setSearchFractionMaxSpeed`(const float& FractionMaxSpeed)

  Set search process fraction max speed.

  Parameters: | FractionMaxSpeed – Search process movement fraction max speed.

void `ALTrackerProxy::``setTargetCoordinates`(const AL::ALValue& Coord)

  Only work with LandMarks target name. Set objects coordinates. Use `ALTrackerProxy::getTargetCoordinates` to get this value.

  Parameters: | Coord – Objects coordinates. Could be: [[first object coordinate], [second object coordinate]] [[x1, y1, z1], [x2, y2, z2]].

void `ALTrackerProxy::``setTimeOut`(const int& TimeMs)

  Set target lost timeout in milliseconds.

  Parameters: | TimeMs – Time in milliseconds.

void `ALTrackerProxy::``stopTracker`()

  Stop the tracker.

void `ALTrackerProxy::``track`(const std::string& TargetName)

  Set the predefined target to track and start tracking process. Target name need to be registered before with `ALTrackerProxy::registerTarget`.

  Parameters: | TargetName – a predefined target name. See: Target names.

void `ALTrackerProxy::``trackEvent`(const std::string& EventName)

  Track an event from ALMemory. The value from EventName should have a predefined structure.

  Parameters: | EventName – ALMemory event name.

## EventName Value Structure

The output ALValue from EventName should be organized as follows:

    EventNameInfo {
      TargetPositionInFrameWorld,
      TimeStamp,
      EffectorId,
      HeadThreshold (optional)
    }

Or

    EventNameInfo {
      TargetPositionInFrameTorso,
      TargetPositionInFrameRobot,
      TimeStamp,
      EffectorId,
      HeadThreshold (optional)
    }

### TargetPositionInFrameWorld

Position6D of target to track in FRAME_WORLD.

### TargetPositionInFrameTorso

Position6D of target to track in FRAME_TORSO.

### TargetPositionInFrameRobot

Position6D of target to track in FRAME_ROBOT.

### TimeStamp

This field is the time stamp of detection, as provided by qi::Clock::now.

    TimeStamp {
      TimeStamp_Seconds,
      Timestamp_Microseconds
    }

### EffectorId

This field corresponds to the ID of the effector used for tracking the target:

> - 0 to track with middle of eyes
> - 1 to track with camera top
> - 2 to track with camera bottom
> - 3 no effector, the head does not move

### HeadThreshold

This is an optional field to avoid oscillation, this corresponds to an angle in radians.

void `ALTrackerProxy::``toggleSearch`(const bool& SearchOn)

  Enables/disables the target search process. Target search process occurs only when the target is lost. Use `ALTrackerProxy::isSearchEnabled` to get this value.

  Parameters: | pSearch – If True and if the target is lost, the robot moves the head in order to find the target. If False and if the target is lost the robot does not move.

void `ALTrackerProxy::``unregisterAllTargets`()

  Unregister all targets and unsubscribe from all extractors.

void `ALTrackerProxy::``unregisterTarget`(const std::string& TargetName)

  Unregister a predefined target and unsubscribe from corresponding extractor.

  Parameters: | TargetName – a predefined target name. See: Target names.

void `ALTrackerProxy::``unregisterTargets`(const std::vector<std::string>& TargetNames)

  Unregister predefined targets and unsubscribe from corresponding extractors.

  Parameters: | TargetNames – array of predefined target names. See: Target names.

Glossary Site map Index Support Contact Legal Notices