melodic noetic   Show EOL distros: 

Map format

Maps manipulated by the tools in this package are stored in a pair of files. The YAML file describes the map meta-data, and names the image file. The image file encodes the occupancy data.

Image format

The image describes the occupancy state of each cell of the world in the color of the corresponding pixel. Whiter pixels are free, blacker pixels are occupied, and pixels in between are unknown. Color and grayscale images are accepted, but most maps are gray (even though they may be stored as if in color). Thresholds in the YAML file are used to divide the three categories; thresholding is done inside the map_server.

When comparing to the threshold parameters, the occupancy probability of an image pixel is computed as follows: occ = (255 - color_avg) / 255.0, where color_avg is the 8-bit value that results from averaging over all channels, e.g. if the image is 24-bit color, a pixel with the color 0x0a0a0a has a probability of 0.96, which is very occupied. The color 0xeeeeee yields 0.07, which is very unoccupied.

When communicated via ROS messages, occupancy is represented as an integer in the range [0,100], with 0 meaning completely free and 100 meaning completely occupied, and the special value -1 for completely unknown.

Image data is read in via SDL_Image; supported formats vary, depending on what SDL_Image provides on a specific platform. Generally speaking, most popular image formats are widely supported. A notable exception is that PNG is not supported on OS X.

YAML format

The YAML format is best explained with a simple, complete example:

image: testmap.png
resolution: 0.1
origin: [0.0, 0.0, 0.0]
occupied_thresh: 0.65
free_thresh: 0.196
negate: 0

Required fields:

• image : Path to the image file containing the occupancy data; can be absolute, or relative to the location of the YAML file

• resolution : Resolution of the map, meters / pixel

• origin : The 2-D pose of the lower-left pixel in the map, as (x, y, yaw), with yaw as counterclockwise rotation (yaw=0 means no rotation). Many parts of the system currently ignore yaw.

• occupied_thresh : Pixels with occupancy probability greater than this threshold are considered completely occupied.

• free_thresh : Pixels with occupancy probability less than this threshold are considered completely free.

• negate : Whether the white/black free/occupied semantics should be reversed (interpretation of thresholds is unaffected)

Command-line Tools

map_server

map_server is a ROS node that reads a map from disk and offers it via a ROS service.

The current implementation of the map_server converts color values in the map image data into ternary occupancy values: free (0), occupied (100), and unknown (-1). Future versions of this tool may use the values between 0 and 100 to communicate finer gradations of occupancy.

Usage

map_server <map.yaml>

Example

rosrun map_server map_server mymap.yaml

Note that the map data may be retrieved via either latched topic (meaning that it is sent once to each new subscriber), or via service. The service may eventually be phased out.

Published Topics

map_metadata (nav_msgs/MapMetaData)

• Receive the map metadata via this latched topic.

map (nav_msgs/OccupancyGrid)

• Receive the map via this latched topic.

Services

static_map (nav_msgs/GetMap)

• Retrieve the map via this service.

Parameters

~frame_id (string, default: "map")

• The frame to set in the header of the published map.

map_saver

map_saver saves a map to disk, e.g., from a SLAM mapping service.

Usage

map_saver [-f mapname]

map_saver retrieves map data and writes it out to map.pgm and map.yaml. Use the -f option to provide a different base name for the output files.

Example

rosrun map_server map_saver -f mymap

Subscribed Topics

map (nav_msgs/OccupancyGrid)

• Map will be retrieved via this latched topic.