SoftBank Robotics documentation What's new in NAOqi 2.8?

ALPeoplePerception API

NAOqi People Perception - Overview | API

Namespace : AL

Methods

float ALPeoplePerception::getMaximumDetectionRange()
Returns:Maximum detection and tracking range in meters. The default value is 3.5 meters.
float ALPeoplePerception::getTimeBeforePersonDisappears()
Returns:Time after which a person disappears from the PeopleList. The default value is 10 seconds. See ALPeoplePerception::setTimeBeforePersonDisappears for a description of this parameter.
float ALPeoplePerception::getTimeBeforeVisiblePersonDisappears()
Returns:Time after which a visible person disappears from the PeopleList. The default value is 2 seconds. See ALPeoplePerception::setTimeBeforeVisiblePersonDisappears for a description of this parameter.
bool ALPeoplePerception::isFaceDetectionEnabled()
Returns:true if the module uses the face detection, false otherwise.
bool ALPeoplePerception::isFastModeEnabled()
Returns:true if the fast mode is enabled, false otherwise.
bool ALPeoplePerception::isGraphicalDisplayEnabled()
Returns:true if the module currently pushes data to ALMemory for graphical display in Choregraphe, false otherwise.
bool ALPeoplePerception::isMovementDetectionEnabled()
Returns:true if the module uses the movement detection, false otherwise.
void ALPeoplePerception::resetPopulation()

Empties the current population and erases all data related to People Perception and associated modules from ALMemory.

void ALPeoplePerception::setFastModeEnabled(const bool& enable)

Enables or disables the fast mode. When enabled, all optional detections (face and movement for example) are disabled. If this method is called with enable = false, all optional detections will be turned on.

Parameters:
  • enable – true or false.
void ALPeoplePerception::setGraphicalDisplayEnabled(const bool& enable)

Enables or disables the push of debug data into ALMemory. These data are used by Choregraphe to display spheres representing humans in the Robot View.

Parameters:
  • enable – true or false.
void ALPeoplePerception::setMaximumDetectionRange(const float& range)

Sets the maximum detection and tracking range. Any person further away than this distance will not be tracked. Setting this range to a smaller value can help preventing the background noise from being detected as a human shape but will require humans to get closer to the robot in order to be successfully detected and tracked.

Parameters:
  • range – Maximum detection and tracking range in meters.
void ALPeoplePerception::setMovementDetectionEnabled(const bool& enable)

Enables or disables the movement detection to detect people. This can make the overall process slower if enabled.

Parameters:
  • enable – true or false.
void ALPeoplePerception::setTimeBeforePersonDisappears(const float& seconds)

Sets the time after which a person disappears from the PeopleList (see Events) if he/she is no more visible because the robot looks away. The robot knows that it moved and that the person cannot be seen anymore if he/she stays at the same position.

Parameters:
  • seconds – Timeout in seconds.
void ALPeoplePerception::setTimeBeforeVisiblePersonDisappears(const float& seconds)

Sets the time after which a person disappears from the PeopleList (see Events) if he/she is no more visible because he/she moved or is hidden from the camera. In this case the robot didn’t move but doesn’t see the person anymore.

Parameters:
  • seconds – Timeout in seconds.
void ALPeoplePerception::setFaceDetectionEnabled(const bool& enable)

Deprecated since version 1.22: The face detection is always enabled.

Events

Event: "PeoplePerception/JustArrived"
callback(std::string eventName, int, std::string subscriberIdentifier)

Raised when a new person is detected and added to the population.

Parameters:
  • eventName (std::string) – “PeoplePerception/JustArrived”
  • id – ID of the person
  • subscriberIdentifier (std::string) –
Event: "PeoplePerception/JustLeft"
callback(std::string eventName, int, std::string subscriberIdentifier)

Raised when a person is removed from the population.

Parameters:
  • eventName (std::string) – “PeoplePerception/JustLeft”
  • id – ID of the person
  • subscriberIdentifier (std::string) –
Event: "PeoplePerception/PeopleDetected"
callback(std::string eventName, AL::ALValue, std::string subscriberIdentifier)

Raised whenever at least one person is visible by the robot. Contains information about the detected people, it is used by ALTracker to track people.

It is organized as follows:

MovementInfo =
[
  [TimeStamp_Seconds, TimeStamp_Microseconds],
  [PersonData_1, PersonData_2, ... PersonData_n],
  CameraPose_InTorsoFrame,
  CameraPose_InRobotFrame,
  Camera_Id
]

