ALVisualCompass API

NAOqi Vision - Overview | API

---

Namespace : AL

#include <alproxies/alvisualcompassproxy.h>

Method list

class ALVisualCompassProxy

• As any module, this module inherits methods from ALModule API.
• It also inherits methods from ALExtractor API and ALVisionExtractor API.
• It also has the following specific methods:
  • ALVisualCompassProxy::enableReferenceRefresh
  • ALVisualCompassProxy::getMatchingQuality
  • ALVisualCompassProxy::getReferenceImage
  • ALVisualCompassProxy::moveStraightTo
  • ALVisualCompassProxy::moveTo
  • ALVisualCompassProxy::setCurrentImageAsReference
  • ALVisualCompassProxy::waitUntilTargetReached

Events lists

• VisualCompass/Deviation()
• VisualCompass/FinalDeviation()
• VisualCompass/InvalidReference()
• VisualCompass/Match()
• VisualCompass/MoveAbort()
• VisualCompass/NewReferenceImageSet()

Methods

void ALVisualCompassProxy::enableReferenceRefresh(const bool& refresh)

Determines if the reference image is taken again at subscribe (default behavior) or not. If not, the reference image is not reset at next subscribe.

Parameters:

• refresh – true / false.

AL::ALValue ALVisualCompassProxy::getMatchingQuality()

Returns the reliability of the matching and the compass deviation computations. It gives both the number of matches and the percentage of inliers for the model. The number of matches must be at least greater than 4 and the percentage over 50% for the matching to be significant.

Returns:Quality with the following format:

• quality[0]: float. Percentage of model inliers amongst matched keypoints. Between 0.0f and 1.0f, must be over 0.5f to be significant.
• quality[1]: int. Number of keypoints that were matched.

AL::ALValue ALVisualCompassProxy::getReferenceImage()

Returns an AL::ALValue containing the image used as a reference.

Returns:AL::ALValue formatted like the output of ALVideoDeviceProxy::getImageRemote.

void ALVisualCompassProxy::moveStraightTo(const float& pDistance)

Makes the robot move forward in a straight line of a given distance. A negative distance value will result in moving backward.

Parameters:

• pDistance – Algebric distance of which to move.

void ALVisualCompassProxy::moveTo(const float& x, const float& y, const float& theta)

Like ALMotionProxy::moveTo, makes the robot move to the given pose in the ground plane, relative to FRAME_ROBOT. Unlike ALMotionProxy::moveTo, the robot decomposes the movement in pure rotation and pure translation: the robot will turn to face the direction defined by x and y, move forwards until the location is reached, then turn one last time to reach the right orientation.

Keep in mind that this function cannot make the robot move backwards (instead it will turn around and move forwards). Furthermore, it always chooses the fastest path. Therefore, it cannot be used to proceed to a full turn (the robot will not move, because it will already have the right orientation).

This is a blocking call.

Parameters:

• x – Distance along the X axis in meters.
• y – Distance along the Y axis in meters.
• theta – Rotation around the Z axis in radians.

bool ALVisualCompassProxy::setCurrentImageAsReference()

Clears the old reference image then sets the current image as new reference image.

Returns:true if the current image was successfully set as new reference image, false otherwise.

void ALVisualCompassProxy::waitUntilTargetReached()

Waits until the end of a ALVisualCompassProxy::moveTo or a ALVisualCompassProxy::moveStraightTo. This is a blocking call.

Events

Event: "VisualCompass/Deviation"

callback(std::string eventName, AL::ALValue value, std::string subscriberIdentifier)

Raised each time the deviation of the current image from the compass is computed. The event is formatted as follows:

VisualCompass/Deviation = [
DeviationInfo,
RobotPosition,
TimeStamp
]

DeviationInfo contains the deviation along Z axis (theta angle for the robot pose) and Y axis.

DeviationInfo = [
  YAxisDeviation,
  ZAxisDeviation,
]

RobotPosition contains the robot position in WORLD_SPACE when the image was taken.

RobotPosition = [
  X,
  Y,
  Theta
]

TimeStamp: this field is the time stamp of the image that was used to compute the deviation.

TimeStamp =
[
  TimeStamp_Seconds,
  Timestamp_Microseconds
]

Event: "VisualCompass/FinalDeviation"

callback(std::string eventName, AL::ALValue value, std::string subscriberIdentifier)

Continually raised by ALVisualCompassProxy::moveTo during rotations. After the rotation, this event allows to access the final deviation.

The event is formatted as follows:

FinalDeviation contains the final deviation along Z axis (theta angle for the robot pose) and Y axis. After a rotation, finalWz will be equal to the angle of which the robot actually turned.

FinalDeviation = [
  finalWy,
  finalWz,
]

Event: "VisualCompass/InvalidReference"

callback(std::string eventName, bool isInvalid, std::string subscriberIdentifier)

Raised with true after failing to set a new reference image.

Event: "VisualCompass/Match"

callback(std::string eventName, AL::ALValue value, std::string subscriberIdentifier)

Note

The full name of this event is VisualCompass/Match in ALMemory.

Raised each time the deviation of the current image from the compass is computed. The event is formatted as follows:

VisualCompass/Match =
[
  ReferenceKeypoints,
  CurrentKeypoints,
  Matches,
  Inliers
]

ReferenceKeypoints is the list of keypoints extracted from the reference image. CurrentKeypoints is the list of keypoints extracted from the current processed image. Both are a list of Keypoint where:

Keypoint =
[
  [X, Y],
  Size,
  Angle,
  Response,
  Octave
]

X and Y are the coordinates of the center of the keypoints in image coordinates, Size is the size of the keypoint, Angle is the keypoint orientation, Response is the keypoint strength, and Octave is the keypoint scale.

Matches is the list of the matches between the keypoints. Each Match is:

Match =
[
  ReferenceIndex,
  CurrentIndex,
  Distance
]

ReferenceIndex is the index of the matched keypoint in the reference list, CurrentIndex is the index of the matched keypoint in the current list, and Distance is the distance between the two keypoints.

Inliers is the list of the match indexes for each direction (Y and Z axis) which correspond to inliers for the Ransac: these are the indexes of the coherent matches used to compute the deviation.

Inliers =
[
   InliersWy = [Idx0, Idx1, ...],
   InliersWz = [Idx0, Idx1, ...]
]

Event: "VisualCompass/MoveAbort"

callback(std::string eventName, bool aborted, std::string subscriberIdentifier)

Raised after the end of a move, with true if the move was aborted or with false if the target was reached.

Event: "VisualCompass/NewReferenceImageSet"

callback(std::string eventName, bool isSet, std::string subscriberIdentifier)

Raised with true after successfully setting a new reference image, raised with false after clearing the reference image.