6.17 localize

Synopsis

The localize interface provides pose information for the robot. Generally speaking, localization drivers will estimate the pose of the robot by comparing observed sensor readings against a pre-defined map of the environment. See, for the example, the regular_mcl and adaptive_mcl drivers, which implement probabilistic Monte-Carlo localization algorithms.

Constants

#define PLAYER_LOCALIZE_MAX_HYPOTHS 10

The maximum number of pose hypotheses.

#define PLAYER_LOCALIZE_SET_POSE_REQ ((uint8_t)1)
#define PLAYER_LOCALIZE_GET_CONFIG_REQ ((uint8_t)2)
#define PLAYER_LOCALIZE_SET_CONFIG_REQ ((uint8_t)3)
#define PLAYER_LOCALIZE_GET_MAP_INFO_REQ ((uint8_t)4)
#define PLAYER_LOCALIZE_GET_MAP_DATA_REQ ((uint8_t)5)

Request/reply packet subtypes

Data

struct player_localize_hypoth : Since the robot pose may be ambiguous (i.e., the robot may at any of a number of widely spaced locations), the localize interface is capable of returning more that one hypothesis. The format for each such hypothesis is as follows:

int32_t mean[3];

The mean value of the pose estimate (mm, mm, arc-seconds).

int64_t cov[3][3];

The covariance matrix pose estimate (mm², arc-seconds²).

uint32_t alpha;

The weight coefficient for linear combination (alpha * 1e6).

struct player_localize_data : The localize interface returns a data packet containing an an array of hypotheses, defined as follows:

uint16_t pending_count;

The number of pending (unprocessed observations)

uint32_t pending_time_sec, pending_time_usec;

The time stamp of the last observation processed.

uint32_t hypoth_count;

The number of pose hypotheses.

player_localize_hypoth_t hypoths[PLAYER_LOCALIZE_MAX_HYPOTHS];

The array of the hypotheses.

Commands

This interface accepts no commands.

Configuration: Set the robot pose estimate

struct player_localize_set_pose : Set the current robot pose hypothesis. The server will reply with a zero length response packet.

uint8_t subtype;

Request subtype; must be PLAYER_LOCALIZE_SET_POSE_REQ.

int32_t mean[3];

The mean value of the pose estimate (mm, mm, arc-seconds).

int64_t cov[3][3];

The covariance matrix pose estimate (mm², arc-seconds²).

Configuration: Get/Set configuration

struct player_localize_config : To retrieve the configuration, set the subtype to PLAYER_LOCALIZE_GET_CONFIG_REQ and leave the other fields empty. The server will reply with the following configuaration fields filled in. To change the current configuration, set the subtype to PLAYER_LOCALIZE_SET_CONFIG_REQ and fill the configuration fields.

uint8_t subtype;

Request subtype; must be either PLAYER_LOCALIZE_GET_CONFIG_REQ or PLAYER_LOCALIZE_SET_CONFIG_REQ

uint32_t num_particles;

Maximum number of particles (for drivers using particle * filters).

Configuration: Get map information

struct player_localize_map_info : Retrieve the size and scale information of a current map. This request is used to get the size information before you request the actual map data. Set the subtype to PLAYER_LOCALIZE_GET_MAP_INFO_REQ; the server will reply with the size information filled in.

uint8_t subtype;

Request subtype; must be PLAYER_LOCALIZE_GET_MAP_INFO_REQ

uint32_t scale;

The scale of the map (pixels per kilometer).

uint32_t width, height;

The size of the map (pixels).

Configuration: Get map data

struct player_localize_map_data : Retrieve the map data. Beacause of the limited size of a request-replay messages, the map data is tranfered in tiles. In the request packet, set the column and row index of a specific tile; the server will reply with the requested map data filled in.

uint8_t subtype;

Request subtype; must be PLAYER_LOCALIZE_MAP_DATA_REQ.

uint32_t col, row;

The tile origin (pixels).

uint32_t width, height;

The size of the tile (pixels).

int8_t data[PLAYER_MAX_REQREP_SIZE - 17];

Cell occupancy value (empty = -1, unknown = 0, occupied = +1).