TimeStamp: this field is the time stamp of the image that was used to perform the detection.

PersonData_i: each of these fields contains the description of a person. It has the following structure:

PersonData_i =
[
  Id,
  DistanceToCamera,
  PitchAngleInImage,
  YawAngleInImage
]

where PitchAngleInImage and YawAngleInImage are angular coordinates of the person’s head in the image, in radians.

CameraPose_InTorsoFrame: describes the Position6D of the camera at the time the image was taken, in FRAME_TORSO.

CameraPose_InRobotFrame: describes the Position6D of the camera at the time the image was taken, in FRAME_ROBOT.

Camera_Id: gives the Id of the camera used for the detection.

Event: "PeoplePerception/PopulationUpdated"
callback(std::string eventName, std::string subscriberIdentifier)

Raised every time the population data has been updated.

Event: "PeoplePerception/PeopleList"
callback(std::string eventName, AL::ALValue list, std::string subscriberIdentifier)

Raised every time the list of persons in the current population changes. The associated data is a list of people IDs (integers) in the current population. These IDs are used to search ALMemory for each person’s attributes. PeopleList is the union of NonVisiblePeopleList and VisiblePeopleList.

For further details, see: PeoplePerception/NonVisiblePeopleList() and PeoplePerception/VisiblePeopleList() .

Event: "PeoplePerception/NonVisiblePeopleList"
callback(std::string eventName, AL::ALValue list, std::string subscriberIdentifier)

Raised every time the list of people who are currently not visible by the robot (the IsVisible attribute equals 0) changes. This list is a subset of the PeopleList.

Event: "PeoplePerception/VisiblePeopleList"
callback(std::string eventName, AL::ALValue list, std::string subscriberIdentifier)

Raised every time the list of people who are currently visible by the robot (the IsVisible attribute equals 1) changes. This list is a subset of the PeopleList.

Event: "PeoplePerception/MaximumDetectionRangeUpdated"
callback(std::string eventName, float, std::string subscriberIdentifier)

Raised when the value of the maximum detection range has been modified.

ALMemory Keys

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

Yaw and Pitch angles (in radians) of the top of the shape of a person relative to the robot’s torso.

float PeoplePerception/Person/<ID>/Distance

Distance (in meters) between the person and the camera.

bool PeoplePerception/Person/<ID>/IsFaceDetected

Says whether the face of the person is detected or not. This key may not be present in memory if the face detection has never been performed on a specific person.

bool PeoplePerception/Person/<ID>/IsVisible

Says whether the person is seen by the robot or not.

int PeoplePerception/Person/<ID>/NotSeenSince

Time elapsed (in seconds) since the last time this person was detected.

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

3D head position of the person in the FRAME_ROBOT space.

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

3D head position of the person in the FRAME_TORSO space.

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

3D head position of the person in the FRAME_WORLD space.

int PeoplePerception/Person/<ID>/PresentSince

Time elapsed (in seconds) since the first time this person was detected.

float PeoplePerception/Person/<ID>/RealHeight

Estimated height of a person in meters. It is computed as the maximum detected height over time.

std::string PeoplePerception/Person/<ID>/ShirtColor

The primary color of clothing of the person. It can be either “Black”, “Gray”, “White”, “Red”, “Orange”, “Yellow”, “Green”, “Blue” or “Purple”.

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

The H, S and V components of the primary color of clothing of the person in the HSV Colorspace.

  • Hue (H) is in the [0, 360[ range,
  • Saturation (S) is in [0, 1],
  • Value (V) is in [0, 1].

Signals

qi::Signal<float> ALPeoplePerception::maximumDetectionRangeChanged

Raised when the maximum detection range is updated. See PeoplePerception/MaximumDetectionRangeUpdated().

  • float maximumRange: New value for the maximum detection range, in meters.
qi::Signal<int> ALPeoplePerception::justArrived

Raised when a new person is detected and added to the population. See PeoplePerception/JustArrived().

  • int ID: ID of the new person.
qi::Signal<int> ALPeoplePerception::justLeft

Raised when a person is removed from the population. See PeoplePerception/JustLeft().

  • int ID: ID of the person removed.
qi::Signal<void> ALPeoplePerception::populationReset

Raised when the population is reset, either by a call to ALPeoplePerception::resetPopulation or when the module is started or stopped.