SoftBank Robotics documentation What's new in NAOqi 2.8?

Exploration API

Overview | API Navigation | API Exploration

Namespace : AL

#include <alproxies/alnavigationproxy.h>

Experimental Methods

qi::Future<void> ALNavigationProxy::explore(float radius)

Warning

This is still a work in progress, and API may change in the future.

Makes Pepper explore autonomously his surrounding environment in the limit of the radius passed as parameter.

Parameters:
  • radius – distance max to explore in meters.
Returns:

a future returning when the exploration finishes.
qi::Future<void> ALNavigationProxy::startMapping()

Warning

This is still a work in progress, and API may change in the future.

Starts the customizable mapping process. At first Pepper runs a base and head scanning behaviour to initialize the map (a few seconds). Then, as opposed to explore, it is the developer’s responsibility to make Pepper move during the mapping, and to stop the mapping when needed. The developer thus has full control over the mapped area.

To stop the mapping process at any time, call stopExploration.

Throws if the robot couldn’t finish the initialization behaviour.

Returns:a future returning when the initialization behaviour finishes.
void ALNavigationProxy::stopExploration()

Warning

This is still a work in progress, and API may change in the future.

Stops any ongoing exploration (started by explore), mapping (started by startMapping) or localization (started by startLocalization). No-op if nothing is running.

std::string ALNavigationProxy::saveExploration()

Warning

This is still a work in progress, and API may change in the future.

Saves the current exploration data on disk for a later use.

Returns:a string indicating the path of the created .explo file.
ALValue ALNavigationProxy::getMetricalMap()

Warning

This is still a work in progress, and API may change in the future.

Returns the map based on the currently loaded exploration. The map is formatted as follow: [mpp, width, height, [originOffsetX, originOffsetY], [pxlVal, ...]]

where:

  • mpp is the resolution of the map in meters per pixel,
  • width and height are the size of the image in pixels,
  • originOffset is the metrical offset of the pixel (0, 0) of the map,
  • and [pxlVal, ...] is the buffer of pixel floating point values between 0 (occupied space) and 100 (free space).

Throws if no exploration is loaded or if the localization is not running.

Returns:an ALValue containing the map formatted as explained.
ALValue ALNavigationProxy::getExplorationPath()

Warning

This is still a work in progress, and API may change in the future.

Returns the sampled Pose2D (x, y, theta) path that the robot did during his exploration.

Throws if no exploration is loaded.

Returns:an ALValue with the path formatted as [[pose0], [pose1], ... , [poseN]] where [pose] is [pX, pY, pTheta].
qi::Future<bool> ALNavigationProxy::navigateToInMap(float x, float y)

Warning

This is still a work in progress, and API may change in the future.

Makes Pepper navigate to a desired target by using the explored map.

Throws if no exploration is loaded or if the localization is not running.

Parameters:
  • target – x and y of the target in explored map frame.
Returns:

a future holding true if the execution succeeded, false otherwise.
ALValue ALNavigationProxy::getRobotPositionInMap()

Warning

This is still a work in progress, and API may change in the future.

Retrieves the localized position of the robot in the current explored map frame.

Throws if no exploration is loaded or if the localization is not running.

Returns:an ALValue containing a Localized Pose.
qi::Future<bool> ALNavigationProxy::loadExploration(std::string path)

Warning

This is still a work in progress, and API may change in the future.

Loads the .explo from the location on the disk.

Returns:a future holding the success of the exploration loading.
void ALNavigationProxy::setDefaultExploration(std::string path)

Warning

This is still a work in progress, and API may change in the future.

Sets an exploration to be loaded at the start of navigation.

Throws if .explo file does not exist.

qi::Future<void> ALNavigationProxy::relocalizeInMap()

Warning

This is still a work in progress, and API may change in the future.

Initializes the Pose2d of the robot in the map, so that it is possible to use other API like getRobotPositionInMap or navigateToInMap.

Throws if no exploration is loaded or if the relocalization failed.

qi::Future<void> ALNavigationProxy::relocalizeInMapWithHint(float x, float y, float theta)

Warning

This is still a work in progress, and API may change in the future.

Requests the localizer to relocalize around estimation pose.

Throws if no exploration is loaded.

Parameters:
  • estimation – x, y and theta of the estimated pose of the robot in map frame.
void ALNavigationProxy::startLocalization()

Warning

This is still a work in progress, and API may change in the future.

Starts the exploration loop that computes the robot localization.

Throws if no exploration is loaded.

void ALNavigationProxy::stopLocalization()

