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

# ALPeoplePerception API

NAOqi People Perception - Overview | API

Namespace : AL

## Method list

class `ALPeoplePerception`

- As any module, this module inherits methods from ALModule API.
- It also inherits methods from ALExtractor API.
- It also has the following specific methods:
  - `ALPeoplePerception::getMaximumDetectionRange`
  - `ALPeoplePerception::getTimeBeforePersonDisappears`
  - `ALPeoplePerception::getTimeBeforeVisiblePersonDisappears`
  - `ALPeoplePerception::isFaceDetectionEnabled`
  - `ALPeoplePerception::isFastModeEnabled`
  - `ALPeoplePerception::isGraphicalDisplayEnabled`
  - `ALPeoplePerception::isMovementDetectionEnabled`
  - `ALPeoplePerception::resetPopulation`
  - `ALPeoplePerception::setFastModeEnabled`
  - `ALPeoplePerception::setGraphicalDisplayEnabled`
  - `ALPeoplePerception::setMaximumDetectionRange`
  - `ALPeoplePerception::setMovementDetectionEnabled`
  - `ALPeoplePerception::setTimeBeforePersonDisappears`
  - `ALPeoplePerception::setTimeBeforeVisiblePersonDisappears`
  - `ALPeoplePerception::setFaceDetectionEnabled` (deprecated)

## Events lists

- `PeoplePerception/JustArrived()`
- `PeoplePerception/JustLeft()`
- `PeoplePerception/PeopleDetected()`
- `PeoplePerception/PopulationUpdated()`
- `PeoplePerception/PeopleList()`
- `PeoplePerception/NonVisiblePeopleList()`
- `PeoplePerception/VisiblePeopleList()`
- `PeoplePerception/MaximumDetectionRangeUpdated()`

## ALMemory Keys list

- `PeoplePerception/Person/<ID>/AnglesYawPitch`
- `PeoplePerception/Person/<ID>/Distance`
- `PeoplePerception/Person/<ID>/IsFaceDetected`
- `PeoplePerception/Person/<ID>/IsVisible`
- `PeoplePerception/Person/<ID>/NotSeenSince`
- `PeoplePerception/Person/<ID>/PositionInRobotFrame`
- `PeoplePerception/Person/<ID>/PositionInTorsoFrame`
- `PeoplePerception/Person/<ID>/PositionInWorldFrame`
- `PeoplePerception/Person/<ID>/PresentSince`
- `PeoplePerception/Person/<ID>/RealHeight`
- `PeoplePerception/Person/<ID>/ShirtColor`
- `PeoplePerception/Person/<ID>/ShirtColorHSV`

## Signal list

- `ALPeoplePerception::maximumDetectionRangeChanged`
- `ALPeoplePerception::justArrived`
- `ALPeoplePerception::justLeft`
- `ALPeoplePerception::populationReset`

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

Glossary Site map Index Support Contact Legal Notices