SoftBank Robotics documentation What's new in NAOqi 2.5?

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

Deprecated Methods

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