area_manager

How to use

To start the area_manager ros node, run the following command on terminal -

> rosrun area_manager area_manager

Description

We define an area as a bounded region in the environment with semantic meaning. This module associates area with the entity to calculate their interaction with other entities. These areas are useful to get a first discrimination of the situation and conditional computation.

Implementation details

In the current implementation, an area is 2.5D dimensions i.e 2D area + height. Areas can be a polygonal (polygons with height) or a cylindrical (circle with height) , static or dynamic. In TOASTER, areas have several parameters: areaType, factType, entityType, owner. The areaType defines the category of the area (such as room, escalator, television_area). As areas could be used for different situation, we use the factType to define what type of calculation needs to be done for entities inside the current area. This parameter is very linked to the semantic of the area. The entityType defines what kinds of entities are concerned by the area. Entities which are not in the category will be ignored. Finally, owner defines which entity "owns" this area. If set, the area is updated with the owner's position and orientation. For a clear relationship between pdg node with its topics, services and other nodes, refer to the figure below.

Facts computation

The facts generated by this module are:

• IsInRoom: this fact is produced for area with areaType equal to room. When a concerned entity (an entity which belongs to the class entityType of the room), is inside the area, this fact is generated. The property is IsInRoom, the propertyType is position, the subProperty is room, the subjectId is the id of the entity inside the room, the targetId is the name of the area, the time is set with the perception time of the entity, the valueType is set to zero and the stringValue is set to true.

example: Bob IsInRoom Livingroom ...

• IsAt: this fact is produced for area with areaType equal to support. When a concerned entity (an entity which belongs to the class entityType of the area), is inside the area, this fact is generated. The property is IsAt, the propertyType is position, the subProperty is location, the subjectId is the id of the entity inside the room, the targetId is the name of the area, the time is set with the perception time of the entity, the valueType is set to zero and the stringValue is set to true.

example: Bob IsAt Livingroom_table ...

• IsInArea: this fact is produced for any other kind of area with areaType different to support and room. When a concerned entity (an entity which belongs to the class entityType of the area), is inside the area, this fact is generated. The property is IsInArea, the propertyType is position, the subProperty is set with areaType, the subjectId is the id of the entity inside the room, the targetId is the name of the area. If the area has an owner, we set targetOwnerId with its id. The time is set with the perception time of the entity, the valueType is set to zero and the stringValue is set to true.

example: Bob IsInArea corridor ...

• AreaDensity: this fact is produced to get the density of element in an area if area has factType set to density. The fact property is AreaDensity, the propertyType is density, the subProperty is set with ratio. The subjectId is the name of the area. The time of the fact is set using the time of the entity in the area. The valueType is set to one and the doubleValue is the ratio nbEntInArea/nbEnt, with nbEntInArea the number of concerned entities (from the entityType of the area) and nbEnt the total number of these entities.

• IsFacing: this fact is computed for entity inside an area with interaction as factType. We compute the orientation of the entity and we compare it with the position of the area owner. If this orientation is close enough, we consider that the entity is facing the area owner. The fact property is IsFacing, the propertyType is posture, the subProperty is set with angle. The subjectId is the id of the entity. The targetId is set with the id of the area's owner. The time of the fact is set using the time of the entity perception. The valueType is set to zero, the stringValue is true and the doubleValue is the angle of deviation between the orientation toward the area's owner and the actual entity orientation.

