LocalizeAndMap¶

level_3

Goal - Make Pepper localize himself in his environment, while building a representation of this environment for potential future use by a Localize action.

// Build the action.
val localizeAndMap: LocalizeAndMap = LocalizeAndMapBuilder.with(qiContext).build()

// Run the action asynchronously.
localizeAndMap.async().run()

// Store the LocalizeAndMap execution.
private var localizationAndMapping: Future<Void>? = null

// Build the action.
LocalizeAndMap localizeAndMap = LocalizeAndMapBuilder.with(qiContext).build();

// Run the action asynchronously.
localizeAndMap.async().run();

// Store the LocalizeAndMap execution.
private Future<Void> localizationAndMapping;

Typical usage - You want Pepper to localize himself and move around his environment, without drifting or losing track of his position relatively to his surroundings. You want Pepper to build an ExplorationMap, representing his surroundings.

How it works¶

// Build the action.
val localizeAndMap: LocalizeAndMap = LocalizeAndMapBuilder.with(qiContext).build()

// Add a listener to get the map when localized.
localizeAndMap.addOnStatusChangedListener { localizationStatus ->
    if (localizationStatus == LocalizationStatus.LOCALIZED) {
        // Stop the action.
        localizingAndMapping?.requestCancellation()
        // Dump the map for future use by a Localize action.
        val explorationMap: ExplorationMap = localizeAndMap.dumpMap()
    }
}

// Run the action.
localizingAndMapping = localizeAndMap.async().run()

// Build the action.
LocalizeAndMap localizeAndMap = LocalizeAndMapBuilder.with(qiContext).build();

// Add a listener to get the map when localized.
localizeAndMap.addOnStatusChangedListener(localizationStatus -> {
    if (localizationStatus == LocalizationStatus.LOCALIZED) {
        // Stop the action.
        localizingAndMapping.requestCancellation();
        // Dump the map for future use by a Localize action.
        ExplorationMap explorationMap = localizeAndMap.dumpMap();
    }
});

// Run the action.
localizingAndMapping = localizeAndMap.async().run();

Extend an existing map¶

level_7

If a map has already be done, it can be extended by giving it to the builder of a new LocalizeAndMap. The robot will load the map, try to localize in it and, if successful, will add data to the ExplorationMap. This functionality is only implemented on ExplorationMaps built with a level_7 SDK on a Pepper equipped with a Stereo Camera. When trying to extend a too old map, or one built with a Pepper not equipped with a Stereo Camera, the LocalizeAndMap call to run() will systematically fail.

// Build the action.
val localizeAndMap: LocalizeAndMap = LocalizeAndMapBuilder.with(qiContext)
                                                                .withMap(explorationMap)
                                                                .build()

// Build the action.
LocalizeAndMap localizeAndMap = LocalizeAndMapBuilder.with(qiContext)
                                                            .withMap(explorationMap)
                                                            .build();

Use case¶

Make Pepper localize himself¶

As long as the LocalizeAndMap is running, Pepper keeps track of his position relatively to his environment. This means the user can call, for example, robotFrame.computeTransform(mapFrame) to know the robot position relatively to the map frame, which is where the robot was when the run() was called.

Performance & Limitations¶

Odometry drift when no Localize or LocalizeAndMap is running¶

If no Localize or LocalizeAndMap action is running, the robot does not keep track of his position relatively to his environment, and only uses proprioceptive information when moving.

This means that while moving, Pepper accumulates odometry drift. If Pepper were to move back and forth for a long time, it would drift and no longer be at the place he would be supposed to be.

Sensibility to environment¶

The localization process uses exteroceptive information to compute Pepper’s location in his environment. It mainly uses laser sensors information, and those only see obstacles up to a few meters. In an open environment, Pepper will get little information and the localization process might give inconsistent results.

Humans and moving objects¶

While mapping his environment, Pepper will consider that the obstacles he detects, including humans, are permanent and will store them in his map. If too many humans are present around Pepper at the time of mapping, this will degrade the performances of Localize actions that will use the resulting map.

Obstacle detection is a process that is continuously running on Pepper, and not only while a LocalizeAndMap action is running. To robustify Pepper’s obstacle detection abilities, sensor values are probabilistically integrated over time. Consequently, Humans that are around Pepper a few seconds before a LocalizeAndMap is started may be taken into account in the map created by the action.

Therefore, before mapping an environment, it is recommended to make sure no humans or moving obstacles are in the vicinity of Pepper, and to wait up to 15 seconds before actually running the LocalizeAndMap action.

Scanning animation¶

When starting a LocalizeAndMap action, the robot will look around to gather sensor information around his initial position. If the LocalizeAndMap is unable to perform this scanning animation, for example because of another already running action, the LocalizeAndMap run will throw an “Animation failed” error.