Warning

This is still a work in progress, and API may change in the future.

Stops the exploration loop that computes the robot localization. No-op if localization loop is not running.

Custom types

Localized Pose

Localized pose is formatted as following:

[Pose, Uncertainty]

where:

  • Pose is the position [X, Y, theta] computed by the localizer
  • Uncertainty is the ellipse with parameters [radiusX, radiusY, orientation] defining the uncertainty ellipse of the localized pose

Code samples

Demonstration applications

Some sample applications are available in opensource on github here: naoqi_navigation_samples.

It contains applications for exploration, map annotation and robot patrol.

Python script for exploring

The following script makes the robot explore a 2 m radius zone, and if everything went OK, saves the exploration on disk, comes back to his starting point, and displays the result map.

explore.py

#! /usr/bin/env python
# -*- encoding: UTF-8 -*-

"""Example: Use explore method."""

import qi
import argparse
import sys
import numpy
import Image


def main(session):
    """
    This example uses the explore method.
    """
    # Get the services ALNavigation and ALMotion.
    navigation_service = session.service("ALNavigation")
    motion_service = session.service("ALMotion")

    # Wake up robot
    motion_service.wakeUp()

    # Explore the environement, in a radius of 2 m.
    radius = 2.0
    navigation_service.explore(radius)
    # Saves the exploration on disk
    path = navigation_service.saveExploration()
    print "Exploration saved at path: \"" + path + "\""
    # Start localization to navigate in map
    navigation_service.startLocalization()
    # Come back to initial position
    navigation_service.navigateToInMap([0., 0., 0.])
    # Stop localization
    navigation_service.stopLocalization()
    # Retrieve and display the map built by the robot
    result_map = navigation_service.getMetricalMap()
    map_width = result_map[1]
    map_height = result_map[2]
    img = numpy.array(result_map[4]).reshape(map_width, map_height)
    img = (100 - img) * 2.55 # from 0..100 to 255..0
    img = numpy.array(img, numpy.uint8)
    Image.frombuffer('L',  (map_width, map_height), img, 'raw', 'L', 0, 1).show()

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--ip", type=str, default="127.0.0.1",
                        help="Robot IP address. On robot or Local Naoqi: use '127.0.0.1'.")
    parser.add_argument("--port", type=int, default=9559,
                        help="Naoqi port number")

    args = parser.parse_args()
    session = qi.Session()
    try:
        session.connect("tcp://" + args.ip + ":" + str(args.port))
    except RuntimeError:
        print ("Can't connect to Naoqi at ip \"" + args.ip + "\" on port " + str(args.port) +".\n"
               "Please check your script arguments. Run with -h option for help.")
        sys.exit(1)
    main(session)

Python script for localizing

The following script loads a map given in argument, relocalizes Pepper inside this map, and navigates to a position in the map.

localize.py

#! /usr/bin/env python
# -*- encoding: UTF-8 -*-

"""Example: Use localization methods"""

import qi
import argparse
import sys


def main(session, exploration_file):
    """
    This example uses localization methods.
    """
    # Get the services ALNavigation and ALMotion.
    navigation_service = session.service("ALNavigation")
    motion_service = session.service("ALMotion")

    # Wake up robot
    motion_service.wakeUp()

    # Load a previously saved exploration
    navigation_service.loadExploration(exploration_file)

    # Relocalize the robot and start the localization process.
    guess = [0., 0.] # assuming the robot is not far from the place where
                     # he started the loaded exploration.
    navigation_service.relocalizeInMap(guess)
    navigation_service.startLocalization()

    # Navigate to another place in the map
    navigation_service.navigateToInMap([2., 0., 0.])

    # Check where the robot arrived
    print "I reached: " + str(navigation_service.getRobotPositionInMap()[0])

    # Stop localization
    navigation_service.stopLocalization()

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--ip", type=str, default="127.0.0.1",
                        help="Robot IP address. On robot or Local Naoqi: use '127.0.0.1'.")
    parser.add_argument("--port", type=int, default=9559,
                        help="Naoqi port number")
    parser.add_argument("--explo", type=str, help="Path to .explo file.")

    args = parser.parse_args()
    session = qi.Session()
    try:
        session.connect("tcp://" + args.ip + ":" + str(args.port))
    except RuntimeError:
        print ("Can't connect to Naoqi at ip \"" + args.ip + "\" on port " + str(args.port) +".\n"
               "Please check your script arguments. Run with -h option for help.")
        sys.exit(1)
    main(session, args.explo)