To compute the presence of an element in an area, we use the distance from the center for circular area which we compare to the ray of the area. For polygonal areas, we use the boost library and the within function of the polygon (see [boost within] (http://www.boost.org/doc/libs/1_61_0/libs/geometry/doc/html/geometry/reference/algorithms/within/within_2.html) ).

Inputs

area_manager takes outputs of PDG module i.e. orientation, positions and other properties of entities.

Outputs

It publishes facts like isInArea, isAt, AreaDensity on topic named /area_manager/factList and areas on topic /area_manager/areaList.

Services

Services provided by area_manager are :

• add_area - In the current implementation, an area is 2.5D dimensions i.e 2D area + height. Areas can be a polygonal (polygons with height) or a cylindrical (circle with height) , static or dynamic. In TOASTER, areas have several parameters: areaType, factType, entityType, myOwner. The areaType defines the category of the area (such as room, escalator, television_area). As areas could be used for different situation, we use the factType to define what type of calculation needs to be done for entities inside the current area. This parameter is very linked to the semantic of the area. The entityType defines what kinds of entities are concerned by the area. Entities which are not in the category will be ignored. myOwner defines which entity "owns" this area. And parameters enterHysteresis and leaveHystereis are to deal with the issue of hysteresis. You can set it as per your choice. Entity will be considered to be inside the area lets say cylinder with radius equal to ray only if it is inside the cylinder with radius ray - enterHysteresis. And once it enters the innermost cylinder, that entity would be added to list of insideEntities. Now, if entity steps out the cylinder with radius ray + leaveHysteresis , then only it would be considered as outside the area. And accordingly, facts will be generated. upComingEntities and leavingEntities has been added for the tracking purpose. Similar concept works for the polygonal areas. If set, the area is updated with the owner's position and orientation. Concerning the id of the area, if an id is given, the area will have this id, replacing the previous area with the same id if any. When no id is specified (the default value 0 is given) the module will assign the area with the first available unsigned integer. If isCircle is true, the area will be determined according to the fields center and ray. Otherwise, it will depend on the poly field and the list of the points wished. The message format of the service looks like this:

NOTE : Area created with some valid owner ID have the position in owner's frame while those with no owner have positions in global frame.

Shell command:

rosservice call /area_manager/add_area "myArea:
  id: 0
  name: ''
  myOwner: ''
  areaType: ''
  factType: ''
  entityType: ''
  isCircle: false
  center: {x: 0.0, y: 0.0, z: 0.0}
  ray: 0.0
  height: 0.0
  poly:
    points:
    - {x: 0.0, y: 0.0, z: 0.0}
  zmin: 0.0
  zmax: 0.0
  enterHysteresis: 0.0
  leaveHysteresis: 0.0
  insideEntities_: [0]
  upcomingEntities_: [0]
  leavingEntities_: [0]" 

• remove_area - Areas can be added and removed as per the requirements. This service is used to remove the area where input is the area's numeric id. This id is positive.

Shell command:

rosservice call /area_manager/remove_area "id: 0"

• remove_all_areas - As the name suggests, service remove_all_areas removes all areas created for the situation assessment.

• print_area - This service takes id of area and prints its details including its position, orientation, owner and list of entities inside this area. Similarly, the service print_all_areas prints details of all areas.

• get_relative_position - This service computes relative position of target with respect to subject and shows it in higher level terms like right, left, ahead, back etc, which are simple for human understanding. It takes string id of subject and target entity.

Shell command:

rosservice call /area_manager/get_relative_position "subjectId: ''
targetId: ''"

• get_multiple_relative_position - This service is used to get relative position of an object compared to an other from an agent point of view. It takes a string agentSubjectId of the agent from which we want the point of view, the string objectSubjectId giving the id of the object which we will use to describe the position of the object identified by the string objectTargetId.

Shell command:

rosservice call /area_manager/get_multiple_relative_position "agentSubjectId: ''
objectSubjectId: ''
targetId: ''"

• publish_all_areas - This service controls the publishing of areas on /area_manager/areaList topic. If this service is called, a parameter name publishingArea_ is negated. The node only publishes on areaList topic if this parameter is positive. By default, it is set to true.

Examples

As an example, it is possible to define a polygon in front of the robot (myRobot) to know if a human is in an interaction configuration. This area triggers some computation such as the human body orientation. It would have as set of parameters <interaction, orientation, humans, myRobot> and is updated with the position and orientation of myRobot. This example is illustrated by the pink area of figure below.

Future work and possible improvement

To improve this module, we should add 3d areas. Also currently the number of areaType is quite limited. A way to improve would be to have a configuration file where we could define a new type of area and tell which facts computation should be triggered for this kind of area. As an example, the computation of facts in move3d_facts or agent_monitor should be triggered according to the configuration with areas. As an example, it could be useless to compute if an agent isMovingToward an object when the object is not in the same room.