Aldebaran documentation What's new in NAOqi 2.4.3?

ALFaceCharacteristics API

NAOqi People Perception - Overview | API

Namespace : AL

#include <alproxies/alfacecharacteristicsproxy.h>

Method list

class ALFaceCharacteristicsProxy


bool ALFaceCharacteristicsProxy::analyzeFaceCharacteristics(int id)

Performs the face analysis on a given person using the ID. This method can be called even if ALFaceCharacteristics is not running in order to update the ALMemory data of this person only.

  • id – ID of the person that should be analyzed.

true if the analysis succeeded and false if something went wrong or if the ID is invalid.

float ALFaceCharacteristicsProxy::getSmilingThreshold()

Returns the current smiling threshold value above which the event FaceCharacteristics/PersonSmiling() is raised.

Returns:threshold value between 0 and 1 (default = 0.7).
void ALFaceCharacteristicsProxy::setSmilingThreshold(float threshold)

Sets the current smiling threshold value.

  • threshold – New threshold value. It must be between 0 and 1.


Event: "FaceCharacteristics/PersonSmiling"
callback(std::string eventName, int id, std::string subscriberIdentifier)

Raised when a person has a smile value above the current threshold (default = 0.7).

  • eventName (std::string) – “FaceCharacteristics/PersonSmiling”
  • id – ID of the person as defined by the ALPeoplePerception API.
  • subscriberIdentifier (std::string) –

ALMemory Keys

AL::ALValue PeoplePerception/Person/<ID>/AgeProperties

Age estimation of a person in the form [age, confidence]. The age is limited to the interval [0, 75] and the confidence is in [0, 1].

<ID> is the ID of the person as defined by the ALPeoplePerception API.
AL::ALValue PeoplePerception/Person/<ID>/ExpressionProperties

Estimation of the facial expression on a person’s face. The associated data is an array containing the detection score of the following five expressions: [neutral, happy, surprised, angry or sad].

Each score ranges from 0 and 1 and represents the probability that the person expresses the corresponding expression. As such, the sum of all five properties is equal to 1, except if the detection failed (in that case all five values are set to zero).

AL::ALValue PeoplePerception/Person/<ID>/FacialPartsProperties

Location of the main face features: eyes, nose, and mouth. The associated ALValue is structured as follows:

  [[x_0, y_0], c_0],    # Left eye (center point)
  [[x_1, y_1], c_1],    # Right eye (center point)
  [[x_2, y_2], c_2],    # Mouth (center point)
  [[x_3, y_3], c_3],    # Left eye (inner limit)
  [[x_4, y_4], c_4],    # Left eye (outer limit)
  [[x_5, y_5], c_5],    # Right eye (inner limit)
  [[x_6, y_6], c_6],    # Right eye (outer limit)
  [[x_7, y_7], c_7],    # Mouth (left limit)
  [[x_8, y_8], c_8],    # Mouth (right limit)
  [[x_9, y_9], c_9],    # Nose (left limit)
  [[x_10, y_10], c_10], # Nose (right limit)
  [[x_11, y_11], c_11]  # Mouth (upper limit)


  • [x, y] are expressed in pixels in the image coordinates.
  • c is the confidence value in the range [0, 1].

Note that the “left” and “right” are from the camera point of view (i.e. left eye in the picture corresponds to the user’s right eye).

AL::ALValue PeoplePerception/Person/<ID>/GenderProperties

Gender estimation of a person in the form [gender, confidence]. Gender is either 0 for female or 1 for male and the confidence is in [0, 1].

AL::ALValue PeoplePerception/Person/<ID>/SmileProperties

Smile degree estimation of a person in the form [smile degree, confidence]. The smile degree is a floating point value between 0 and 1 where 0 means “no smile” and 1 is a large smile. The confidence is in [0, 1].