Frame


level_1


What is it

A Frame represents a spacial position. This is typically an object or a person position.

See also javadoc: Frame.

How to use it

Making and managing attached frames

From any existing Frame, it is possible to build a new AttachedFrame, that moves with its parent frame. After creation, the offset transform between the parent and the attached frame can be updated at any time.

This is typically used to define targets for GoTo or LookAt actions relatively to existing frames.

Frame baseFrame = ...;
Transform transform1 = TransformBuilder.create().fromXTranslation(1);
AttachedFrame attachedFrame = baseFrame.makeAttachedFrame(transform1);
Transform transform2 = TransformBuilder.create().fromXTranslation(2);
attachedFrame.update(transform2);

Making and managing free frames

A FreeFrame represents a location free to be placed anywhere, that does not move when other frames move. It is created from the Mapping service. The global position of a free frame can be updated by giving its Transform in another frame at any time, see Timestamps.

Free frames are typically used by services detecting objects or persons in the environment, and updating periodically their location relatively to the robot. When the transform between a base frame and the updated free frame comes from robot sensor data, it is recommended to use the timestamp associated with that data when updating the free frame. If no timestamp is available, FreeFrame.update() can be called with an arbitrary 0 timestamp. The method will fall back on updating the free frame relatively to the last known location of the base frame.

Mapping mapping = qiContext.getMapping();
FreeFrame freeFrame = mapping.makeFreeFrame();
Frame baseFrame = ...;
Transform transform = ...;
freeFrame.update(baseFrame, transform, timestamp);

Make Pepper go to a location

You can use a Frame to specify a location where Pepper should go to:

Frame targetFrame = ...;

GoTo goTo = GoToBuilder.with(qiContext)
                       .withFrame(targetFrame)
                       .build();

goTo.async().run();

The frames you should know

Robot Frame

Frame representing the robot location.

https://developer.softbankrobotics.com/sites/default/files/repository/60_rst_pepper/public/source/_build/html/_images/robot_frame.png

It can be retrieved using the Actuation service:

Actuation actuation = qiContext.getActuation();
Frame robotFrame = actuation.robotFrame();

Human head Frame

Frame representing the human location.

https://developer.softbankrobotics.com/sites/default/files/repository/60_rst_pepper/public/source/_build/html/_images/human_head_frame.png

It is accessible via a Human instance:

Human human = ...;
Frame headFrame = human.getHeadFrame();

Gaze Frame

Frame representing the position and orientation of the robot gaze. When looking at a target, the robot will align this frame x-axis with the target origin.

https://developer.softbankrobotics.com/sites/default/files/repository/60_rst_pepper/public/source/_build/html/_images/gaze_frame.png

To retrieve it, use the Actuation service:

Actuation actuation = qiContext.getActuation();
Frame gazeFrame = actuation.gazeFrame();

Map Frame

Frame representing the origin of the map in which Pepper is localized. The Map Frame is not available if the localization process is not running.

To retrieve it, use the Mapping service:

Mapping mapping = qiContext.getMapping();
Frame mapFrame = mapping.mapFrame();

Charging Station Frame

Frame representing the position and orientation of Pepper’s charging station. The Charging Station Frame is not available if Pepper has never seen or sensed his Charging Station.

https://developer.softbankrobotics.com/sites/default/files/repository/60_rst_pepper/public/source/_build/html/_images/charging_station_frame.png

It can be retrieved using the Mapping service:

Mapping mapping = qiContext.getMapping();
Frame chargingStationFrame = mapping.chargingStationFrame();